Import Upstream version 4.92
[hcoop/debian/exim4.git] / doc / spec.txt
1 Specification of the Exim Mail Transfer Agent
2
3 Exim Maintainers
4
5 Copyright (c) 2018 University of Cambridge
6
7 Revision 4.92 10 Feb 2019 EM
8
9 -------------------------------------------------------------------------------
10
11 TABLE OF CONTENTS
12
13 1. Introduction
14
15 1.1. Exim documentation
16 1.2. FTP site and websites
17 1.3. Mailing lists
18 1.4. Bug reports
19 1.5. Where to find the Exim distribution
20 1.6. Limitations
21 1.7. Runtime configuration
22 1.8. Calling interface
23 1.9. Terminology
24
25 2. Incorporated code
26 3. How Exim receives and delivers mail
27
28 3.1. Overall philosophy
29 3.2. Policy control
30 3.3. User filters
31 3.4. Message identification
32 3.5. Receiving mail
33 3.6. Handling an incoming message
34 3.7. Life of a message
35 3.8. Processing an address for delivery
36 3.9. Processing an address for verification
37 3.10. Running an individual router
38 3.11. Duplicate addresses
39 3.12. Router preconditions
40 3.13. Delivery in detail
41 3.14. Retry mechanism
42 3.15. Temporary delivery failure
43 3.16. Permanent delivery failure
44 3.17. Failures to deliver bounce messages
45
46 4. Building and installing Exim
47
48 4.1. Unpacking
49 4.2. Multiple machine architectures and operating systems
50 4.3. PCRE library
51 4.4. DBM libraries
52 4.5. Pre-building configuration
53 4.6. Support for iconv()
54 4.7. Including TLS/SSL encryption support
55 4.8. Use of tcpwrappers
56 4.9. Including support for IPv6
57 4.10. Dynamically loaded lookup module support
58 4.11. The building process
59 4.12. Output from "make"
60 4.13. Overriding build-time options for Exim
61 4.14. OS-specific header files
62 4.15. Overriding build-time options for the monitor
63 4.16. Installing Exim binaries and scripts
64 4.17. Installing info documentation
65 4.18. Setting up the spool directory
66 4.19. Testing
67 4.20. Replacing another MTA with Exim
68 4.21. Upgrading Exim
69 4.22. Stopping the Exim daemon on Solaris
70
71 5. The Exim command line
72
73 5.1. Setting options by program name
74 5.2. Trusted and admin users
75 5.3. Command line options
76
77 6. The Exim runtime configuration file
78
79 6.1. Using a different configuration file
80 6.2. Configuration file format
81 6.3. File inclusions in the configuration file
82 6.4. Macros in the configuration file
83 6.5. Macro substitution
84 6.6. Redefining macros
85 6.7. Overriding macro values
86 6.8. Example of macro usage
87 6.9. Builtin macros
88 6.10. Conditional skips in the configuration file
89 6.11. Common option syntax
90 6.12. Boolean options
91 6.13. Integer values
92 6.14. Octal integer values
93 6.15. Fixed point numbers
94 6.16. Time intervals
95 6.17. String values
96 6.18. Expanded strings
97 6.19. User and group names
98 6.20. List construction
99 6.21. Changing list separators
100 6.22. Empty items in lists
101 6.23. Format of driver configurations
102
103 7. The default configuration file
104
105 7.1. Macros
106 7.2. Main configuration settings
107 7.3. ACL configuration
108 7.4. Router configuration
109 7.5. Transport configuration
110 7.6. Default retry rule
111 7.7. Rewriting configuration
112 7.8. 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
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
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 submissions (aka 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
373 41. The tls authenticator
374 42. Encrypted SMTP connections using TLS/SSL
375
376 42.1. Support for the "submissions" (aka "ssmtp" and "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 42.15. DANE
391
392 43. Access control lists
393
394 43.1. Testing ACLs
395 43.2. Specifying when ACLs are used
396 43.3. The non-SMTP ACLs
397 43.4. The SMTP connect ACL
398 43.5. The EHLO/HELO ACL
399 43.6. The DATA ACLs
400 43.7. The SMTP DKIM ACL
401 43.8. The SMTP MIME ACL
402 43.9. The SMTP PRDR ACL
403 43.10. The QUIT ACL
404 43.11. The not-QUIT ACL
405 43.12. Finding an ACL to use
406 43.13. ACL return codes
407 43.14. Unset ACL options
408 43.15. Data for message ACLs
409 43.16. Data for non-message ACLs
410 43.17. Format of an ACL
411 43.18. ACL verbs
412 43.19. ACL variables
413 43.20. Condition and modifier processing
414 43.21. ACL modifiers
415 43.22. Use of the control modifier
416 43.23. Summary of message fixup control
417 43.24. Adding header lines in ACLs
418 43.25. Removing header lines in ACLs
419 43.26. ACL conditions
420 43.27. Using DNS lists
421 43.28. Specifying the IP address for a DNS list lookup
422 43.29. DNS lists keyed on domain names
423 43.30. Multiple explicit keys for a DNS list
424 43.31. Data returned by DNS lists
425 43.32. Variables set from DNS lists
426 43.33. Additional matching conditions for DNS lists
427 43.34. Negated DNS matching conditions
428 43.35. Handling multiple DNS records from a DNS list
429 43.36. Detailed information from merged DNS lists
430 43.37. DNS lists and IPv6
431 43.38. Rate limiting incoming messages
432 43.39. Ratelimit options for what is being measured
433 43.40. Ratelimit update modes
434 43.41. Ratelimit options for handling fast clients
435 43.42. Limiting the rate of different events
436 43.43. Using rate limiting
437 43.44. Address verification
438 43.45. Callout verification
439 43.46. Additional parameters for callouts
440 43.47. Callout caching
441 43.48. Sender address verification reporting
442 43.49. Redirection while verifying
443 43.50. Client SMTP authorization (CSA)
444 43.51. Bounce address tag validation
445 43.52. Using an ACL to control relaying
446 43.53. Checking a relay configuration
447
448 44. Content scanning at ACL time
449
450 44.1. Scanning for viruses
451 44.2. Scanning with SpamAssassin and Rspamd
452 44.3. Calling SpamAssassin from an Exim ACL
453 44.4. Scanning MIME parts
454 44.5. Scanning with regular expressions
455
456 45. Adding a local scan function to Exim
457
458 45.1. Building Exim to use a local scan function
459 45.2. API for local_scan()
460 45.3. Configuration options for local_scan()
461 45.4. Available Exim variables
462 45.5. Structure of header lines
463 45.6. Structure of recipient items
464 45.7. Available Exim functions
465 45.8. More about Exim's memory handling
466
467 46. System-wide message filtering
468
469 46.1. Specifying a system filter
470 46.2. Testing a system filter
471 46.3. Contents of a system filter
472 46.4. Additional variable for system filters
473 46.5. Defer, freeze, and fail commands for system filters
474 46.6. Adding and removing headers in a system filter
475 46.7. Setting an errors address in a system filter
476 46.8. Per-address filtering
477
478 47. Message processing
479
480 47.1. Submission mode for non-local messages
481 47.2. Line endings
482 47.3. Unqualified addresses
483 47.4. The UUCP From line
484 47.5. Resent- header lines
485 47.6. The Auto-Submitted: header line
486 47.7. The Bcc: header line
487 47.8. The Date: header line
488 47.9. The Delivery-date: header line
489 47.10. The Envelope-to: header line
490 47.11. The From: header line
491 47.12. The Message-ID: header line
492 47.13. The Received: header line
493 47.14. The References: header line
494 47.15. The Return-path: header line
495 47.16. The Sender: header line
496 47.17. Adding and removing header lines in routers and transports
497 47.18. Constructed addresses
498 47.19. Case of local parts
499 47.20. Dots in local parts
500 47.21. Rewriting addresses
501
502 48. SMTP processing
503
504 48.1. Outgoing SMTP and LMTP over TCP/IP
505 48.2. Errors in outgoing SMTP
506 48.3. Incoming SMTP messages over TCP/IP
507 48.4. Unrecognized SMTP commands
508 48.5. Syntax and protocol errors in SMTP commands
509 48.6. Use of non-mail SMTP commands
510 48.7. The VRFY and EXPN commands
511 48.8. The ETRN command
512 48.9. Incoming local SMTP
513 48.10. Outgoing batched SMTP
514 48.11. Incoming batched SMTP
515
516 49. Customizing bounce and warning messages
517
518 49.1. Customizing bounce messages
519 49.2. Customizing warning messages
520
521 50. Some common configuration settings
522
523 50.1. Sending mail to a smart host
524 50.2. Using Exim to handle mailing lists
525 50.3. Syntax errors in mailing lists
526 50.4. Re-expansion of mailing lists
527 50.5. Closed mailing lists
528 50.6. Variable Envelope Return Paths (VERP)
529 50.7. Virtual domains
530 50.8. Multiple user mailboxes
531 50.9. Simplified vacation processing
532 50.10. Taking copies of mail
533 50.11. Intermittently connected hosts
534 50.12. Exim on the upstream server host
535 50.13. Exim on the intermittently connected client host
536
537 51. Using Exim as a non-queueing client
538 52. Log files
539
540 52.1. Where the logs are written
541 52.2. Logging to local files that are periodically "cycled"
542 52.3. Datestamped log files
543 52.4. Logging to syslog
544 52.5. Log line flags
545 52.6. Logging message reception
546 52.7. Logging deliveries
547 52.8. Discarded deliveries
548 52.9. Deferred deliveries
549 52.10. Delivery failures
550 52.11. Fake deliveries
551 52.12. Completion
552 52.13. Summary of Fields in Log Lines
553 52.14. Other log entries
554 52.15. Reducing or increasing what is logged
555 52.16. Message log
556
557 53. Exim utilities
558
559 53.1. Finding out what Exim processes are doing (exiwhat)
560 53.2. Selective queue listing (exiqgrep)
561 53.3. Summarizing the queue (exiqsumm)
562 53.4. Extracting specific information from the log (exigrep)
563 53.5. Selecting messages by various criteria (exipick)
564 53.6. Cycling log files (exicyclog)
565 53.7. Mail statistics (eximstats)
566 53.8. Checking access policy (exim_checkaccess)
567 53.9. Making DBM files (exim_dbmbuild)
568 53.10. Finding individual retry times (exinext)
569 53.11. Hints database maintenance
570 53.12. exim_dumpdb
571 53.13. exim_tidydb
572 53.14. exim_fixdb
573 53.15. Mailbox maintenance (exim_lock)
574
575 54. The Exim monitor
576
577 54.1. Running the monitor
578 54.2. The stripcharts
579 54.3. Main action buttons
580 54.4. The log display
581 54.5. The queue display
582 54.6. The queue menu
583
584 55. Security considerations
585
586 55.1. Building a more "hardened" Exim
587 55.2. Root privilege
588 55.3. Running Exim without privilege
589 55.4. Delivering to local files
590 55.5. Running local commands
591 55.6. Trust in configuration data
592 55.7. IPv4 source routing
593 55.8. The VRFY, EXPN, and ETRN commands in SMTP
594 55.9. Privileged users
595 55.10. Spool files
596 55.11. Use of argv[0]
597 55.12. Use of %f formatting
598 55.13. Embedded Exim path
599 55.14. Dynamic module directory
600 55.15. Use of sprintf()
601 55.16. Use of debug_printf() and log_write()
602 55.17. Use of strcat() and strcpy()
603
604 56. Format of spool files
605
606 56.1. Format of the -H file
607 56.2. Format of the -D file
608
609 57. DKIM and SPF
610
611 57.1. DKIM (DomainKeys Identified Mail)
612 57.2. Signing outgoing messages
613 57.3. Verifying DKIM signatures in incoming mail
614 57.4. SPF (Sender Policy Framework)
615
616 58. Proxies
617
618 58.1. Inbound proxies
619 58.2. Outbound proxies
620 58.3. Logging
621
622 59. Internationalisation
623
624 59.1. MTA operations
625 59.2. MDA operations
626
627 60. Events
628 61. Adding new drivers or lookup types
629
630
631
632 ===============================================================================
633 1. INTRODUCTION
634
635 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
636 Unix-like operating systems. It was designed on the assumption that it would be
637 run on hosts that are permanently connected to the Internet. However, it can be
638 used on intermittently connected hosts with suitable configuration adjustments.
639
640 Configuration files currently exist for the following operating systems: AIX,
641 BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/
642 Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
643 OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
644 Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare.
645 Some of these operating systems are no longer current and cannot easily be
646 tested, so the configuration files may no longer work in practice.
647
648 There are also configuration files for compiling Exim in the Cygwin environment
649 that can be installed on systems running Windows. However, this document does
650 not contain any information about running Exim in the Cygwin environment.
651
652 The terms and conditions for the use and distribution of Exim are contained in
653 the file NOTICE. Exim is distributed under the terms of the GNU General Public
654 Licence, a copy of which may be found in the file LICENCE.
655
656 The use, supply, or promotion of Exim for the purpose of sending bulk,
657 unsolicited electronic mail is incompatible with the basic aims of Exim, which
658 revolve around the free provision of a service that enhances the quality of
659 personal communications. The author of Exim regards indiscriminate mass-mailing
660 as an antisocial, irresponsible abuse of the Internet.
661
662 Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
663 experience of running and working on the Smail 3 code, I could never have
664 contemplated starting to write a new MTA. Many of the ideas and user interfaces
665 were originally taken from Smail 3, though the actual code of Exim is entirely
666 new, and has developed far beyond the initial concept.
667
668 Many people, both in Cambridge and around the world, have contributed to the
669 development and the testing of Exim, and to porting it to various operating
670 systems. I am grateful to them all. The distribution now contains a file called
671 ACKNOWLEDGMENTS, in which I have started recording the names of contributors.
672
673
674 1.1 Exim documentation
675 ----------------------
676
677 This edition of the Exim specification applies to version 4.92 of Exim.
678 Substantive changes from the 4.91 edition are marked in some renditions of this
679 document; this paragraph is so marked if the rendition is capable of showing a
680 change indicator.
681
682 This document is very much a reference manual; it is not a tutorial. The reader
683 is expected to have some familiarity with the SMTP mail transfer protocol and
684 with general Unix system administration. Although there are some discussions
685 and examples in places, the information is mostly organized in a way that makes
686 it easy to look up, rather than in a natural order for sequential reading.
687 Furthermore, this manual aims to cover every aspect of Exim in detail,
688 including a number of rarely-used, special-purpose features that are unlikely
689 to be of very wide interest.
690
691 An "easier" discussion of Exim which provides more in-depth explanatory,
692 introductory, and tutorial material can be found in a book entitled The Exim
693 SMTP Mail Server (second edition, 2007), published by UIT Cambridge (https://
694 www.uit.co.uk/exim-book/).
695
696 The book also contains a chapter that gives a general introduction to SMTP and
697 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
698 with the latest release of Exim. (Note that the earlier book about Exim,
699 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
700
701 If you are using a Debian distribution of Exim, you will find information about
702 Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian.
703 The command man update-exim.conf is another source of Debian-specific
704 information.
705
706 As Exim develops, there may be features in newer versions that have not yet
707 made it into this document, which is updated only when the most significant
708 digit of the fractional part of the version number changes. Specifications of
709 new features that are not yet in this manual are placed in the file doc/
710 NewStuff in the Exim distribution.
711
712 Some features may be classified as "experimental". These may change
713 incompatibly while they are developing, or even be withdrawn. For this reason,
714 they are not documented in this manual. Information about experimental features
715 can be found in the file doc/experimental.txt.
716
717 All changes to Exim (whether new features, bug fixes, or other kinds of change)
718 are noted briefly in the file called doc/ChangeLog.
719
720 This specification itself is available as an ASCII file in doc/spec.txt so that
721 it can easily be searched with a text editor. Other files in the doc directory
722 are:
723
724 OptionLists.txt list of all options in alphabetical order
725 dbm.discuss.txt discussion about DBM libraries
726 exim.8 a man page of Exim's command line options
727 experimental.txt documentation of experimental features
728 filter.txt specification of the filter language
729 Exim3.upgrade upgrade notes from release 2 to release 3
730 Exim4.upgrade upgrade notes from release 3 to release 4
731 openssl.txt installing a current OpenSSL release
732
733 The main specification and the specification of the filtering language are also
734 available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.5
735 below tells you how to get hold of these.
736
737
738 1.2 FTP site and websites
739 -------------------------
740
741 The primary site for Exim source distributions is the exim.org FTP site,
742 available over HTTPS, HTTP and FTP. These services, and the exim.org website,
743 are hosted at the University of Cambridge.
744
745 As well as Exim distribution tar files, the Exim website contains a number of
746 differently formatted versions of the documentation. A recent addition to the
747 online information is the Exim wiki (https://wiki.exim.org), which contains
748 what used to be a separate FAQ, as well as various other examples, tips, and
749 know-how that have been contributed by Exim users. The wiki site should always
750 redirect to the correct place, which is currently provided by GitHub, and is
751 open to editing by anyone with a GitHub account.
752
753 An Exim Bugzilla exists at https://bugs.exim.org. You can use this to report
754 bugs, and also to add items to the wish list. Please search first to check that
755 you are not duplicating a previous entry. Please do not ask for configuration
756 help in the bug-tracker.
757
758
759 1.3 Mailing lists
760 -----------------
761
762 The following Exim mailing lists exist:
763
764 exim-announce@exim.org Moderated, low volume announcements list
765 exim-users@exim.org General discussion list
766 exim-dev@exim.org Discussion of bugs, enhancements, etc.
767 exim-cvs@exim.org Automated commit messages from the VCS
768
769 You can subscribe to these lists, change your existing subscriptions, and view
770 or search the archives via the mailing lists link on the Exim home page. If you
771 are using a Debian distribution of Exim, you may wish to subscribe to the
772 Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this
773 web page:
774
775 https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users
776
777 Please ask Debian-specific questions on that list and not on the general Exim
778 lists.
779
780
781 1.4 Bug reports
782 ---------------
783
784 Reports of obvious bugs can be emailed to bugs@exim.org or reported via the
785 Bugzilla (https://bugs.exim.org). However, if you are unsure whether some
786 behaviour is a bug or not, the best thing to do is to post a message to the
787 exim-dev mailing list and have it discussed.
788
789
790 1.5 Where to find the Exim distribution
791 ---------------------------------------
792
793 The master distribution site for the Exim distribution is
794
795 https://downloads.exim.org/
796
797 The service is available over HTTPS, HTTP and FTP. We encourage people to
798 migrate to HTTPS.
799
800 The content served at https://downloads.exim.org/ is identical to the content
801 served at https://ftp.exim.org/pub/exim and ftp://ftp.exim.org/pub/exim.
802
803 If accessing via a hostname containing ftp, then the file references that
804 follow are relative to the exim directories at these sites. If accessing via
805 the hostname downloads then the subdirectories described here are top-level
806 directories.
807
808 There are now quite a number of independent mirror sites around the world.
809 Those that I know about are listed in the file called Mirrors.
810
811 Within the top exim directory there are subdirectories called exim3 (for
812 previous Exim 3 distributions), exim4 (for the latest Exim 4 distributions),
813 and Testing for testing versions. In the exim4 subdirectory, the current
814 release can always be found in files called
815
816 exim-n.nn.tar.xz
817 exim-n.nn.tar.gz
818 exim-n.nn.tar.bz2
819
820 where n.nn is the highest such version number in the directory. The three files
821 contain identical data; the only difference is the type of compression. The .xz
822 file is usually the smallest, while the .gz file is the most portable to old
823 systems.
824
825 The distributions will be PGP signed by an individual key of the Release
826 Coordinator. This key will have a uid containing an email address in the
827 exim.org domain and will have signatures from other people, including other
828 Exim maintainers. We expect that the key will be in the "strong set" of PGP
829 keys. There should be a trust path to that key from the Exim Maintainer's PGP
830 keys, a version of which can be found in the release directory in the file
831 Exim-Maintainers-Keyring.asc. All keys used will be available in public
832 keyserver pools, such as pool.sks-keyservers.net.
833
834 At the time of the last update, releases were being made by Jeremy Harris and
835 signed with key 0xBCE58C8CE41F32DF. Other recent keys used for signing are
836 those of Heiko Schlittermann, 0x26101B62F69376CE, and of Phil Pennock,
837 0x4D1E900E14C1CC04.
838
839 The signatures for the tar bundles are in:
840
841 exim-n.nn.tar.xz.asc
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 available in a separate
846 file in the directory ChangeLogs so that it is possible to find out what has
847 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 and .xz forms.
860
861
862 1.6 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.7 Runtime configuration
899 -------------------------
900
901 Exim's runtime configuration is held in a single text file that is divided into
902 a number of sections. The entries in this file consist of keywords and values,
903 in the style of Smail 3 configuration files. A default configuration file which
904 is suitable for simple online installations is provided in the distribution,
905 and is described in chapter 7 below.
906
907
908 1.8 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 in 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 in 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.9 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 a
933 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 the part
970 of an email address that precedes the @ sign. The part that follows the @ sign
971 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 in 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 https://cr.yp.to/cdb.html. This implementation
1025 borrows some code from Dan Bernstein's implementation (which has no
1026 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 (https://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 license 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 from 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,
1150 respectively, at these two points (see chapter 43). Denial of access
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
1164 and decide whether to accept it or not (see chapter 45). If the message is
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
1172 available in the form of the system filter (see chapter 46). This runs at
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 filenames, 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 called "batch SMTP" format, but it isn't really SMTP. The
1255 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 addresses
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
1286 requirements are not met. The local_scan() function (see chapter 45) is run for
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
1320 first spool file is described in chapter 56.
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 all 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
1354 delayed deliveries for each recipient (see chapter 52). The log lines are also
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 Exim crash after a successful delivery but before the
1371 spool file has been updated, the journal is left lying around. The next time
1372 Exim attempts to deliver the message, it reads the journal file and updates the
1373 spool file before proceeding. This minimizes the chances of double deliveries
1374 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. Runtime options specify which ones are
1384 actually used for delivering messages.
1385
1386 Each driver that is specified in the runtime 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 specifically by the local host.
1420 Typically these are addresses for arbitrary domains on the Internet. A
1421 precondition is set up which looks for the special domains known to the host
1422 (for example, its own domain name), and the router is run for addresses that do
1423 not match. Typically, this is a router that looks up domains in the DNS in
1424 order to find the hosts to which this address routes. If it succeeds, the
1425 address is assigned to a suitable SMTP transport; if it does not succeed, the
1426 router is configured 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. This
1474 option can be used to set up multiple deliveries with different routing
1475 (for example, for keeping archive copies of messages). When unseen is set,
1476 the address is passed to the next router. Normally, however, an accept
1477 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 case-sensitively. 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
1624 Some additional features are available in system filters - see chapter 46
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 in your queue forever. 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.
1749 See chapter 49 for details.
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
1760 50.2) it is common to direct bounce messages to the manager of the list.
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 in 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,
1783 exim-4.92) into which the following files are placed:
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 with
1804 the Exim binary. The util directory contains a few optional scripts that may be
1805 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. A C99-capable compiler will be required for the build.
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 package or the PCRE development package for your operating system. If your
1827 system has a normal PCRE installation the Exim build process will need no
1828 further configuration. If the library or the headers are in an unusual location
1829 you will need to either set the PCRE_LIBS and INCLUDE directives appropriately,
1830 or set PCRE_CONFIG=yes to use the installed pcre-config command. If your
1831 operating system has no PCRE support then you will need to obtain and build the
1832 current PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More
1833 information on PCRE is available at https://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
1867 filename 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 when
1880 Exim last revamped support were numbered 4.x. Maintenance of some of the
1881 earlier releases has ceased. All versions of Berkeley DB could be obtained
1882 from http://www.sleepycat.com/, which is now a redirect to their new
1883 owner's page with far newer versions listed. It is probably wise to plan to
1884 move your storage configurations away from Berkeley DB format, as today
1885 there are smaller and simpler alternatives more suited to Exim's usage
1886 model.
1887
1888 6. Yet another DBM library, called tdb, is available from https://
1889 sourceforge.net/projects/tdb/files/. It has its own interface, and also
1890 operates on a single file.
1891
1892 Exim and its utilities can be compiled to use any of these interfaces. In order
1893 to use any version of the Berkeley DB package in native mode, you must set
1894 USE_DB in an appropriate configuration file (typically Local/Makefile). For
1895 example:
1896
1897 USE_DB=yes
1898
1899 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is
1900 diagnosed if you set more than one of these.
1901
1902 At the lowest level, the build-time configuration sets none of these options,
1903 thereby assuming an interface of type (1). However, some operating system
1904 configuration files (for example, those for the BSD operating systems and
1905 Linux) assume type (4) by setting USE_DB as their default, and the
1906 configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile
1907 , however, overrides these system defaults.
1908
1909 As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to
1910 set DBMLIB, to cause inclusion of the appropriate library, as in one of these
1911 lines:
1912
1913 DBMLIB = -ldb
1914 DBMLIB = -ltdb
1915
1916 Settings like that will work if the DBM library is installed in the standard
1917 place. Sometimes it is not, and the library's header file may also not be in
1918 the default path. You may need to set INCLUDE to specify where the header file
1919 is, and to specify the path to the library more fully in DBMLIB, as in this
1920 example:
1921
1922 INCLUDE=-I/usr/local/include/db-4.1
1923 DBMLIB=/usr/local/lib/db-4.1/libdb.a
1924
1925 There is further detailed discussion about the various DBM libraries in the
1926 file doc/dbm.discuss.txt in the Exim distribution.
1927
1928
1929 4.5 Pre-building configuration
1930 ------------------------------
1931
1932 Before building Exim, a local configuration file that specifies options
1933 independent of any operating system has to be created with the name Local/
1934 Makefile. A template for this file is supplied as the file src/EDITME, and it
1935 contains full descriptions of all the option settings therein. These
1936 descriptions are therefore not repeated here. If you are building Exim for the
1937 first time, the simplest thing to do is to copy src/EDITME to Local/Makefile,
1938 then read it and edit it appropriately.
1939
1940 There are three settings that you must supply, because Exim will not build
1941 without them. They are the location of the runtime configuration file
1942 (CONFIGURE_FILE), the directory in which Exim binaries will be installed
1943 (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe
1944 EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a
1945 colon-separated list of filenames; Exim uses the first of them that exists.
1946
1947 There are a few other parameters that can be specified either at build time or
1948 at runtime, to enable the same binary to be used on a number of different
1949 machines. However, if the locations of Exim's spool directory and log file
1950 directory (if not within the spool directory) are fixed, it is recommended that
1951 you specify them in Local/Makefile instead of at runtime, so that errors
1952 detected early in Exim's execution (such as a malformed configuration file) can
1953 be logged.
1954
1955 Exim's interfaces for calling virus and spam scanning software directly from
1956 access control lists are not compiled by default. If you want to include these
1957 facilities, you need to set
1958
1959 WITH_CONTENT_SCAN=yes
1960
1961 in your Local/Makefile. For details of the facilities themselves, see chapter
1962 44.
1963
1964 If you are going to build the Exim monitor, a similar configuration process is
1965 required. The file exim_monitor/EDITME must be edited appropriately for your
1966 installation and saved under the name Local/eximon.conf. If you are happy with
1967 the default settings described in exim_monitor/EDITME, Local/eximon.conf can be
1968 empty, but it must exist.
1969
1970 This is all the configuration that is needed in straightforward cases for known
1971 operating systems. However, the building process is set up so that it is easy
1972 to override options that are set by default or by operating-system-specific
1973 configuration files, for example, to change the C compiler, which defaults to
1974 gcc. See section 4.13 below for details of how to do this.
1975
1976
1977 4.6 Support for iconv()
1978 -----------------------
1979
1980 The contents of header lines in messages may be encoded according to the rules
1981 described RFC 2047. This makes it possible to transmit characters that are not
1982 in the ASCII character set, and to label them as being in a particular
1983 character set. When Exim is inspecting header lines by means of the $h_
1984 mechanism, it decodes them, and translates them into a specified character set
1985 (default is set at build time). The translation is possible only if the
1986 operating system supports the iconv() function.
1987
1988 However, some of the operating systems that supply iconv() do not support very
1989 many conversions. The GNU libiconv library (available from https://www.gnu.org/
1990 software/libiconv/) can be installed on such systems to remedy this deficiency,
1991 as well as on systems that do not supply iconv() at all. After installing
1992 libiconv, you should add
1993
1994 HAVE_ICONV=yes
1995
1996 to your Local/Makefile and rebuild Exim.
1997
1998
1999 4.7 Including TLS/SSL encryption support
2000 ----------------------------------------
2001
2002 Exim can be built to support encrypted SMTP connections, using the STARTTLS
2003 command as per RFC 2487. It can also support legacy clients that expect to
2004 start a TLS session immediately on connection to a non-standard port (see the
2005 tls_on_connect_ports runtime option and the -tls-on-connect command line
2006 option).
2007
2008 If you want to build Exim with TLS support, you must first install either the
2009 OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
2010 implementing SSL.
2011
2012 If OpenSSL is installed, you should set
2013
2014 SUPPORT_TLS=yes
2015 TLS_LIBS=-lssl -lcrypto
2016
2017 in Local/Makefile. You may also need to specify the locations of the OpenSSL
2018 library and include files. For example:
2019
2020 SUPPORT_TLS=yes
2021 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
2022 TLS_INCLUDE=-I/usr/local/openssl/include/
2023
2024 If you have pkg-config available, then instead you can just use:
2025
2026 SUPPORT_TLS=yes
2027 USE_OPENSSL_PC=openssl
2028
2029 If GnuTLS is installed, you should set
2030
2031 SUPPORT_TLS=yes
2032 USE_GNUTLS=yes
2033 TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
2034
2035 in Local/Makefile, and again you may need to specify the locations of the
2036 library and include files. For example:
2037
2038 SUPPORT_TLS=yes
2039 USE_GNUTLS=yes
2040 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
2041 TLS_INCLUDE=-I/usr/gnu/include
2042
2043 If you have pkg-config available, then instead you can just use:
2044
2045 SUPPORT_TLS=yes
2046 USE_GNUTLS=yes
2047 USE_GNUTLS_PC=gnutls
2048
2049 You do not need to set TLS_INCLUDE if the relevant directory is already
2050 specified in INCLUDE. Details of how to configure Exim to make use of TLS are
2051 given in chapter 42.
2052
2053
2054 4.8 Use of tcpwrappers
2055 ----------------------
2056
2057 Exim can be linked with the tcpwrappers library in order to check incoming SMTP
2058 calls using the tcpwrappers control files. This may be a convenient alternative
2059 to Exim's own checking facilities for installations that are already making use
2060 of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS
2061 in Local/Makefile, arrange for the file tcpd.h to be available at compile time,
2062 and also ensure that the library libwrap.a is available at link time, typically
2063 by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed
2064 in /usr/local, you might have
2065
2066 USE_TCP_WRAPPERS=yes
2067 CFLAGS=-O -I/usr/local/include
2068 EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
2069
2070 in Local/Makefile. The daemon name to use in the tcpwrappers control files is
2071 "exim". For example, the line
2072
2073 exim : LOCAL 192.168.1. .friendly.domain.example
2074
2075 in your /etc/hosts.allow file allows connections from the local host, from the
2076 subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other
2077 connections are denied. The daemon name used by tcpwrappers can be changed at
2078 build time by setting TCP_WRAPPERS_DAEMON_NAME in Local/Makefile, or by setting
2079 tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers
2080 documentation for further details.
2081
2082
2083 4.9 Including support for IPv6
2084 ------------------------------
2085
2086 Exim contains code for use on systems that have IPv6 support. Setting
2087 "HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may
2088 also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6
2089 support is not fully integrated into the normal include and library files.
2090
2091 Two different types of DNS record for handling IPv6 addresses have been
2092 defined. AAAA records (analogous to A records for IPv4) are in use, and are
2093 currently seen as the mainstream. Another record type called A6 was proposed as
2094 better than AAAA because it had more flexibility. However, it was felt to be
2095 over-complex, and its status was reduced to "experimental". Exim used to have a
2096 compile option for including A6 record support but this has now been withdrawn.
2097
2098
2099 4.10 Dynamically loaded lookup module support
2100 ---------------------------------------------
2101
2102 On some platforms, Exim supports not compiling all lookup types directly into
2103 the main binary, instead putting some into external modules which can be loaded
2104 on demand. This permits packagers to build Exim with support for lookups with
2105 extensive library dependencies without requiring all users to install all of
2106 those dependencies. Most, but not all, lookup types can be built this way.
2107
2108 Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be
2109 installed; Exim will only load modules from that directory, as a security
2110 measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your
2111 OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting
2112 "EXTRALIBS" may also be necessary, see src/EDITME for details.
2113
2114 Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"<
2115 lookup_type> flags to have the value "2" instead of "yes". For example, this
2116 will build in lsearch but load sqlite and mysql support on demand:
2117
2118 LOOKUP_LSEARCH=yes
2119 LOOKUP_SQLITE=2
2120 LOOKUP_MYSQL=2
2121
2122
2123 4.11 The building process
2124 -------------------------
2125
2126 Once Local/Makefile (and Local/eximon.conf, if required) have been created, run
2127 make at the top level. It determines the architecture and operating system
2128 types, and creates a build directory if one does not exist. For example, on a
2129 Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created.
2130 Symbolic links to relevant source files are installed in the build directory.
2131
2132 If this is the first time make has been run, it calls a script that builds a
2133 make file inside the build directory, using the configuration files from the
2134 Local directory. The new make file is then passed to another instance of make.
2135 This does the real work, building a number of utility scripts, and then
2136 compiling and linking the binaries for the Exim monitor (if configured), a
2137 number of utility programs, and finally Exim itself. The command "make
2138 makefile" can be used to force a rebuild of the make file in the build
2139 directory, should this ever be necessary.
2140
2141 If you have problems building Exim, check for any comments there may be in the
2142 README file concerning your operating system, and also take a look at the FAQ,
2143 where some common problems are covered.
2144
2145
2146 4.12 Output from "make"
2147 -----------------------
2148
2149 The output produced by the make process for compile lines is often very
2150 unreadable, because these lines can be very long. For this reason, the normal
2151 output is suppressed by default, and instead output similar to that which
2152 appears when compiling the 2.6 Linux kernel is generated: just a short line for
2153 each module that is being compiled or linked. However, it is still possible to
2154 get the full output, by calling make like this:
2155
2156 FULLECHO='' make -e
2157
2158 The value of FULLECHO defaults to "@", the flag character that suppresses
2159 command reflection in make. When you ask for the full output, it is given in
2160 addition to the short output.
2161
2162
2163 4.13 Overriding build-time options for Exim
2164 -------------------------------------------
2165
2166 The main make file that is created at the beginning of the building process
2167 consists of the concatenation of a number of files which set configuration
2168 values, followed by a fixed set of make instructions. If a value is set more
2169 than once, the last setting overrides any previous ones. This provides a
2170 convenient way of overriding defaults. The files that are concatenated are, in
2171 order:
2172
2173 OS/Makefile-Default
2174 OS/Makefile-<ostype>
2175 Local/Makefile
2176 Local/Makefile-<ostype>
2177 Local/Makefile-<archtype>
2178 Local/Makefile-<ostype>-<archtype>
2179 OS/Makefile-Base
2180
2181 where <ostype> is the operating system type and <archtype> is the architecture
2182 type. Local/Makefile is required to exist, and the building process fails if it
2183 is absent. The other three Local files are optional, and are often not needed.
2184
2185 The values used for <ostype> and <archtype> are obtained from scripts called
2186 scripts/os-type and scripts/arch-type respectively. If either of the
2187 environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are
2188 used, thereby providing a means of forcing particular settings. Otherwise, the
2189 scripts try to get values from the uname command. If this fails, the shell
2190 variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations
2191 are then applied, to produce the standard names that Exim expects. You can run
2192 these scripts directly from the shell in order to find out what values are
2193 being used on your system.
2194
2195 OS/Makefile-Default contains comments about the variables that are set therein.
2196 Some (but not all) are mentioned below. If there is something that needs
2197 changing, review the contents of this file and the contents of the make file
2198 for your operating system (OS/Makefile-<ostype>) to see what the default values
2199 are.
2200
2201 If you need to change any of the values that are set in OS/Makefile-Default or
2202 in OS/Makefile-<ostype>, or to add any new definitions, you do not need to
2203 change the original files. Instead, you should make the changes by putting the
2204 new values in an appropriate Local file. For example, when building Exim in
2205 many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1)
2206 operating system, it is necessary to specify that the C compiler is called cc
2207 rather than gcc. Also, the compiler must be called with the option -std1, to
2208 make it recognize some of the features of Standard C that Exim uses. (Most
2209 other compilers recognize Standard C by default.) To do this, you should create
2210 a file called Local/Makefile-OSF1 containing the lines
2211
2212 CC=cc
2213 CFLAGS=-std1
2214
2215 If you are compiling for just one operating system, it may be easier to put
2216 these lines directly into Local/Makefile.
2217
2218 Keeping all your local configuration settings separate from the distributed
2219 files makes it easy to transfer them to new versions of Exim simply by copying
2220 the contents of the Local directory.
2221
2222 Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
2223 lookup, but not all systems have these components installed, so the default is
2224 not to include the relevant code in the binary. All the different kinds of file
2225 and database lookup that Exim supports are implemented as separate code modules
2226 which are included only if the relevant compile-time options are set. In the
2227 case of LDAP, NIS, and NIS+, the settings for Local/Makefile are:
2228
2229 LOOKUP_LDAP=yes
2230 LOOKUP_NIS=yes
2231 LOOKUP_NISPLUS=yes
2232
2233 and similar settings apply to the other lookup types. They are all listed in
2234 src/EDITME. In many cases the relevant include files and interface libraries
2235 need to be installed before compiling Exim. However, there are some optional
2236 lookup types (such as cdb) for which the code is entirely contained within
2237 Exim, and no external include files or libraries are required. When a lookup
2238 type is not included in the binary, attempts to configure Exim to use it cause
2239 runtime configuration errors.
2240
2241 Many systems now use a tool called pkg-config to encapsulate information about
2242 how to compile against a library; Exim has some initial support for being able
2243 to use pkg-config for lookups and authenticators. For any given makefile
2244 variable which starts "LOOKUP_" or "AUTH_", you can add a new variable with the
2245 "_PC" suffix in the name and assign as the value the name of the package to be
2246 queried. The results of querying via the pkg-config command will be added to
2247 the appropriate Makefile variables with "+=" directives, so your version of
2248 make will need to support that syntax. For instance:
2249
2250 LOOKUP_SQLITE=yes
2251 LOOKUP_SQLITE_PC=sqlite3
2252 AUTH_GSASL=yes
2253 AUTH_GSASL_PC=libgsasl
2254 AUTH_HEIMDAL_GSSAPI=yes
2255 AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
2256
2257 Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines
2258 to be called during string expansion. To enable this facility,
2259
2260 EXIM_PERL=perl.o
2261
2262 must be defined in Local/Makefile. Details of this facility are given in
2263 chapter 12.
2264
2265 The location of the X11 libraries is something that varies a lot between
2266 operating systems, and there may be different versions of X11 to cope with.
2267 Exim itself makes no use of X11, but if you are compiling the Exim monitor, the
2268 X11 libraries must be available. The following three variables are set in OS/
2269 Makefile-Default:
2270
2271 X11=/usr/X11R6
2272 XINCLUDE=-I$(X11)/include
2273 XLFLAGS=-L$(X11)/lib
2274
2275 These are overridden in some of the operating-system configuration files. For
2276 example, in OS/Makefile-SunOS5 there is
2277
2278 X11=/usr/openwin
2279 XINCLUDE=-I$(X11)/include
2280 XLFLAGS=-L$(X11)/lib -R$(X11)/lib
2281
2282 If you need to override the default setting for your operating system, place a
2283 definition of all three of these variables into your Local/Makefile-<ostype>
2284 file.
2285
2286 If you need to add any extra libraries to the link steps, these can be put in a
2287 variable called EXTRALIBS, which appears in all the link commands, but by
2288 default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command
2289 for linking the main Exim binary, and not for any associated utilities.
2290
2291 There is also DBMLIB, which appears in the link commands for binaries that use
2292 DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which
2293 appears only in the link step for the Exim monitor binary, and which can be
2294 used, for example, to include additional X11 libraries.
2295
2296 The make file copes with rebuilding Exim correctly if any of the configuration
2297 files are edited. However, if an optional configuration file is deleted, it is
2298 necessary to touch the associated non-optional file (that is, Local/Makefile or
2299 Local/eximon.conf) before rebuilding.
2300
2301
2302 4.14 OS-specific header files
2303 -----------------------------
2304
2305 The OS directory contains a number of files with names of the form os.h-
2306 <ostype>. These are system-specific C header files that should not normally
2307 need to be changed. There is a list of macro settings that are recognized in
2308 the file OS/os.configuring, which should be consulted if you are porting Exim
2309 to a new operating system.
2310
2311
2312 4.15 Overriding build-time options for the monitor
2313 --------------------------------------------------
2314
2315 A similar process is used for overriding things when building the Exim monitor,
2316 where the files that are involved are
2317
2318 OS/eximon.conf-Default
2319 OS/eximon.conf-<ostype>
2320 Local/eximon.conf
2321 Local/eximon.conf-<ostype>
2322 Local/eximon.conf-<archtype>
2323 Local/eximon.conf-<ostype>-<archtype>
2324
2325 As with Exim itself, the final three files need not exist, and in this case the
2326 OS/eximon.conf-<ostype> file is also optional. The default values in OS/
2327 eximon.conf-Default can be overridden dynamically by setting environment
2328 variables of the same name, preceded by EXIMON_. For example, setting
2329 EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at
2330 runtime.
2331
2332
2333 4.16 Installing Exim binaries and scripts
2334 -----------------------------------------
2335
2336 The command "make install" runs the exim_install script with no arguments. The
2337 script copies binaries and utility scripts into the directory whose name is
2338 specified by the BIN_DIRECTORY setting in Local/Makefile. The install script
2339 copies files only if they are newer than the files they are going to replace.
2340 The Exim binary is required to be owned by root and have the setuid bit set,
2341 for normal configurations. Therefore, you must run "make install" as root so
2342 that it can set up the Exim binary in this way. However, in some special
2343 situations (for example, if a host is doing no local deliveries) it may be
2344 possible to run Exim without making the binary setuid root (see chapter 55 for
2345 details).
2346
2347 Exim's runtime configuration file is named by the CONFIGURE_FILE setting in
2348 Local/Makefile. If this names a single file, and the file does not exist, the
2349 default configuration file src/configure.default is copied there by the
2350 installation script. If a runtime configuration file already exists, it is left
2351 alone. If CONFIGURE_FILE is a colon-separated list, naming several alternative
2352 files, no default is installed.
2353
2354 One change is made to the default configuration file when it is installed: the
2355 default configuration contains a router that references a system aliases file.
2356 The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in
2357 Local/Makefile (/etc/aliases by default). If the system aliases file does not
2358 exist, the installation script creates it, and outputs a comment to the user.
2359
2360 The created file contains no aliases, but it does contain comments about the
2361 aliases a site should normally have. Mail aliases have traditionally been kept
2362 in /etc/aliases. However, some operating systems are now using /etc/mail/
2363 aliases. You should check if yours is one of these, and change Exim's
2364 configuration if necessary.
2365
2366 The default configuration uses the local host's name as the only local domain,
2367 and is set up to do local deliveries into the shared directory /var/mail,
2368 running as the local user. System aliases and .forward files in users' home
2369 directories are supported, but no NIS or NIS+ support is configured. Domains
2370 other than the name of the local host are routed using the DNS, with delivery
2371 over SMTP.
2372
2373 It is possible to install Exim for special purposes (such as building a binary
2374 distribution) in a private part of the file system. You can do this by a
2375 command such as
2376
2377 make DESTDIR=/some/directory/ install
2378
2379 This has the effect of pre-pending the specified directory to all the file
2380 paths, except the name of the system aliases file that appears in the default
2381 configuration. (If a default alias file is created, its name is modified.) For
2382 backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is
2383 deprecated.
2384
2385 Running make install does not copy the Exim 4 conversion script convert4r4. You
2386 will probably run this only once if you are upgrading from Exim 3. None of the
2387 documentation files in the doc directory are copied, except for the info files
2388 when you have set INFO_DIRECTORY, as described in section 4.17 below.
2389
2390 For the utility programs, old versions are renamed by adding the suffix .O to
2391 their names. The Exim binary itself, however, is handled differently. It is
2392 installed under a name that includes the version number and the compile number,
2393 for example, exim-4.92-1. The script then arranges for a symbolic link called
2394 exim to point to the binary. If you are updating a previous version of Exim,
2395 the script takes care to ensure that the name exim is never absent from the
2396 directory (as seen by other processes).
2397
2398 If you want to see what the make install will do before running it for real,
2399 you can pass the -n option to the installation script by this command:
2400
2401 make INSTALL_ARG=-n install
2402
2403 The contents of the variable INSTALL_ARG are passed to the installation script.
2404 You do not need to be root to run this test. Alternatively, you can run the
2405 installation script directly, but this must be from within the build directory.
2406 For example, from the top-level Exim directory you could use this command:
2407
2408 (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
2409
2410 There are two other options that can be supplied to the installation script.
2411
2412 * -no_chown bypasses the call to change the owner of the installed binary to
2413 root, and the call to make it a setuid binary.
2414
2415 * -no_symlink bypasses the setting up of the symbolic link exim to the
2416 installed binary.
2417
2418 INSTALL_ARG can be used to pass these options to the script. For example:
2419
2420 make INSTALL_ARG=-no_symlink install
2421
2422 The installation script can also be given arguments specifying which files are
2423 to be copied. For example, to install just the Exim binary, and nothing else,
2424 without creating the symbolic link, you could use:
2425
2426 make INSTALL_ARG='-no_symlink exim' install
2427
2428
2429 4.17 Installing info documentation
2430 ----------------------------------
2431
2432 Not all systems use the GNU info system for documentation, and for this reason,
2433 the Texinfo source of Exim's documentation is not included in the main
2434 distribution. Instead it is available separately from the FTP site (see section
2435 1.5).
2436
2437 If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of
2438 the documentation is found in the source tree, running "make install"
2439 automatically builds the info files and installs them.
2440
2441
2442 4.18 Setting up the spool directory
2443 -----------------------------------
2444
2445 When it starts up, Exim tries to create its spool directory if it does not
2446 exist. The Exim uid and gid are used for the owner and group of the spool
2447 directory. Sub-directories are automatically created in the spool directory as
2448 necessary.
2449
2450
2451 4.19 Testing
2452 ------------
2453
2454 Having installed Exim, you can check that the runtime configuration file is
2455 syntactically valid by running the following command, which assumes that the
2456 Exim binary directory is within your PATH environment variable:
2457
2458 exim -bV
2459
2460 If there are any errors in the configuration file, Exim outputs error messages.
2461 Otherwise it outputs the version number and build date, the DBM library that is
2462 being used, and information about which drivers and other optional code modules
2463 are included in the binary. Some simple routing tests can be done by using the
2464 address testing option. For example,
2465
2466 exim -bt <local username>
2467
2468 should verify that it recognizes a local mailbox, and
2469
2470 exim -bt <remote address>
2471
2472 a remote one. Then try getting it to deliver mail, both locally and remotely.
2473 This can be done by passing messages directly to Exim, without going through a
2474 user agent. For example:
2475
2476 exim -v postmaster@your.domain.example
2477 From: user@your.domain.example
2478 To: postmaster@your.domain.example
2479 Subject: Testing Exim
2480
2481 This is a test message.
2482 ^D
2483
2484 The -v option causes Exim to output some verification of what it is doing. In
2485 this case you should see copies of three log lines, one for the message's
2486 arrival, one for its delivery, and one containing "Completed".
2487
2488 If you encounter problems, look at Exim's log files (mainlog and paniclog) to
2489 see if there is any relevant information there. Another source of information
2490 is running Exim with debugging turned on, by specifying the -d option. If a
2491 message is stuck on Exim's spool, you can force a delivery with debugging
2492 turned on by a command of the form
2493
2494 exim -d -M <exim-message-id>
2495
2496 You must be root or an "admin user" in order to do this. The -d option produces
2497 rather a lot of output, but you can cut this down to specific areas. For
2498 example, if you use -d-all+route only the debugging information relevant to
2499 routing is included. (See the -d option in chapter 5 for more details.)
2500
2501 One specific problem that has shown up on some sites is the inability to do
2502 local deliveries into a shared mailbox directory, because it does not have the
2503 "sticky bit" set on it. By default, Exim tries to create a lock file before
2504 writing to a mailbox file, and if it cannot create the lock file, the delivery
2505 is deferred. You can get round this either by setting the "sticky bit" on the
2506 directory, or by setting a specific group for local deliveries and allowing
2507 that group to create files in the directory (see the comments above the
2508 local_delivery transport in the default configuration file). Another approach
2509 is to configure Exim not to use lock files, but just to rely on fcntl() locking
2510 instead. However, you should do this only if all user agents also use fcntl()
2511 locking. For further discussion of locking issues, see chapter 26.
2512
2513 One thing that cannot be tested on a system that is already running an MTA is
2514 the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX
2515 option can be used to run an Exim daemon that listens on some other port, or
2516 inetd can be used to do this. The -bh option and the exim_checkaccess utility
2517 can be used to check out policy controls on incoming SMTP mail.
2518
2519 Testing a new version on a system that is already running Exim can most easily
2520 be done by building a binary with a different CONFIGURE_FILE setting. From
2521 within the runtime configuration, all other file and directory names that Exim
2522 uses can be altered, in order to keep it entirely clear of the production
2523 version.
2524
2525
2526 4.20 Replacing another MTA with Exim
2527 ------------------------------------
2528
2529 Building and installing Exim for the first time does not of itself put it in
2530 general use. The name by which the system's MTA is called by mail user agents
2531 is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating
2532 system), and it is necessary to make this name point to the exim binary in
2533 order to get the user agents to pass messages to Exim. This is normally done by
2534 renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a
2535 symbolic link to the exim binary. It is a good idea to remove any setuid
2536 privilege and executable status from the old MTA. It is then necessary to stop
2537 and restart the mailer daemon, if one is running.
2538
2539 Some operating systems have introduced alternative ways of switching MTAs. For
2540 example, if you are running FreeBSD, you need to edit the file /etc/mail/
2541 mailer.conf instead of setting up a symbolic link as just described. A typical
2542 example of the contents of this file for running Exim is as follows:
2543
2544 sendmail /usr/exim/bin/exim
2545 send-mail /usr/exim/bin/exim
2546 mailq /usr/exim/bin/exim -bp
2547 newaliases /usr/bin/true
2548
2549 Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your
2550 Exim installation is "live". Check it by sending a message from your favourite
2551 user agent.
2552
2553 You should consider what to tell your users about the change of MTA. Exim may
2554 have different capabilities to what was previously running, and there are
2555 various operational differences such as the text of messages produced by
2556 command line options and in bounce messages. If you allow your users to make
2557 use of Exim's filtering capabilities, you should make the document entitled
2558 Exim's interface to mail filtering available to them.
2559
2560
2561 4.21 Upgrading Exim
2562 -------------------
2563
2564 If you are already running Exim on your host, building and installing a new
2565 version automatically makes it available to MUAs, or any other programs that
2566 call the MTA directly. However, if you are running an Exim daemon, you do need
2567 to send it a HUP signal, to make it re-execute itself, and thereby pick up the
2568 new binary. You do not need to stop processing mail in order to install a new
2569 version of Exim. The install script does not modify an existing runtime
2570 configuration file.
2571
2572
2573 4.22 Stopping the Exim daemon on Solaris
2574 ----------------------------------------
2575
2576 The standard command for stopping the mailer daemon on Solaris is
2577
2578 /etc/init.d/sendmail stop
2579
2580 If /usr/lib/sendmail has been turned into a symbolic link, this script fails to
2581 stop Exim because it uses the command ps -e and greps the output for the text
2582 "sendmail"; this is not present because the actual program name (that is,
2583 "exim") is given by the ps command with these options. A solution is to replace
2584 the line that finds the process id with something like
2585
2586 pid=`cat /var/spool/exim/exim-daemon.pid`
2587
2588 to obtain the daemon's pid directly from the file that Exim saves it in.
2589
2590 Note, however, that stopping the daemon does not "stop Exim". Messages can
2591 still be received from local processes, and if automatic delivery is configured
2592 (the normal case), deliveries will still occur.
2593
2594
2595
2596 ===============================================================================
2597 5. THE EXIM COMMAND LINE
2598
2599 Exim's command line takes the standard Unix form of a sequence of options, each
2600 starting with a hyphen character, followed by a number of arguments. The
2601 options are compatible with the main options of Sendmail, and there are also
2602 some additional options, some of which are compatible with Smail 3. Certain
2603 combinations of options do not make sense, and provoke an error if used. The
2604 form of the arguments depends on which options are set.
2605
2606
2607 5.1 Setting options by program name
2608 -----------------------------------
2609
2610 If Exim is called under the name mailq, it behaves as if the option -bp were
2611 present before any other options. The -bp option requests a listing of the
2612 contents of the mail queue on the standard output. This feature is for
2613 compatibility with some systems that contain a command of that name in one of
2614 the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/
2615 sendmail.
2616
2617 If Exim is called under the name rsmtp it behaves as if the option -bS were
2618 present before any other options, for compatibility with Smail. The -bS option
2619 is used for reading in a number of messages in batched SMTP format.
2620
2621 If Exim is called under the name rmail it behaves as if the -i and -oee options
2622 were present before any other options, for compatibility with Smail. The name
2623 rmail is used as an interface by some UUCP systems.
2624
2625 If Exim is called under the name runq it behaves as if the option -q were
2626 present before any other options, for compatibility with Smail. The -q option
2627 causes a single queue runner process to be started.
2628
2629 If Exim is called under the name newaliases it behaves as if the option -bi
2630 were present before any other options, for compatibility with Sendmail. This
2631 option is used for rebuilding Sendmail's alias file. Exim does not have the
2632 concept of a single alias file, but can be configured to run a given command if
2633 called with the -bi option.
2634
2635
2636 5.2 Trusted and admin users
2637 ---------------------------
2638
2639 Some Exim options are available only to trusted users and others are available
2640 only to admin users. In the description below, the phrases "Exim user" and
2641 "Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in
2642 Local/Makefile or set by the exim_user and exim_group options. These do not
2643 necessarily have to use the name "exim".
2644
2645 * The trusted users are root, the Exim user, any user listed in the
2646 trusted_users configuration option, and any user whose current group or any
2647 supplementary group is one of those listed in the trusted_groups
2648 configuration option. Note that the Exim group is not automatically
2649 trusted.
2650
2651 Trusted users are always permitted to use the -f option or a leading
2652 "From " line to specify the envelope sender of a message that is passed to
2653 Exim through the local interface (see the -bm and -f options below). See
2654 the untrusted_set_sender option for a way of permitting non-trusted users
2655 to set envelope senders.
2656
2657 For a trusted user, there is never any check on the contents of the From:
2658 header line, and a Sender: line is never added. Furthermore, any existing
2659 Sender: line in incoming local (non-TCP/IP) messages is not removed.
2660
2661 Trusted users may also specify a host name, host address, interface
2662 address, protocol name, ident value, and authentication data when
2663 submitting a message locally. Thus, they are able to insert messages into
2664 Exim's queue locally that have the characteristics of messages received
2665 from a remote host. Untrusted users may in some circumstances use -f, but
2666 can never set the other values that are available to trusted users.
2667
2668 * The admin users are root, the Exim user, and any user that is a member of
2669 the Exim group or of any group listed in the admin_groups configuration
2670 option. The current group does not have to be one of these groups.
2671
2672 Admin users are permitted to list the queue, and to carry out certain
2673 operations on messages, for example, to force delivery failures. It is also
2674 necessary to be an admin user in order to see the full information provided
2675 by the Exim monitor, and full debugging output.
2676
2677 By default, the use of the -M, -q, -R, and -S options to cause Exim to
2678 attempt delivery of messages on its queue is restricted to admin users.
2679 However, this restriction can be relaxed by setting the prod_requires_admin
2680 option false (that is, specifying no_prod_requires_admin).
2681
2682 Similarly, the use of the -bp option to list all the messages in the queue
2683 is restricted to admin users unless queue_list_requires_admin is set false.
2684
2685 Warning: If you configure your system so that admin users are able to edit
2686 Exim's configuration file, you are giving those users an easy way of getting
2687 root. There is further discussion of this issue at the start of chapter 6.
2688
2689
2690 5.3 Command line options
2691 ------------------------
2692
2693 Exim's command line options are described in alphabetical order below. If none
2694 of the options that specifies a specific action (such as starting the daemon or
2695 a queue runner, or testing an address, or receiving a message in a specific
2696 format, or listing the queue) are present, and there is at least one argument
2697 on the command line, -bm (accept a local message on the standard input, with
2698 the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a
2699 brief message about itself and exits.
2700
2701 --
2702
2703 This is a pseudo-option whose only purpose is to terminate the options and
2704 therefore to cause subsequent command line items to be treated as arguments
2705 rather than options, even if they begin with hyphens.
2706
2707 --help
2708
2709 This option causes Exim to output a few sentences stating what it is. The
2710 same output is generated if the Exim binary is called with no options and
2711 no arguments.
2712
2713 --version
2714
2715 This option is an alias for -bV and causes version information to be
2716 displayed.
2717
2718 -Ac, -Am
2719
2720 These options are used by Sendmail for selecting configuration files and
2721 are ignored by Exim.
2722
2723 -B<type>
2724
2725 This is a Sendmail option for selecting 7 or 8 bit processing. Exim is
2726 8-bit clean; it ignores this option.
2727
2728 -bd
2729
2730 This option runs Exim as a daemon, awaiting incoming SMTP connections.
2731 Usually the -bd option is combined with the -q<time> option, to specify
2732 that the daemon should also initiate periodic queue runs.
2733
2734 The -bd option can be used only by an admin user. If either of the -d
2735 (debugging) or -v (verifying) options are set, the daemon does not
2736 disconnect from the controlling terminal. When running this way, it can be
2737 stopped by pressing ctrl-C.
2738
2739 By default, Exim listens for incoming connections to the standard SMTP port
2740 on all the host's running interfaces. However, it is possible to listen on
2741 other ports, on multiple ports, and only on specific interfaces. Chapter 13
2742 contains a description of the options that control this.
2743
2744 When a listening daemon is started without the use of -oX (that is, without
2745 overriding the normal configuration), it writes its process id to a file
2746 called exim-daemon.pid in Exim's spool directory. This location can be
2747 overridden by setting PID_FILE_PATH in Local/Makefile. The file is written
2748 while Exim is still running as root.
2749
2750 When -oX is used on the command line to start a listening daemon, the
2751 process id is not written to the normal pid file path. However, -oP can be
2752 used to specify a path on the command line if a pid file is required.
2753
2754 The SIGHUP signal can be used to cause the daemon to re-execute itself.
2755 This should be done whenever Exim's configuration file, or any file that is
2756 incorporated into it by means of the .include facility, is changed, and
2757 also whenever a new version of Exim is installed. It is not necessary to do
2758 this when other files that are referenced from the configuration (for
2759 example, alias files) are changed, because these are reread each time they
2760 are used.
2761
2762 -bdf
2763
2764 This option has the same effect as -bd except that it never disconnects
2765 from the controlling terminal, even when no debugging is specified.
2766
2767 -be
2768
2769 Run Exim in expansion testing mode. Exim discards its root privilege, to
2770 prevent ordinary users from using this mode to read otherwise inaccessible
2771 files. If no arguments are given, Exim runs interactively, prompting for
2772 lines of data. Otherwise, it processes each argument in turn.
2773
2774 If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load
2775 the libreadline library dynamically whenever the -be option is used without
2776 command line arguments. If successful, it uses the readline() function,
2777 which provides extensive line-editing facilities, for reading the test
2778 data. A line history is supported.
2779
2780 Long expansion expressions can be split over several lines by using
2781 backslash continuations. As in Exim's runtime configuration, white space at
2782 the start of continuation lines is ignored. Each argument or data line is
2783 passed through the string expansion mechanism, and the result is output.
2784 Variable values from the configuration file (for example, $qualify_domain)
2785 are available, but no message-specific values (such as $message_exim_id)
2786 are set, because no message is being processed (but see -bem and -Mset).
2787
2788 Note: If you use this mechanism to test lookups, and you change the data
2789 files or databases you are using, you must exit and restart Exim before
2790 trying the same lookup again. Otherwise, because each Exim process caches
2791 the results of lookups, you will just get the same result as before.
2792
2793 Macro processing is done on lines before string-expansion: new macros can
2794 be defined and macros will be expanded. Because macros in the config file
2795 are often used for secrets, those are only available to admin users.
2796
2797 -bem <filename>
2798
2799 This option operates like -be except that it must be followed by the name
2800 of a file. For example:
2801
2802 exim -bem /tmp/testmessage
2803
2804 The file is read as a message (as if receiving a locally-submitted non-SMTP
2805 message) before any of the test expansions are done. Thus, message-specific
2806 variables such as $message_size and $header_from: are available. However,
2807 no Received: header is added to the message. If the -t option is set,
2808 recipients are read from the headers in the normal way, and are shown in
2809 the $recipients variable. Note that recipients cannot be given on the
2810 command line, because further arguments are taken as strings to expand
2811 (just like -be).
2812
2813 -bF <filename>
2814
2815 This option is the same as -bf except that it assumes that the filter being
2816 tested is a system filter. The additional commands that are available only
2817 in system filters are recognized.
2818
2819 -bf <filename>
2820
2821 This option runs Exim in user filter testing mode; the file is the filter
2822 file to be tested, and a test message must be supplied on the standard
2823 input. If there are no message-dependent tests in the filter, an empty file
2824 can be supplied.
2825
2826 If you want to test a system filter file, use -bF instead of -bf. You can
2827 use both -bF and -bf on the same command, in order to test a system filter
2828 and a user filter in the same run. For example:
2829
2830 exim -bF /system/filter -bf /user/filter </test/message
2831
2832 This is helpful when the system filter adds header lines or sets filter
2833 variables that are used by the user filter.
2834
2835 If the test filter file does not begin with one of the special lines
2836
2837 # Exim filter
2838 # Sieve filter
2839
2840 it is taken to be a normal .forward file, and is tested for validity under
2841 that interpretation. See sections 22.4 to 22.6 for a description of the
2842 possible contents of non-filter redirection lists.
2843
2844 The result of an Exim command that uses -bf, provided no errors are
2845 detected, is a list of the actions that Exim would try to take if presented
2846 with the message for real. More details of filter testing are given in the
2847 separate document entitled Exim's interfaces to mail filtering.
2848
2849 When testing a filter file, the envelope sender can be set by the -f
2850 option, or by a "From " line at the start of the test message. Various
2851 parameters that would normally be taken from the envelope recipient address
2852 of the message can be set by means of additional command line options (see
2853 the next four options).
2854
2855 -bfd <domain>
2856
2857 This sets the domain of the recipient address when a filter file is being
2858 tested by means of the -bf option. The default is the value of
2859 $qualify_domain.
2860
2861 -bfl <local part>
2862
2863 This sets the local part of the recipient address when a filter file is
2864 being tested by means of the -bf option. The default is the username of the
2865 process that calls Exim. A local part should be specified with any prefix
2866 or suffix stripped, because that is how it appears to the filter when a
2867 message is actually being delivered.
2868
2869 -bfp <prefix>
2870
2871 This sets the prefix of the local part of the recipient address when a
2872 filter file is being tested by means of the -bf option. The default is an
2873 empty prefix.
2874
2875 -bfs <suffix>
2876
2877 This sets the suffix of the local part of the recipient address when a
2878 filter file is being tested by means of the -bf option. The default is an
2879 empty suffix.
2880
2881 -bh <IP address>
2882
2883 This option runs a fake SMTP session as if from the given IP address, using
2884 the standard input and output. The IP address may include a port number at
2885 the end, after a full stop. For example:
2886
2887 exim -bh 10.9.8.7.1234
2888 exim -bh fe80::a00:20ff:fe86:a061.5678
2889
2890 When an IPv6 address is given, it is converted into canonical form. In the
2891 case of the second example above, the value of $sender_host_address after
2892 conversion to the canonical form is
2893 "fe80:0000:0000:0a00:20ff:fe86:a061.5678".
2894
2895 Comments as to what is going on are written to the standard error file.
2896 These include lines beginning with "LOG" for anything that would have been
2897 logged. This facility is provided for testing configuration options for
2898 incoming messages, to make sure they implement the required policy. For
2899 example, you can test your relay controls using -bh.
2900
2901 Warning 1: You can test features of the configuration that rely on ident
2902 (RFC 1413) information by using the -oMt option. However, Exim cannot
2903 actually perform an ident callout when testing using -bh because there is
2904 no incoming SMTP connection.
2905
2906 Warning 2: Address verification callouts (see section 43.45) are also
2907 skipped when testing using -bh. If you want these callouts to occur, use
2908 -bhc instead.
2909
2910 Messages supplied during the testing session are discarded, and nothing is
2911 written to any of the real log files. There may be pauses when DNS (and
2912 other) lookups are taking place, and of course these may time out. The -oMi
2913 option can be used to specify a specific IP interface and port if this is
2914 important, and -oMaa and -oMai can be used to set parameters as if the SMTP
2915 session were authenticated.
2916
2917 The exim_checkaccess utility is a "packaged" version of -bh whose output
2918 just states whether a given recipient address from a given host is
2919 acceptable or not. See section 53.8.
2920
2921 Features such as authentication and encryption, where the client input is
2922 not plain text, cannot easily be tested with -bh. Instead, you should use a
2923 specialized SMTP test program such as swaks.
2924
2925 -bhc <IP address>
2926
2927 This option operates in the same way as -bh, except that address
2928 verification callouts are performed if required. This includes consulting
2929 and updating the callout cache database.
2930
2931 -bi
2932
2933 Sendmail interprets the -bi option as a request to rebuild its alias file.
2934 Exim does not have the concept of a single alias file, and so it cannot
2935 mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi
2936 option tend to appear in various scripts such as NIS make files, so the
2937 option must be recognized.
2938
2939 If -bi is encountered, the command specified by the bi_command
2940 configuration option is run, under the uid and gid of the caller of Exim.
2941 If the -oA option is used, its value is passed to the command as an
2942 argument. The command set by bi_command may not contain arguments. The
2943 command can use the exim_dbmbuild utility, or some other means, to rebuild
2944 alias files if this is required. If the bi_command option is not set,
2945 calling Exim with -bi is a no-op.
2946
2947 -bI:help
2948
2949 We shall provide various options starting "-bI:" for querying Exim for
2950 information. The output of many of these will be intended for machine
2951 consumption. This one is not. The -bI:help option asks Exim for a synopsis
2952 of supported options beginning "-bI:". Use of any of these options shall
2953 cause Exim to exit after producing the requested output.
2954
2955 -bI:dscp
2956
2957 This option causes Exim to emit an alphabetically sorted list of all
2958 recognised DSCP names.
2959
2960 -bI:sieve
2961
2962 This option causes Exim to emit an alphabetically sorted list of all
2963 supported Sieve protocol extensions on stdout, one per line. This is
2964 anticipated to be useful for ManageSieve (RFC 5804) implementations, in
2965 providing that protocol's "SIEVE" capability response line. As the precise
2966 list may depend upon compile-time build options, which this option will
2967 adapt to, this is the only way to guarantee a correct response.
2968
2969 -bm
2970
2971 This option runs an Exim receiving process that accepts an incoming,
2972 locally-generated message on the standard input. The recipients are given
2973 as the command arguments (except when -t is also present - see below). Each
2974 argument can be a comma-separated list of RFC 2822 addresses. This is the
2975 default option for selecting the overall action of an Exim call; it is
2976 assumed if no other conflicting option is present.
2977
2978 If any addresses in the message are unqualified (have no domain), they are
2979 qualified by the values of the qualify_domain or qualify_recipient options,
2980 as appropriate. The -bnq option (see below) provides a way of suppressing
2981 this for special cases.
2982
2983 Policy checks on the contents of local messages can be enforced by means of
2984 the non-SMTP ACL. See chapter 43 for details.
2985
2986 The return code is zero if the message is successfully accepted. Otherwise,
2987 the action is controlled by the -oex option setting - see below.
2988
2989 The format of the message must be as defined in RFC 2822, except that, for
2990 compatibility with Sendmail and Smail, a line in one of the forms
2991
2992 From sender Fri Jan 5 12:55 GMT 1997
2993 From sender Fri, 5 Jan 97 12:55:01
2994
2995 (with the weekday optional, and possibly with additional text after the
2996 date) is permitted to appear at the start of the message. There appears to
2997 be no authoritative specification of the format of this line. Exim
2998 recognizes it by matching against the regular expression defined by the
2999 uucp_from_pattern option, which can be changed if necessary.
3000
3001 The specified sender is treated as if it were given as the argument to the
3002 -f option, but if a -f option is also present, its argument is used in
3003 preference to the address taken from the message. The caller of Exim must
3004 be a trusted user for the sender of a message to be set in this way.
3005
3006 -bmalware <filename>
3007
3008 This debugging option causes Exim to scan the given file or directory
3009 (depending on the used scanner interface), using the malware scanning
3010 framework. The option of av_scanner influences this option, so if
3011 av_scanner's value is dependent upon an expansion then the expansion should
3012 have defaults which apply to this invocation. ACLs are not invoked, so if
3013 av_scanner references an ACL variable then that variable will never be
3014 populated and -bmalware will fail.
3015
3016 Exim will have changed working directory before resolving the filename, so
3017 using fully qualified pathnames is advisable. Exim will be running as the
3018 Exim user when it tries to open the file, rather than as the invoking user.
3019 This option requires admin privileges.
3020
3021 The -bmalware option will not be extended to be more generally useful,
3022 there are better tools for file-scanning. This option exists to help
3023 administrators verify their Exim and AV scanner configuration.
3024
3025 -bnq
3026
3027 By default, Exim automatically qualifies unqualified addresses (those
3028 without domains) that appear in messages that are submitted locally (that
3029 is, not over TCP/IP). This qualification applies both to addresses in
3030 envelopes, and addresses in header lines. Sender addresses are qualified
3031 using qualify_domain, and recipient addresses using qualify_recipient
3032 (which defaults to the value of qualify_domain).
3033
3034 Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is
3035 being used to re-submit messages that originally came from remote hosts
3036 after content scanning, you probably do not want to qualify unqualified
3037 addresses in header lines. (Such lines will be present only if you have not
3038 enabled a header syntax check in the appropriate ACL.)
3039
3040 The -bnq option suppresses all qualification of unqualified addresses in
3041 messages that originate on the local host. When this is used, unqualified
3042 addresses in the envelope provoke errors (causing message rejection) and
3043 unqualified addresses in header lines are left alone.
3044
3045 -bP
3046
3047 If this option is given with no arguments, it causes the values of all
3048 Exim's main configuration options to be written to the standard output. The
3049 values of one or more specific options can be requested by giving their
3050 names as arguments, for example:
3051
3052 exim -bP qualify_domain hold_domains
3053
3054 However, any option setting that is preceded by the word "hide" in the
3055 configuration file is not shown in full, except to an admin user. For other
3056 users, the output is as in this example:
3057
3058 mysql_servers = <value not displayable>
3059
3060 If config is given as an argument, the config is output, as it was parsed,
3061 any include file resolved, any comment removed.
3062
3063 If config_file is given as an argument, the name of the runtime
3064 configuration file is output. (configure_file works too, for backward
3065 compatibility.) If a list of configuration files was supplied, the value
3066 that is output here is the name of the file that was actually used.
3067
3068 If the -n flag is given, then for most modes of -bP operation the name will
3069 not be output.
3070
3071 If log_file_path or pid_file_path are given, the names of the directories
3072 where log files and daemon pid files are written are output, respectively.
3073 If these values are unset, log files are written in a sub-directory of the
3074 spool directory called log, and the pid file is written directly into the
3075 spool directory.
3076
3077 If -bP is followed by a name preceded by "+", for example,
3078
3079 exim -bP +local_domains
3080
3081 it searches for a matching named list of any type (domain, host, address,
3082 or local part) and outputs what it finds.
3083
3084 If one of the words router, transport, or authenticator is given, followed
3085 by the name of an appropriate driver instance, the option settings for that
3086 driver are output. For example:
3087
3088 exim -bP transport local_delivery
3089
3090 The generic driver options are output first, followed by the driver's
3091 private options. A list of the names of drivers of a particular type can be
3092 obtained by using one of the words router_list, transport_list, or
3093 authenticator_list, and a complete list of all drivers with their option
3094 settings can be obtained by using routers, transports, or authenticators.
3095
3096 If environment is given as an argument, the set of environment variables is
3097 output, line by line. Using the -n flag suppresses the value of the
3098 variables.
3099
3100 If invoked by an admin user, then macro, macro_list and macros are
3101 available, similarly to the drivers. Because macros are sometimes used for
3102 storing passwords, this option is restricted. The output format is one item
3103 per line. For the "-bP macro <name>" form, if no such macro is found the
3104 exit status will be nonzero.
3105
3106 -bp
3107
3108 This option requests a listing of the contents of the mail queue on the
3109 standard output. If the -bp option is followed by a list of message ids,
3110 just those messages are listed. By default, this option can be used only by
3111 an admin user. However, the queue_list_requires_admin option can be set
3112 false to allow any user to see the queue.
3113
3114 Each message in the queue is displayed as in the following example:
3115
3116 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
3117 red.king@looking-glass.fict.example
3118 <other addresses>
3119
3120 The first line contains the length of time the message has been in the
3121 queue (in this case 25 minutes), the size of the message (2.9K), the unique
3122 local identifier for the message, and the message sender, as contained in
3123 the envelope. For bounce messages, the sender address is empty, and appears
3124 as "<>". If the message was submitted locally by an untrusted user who
3125 overrode the default sender address, the user's login name is shown in
3126 parentheses before the sender address.
3127
3128 If the message is frozen (attempts to deliver it are suspended) then the
3129 text "*** frozen ***" is displayed at the end of this line.
3130
3131 The recipients of the message (taken from the envelope, not the headers)
3132 are displayed on subsequent lines. Those addresses to which the message has
3133 already been delivered are marked with the letter D. If an original address
3134 gets expanded into several addresses via an alias or forward file, the
3135 original is displayed with a D only when deliveries for all of its child
3136 addresses are complete.
3137
3138 -bpa
3139
3140 This option operates like -bp, but in addition it shows delivered addresses
3141 that were generated from the original top level address(es) in each message
3142 by alias or forwarding operations. These addresses are flagged with "+D"
3143 instead of just "D".
3144
3145 -bpc
3146
3147 This option counts the number of messages in the queue, and writes the
3148 total to the standard output. It is restricted to admin users, unless
3149 queue_list_requires_admin is set false.
3150
3151 -bpr
3152
3153 This option operates like -bp, but the output is not sorted into
3154 chronological order of message arrival. This can speed it up when there are
3155 lots of messages in the queue, and is particularly useful if the output is
3156 going to be post-processed in a way that doesn't need the sorting.
3157
3158 -bpra
3159
3160 This option is a combination of -bpr and -bpa.
3161
3162 -bpru
3163
3164 This option is a combination of -bpr and -bpu.
3165
3166 -bpu
3167
3168 This option operates like -bp but shows only undelivered top-level
3169 addresses for each message displayed. Addresses generated by aliasing or
3170 forwarding are not shown, unless the message was deferred after processing
3171 by a router with the one_time option set.
3172
3173 -brt
3174
3175 This option is for testing retry rules, and it must be followed by up to
3176 three arguments. It causes Exim to look for a retry rule that matches the
3177 values and to write it to the standard output. For example:
3178
3179 exim -brt bach.comp.mus.example
3180 Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
3181
3182 See chapter 32 for a description of Exim's retry rules. The first argument,
3183 which is required, can be a complete address in the form local_part@domain,
3184 or it can be just a domain name. If the second argument contains a dot, it
3185 is interpreted as an optional second domain name; if no retry rule is found
3186 for the first argument, the second is tried. This ties in with Exim's
3187 behaviour when looking for retry rules for remote hosts - if no rule is
3188 found that matches the host, one that matches the mail domain is sought.
3189 Finally, an argument that is the name of a specific delivery error, as used
3190 in setting up retry rules, can be given. For example:
3191
3192 exim -brt haydn.comp.mus.example quota_3d
3193 Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m
3194
3195 -brw
3196
3197 This option is for testing address rewriting rules, and it must be followed
3198 by a single argument, consisting of either a local part without a domain,
3199 or a complete address with a fully qualified domain. Exim outputs how this
3200 address would be rewritten for each possible place it might appear. See
3201 chapter 31 for further details.
3202
3203 -bS
3204
3205 This option is used for batched SMTP input, which is an alternative
3206 interface for non-interactive local message submission. A number of
3207 messages can be submitted in a single run. However, despite its name, this
3208 is not really SMTP input. Exim reads each message's envelope from SMTP
3209 commands on the standard input, but generates no responses. If the caller
3210 is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL
3211 commands are believed; otherwise the sender is always the caller of Exim.
3212
3213 The message itself is read from the standard input, in SMTP format (leading
3214 dots doubled), terminated by a line containing just a single dot. An error
3215 is provoked if the terminating dot is missing. A further message may then
3216 follow.
3217
3218 As for other local message submissions, the contents of incoming batch SMTP
3219 messages can be checked using the non-SMTP ACL (see chapter 43).
3220 Unqualified addresses are automatically qualified using qualify_domain and
3221 qualify_recipient, as appropriate, unless the -bnq option is used.
3222
3223 Some other SMTP commands are recognized in the input. HELO and EHLO act as
3224 RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest
3225 of the standard input.
3226
3227 If any error is encountered, reports are written to the standard output and
3228 error streams, and Exim gives up immediately. The return code is 0 if no
3229 error was detected; it is 1 if one or more messages were accepted before
3230 the error was detected; otherwise it is 2.
3231
3232 More details of input using batched SMTP are given in section 48.11.
3233
3234 -bs
3235
3236 This option causes Exim to accept one or more messages by reading SMTP
3237 commands on the standard input, and producing SMTP replies on the standard
3238 output. SMTP policy controls, as defined in ACLs (see chapter 43) are
3239 applied. Some user agents use this interface as a way of passing
3240 locally-generated messages to the MTA.
3241
3242 In this usage, if the caller of Exim is trusted, or untrusted_set_sender is
3243 set, the senders of messages are taken from the SMTP MAIL commands.
3244 Otherwise the content of these commands is ignored and the sender is set up
3245 as the calling user. Unqualified addresses are automatically qualified
3246 using qualify_domain and qualify_recipient, as appropriate, unless the -bnq
3247 option is used.
3248
3249 The -bs option is also used to run Exim from inetd, as an alternative to
3250 using a listening daemon. Exim can distinguish the two cases by checking
3251 whether the standard input is a TCP/IP socket. When Exim is called from
3252 inetd, the source of the mail is assumed to be remote, and the comments
3253 above concerning senders and qualification do not apply. In this situation,
3254 Exim behaves in exactly the same way as it does when receiving a message
3255 via the listening daemon.
3256
3257 -bt
3258
3259 This option runs Exim in address testing mode, in which each argument is
3260 taken as a recipient address to be tested for deliverability. The results
3261 are written to the standard output. If a test fails, and the caller is not
3262 an admin user, no details of the failure are output, because these might
3263 contain sensitive information such as usernames and passwords for database
3264 lookups.
3265
3266 If no arguments are given, Exim runs in an interactive manner, prompting
3267 with a right angle bracket for addresses to be tested.
3268
3269 Unlike the -be test option, you cannot arrange for Exim to use the readline
3270 () function, because it is running as root and there are security issues.
3271
3272 Each address is handled as if it were the recipient address of a message
3273 (compare the -bv option). It is passed to the routers and the result is
3274 written to the standard output. However, any router that has
3275 no_address_test set is bypassed. This can make -bt easier to use for
3276 genuine routing tests if your first router passes everything to a scanner
3277 program.
3278
3279 The return code is 2 if any address failed outright; it is 1 if no address
3280 failed outright but at least one could not be resolved for some reason.
3281 Return code 0 is given only when all addresses succeed.
3282
3283 Note: When actually delivering a message, Exim removes duplicate recipient
3284 addresses after routing is complete, so that only one delivery takes place.
3285 This does not happen when testing with -bt; the full results of routing are
3286 always shown.
3287
3288 Warning: -bt can only do relatively simple testing. If any of the routers
3289 in the configuration makes any tests on the sender address of a message,
3290 you can use the -f option to set an appropriate sender when running -bt
3291 tests. Without it, the sender is assumed to be the calling user at the
3292 default qualifying domain. However, if you have set up (for example)
3293 routers whose behaviour depends on the contents of an incoming message, you
3294 cannot test those conditions using -bt. The -N option provides a possible
3295 way of doing such tests.
3296
3297 -bV
3298
3299 This option causes Exim to write the current version number, compilation
3300 number, and compilation date of the exim binary to the standard output. It
3301 also lists the DBM library that is being used, the optional modules (such
3302 as specific lookup types), the drivers that are included in the binary, and
3303 the name of the runtime configuration file that is in use.
3304
3305 As part of its operation, -bV causes Exim to read and syntax check its
3306 configuration file. However, this is a static check only. It cannot check
3307 values that are to be expanded. For example, although a misspelt ACL verb
3308 is detected, an error in the verb's arguments is not. You cannot rely on
3309 -bV alone to discover (for example) all the typos in the configuration;
3310 some realistic testing is needed. The -bh and -N options provide more
3311 dynamic testing facilities.
3312
3313 -bv
3314
3315 This option runs Exim in address verification mode, in which each argument
3316 is taken as a recipient address to be verified by the routers. (This does
3317 not involve any verification callouts). During normal operation,
3318 verification happens mostly as a consequence processing a verify condition
3319 in an ACL (see chapter 43). If you want to test an entire ACL, possibly
3320 including callouts, see the -bh and -bhc options.
3321
3322 If verification fails, and the caller is not an admin user, no details of
3323 the failure are output, because these might contain sensitive information
3324 such as usernames and passwords for database lookups.
3325
3326 If no arguments are given, Exim runs in an interactive manner, prompting
3327 with a right angle bracket for addresses to be verified.
3328
3329 Unlike the -be test option, you cannot arrange for Exim to use the readline
3330 () function, because it is running as exim and there are security issues.
3331
3332 Verification differs from address testing (the -bt option) in that routers
3333 that have no_verify set are skipped, and if the address is accepted by a
3334 router that has fail_verify set, verification fails. The address is
3335 verified as a recipient if -bv is used; to test verification for a sender
3336 address, -bvs should be used.
3337
3338 If the -v option is not set, the output consists of a single line for each
3339 address, stating whether it was verified or not, and giving a reason in the
3340 latter case. Without -v, generating more than one address by redirection
3341 causes verification to end successfully, without considering the generated
3342 addresses. However, if just one address is generated, processing continues,
3343 and the generated address must verify successfully for the overall
3344 verification to succeed.
3345
3346 When -v is set, more details are given of how the address has been handled,
3347 and in the case of address redirection, all the generated addresses are
3348 also considered. Verification may succeed for some and fail for others.
3349
3350 The return code is 2 if any address failed outright; it is 1 if no address
3351 failed outright but at least one could not be resolved for some reason.
3352 Return code 0 is given only when all addresses succeed.
3353
3354 If any of the routers in the configuration makes any tests on the sender
3355 address of a message, you should use the -f option to set an appropriate
3356 sender when running -bv tests. Without it, the sender is assumed to be the
3357 calling user at the default qualifying domain.
3358
3359 -bvs
3360
3361 This option acts like -bv, but verifies the address as a sender rather than
3362 a recipient address. This affects any rewriting and qualification that
3363 might happen.
3364
3365 -bw
3366
3367 This option runs Exim as a daemon, awaiting incoming SMTP connections,
3368 similarly to the -bd option. All port specifications on the command-line
3369 and in the configuration file are ignored. Queue-running may not be
3370 specified.
3371
3372 In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
3373 listening for connections. This permits the system to start up and have
3374 inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
3375 each port only when the first connection is received.
3376
3377 If the option is given as -bw<time> then the time is a timeout, after which
3378 the daemon will exit, which should cause inetd to listen once more.
3379
3380 -C <filelist>
3381
3382 This option causes Exim to find the runtime configuration file from the
3383 given list instead of from the list specified by the CONFIGURE_FILE
3384 compile-time setting. Usually, the list will consist of just a single
3385 filename, but it can be a colon-separated list of names. In this case, the
3386 first file that exists is used. Failure to open an existing file stops Exim
3387 from proceeding any further along the list, and an error is generated.
3388
3389 When this option is used by a caller other than root, and the list is
3390 different from the compiled-in list, Exim gives up its root privilege
3391 immediately, and runs with the real and effective uid and gid set to those
3392 of the caller. However, if a TRUSTED_CONFIG_LIST file is defined in Local/
3393 Makefile, that file contains a list of full pathnames, one per line, for
3394 configuration files which are trusted. Root privilege is retained for any
3395 configuration file so listed, as long as the caller is the Exim user (or
3396 the user specified in the CONFIGURE_OWNER option, if any), and as long as
3397 the configuration file is not writeable by inappropriate users or groups.
3398
3399 Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
3400 configuration using -C right through message reception and delivery, even
3401 if the caller is root. The reception works, but by that time, Exim is
3402 running as the Exim user, so when it re-executes to regain privilege for
3403 the delivery, the use of -C causes privilege to be lost. However, root can
3404 test reception and delivery using two separate commands (one to put a
3405 message in the queue, using -odq, and another to do the delivery, using -M
3406 ).
3407
3408 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix
3409 string with which any file named in a -C command line option must start. In
3410 addition, the filename must not contain the sequence "/../". However, if
3411 the value of the -C option is identical to the value of CONFIGURE_FILE in
3412 Local/Makefile, Exim ignores -C and proceeds as usual. There is no default
3413 setting for ALT_CONFIG_PREFIX; when it is unset, any filename can be used
3414 with -C.
3415
3416 ALT_CONFIG_PREFIX can be used to confine alternative configuration files to
3417 a directory to which only root has access. This prevents someone who has
3418 broken into the Exim account from running a privileged Exim with an
3419 arbitrary configuration file.
3420
3421 The -C facility is useful for ensuring that configuration files are
3422 syntactically correct, but cannot be used for test deliveries, unless the
3423 caller is privileged, or unless it is an exotic configuration that does not
3424 require privilege. No check is made on the owner or group of the files
3425 specified by this option.
3426
3427 -D<macro>=<value>
3428
3429 This option can be used to override macro definitions in the configuration
3430 file (see section 6.4). However, like -C, if it is used by an unprivileged
3431 caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION
3432 is defined in Local/Makefile, the use of -D is completely disabled, and its
3433 use causes an immediate error exit.
3434
3435 If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a
3436 colon-separated list of macros which are considered safe and, if -D only
3437 supplies macros from this list, and the values are acceptable, then Exim
3438 will not give up root privilege if the caller is root, the Exim run-time
3439 user, or the CONFIGURE_OWNER, if set. This is a transition mechanism and is
3440 expected to be removed in the future. Acceptable values for the macros
3441 satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
3442
3443 The entire option (including equals sign if present) must all be within one
3444 command line item. -D can be used to set the value of a macro to the empty
3445 string, in which case the equals sign is optional. These two commands are
3446 synonymous:
3447
3448 exim -DABC ...
3449 exim -DABC= ...
3450
3451 To include spaces in a macro definition item, quotes must be used. If you
3452 use quotes, spaces are permitted around the macro name and the equals sign.
3453 For example:
3454
3455 exim '-D ABC = something' ...
3456
3457 -D may be repeated up to 10 times on a command line. Only macro names up to
3458 22 letters long can be set.
3459
3460 -d<debug options>
3461
3462 This option causes debugging information to be written to the standard
3463 error stream. It is restricted to admin users because debugging output may
3464 show database queries that contain password information. Also, the details
3465 of users' filter files should be protected. If a non-admin user uses -d,
3466 Exim writes an error message to the standard error stream and exits with a
3467 non-zero return code.
3468
3469 When -d is used, -v is assumed. If -d is given on its own, a lot of
3470 standard debugging data is output. This can be reduced, or increased to
3471 include some more rarely needed information, by directly following -d with
3472 a string made up of names preceded by plus or minus characters. These add
3473 or remove sets of debugging data, respectively. For example, -d+filter adds
3474 filter debugging, whereas -d-all+filter selects only filter debugging. Note
3475 that no spaces are allowed in the debug setting. The available debugging
3476 categories are:
3477
3478 acl ACL interpretation
3479 auth authenticators
3480 deliver general delivery logic
3481 dns DNS lookups (see also resolver)
3482 dnsbl DNS black list (aka RBL) code
3483 exec arguments for execv() calls
3484 expand detailed debugging for string expansions
3485 filter filter handling
3486 hints_lookup hints data lookups
3487 host_lookup all types of name-to-IP address handling
3488 ident ident lookup
3489 interface lists of local interfaces
3490 lists matching things in lists
3491 load system load checks
3492 local_scan can be used by local_scan() (see chapter 45)
3493 lookup general lookup code and all lookups
3494 memory memory handling
3495 noutf8 modifier: avoid UTF-8 line-drawing
3496 pid modifier: add pid to debug output lines
3497 process_info setting info for the process log
3498 queue_run queue runs
3499 receive general message reception logic
3500 resolver turn on the DNS resolver's debugging output
3501 retry retry handling
3502 rewrite address rewriting
3503 route address routing
3504 timestamp modifier: add timestamp to debug output lines
3505 tls TLS logic
3506 transport transports
3507 uid changes of uid/gid and looking up uid/gid
3508 verify address verification logic
3509 all almost all of the above (see below), and also -v
3510
3511 The "all" option excludes "memory" when used as "+all", but includes it for
3512 "-all". The reason for this is that "+all" is something that people tend to
3513 use when generating debug output for Exim maintainers. If "+memory" is
3514 included, an awful lot of output that is very rarely of interest is
3515 generated, so it now has to be explicitly requested. However, "-all" does
3516 turn everything off.
3517
3518 The "resolver" option produces output only if the DNS resolver was compiled
3519 with DEBUG enabled. This is not the case in some operating systems. Also,
3520 unfortunately, debugging output from the DNS resolver is written to stdout
3521 rather than stderr.
3522
3523 The default (-d with no argument) omits "expand", "filter", "interface",
3524 "load", "memory", "pid", "resolver", and "timestamp". However, the "pid"
3525 selector is forced when debugging is turned on for a daemon, which then
3526 passes it on to any re-executed Exims. Exim also automatically adds the pid
3527 to debug lines when several remote deliveries are run in parallel.
3528
3529 The "timestamp" selector causes the current time to be inserted at the
3530 start of all debug output lines. This can be useful when trying to track
3531 down delays in processing.
3532
3533 The "noutf8" selector disables the use of UTF-8 line-drawing characters to
3534 group related information. When disabled. ascii-art is used instead. Using
3535 the "+all" option does not set this modifier,
3536
3537 If the debug_print option is set in any driver, it produces output whenever
3538 any debugging is selected, or if -v is used.
3539
3540 -dd<debug options>
3541
3542 This option behaves exactly like -d except when used on a command that
3543 starts a daemon process. In that case, debugging is turned off for the
3544 subprocesses that the daemon creates. Thus, it is useful for monitoring the
3545 behaviour of the daemon without creating as much output as full debugging
3546 does.
3547
3548 -dropcr
3549
3550 This is an obsolete option that is now a no-op. It used to affect the way
3551 Exim handled CR and LF characters in incoming messages. What happens now is
3552 described in section 47.2.
3553
3554 -E
3555
3556 This option specifies that an incoming message is a locally-generated
3557 delivery failure report. It is used internally by Exim when handling
3558 delivery failures and is not intended for external use. Its only effect is
3559 to stop Exim generating certain messages to the postmaster, as otherwise
3560 message cascades could occur in some situations. As part of the same
3561 option, a message id may follow the characters -E. If it does, the log
3562 entry for the receipt of the new message contains the id, following "R=",
3563 as a cross-reference.
3564
3565 -ex
3566
3567 There are a number of Sendmail options starting with -oe which seem to be
3568 called by various programs without the leading o in the option. For
3569 example, the vacation program uses -eq. Exim treats all options of the form
3570 -ex as synonymous with the corresponding -oex options.
3571
3572 -F <string>
3573
3574 This option sets the sender's full name for use when a locally-generated
3575 message is being accepted. In the absence of this option, the user's gecos
3576 entry from the password data is used. As users are generally permitted to
3577 alter their gecos entries, no security considerations are involved. White
3578 space between -F and the <string> is optional.
3579
3580 -f <address>
3581
3582 This option sets the address of the envelope sender of a locally-generated
3583 message (also known as the return path). The option can normally be used
3584 only by a trusted user, but untrusted_set_sender can be set to allow
3585 untrusted users to use it.
3586
3587 Processes running as root or the Exim user are always trusted. Other
3588 trusted users are defined by the trusted_users or trusted_groups options.
3589 In the absence of -f, or if the caller is not trusted, the sender of a
3590 local message is set to the caller's login name at the default qualify
3591 domain.
3592
3593 There is one exception to the restriction on the use of -f: an empty sender
3594 can be specified by any user, trusted or not, to create a message that can
3595 never provoke a bounce. An empty sender can be specified either as an empty
3596 string, or as a pair of angle brackets with nothing between them, as in
3597 these examples of shell commands:
3598
3599 exim -f '<>' user@domain
3600 exim -f "" user@domain
3601
3602 In addition, the use of -f is not restricted when testing a filter file
3603 with -bf or when testing or verifying addresses using the -bt or -bv
3604 options.
3605
3606 Allowing untrusted users to change the sender address does not of itself
3607 make it possible to send anonymous mail. Exim still checks that the From:
3608 header refers to the local user, and if it does not, it adds a Sender:
3609 header, though this can be overridden by setting no_local_from_check.
3610
3611 White space between -f and the <address> is optional (that is, they can be
3612 given as two arguments or one combined argument). The sender of a
3613 locally-generated message can also be set (when permitted) by an initial
3614 "From " line in the message - see the description of -bm above - but if -f
3615 is also present, it overrides "From ".
3616
3617 -G
3618
3619 This option is equivalent to an ACL applying:
3620
3621 control = suppress_local_fixups
3622
3623 for every message received. Note that Sendmail will complain about such bad
3624 formatting, where Exim silently just does not fix it up. This may change in
3625 future.
3626
3627 As this affects audit information, the caller must be a trusted user to use
3628 this option.
3629
3630 -h <number>
3631
3632 This option is accepted for compatibility with Sendmail, but has no effect.
3633 (In Sendmail it overrides the "hop count" obtained by counting Received:
3634 headers.)
3635
3636 -i
3637
3638 This option, which has the same effect as -oi, specifies that a dot on a
3639 line by itself should not terminate an incoming, non-SMTP message. I can
3640 find no documentation for this option in Solaris 2.4 Sendmail, but the
3641 mailx command in Solaris 2.4 uses it. See also -ti.
3642
3643 -L <tag>
3644
3645 This option is equivalent to setting syslog_processname in the config file
3646 and setting log_file_path to "syslog". Its use is restricted to
3647 administrators. The configuration file has to be read and parsed, to
3648 determine access rights, before this is set and takes effect, so early
3649 configuration file errors will not honour this flag.
3650
3651 The tag should not be longer than 32 characters.
3652
3653 -M <message id> <message id> ...
3654
3655 This option requests Exim to run a delivery attempt on each message in
3656 turn. If any of the messages are frozen, they are automatically thawed
3657 before the delivery attempt. The settings of queue_domains,
3658 queue_smtp_domains, and hold_domains are ignored.
3659
3660 Retry hints for any of the addresses are overridden - Exim tries to deliver
3661 even if the normal retry time has not yet been reached. This option
3662 requires the caller to be an admin user. However, there is an option called
3663 prod_requires_admin which can be set false to relax this restriction (and
3664 also the same requirement for the -q, -R, and -S options).
3665
3666 The deliveries happen synchronously, that is, the original Exim process
3667 does not terminate until all the delivery attempts have finished. No output
3668 is produced unless there is a serious error. If you want to see what is
3669 happening, use the -v option as well, or inspect Exim's main log.
3670
3671 -Mar <message id> <address> <address> ...
3672
3673 This option requests Exim to add the addresses to the list of recipients of
3674 the message ("ar" for "add recipients"). The first argument must be a
3675 message id, and the remaining ones must be email addresses. However, if the
3676 message is active (in the middle of a delivery attempt), it is not altered.
3677 This option can be used only by an admin user.
3678
3679 -MC <transport> <hostname> <sequence number> <message id>
3680
3681 This option is not intended for use by external callers. It is used
3682 internally by Exim to invoke another instance of itself to deliver a
3683 waiting message using an existing SMTP connection, which is passed as the
3684 standard input. Details are given in chapter 48. This must be the final
3685 option, and the caller must be root or the Exim user in order to use it.
3686
3687 -MCA
3688
3689 This option is not intended for use by external callers. It is used
3690 internally by Exim in conjunction with the -MC option. It signifies that
3691 the connection to the remote host has been authenticated.
3692
3693 -MCD
3694
3695 This option is not intended for use by external callers. It is used
3696 internally by Exim in conjunction with the -MC option. It signifies that
3697 the remote host supports the ESMTP DSN extension.
3698
3699 -MCG <queue name>
3700
3701 This option is not intended for use by external callers. It is used
3702 internally by Exim in conjunction with the -MC option. It signifies that an
3703 alternate queue is used, named by the following argument.
3704
3705 -MCK
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. It signifies that a
3709 remote host supports the ESMTP CHUNKING extension.
3710
3711 -MCP
3712
3713 This option is not intended for use by external callers. It is used
3714 internally by Exim in conjunction with the -MC option. It signifies that
3715 the server to which Exim is connected supports pipelining.
3716
3717 -MCQ <process id> <pipe fd>
3718
3719 This option is not intended for use by external callers. It is used
3720 internally by Exim in conjunction with the -MC option when the original
3721 delivery was started by a queue runner. It passes on the process id of the
3722 queue runner, together with the file descriptor number of an open pipe.
3723 Closure of the pipe signals the final completion of the sequence of
3724 processes that are passing messages through the same SMTP connection.
3725
3726 -MCS
3727
3728 This option is not intended for use by external callers. It is used
3729 internally by Exim in conjunction with the -MC option, and passes on the
3730 fact that the SMTP SIZE option should be used on messages delivered down
3731 the existing connection.
3732
3733 -MCT
3734
3735 This option is not intended for use by external callers. It is used
3736 internally by Exim in conjunction with the -MC option, and passes on the
3737 fact that the host to which Exim is connected supports TLS encryption.
3738
3739 -MCt <IP address> <port> <cipher>
3740
3741 This option is not intended for use by external callers. It is used
3742 internally by Exim in conjunction with the -MC option, and passes on the
3743 fact that the connection is being proxied by a parent process for handling
3744 TLS encryption. The arguments give the local address and port being
3745 proxied, and the TLS cipher.
3746
3747 -Mc <message id> <message id> ...
3748
3749 This option requests Exim to run a delivery attempt on each message, in
3750 turn, but unlike the -M option, it does check for retry hints, and respects
3751 any that are found. This option is not very useful to external callers. It
3752 is provided mainly for internal use by Exim when it needs to re-invoke
3753 itself in order to regain root privilege for a delivery (see chapter 55).
3754 However, -Mc can be useful when testing, in order to run a delivery that
3755 respects retry times and other options such as hold_domains that are
3756 overridden when -M is used. Such a delivery does not count as a queue run.
3757 If you want to run a specific delivery as if in a queue run, you should use
3758 -q with a message id argument. A distinction between queue run deliveries
3759 and other deliveries is made in one or two places.
3760
3761 -Mes <message id> <address>
3762
3763 This option requests Exim to change the sender address in the message to
3764 the given address, which must be a fully qualified address or "<>" ("es"
3765 for "edit sender"). There must be exactly two arguments. The first argument
3766 must be a message id, and the second one an email address. However, if the
3767 message is active (in the middle of a delivery attempt), its status is not
3768 altered. This option can be used only by an admin user.
3769
3770 -Mf <message id> <message id> ...
3771
3772 This option requests Exim to mark each listed message as "frozen". This
3773 prevents any delivery attempts taking place until the message is "thawed",
3774 either manually or as a result of the auto_thaw configuration option.
3775 However, if any of the messages are active (in the middle of a delivery
3776 attempt), their status is not altered. This option can be used only by an
3777 admin user.
3778
3779 -Mg <message id> <message id> ...
3780
3781 This option requests Exim to give up trying to deliver the listed messages,
3782 including any that are frozen. However, if any of the messages are active,
3783 their status is not altered. For non-bounce messages, a delivery error
3784 message is sent to the sender, containing the text "cancelled by
3785 administrator". Bounce messages are just discarded. This option can be used
3786 only by an admin user.
3787
3788 -Mmad <message id> <message id> ...
3789
3790 This option requests Exim to mark all the recipient addresses in the
3791 messages as already delivered ("mad" for "mark all delivered"). However, if
3792 any message is active (in the middle of a delivery attempt), its status is
3793 not altered. This option can be used only by an admin user.
3794
3795 -Mmd <message id> <address> <address> ...
3796
3797 This option requests Exim to mark the given addresses as already delivered
3798 ("md" for "mark delivered"). The first argument must be a message id, and
3799 the remaining ones must be email addresses. These are matched to recipient
3800 addresses in the message in a case-sensitive manner. If the message is
3801 active (in the middle of a delivery attempt), its status is not altered.
3802 This option can be used only by an admin user.
3803
3804 -Mrm <message id> <message id> ...
3805
3806 This option requests Exim to remove the given messages from the queue. No
3807 bounce messages are sent; each message is simply forgotten. However, if any
3808 of the messages are active, their status is not altered. This option can be
3809 used only by an admin user or by the user who originally caused the message
3810 to be placed in the queue.
3811
3812 -Mset <message id>
3813
3814 This option is useful only in conjunction with -be (that is, when testing
3815 string expansions). Exim loads the given message from its spool before
3816 doing the test expansions, thus setting message-specific variables such as
3817 $message_size and the header variables. The $recipients variable is made
3818 available. This feature is provided to make it easier to test expansions
3819 that make use of these variables. However, this option can be used only by
3820 an admin user. See also -bem.
3821
3822 -Mt <message id> <message id> ...
3823
3824 This option requests Exim to "thaw" any of the listed messages that are
3825 "frozen", so that delivery attempts can resume. However, if any of the
3826 messages are active, their status is not altered. This option can be used
3827 only by an admin user.
3828
3829 -Mvb <message id>
3830
3831 This option causes the contents of the message body (-D) spool file to be
3832 written to the standard output. This option can be used only by an admin
3833 user.
3834
3835 -Mvc <message id>
3836
3837 This option causes a copy of the complete message (header lines plus body)
3838 to be written to the standard output in RFC 2822 format. This option can be
3839 used only by an admin user.
3840
3841 -Mvh <message id>
3842
3843 This option causes the contents of the message headers (-H) spool file to
3844 be written to the standard output. This option can be used only by an admin
3845 user.
3846
3847 -Mvl <message id>
3848
3849 This option causes the contents of the message log spool file to be written
3850 to the standard output. This option can be used only by an admin user.
3851
3852 -m
3853
3854 This is apparently a synonym for -om that is accepted by Sendmail, so Exim
3855 treats it that way too.
3856
3857 -N
3858
3859 This is a debugging option that inhibits delivery of a message at the
3860 transport level. It implies -v. Exim goes through many of the motions of
3861 delivery - it just doesn't actually transport the message, but instead
3862 behaves as if it had successfully done so. However, it does not make any
3863 updates to the retry database, and the log entries for deliveries are
3864 flagged with "*>" rather than "=>".
3865
3866 Because -N discards any message to which it applies, only root or the Exim
3867 user are allowed to use it with -bd, -q, -R or -M. In other words, an
3868 ordinary user can use it only when supplying an incoming message to which
3869 it will apply. Although transportation never fails when -N is set, an
3870 address may be deferred because of a configuration problem on a transport,
3871 or a routing problem. Once -N has been used for a delivery attempt, it
3872 sticks to the message, and applies to any subsequent delivery attempts that
3873 may happen for that message.
3874
3875 -n
3876
3877 This option is interpreted by Sendmail to mean "no aliasing". For normal
3878 modes of operation, it is ignored by Exim. When combined with -bP it makes
3879 the output more terse (suppresses option names, environment values and
3880 config pretty printing).
3881
3882 -O <data>
3883
3884 This option is interpreted by Sendmail to mean "set option". It is ignored
3885 by Exim.
3886
3887 -oA <file name>
3888
3889 This option is used by Sendmail in conjunction with -bi to specify an
3890 alternative alias filename. Exim handles -bi differently; see the
3891 description above.
3892
3893 -oB <n>
3894
3895 This is a debugging option which limits the maximum number of messages that
3896 can be delivered down one SMTP connection, overriding the value set in any
3897 smtp transport. If <n> is omitted, the limit is set to 1.
3898
3899 -odb
3900
3901 This option applies to all modes in which Exim accepts incoming messages,
3902 including the listening daemon. It requests "background" delivery of such
3903 messages, which means that the accepting process automatically starts a
3904 delivery process for each message received, but does not wait for the
3905 delivery processes to finish.
3906
3907 When all the messages have been received, the reception process exits,
3908 leaving the delivery processes to finish in their own time. The standard
3909 output and error streams are closed at the start of each delivery process.
3910 This is the default action if none of the -od options are present.
3911
3912 If one of the queueing options in the configuration file (queue_only or
3913 queue_only_file, for example) is in effect, -odb overrides it if
3914 queue_only_override is set true, which is the default setting. If
3915 queue_only_override is set false, -odb has no effect.
3916
3917 -odf
3918
3919 This option requests "foreground" (synchronous) delivery when Exim has
3920 accepted a locally-generated message. (For the daemon it is exactly the
3921 same as -odb.) A delivery process is automatically started to deliver the
3922 message, and Exim waits for it to complete before proceeding.
3923
3924 The original Exim reception process does not finish until the delivery
3925 process for the final message has ended. The standard error stream is left
3926 open during deliveries.
3927
3928 However, like -odb, this option has no effect if queue_only_override is
3929 false and one of the queueing options in the configuration file is in
3930 effect.
3931
3932 If there is a temporary delivery error during foreground delivery, the
3933 message is left in the queue for later delivery, and the original reception
3934 process exits. See chapter 51 for a way of setting up a restricted
3935 configuration that never queues messages.
3936
3937 -odi
3938
3939 This option is synonymous with -odf. It is provided for compatibility with
3940 Sendmail.
3941
3942 -odq
3943
3944 This option applies to all modes in which Exim accepts incoming messages,
3945 including the listening daemon. It specifies that the accepting process
3946 should not automatically start a delivery process for each message
3947 received. Messages are placed in the queue, and remain there until a
3948 subsequent queue runner process encounters them. There are several
3949 configuration options (such as queue_only) that can be used to queue
3950 incoming messages under certain conditions. This option overrides all of
3951 them and also -odqs. It always forces queueing.
3952
3953 -odqs
3954
3955 This option is a hybrid between -odb/-odi and -odq. However, like -odb and
3956 -odi, this option has no effect if queue_only_override is false and one of
3957 the queueing options in the configuration file is in effect.
3958
3959 When -odqs does operate, a delivery process is started for each incoming
3960 message, in the background by default, but in the foreground if -odi is
3961 also present. The recipient addresses are routed, and local deliveries are
3962 done in the normal way. However, if any SMTP deliveries are required, they
3963 are not done at this time, so the message remains in the queue until a
3964 subsequent queue runner process encounters it. Because routing was done,
3965 Exim knows which messages are waiting for which hosts, and so a number of
3966 messages for the same host can be sent in a single SMTP connection. The
3967 queue_smtp_domains configuration option has the same effect for specific
3968 domains. See also the -qq option.
3969
3970 -oee
3971
3972 If an error is detected while a non-SMTP message is being received (for
3973 example, a malformed address), the error is reported to the sender in a
3974 mail message.
3975
3976 Provided this error message is successfully sent, the Exim receiving
3977 process exits with a return code of zero. If not, the return code is 2 if
3978 the problem is that the original message has no recipients, or 1 for any
3979 other error. This is the default -oex option if Exim is called as rmail.
3980
3981 -oem
3982
3983 This is the same as -oee, except that Exim always exits with a non-zero
3984 return code, whether or not the error message was successfully sent. This
3985 is the default -oex option, unless Exim is called as rmail.
3986
3987 -oep
3988
3989 If an error is detected while a non-SMTP message is being received, the
3990 error is reported by writing a message to the standard error file (stderr).
3991 The return code is 1 for all errors.
3992
3993 -oeq
3994
3995 This option is supported for compatibility with Sendmail, but has the same
3996 effect as -oep.
3997
3998 -oew
3999
4000 This option is supported for compatibility with Sendmail, but has the same
4001 effect as -oem.
4002
4003 -oi
4004
4005 This option, which has the same effect as -i, specifies that a dot on a
4006 line by itself should not terminate an incoming, non-SMTP message.
4007 Otherwise, a single dot does terminate, though Exim does no special
4008 processing for other lines that start with a dot. This option is set by
4009 default if Exim is called as rmail. See also -ti.
4010
4011 -oitrue
4012
4013 This option is treated as synonymous with -oi.
4014
4015 -oMa <host address>
4016
4017 A number of options starting with -oM can be used to set values associated
4018 with remote hosts on locally-submitted messages (that is, messages not
4019 received over TCP/IP). These options can be used by any caller in
4020 conjunction with the -bh, -be, -bf, -bF, -bt, or -bv testing options. In
4021 other circumstances, they are ignored unless the caller is trusted.
4022
4023 The -oMa option sets the sender host address. This may include a port
4024 number at the end, after a full stop (period). For example:
4025
4026 exim -bs -oMa 10.9.8.7.1234
4027
4028 An alternative syntax is to enclose the IP address in square brackets,
4029 followed by a colon and the port number:
4030
4031 exim -bs -oMa [10.9.8.7]:1234
4032
4033 The IP address is placed in the $sender_host_address variable, and the
4034 port, if present, in $sender_host_port. If both -oMa and -bh are present on
4035 the command line, the sender host IP address is taken from whichever one is
4036 last.
4037
4038 -oMaa <name>
4039
4040 See -oMa above for general remarks about the -oM options. The -oMaa option
4041 sets the value of $sender_host_authenticated (the authenticator name). See
4042 chapter 33 for a discussion of SMTP authentication. This option can be used
4043 with -bh and -bs to set up an authenticated SMTP session without actually
4044 using the SMTP AUTH command.
4045
4046 -oMai <string>
4047
4048 See -oMa above for general remarks about the -oM options. The -oMai option
4049 sets the value of $authenticated_id (the id that was authenticated). This
4050 overrides the default value (the caller's login id, except with -bh, where
4051 there is no default) for messages from local sources. See chapter 33 for a
4052 discussion of authenticated ids.
4053
4054 -oMas <address>
4055
4056 See -oMa above for general remarks about the -oM options. The -oMas option
4057 sets the authenticated sender value in $authenticated_sender. It overrides
4058 the sender address that is created from the caller's login id for messages
4059 from local sources, except when -bh is used, when there is no default. For
4060 both -bh and -bs, an authenticated sender that is specified on a MAIL
4061 command overrides this value. See chapter 33 for a discussion of
4062 authenticated senders.
4063
4064 -oMi <interface address>
4065
4066 See -oMa above for general remarks about the -oM options. The -oMi option
4067 sets the IP interface address value. A port number may be included, using
4068 the same syntax as for -oMa. The interface address is placed in
4069 $received_ip_address and the port number, if present, in $received_port.
4070
4071 -oMm <message reference>
4072
4073 See -oMa above for general remarks about the -oM options. The -oMm option
4074 sets the message reference, e.g. message-id, and is logged during delivery.
4075 This is useful when some kind of audit trail is required to tie messages
4076 together. The format of the message reference is checked and will abort if
4077 the format is invalid. The option will only be accepted if exim is running
4078 in trusted mode, not as any regular user.
4079
4080 The best example of a message reference is when Exim sends a bounce
4081 message. The message reference is the message-id of the original message
4082 for which Exim is sending the bounce.
4083
4084 -oMr <protocol name>
4085
4086 See -oMa above for general remarks about the -oM options. The -oMr option
4087 sets the received protocol value that is stored in $received_protocol.
4088 However, it does not apply (and is ignored) when -bh or -bs is used. For
4089 -bh, the protocol is forced to one of the standard SMTP protocol names (see
4090 the description of $received_protocol in section 11.9). For -bs, the
4091 protocol is always "local-" followed by one of those same names. For -bS
4092 (batched SMTP) however, the protocol can be set by -oMr. Repeated use of
4093 this option is not supported.
4094
4095 -oMs <host name>
4096
4097 See -oMa above for general remarks about the -oM options. The -oMs option
4098 sets the sender host name in $sender_host_name. When this option is
4099 present, Exim does not attempt to look up a host name from an IP address;
4100 it uses the name it is given.
4101
4102 -oMt <ident string>
4103
4104 See -oMa above for general remarks about the -oM options. The -oMt option
4105 sets the sender ident value in $sender_ident. The default setting for local
4106 callers is the login id of the calling process, except when -bh is used,
4107 when there is no default.
4108
4109 -om
4110
4111 In Sendmail, this option means "me too", indicating that the sender of a
4112 message should receive a copy of the message if the sender appears in an
4113 alias expansion. Exim always does this, so the option does nothing.
4114
4115 -oo
4116
4117 This option is ignored. In Sendmail it specifies "old style headers",
4118 whatever that means.
4119
4120 -oP <path>
4121
4122 This option is useful only in conjunction with -bd or -q with a time value.
4123 The option specifies the file to which the process id of the daemon is
4124 written. When -oX is used with -bd, or when -q with a time is used without
4125 -bd, this is the only way of causing Exim to write a pid file, because in
4126 those cases, the normal pid file is not used.
4127
4128 -or <time>
4129
4130 This option sets a timeout value for incoming non-SMTP messages. If it is
4131 not set, Exim will wait forever for the standard input. The value can also
4132 be set by the receive_timeout option. The format used for specifying times
4133 is described in section 6.16.
4134
4135 -os <time>
4136
4137 This option sets a timeout value for incoming SMTP messages. The timeout
4138 applies to each SMTP command and block of data. The value can also be set
4139 by the smtp_receive_timeout option; it defaults to 5 minutes. The format
4140 used for specifying times is described in section 6.16.
4141
4142 -ov
4143
4144 This option has exactly the same effect as -v.
4145
4146 -oX <number or string>
4147
4148 This option is relevant only when the -bd (start listening daemon) option
4149 is also given. It controls which ports and interfaces the daemon uses.
4150 Details of the syntax, and how it interacts with configuration file
4151 options, are given in chapter 13. When -oX is used to start a daemon, no
4152 pid file is written unless -oP is also present to specify a pid filename.
4153
4154 -pd
4155
4156 This option applies when an embedded Perl interpreter is linked with Exim
4157 (see chapter 12). It overrides the setting of the perl_at_start option,
4158 forcing the starting of the interpreter to be delayed until it is needed.
4159
4160 -ps
4161
4162 This option applies when an embedded Perl interpreter is linked with Exim
4163 (see chapter 12). It overrides the setting of the perl_at_start option,
4164 forcing the starting of the interpreter to occur as soon as Exim is
4165 started.
4166
4167 -p<rval>:<sval>
4168
4169 For compatibility with Sendmail, this option is equivalent to
4170
4171 -oMr <rval> -oMs <sval>
4172
4173 It sets the incoming protocol and host name (for trusted callers). The host
4174 name and its colon can be omitted when only the protocol is to be set. Note
4175 the Exim already has two private options, -pd and -ps, that refer to
4176 embedded Perl. It is therefore impossible to set a protocol value of "d" or
4177 "s" using this option (but that does not seem a real limitation). Repeated
4178 use of this option is not supported.
4179
4180 -q
4181
4182 This option is normally restricted to admin users. However, there is a
4183 configuration option called prod_requires_admin which can be set false to
4184 relax this restriction (and also the same requirement for the -M, -R, and
4185 -S options).
4186
4187 If other commandline options do not specify an action, the -q option starts
4188 one queue runner process. This scans the queue of waiting messages, and
4189 runs a delivery process for each one in turn. It waits for each delivery
4190 process to finish before starting the next one. A delivery process may not
4191 actually do any deliveries if the retry times for the addresses have not
4192 been reached. Use -qf (see below) if you want to override this.
4193
4194 If the delivery process spawns other processes to deliver other messages
4195 down passed SMTP connections, the queue runner waits for these to finish
4196 before proceeding.
4197
4198 When all the queued messages have been considered, the original queue
4199 runner process terminates. In other words, a single pass is made over the
4200 waiting mail, one message at a time. Use -q with a time (see below) if you
4201 want this to be repeated periodically.
4202
4203 Exim processes the waiting messages in an unpredictable order. It isn't
4204 very random, but it is likely to be different each time, which is all that
4205 matters. If one particular message screws up a remote MTA, other messages
4206 to the same MTA have a chance of getting through if they get tried first.
4207
4208 It is possible to cause the messages to be processed in lexical message id
4209 order, which is essentially the order in which they arrived, by setting the
4210 queue_run_in_order option, but this is not recommended for normal use.
4211
4212 -q<qflags>
4213
4214 The -q option may be followed by one or more flag letters that change its
4215 behaviour. They are all optional, but if more than one is present, they
4216 must appear in the correct order. Each flag is described in a separate item
4217 below.
4218
4219 -qq...
4220
4221 An option starting with -qq requests a two-stage queue run. In the first
4222 stage, the queue is scanned as if the queue_smtp_domains option matched
4223 every domain. Addresses are routed, local deliveries happen, but no remote
4224 transports are run.
4225
4226 The hints database that remembers which messages are waiting for specific
4227 hosts is updated, as if delivery to those hosts had been deferred. After
4228 this is complete, a second, normal queue scan happens, with routing and
4229 delivery taking place as normal. Messages that are routed to the same host
4230 should mostly be delivered down a single SMTP connection because of the
4231 hints that were set up during the first queue scan. This option may be
4232 useful for hosts that are connected to the Internet intermittently.
4233
4234 -q[q]i...
4235
4236 If the i flag is present, the queue runner runs delivery processes only for
4237 those messages that haven't previously been tried. (i stands for "initial
4238 delivery".) This can be helpful if you are putting messages in the queue
4239 using -odq and want a queue runner just to process the new messages.
4240
4241 -q[q][i]f...
4242
4243 If one f flag is present, a delivery attempt is forced for each non-frozen
4244 message, whereas without f only those non-frozen addresses that have passed
4245 their retry times are tried.
4246
4247 -q[q][i]ff...
4248
4249 If ff is present, a delivery attempt is forced for every message, whether
4250 frozen or not.
4251
4252 -q[q][i][f[f]]l
4253
4254 The l (the letter "ell") flag specifies that only local deliveries are to
4255 be done. If a message requires any remote deliveries, it remains in the
4256 queue for later delivery.
4257
4258 -q[q][i][f[f]][l][G<name>[/<time>]]]
4259
4260 If the G flag and a name is present, the queue runner operates on the queue
4261 with the given name rather than the default queue. The name should not
4262 contain a / character. For a periodic queue run (see below) append to the
4263 name a slash and a time value.
4264
4265 If other commandline options specify an action, a -qG<name> option will
4266 specify a queue to operate on. For example:
4267
4268 exim -bp -qGquarantine
4269 mailq -qGquarantine
4270 exim -qGoffpeak -Rf @special.domain.example
4271
4272 -q<qflags> <start id> <end id>
4273
4274 When scanning the queue, Exim can be made to skip over messages whose ids
4275 are lexically less than a given value by following the -q option with a
4276 starting message id. For example:
4277
4278 exim -q 0t5C6f-0000c8-00
4279
4280 Messages that arrived earlier than "0t5C6f-0000c8-00" are not inspected. If
4281 a second message id is given, messages whose ids are lexically greater than
4282 it are also skipped. If the same id is given twice, for example,
4283
4284 exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
4285
4286 just one delivery process is started, for that message. This differs from
4287 -M in that retry data is respected, and it also differs from -Mc in that it
4288 counts as a delivery from a queue run. Note that the selection mechanism
4289 does not affect the order in which the messages are scanned. There are also
4290 other ways of selecting specific sets of messages for delivery in a queue
4291 run - see -R and -S.
4292
4293 -q<qflags><time>
4294
4295 When a time value is present, the -q option causes Exim to run as a daemon,
4296 starting a queue runner process at intervals specified by the given time
4297 value (whose format is described in section 6.16). This form of the -q
4298 option is commonly combined with the -bd option, in which case a single
4299 daemon process handles both functions. A common way of starting up a
4300 combined daemon at system boot time is to use a command such as
4301
4302 /usr/exim/bin/exim -bd -q30m
4303
4304 Such a daemon listens for incoming SMTP calls, and also starts a queue
4305 runner process every 30 minutes.
4306
4307 When a daemon is started by -q with a time value, but without -bd, no pid
4308 file is written unless one is explicitly requested by the -oP option.
4309
4310 -qR<rsflags> <string>
4311
4312 This option is synonymous with -R. It is provided for Sendmail
4313 compatibility.
4314
4315 -qS<rsflags> <string>
4316
4317 This option is synonymous with -S.
4318
4319 -R<rsflags> <string>
4320
4321 The <rsflags> may be empty, in which case the white space before the string
4322 is optional, unless the string is f, ff, r, rf, or rff, which are the
4323 possible values for <rsflags>. White space is required if <rsflags> is not
4324 empty.
4325
4326 This option is similar to -q with no time value, that is, it causes Exim to
4327 perform a single queue run, except that, when scanning the messages on the
4328 queue, Exim processes only those that have at least one undelivered
4329 recipient address containing the given string, which is checked in a
4330 case-independent way. If the <rsflags> start with r, <string> is
4331 interpreted as a regular expression; otherwise it is a literal string.
4332
4333 If you want to do periodic queue runs for messages with specific
4334 recipients, you can combine -R with -q and a time value. For example:
4335
4336 exim -q25m -R @special.domain.example
4337
4338 This example does a queue run for messages with recipients in the given
4339 domain every 25 minutes. Any additional flags that are specified with -q
4340 are applied to each queue run.
4341
4342 Once a message is selected for delivery by this mechanism, all its
4343 addresses are processed. For the first selected message, Exim overrides any
4344 retry information and forces a delivery attempt for each undelivered
4345 address. This means that if delivery of any address in the first message is
4346 successful, any existing retry information is deleted, and so delivery
4347 attempts for that address in subsequently selected messages (which are
4348 processed without forcing) will run. However, if delivery of any address
4349 does not succeed, the retry information is updated, and in subsequently
4350 selected messages, the failing address will be skipped.
4351
4352 If the <rsflags> contain f or ff, the delivery forcing applies to all
4353 selected messages, not just the first; frozen messages are included when ff
4354 is present.
4355
4356 The -R option makes it straightforward to initiate delivery of all messages
4357 to a given domain after a host has been down for some time. When the SMTP
4358 command ETRN is accepted by its ACL (see chapter 43), its default effect is
4359 to run Exim with the -R option, but it can be configured to run an
4360 arbitrary command instead.
4361
4362 -r
4363
4364 This is a documented (for Sendmail) obsolete alternative name for -f.
4365
4366 -S<rsflags> <string>
4367
4368 This option acts like -R except that it checks the string against each
4369 message's sender instead of against the recipients. If -R is also set, both
4370 conditions must be met for a message to be selected. If either of the
4371 options has f or ff in its flags, the associated action is taken.
4372
4373 -Tqt <times>
4374
4375 This is an option that is exclusively for use by the Exim testing suite. It
4376 is not recognized when Exim is run normally. It allows for the setting up
4377 of explicit "queue times" so that various warning/retry features can be
4378 tested.
4379
4380 -t
4381
4382 When Exim is receiving a locally-generated, non-SMTP message on its
4383 standard input, the -t option causes the recipients of the message to be
4384 obtained from the To:, Cc:, and Bcc: header lines in the message instead of
4385 from the command arguments. The addresses are extracted before any
4386 rewriting takes place and the Bcc: header line, if present, is then
4387 removed.
4388
4389 If the command has any arguments, they specify addresses to which the
4390 message is not to be delivered. That is, the argument addresses are removed
4391 from the recipients list obtained from the headers. This is compatible with
4392 Smail 3 and in accordance with the documented behaviour of several versions
4393 of Sendmail, as described in man pages on a number of operating systems
4394 (e.g. Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail
4395 add argument addresses to those obtained from the headers, and the O'Reilly
4396 Sendmail book documents it that way. Exim can be made to add argument
4397 addresses instead of subtracting them by setting the option
4398 extract_addresses_remove_arguments false.
4399
4400 If there are any Resent- header lines in the message, Exim extracts
4401 recipients from all Resent-To:, Resent-Cc:, and Resent-Bcc: header lines
4402 instead of from To:, Cc:, and Bcc:. This is for compatibility with Sendmail
4403 and other MTAs. (Prior to release 4.20, Exim gave an error if -t was used
4404 in conjunction with Resent- header lines.)
4405
4406 RFC 2822 talks about different sets of Resent- header lines (for when a
4407 message is resent several times). The RFC also specifies that they should
4408 be added at the front of the message, and separated by Received: lines. It
4409 is not at all clear how -t should operate in the present of multiple sets,
4410 nor indeed exactly what constitutes a "set". In practice, it seems that
4411 MUAs do not follow the RFC. The Resent- lines are often added at the end of
4412 the header, and if a message is resent more than once, it is common for the
4413 original set of Resent- headers to be renamed as X-Resent- when a new set
4414 is added. This removes any possible ambiguity.
4415
4416 -ti
4417
4418 This option is exactly equivalent to -t -i. It is provided for
4419 compatibility with Sendmail.
4420
4421 -tls-on-connect
4422
4423 This option is available when Exim is compiled with TLS support. It forces
4424 all incoming SMTP connections to behave as if the incoming port is listed
4425 in the tls_on_connect_ports option. See section 13.4 and chapter 42 for
4426 further details.
4427
4428 -U
4429
4430 Sendmail uses this option for "initial message submission", and its
4431 documentation states that in future releases, it may complain about
4432 syntactically invalid messages rather than fixing them when this flag is
4433 not set. Exim ignores this option.
4434
4435 -v
4436
4437 This option causes Exim to write information to the standard error stream,
4438 describing what it is doing. In particular, it shows the log lines for
4439 receiving and delivering a message, and if an SMTP connection is made, the
4440 SMTP dialogue is shown. Some of the log lines shown may not actually be
4441 written to the log if the setting of log_selector discards them. Any
4442 relevant selectors are shown with each log line. If none are shown, the
4443 logging is unconditional.
4444
4445 -x
4446
4447 AIX uses -x for a private purpose ("mail from a local mail program has
4448 National Language Support extended characters in the body of the mail
4449 item"). It sets -x when calling the MTA from its mail command. Exim ignores
4450 this option.
4451
4452 -X <logfile>
4453
4454 This option is interpreted by Sendmail to cause debug information to be
4455 sent to the named file. It is ignored by Exim.
4456
4457 -z <log-line>
4458
4459 This option writes its argument to Exim's logfile. Use is restricted to
4460 administrators; the intent is for operational notes. Quotes should be used
4461 to maintain a multi-word item as a single argument, under most shells.
4462
4463
4464
4465 ===============================================================================
4466 6. THE EXIM RUNTIME CONFIGURATION FILE
4467
4468 Exim uses a single runtime configuration file that is read whenever an Exim
4469 binary is executed. Note that in normal operation, this happens frequently,
4470 because Exim is designed to operate in a distributed manner, without central
4471 control.
4472
4473 If a syntax error is detected while reading the configuration file, Exim writes
4474 a message on the standard error, and exits with a non-zero return code. The
4475 message is also written to the panic log. Note: Only simple syntax errors can
4476 be detected at this time. The values of any expanded options are not checked
4477 until the expansion happens, even when the expansion does not actually alter
4478 the string.
4479
4480 The name of the configuration file is compiled into the binary for security
4481 reasons, and is specified by the CONFIGURE_FILE compilation option. In most
4482 configurations, this specifies a single file. However, it is permitted to give
4483 a colon-separated list of filenames, in which case Exim uses the first existing
4484 file in the list.
4485
4486 The runtime configuration file must be owned by root or by the user that is
4487 specified at compile time by the CONFIGURE_OWNER option (if set). The
4488 configuration file must not be world-writeable, or group-writeable unless its
4489 group is the root group or the one specified at compile time by the
4490 CONFIGURE_GROUP option.
4491
4492 Warning: In a conventional configuration, where the Exim binary is setuid to
4493 root, anybody who is able to edit the runtime configuration file has an easy
4494 way to run commands as root. If you specify a user or group in the
4495 CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who
4496 are members of that group will trivially be able to obtain root privileges.
4497
4498 Up to Exim version 4.72, the runtime configuration file was also permitted to
4499 be writeable by the Exim user and/or group. That has been changed in Exim 4.73
4500 since it offered a simple privilege escalation for any attacker who managed to
4501 compromise the Exim user account.
4502
4503 A default configuration file, which will work correctly in simple situations,
4504 is provided in the file src/configure.default. If CONFIGURE_FILE defines just
4505 one filename, the installation process copies the default configuration to a
4506 new file of that name if it did not previously exist. If CONFIGURE_FILE is a
4507 list, no default is automatically installed. Chapter 7 is a "walk-through"
4508 discussion of the default configuration.
4509
4510
4511 6.1 Using a different configuration file
4512 ----------------------------------------
4513
4514 A one-off alternate configuration can be specified by the -C command line
4515 option, which may specify a single file or a list of files. However, when -C is
4516 used, Exim gives up its root privilege, unless called by root (or unless the
4517 argument for -C is identical to the built-in value from CONFIGURE_FILE), or is
4518 listed in the TRUSTED_CONFIG_LIST file and the caller is the Exim user or the
4519 user specified in the CONFIGURE_OWNER setting. -C is useful mainly for checking
4520 the syntax of configuration files before installing them. No owner or group
4521 checks are done on a configuration file specified by -C, if root privilege has
4522 been dropped.
4523
4524 Even the Exim user is not trusted to specify an arbitrary configuration file
4525 with the -C option to be used with root privileges, unless that file is listed
4526 in the TRUSTED_CONFIG_LIST file. This locks out the possibility of testing a
4527 configuration using -C right through message reception and delivery, even if
4528 the caller is root. The reception works, but by that time, Exim is running as
4529 the Exim user, so when it re-execs to regain privilege for the delivery, the
4530 use of -C causes privilege to be lost. However, root can test reception and
4531 delivery using two separate commands (one to put a message in the queue, using
4532 -odq, and another to do the delivery, using -M).
4533
4534 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string
4535 with which any file named in a -C command line option must start. In addition,
4536 the filename must not contain the sequence "/../". There is no default setting
4537 for ALT_CONFIG_PREFIX; when it is unset, any filename can be used with -C.
4538
4539 One-off changes to a configuration can be specified by the -D command line
4540 option, which defines and overrides values for macros used inside the
4541 configuration file. However, like -C, the use of this option by a
4542 non-privileged user causes Exim to discard its root privilege. If
4543 DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely
4544 disabled, and its use causes an immediate error exit.
4545
4546 The WHITELIST_D_MACROS option in Local/Makefile permits the binary builder to
4547 declare certain macro names trusted, such that root privilege will not
4548 necessarily be discarded. WHITELIST_D_MACROS defines a colon-separated list of
4549 macros which are considered safe and, if -D only supplies macros from this
4550 list, and the values are acceptable, then Exim will not give up root privilege
4551 if the caller is root, the Exim run-time user, or the CONFIGURE_OWNER, if set.
4552 This is a transition mechanism and is expected to be removed in the future.
4553 Acceptable values for the macros satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
4554
4555 Some sites may wish to use the same Exim binary on different machines that
4556 share a file system, but to use different configuration files on each machine.
4557 If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a
4558 file whose name is the configuration filename followed by a dot and the
4559 machine's node name, as obtained from the uname() function. If this file does
4560 not exist, the standard name is tried. This processing occurs for each filename
4561 in the list given by CONFIGURE_FILE or -C.
4562
4563 In some esoteric situations different versions of Exim may be run under
4564 different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help
4565 with this. See the comments in src/EDITME for details.
4566
4567
4568 6.2 Configuration file format
4569 -----------------------------
4570
4571 Exim's configuration file is divided into a number of different parts. General
4572 option settings must always appear at the start of the file. The other parts
4573 are all optional, and may appear in any order. Each part other than the first
4574 is introduced by the word "begin" followed by at least one literal space, and
4575 the name of the part. The optional parts are:
4576
4577 * ACL: Access control lists for controlling incoming SMTP mail (see chapter
4578 43).
4579
4580 * authenticators: Configuration settings for the authenticator drivers. These
4581 are concerned with the SMTP AUTH command (see chapter 33).
4582
4583 * routers: Configuration settings for the router drivers. Routers process
4584 addresses and determine how the message is to be delivered (see chapters 15
4585 -22).
4586
4587 * transports: Configuration settings for the transport drivers. Transports
4588 define mechanisms for copying messages to destinations (see chapters 24-30
4589 ).
4590
4591 * retry: Retry rules, for use when a message cannot be delivered immediately.
4592 If there is no retry section, or if it is empty (that is, no retry rules
4593 are defined), Exim will not retry deliveries. In this situation, temporary
4594 errors are treated the same as permanent errors. Retry rules are discussed
4595 in chapter 32.
4596
4597 * rewrite: Global address rewriting rules, for use when a message arrives and
4598 when new addresses are generated during delivery. Rewriting is discussed in
4599 chapter 31.
4600
4601 * local_scan: Private options for the local_scan() function. If you want to
4602 use this feature, you must set
4603
4604 LOCAL_SCAN_HAS_OPTIONS=yes
4605
4606 in Local/Makefile before building Exim. Details of the local_scan()
4607 facility are given in chapter 45.
4608
4609 Leading and trailing white space in configuration lines is always ignored.
4610
4611 Blank lines in the file, and lines starting with a # character (ignoring
4612 leading white space) are treated as comments and are ignored. Note: A #
4613 character other than at the beginning of a line is not treated specially, and
4614 does not introduce a comment.
4615
4616 Any non-comment line can be continued by ending it with a backslash. Note that
4617 the general rule for white space means that trailing white space after the
4618 backslash and leading white space at the start of continuation lines is
4619 ignored. Comment lines beginning with # (but not empty lines) may appear in the
4620 middle of a sequence of continuation lines.
4621
4622 A convenient way to create a configuration file is to start from the default,
4623 which is supplied in src/configure.default, and add, delete, or change settings
4624 as required.
4625
4626 The ACLs, retry rules, and rewriting rules have their own syntax which is
4627 described in chapters 43, 32, and 31, respectively. The other parts of the
4628 configuration file have some syntactic items in common, and these are described
4629 below, from section 6.11 onwards. Before that, the inclusion, macro, and
4630 conditional facilities are described.
4631
4632
4633 6.3 File inclusions in the configuration file
4634 ---------------------------------------------
4635
4636 You can include other files inside Exim's runtime configuration file by using
4637 this syntax:
4638
4639 .include <filename>
4640 .include_if_exists <filename>
4641
4642 on a line by itself. Double quotes round the filename are optional. If you use
4643 the first form, a configuration error occurs if the file does not exist; the
4644 second form does nothing for non-existent files. The first form allows a
4645 relative name. It is resolved relative to the directory of the including file.
4646 For the second form an absolute filename is required.
4647
4648 Includes may be nested to any depth, but remember that Exim reads its
4649 configuration file often, so it is a good idea to keep them to a minimum. If
4650 you change the contents of an included file, you must HUP the daemon, because
4651 an included file is read only when the configuration itself is read.
4652
4653 The processing of inclusions happens early, at a physical line level, so, like
4654 comment lines, an inclusion can be used in the middle of an option setting, for
4655 example:
4656
4657 hosts_lookup = a.b.c \
4658 .include /some/file
4659
4660 Include processing happens after macro processing (see below). Its effect is to
4661 process the lines of the included file as if they occurred inline where the
4662 inclusion appears.
4663
4664
4665 6.4 Macros in the configuration file
4666 ------------------------------------
4667
4668 If a line in the main part of the configuration (that is, before the first
4669 "begin" line) begins with an upper case letter, it is taken as a macro
4670 definition, and must be of the form
4671
4672 <name> = <rest of line>
4673
4674 The name must consist of letters, digits, and underscores, and need not all be
4675 in upper case, though that is recommended. The rest of the line, including any
4676 continuations, is the replacement text, and has leading and trailing white
4677 space removed. Quotes are not removed. The replacement text can never end with
4678 a backslash character, but this doesn't seem to be a serious limitation.
4679
4680 Macros may also be defined between router, transport, authenticator, or ACL
4681 definitions. They may not, however, be defined within an individual driver or
4682 ACL, or in the local_scan, retry, or rewrite sections of the configuration.
4683
4684
4685 6.5 Macro substitution
4686 ----------------------
4687
4688 Once a macro is defined, all subsequent lines in the file (and any included
4689 files) are scanned for the macro name; if there are several macros, the line is
4690 scanned for each, in turn, in the order in which the macros are defined. The
4691 replacement text is not re-scanned for the current macro, though it is scanned
4692 for subsequently defined macros. For this reason, a macro name may not contain
4693 the name of a previously defined macro as a substring. You could, for example,
4694 define
4695
4696 ABCD_XYZ = <something>
4697 ABCD = <something else>
4698
4699 but putting the definitions in the opposite order would provoke a configuration
4700 error. Macro expansion is applied to individual physical lines from the file,
4701 before checking for line continuation or file inclusion (see above). If a line
4702 consists solely of a macro name, and the expansion of the macro is empty, the
4703 line is ignored. A macro at the start of a line may turn the line into a
4704 comment line or a ".include" line.
4705
4706
4707 6.6 Redefining macros
4708 ---------------------
4709
4710 Once defined, the value of a macro can be redefined later in the configuration
4711 (or in an included file). Redefinition is specified by using == instead of =.
4712 For example:
4713
4714 MAC = initial value
4715 ...
4716 MAC == updated value
4717
4718 Redefinition does not alter the order in which the macros are applied to the
4719 subsequent lines of the configuration file. It is still the same order in which
4720 the macros were originally defined. All that changes is the macro's value.
4721 Redefinition makes it possible to accumulate values. For example:
4722
4723 MAC = initial value
4724 ...
4725 MAC == MAC and something added
4726
4727 This can be helpful in situations where the configuration file is built from a
4728 number of other files.
4729
4730
4731 6.7 Overriding macro values
4732 ---------------------------
4733
4734 The values set for macros in the configuration file can be overridden by the -D
4735 command line option, but Exim gives up its root privilege when -D is used,
4736 unless called by root or the Exim user. A definition on the command line using
4737 the -D option causes all definitions and redefinitions within the file to be
4738 ignored.
4739
4740
4741 6.8 Example of macro usage
4742 --------------------------
4743
4744 As an example of macro usage, consider a configuration where aliases are looked
4745 up in a MySQL database. It helps to keep the file less cluttered if long
4746 strings such as SQL statements are defined separately as macros, for example:
4747
4748 ALIAS_QUERY = select mailbox from user where \
4749 login='${quote_mysql:$local_part}';
4750
4751 This can then be used in a redirect router setting like this:
4752
4753 data = ${lookup mysql{ALIAS_QUERY}}
4754
4755 In earlier versions of Exim macros were sometimes used for domain, host, or
4756 address lists. In Exim 4 these are handled better by named lists - see section
4757 10.5.
4758
4759
4760 6.9 Builtin macros
4761 ------------------
4762
4763 Exim defines some macros depending on facilities available, which may differ
4764 due to build-time definitions and from one release to another. All of these
4765 macros start with an underscore. They can be used to conditionally include
4766 parts of a configuration (see below).
4767
4768 The following classes of macros are defined:
4769
4770 _HAVE_* build-time defines
4771 _DRIVER_ROUTER_* router drivers
4772 _DRIVER_TRANSPORT_* transport drivers
4773 _DRIVER_AUTHENTICATOR_* authenticator drivers
4774 _LOG_* log_selector values
4775 _OPT_MAIN_* main config options
4776 _OPT_ROUTERS_* generic router options
4777 _OPT_TRANSPORTS_* generic transport options
4778 _OPT_AUTHENTICATORS_* generic authenticator options
4779 _OPT_ROUTER_*_* private router options
4780 _OPT_TRANSPORT_*_* private transport options
4781 _OPT_AUTHENTICATOR_*_* private authenticator options
4782
4783 Use an "exim -bP macros" command to get the list of macros.
4784
4785
4786 6.10 Conditional skips in the configuration file
4787 ------------------------------------------------
4788
4789 You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef",
4790 ".else", and ".endif" to dynamically include or exclude portions of the
4791 configuration file. The processing happens whenever the file is read (that is,
4792 when an Exim binary starts to run).
4793
4794 The implementation is very simple. Instances of the first four directives must
4795 be followed by text that includes the names of one or macros. The condition
4796 that is tested is whether or not any macro substitution has taken place in the
4797 line. Thus:
4798
4799 .ifdef AAA
4800 message_size_limit = 50M
4801 .else
4802 message_size_limit = 100M
4803 .endif
4804
4805 sets a message size limit of 50M if the macro "AAA" is defined (or "A" or
4806 "AA"), and 100M otherwise. If there is more than one macro named on the line,
4807 the condition is true if any of them are defined. That is, it is an "or"
4808 condition. To obtain an "and" condition, you need to use nested ".ifdef"s.
4809
4810 Although you can use a macro expansion to generate one of these directives, it
4811 is not very useful, because the condition "there was a macro substitution in
4812 this line" will always be true.
4813
4814 Text following ".else" and ".endif" is ignored, and can be used as comment to
4815 clarify complicated nestings.
4816
4817
4818 6.11 Common option syntax
4819 -------------------------
4820
4821 For the main set of options, driver options, and local_scan() options, each
4822 setting is on a line by itself, and starts with a name consisting of lower-case
4823 letters and underscores. Many options require a data value, and in these cases
4824 the name must be followed by an equals sign (with optional white space) and
4825 then the value. For example:
4826
4827 qualify_domain = mydomain.example.com
4828
4829 Some option settings may contain sensitive data, for example, passwords for
4830 accessing databases. To stop non-admin users from using the -bP command line
4831 option to read these values, you can precede the option settings with the word
4832 "hide". For example:
4833
4834 hide mysql_servers = localhost/users/admin/secret-password
4835
4836 For non-admin users, such options are displayed like this:
4837
4838 mysql_servers = <value not displayable>
4839
4840 If "hide" is used on a driver option, it hides the value of that option on all
4841 instances of the same driver.
4842
4843 The following sections describe the syntax used for the different data types
4844 that are found in option settings.
4845
4846
4847 6.12 Boolean options
4848 --------------------
4849
4850 Options whose type is given as boolean are on/off switches. There are two
4851 different ways of specifying such options: with and without a data value. If
4852 the option name is specified on its own without data, the switch is turned on;
4853 if it is preceded by "no_" or "not_" the switch is turned off. However, boolean
4854 options may be followed by an equals sign and one of the words "true", "false",
4855 "yes", or "no", as an alternative syntax. For example, the following two
4856 settings have exactly the same effect:
4857
4858 queue_only
4859 queue_only = true
4860
4861 The following two lines also have the same (opposite) effect:
4862
4863 no_queue_only
4864 queue_only = false
4865
4866 You can use whichever syntax you prefer.
4867
4868
4869 6.13 Integer values
4870 -------------------
4871
4872 If an option's type is given as "integer", the value can be given in decimal,
4873 hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
4874 number is assumed. Otherwise, it is treated as an octal number unless it starts
4875 with the characters "0x", in which case the remainder is interpreted as a
4876 hexadecimal number.
4877
4878 If an integer value is followed by the letter K, it is multiplied by 1024; if
4879 it is followed by the letter M, it is multiplied by 1024x1024; if by the letter
4880 G, 1024x1024x1024. When the values of integer option settings are output,
4881 values which are an exact multiple of 1024 or 1024x1024 are sometimes, but not
4882 always, printed using the letters K and M. The printing style is independent of
4883 the actual input format that was used.
4884
4885
4886 6.14 Octal integer values
4887 -------------------------
4888
4889 If an option's type is given as "octal integer", its value is always
4890 interpreted as an octal number, whether or not it starts with the digit zero.
4891 Such options are always output in octal.
4892
4893
4894 6.15 Fixed point numbers
4895 ------------------------
4896
4897 If an option's type is given as "fixed-point", its value must be a decimal
4898 integer, optionally followed by a decimal point and up to three further digits.
4899
4900
4901 6.16 Time intervals
4902 -------------------
4903
4904 A time interval is specified as a sequence of numbers, each followed by one of
4905 the following letters, with no intervening white space:
4906
4907 s seconds
4908 m minutes
4909 h hours
4910 d days
4911 w weeks
4912
4913 For example, "3h50m" specifies 3 hours and 50 minutes. The values of time
4914 intervals are output in the same format. Exim does not restrict the values; it
4915 is perfectly acceptable, for example, to specify "90m" instead of "1h30m".
4916
4917
4918 6.17 String values
4919 ------------------
4920
4921 If an option's type is specified as "string", the value can be specified with
4922 or without double-quotes. If it does not start with a double-quote, the value
4923 consists of the remainder of the line plus any continuation lines, starting at
4924 the first character after any leading white space, with trailing white space
4925 removed, and with no interpretation of the characters in the string. Because
4926 Exim removes comment lines (those beginning with #) at an early stage, they can
4927 appear in the middle of a multi-line string. The following two settings are
4928 therefore equivalent:
4929
4930 trusted_users = uucp:mail
4931 trusted_users = uucp:\
4932 # This comment line is ignored
4933 mail
4934
4935 If a string does start with a double-quote, it must end with a closing
4936 double-quote, and any backslash characters other than those used for line
4937 continuation are interpreted as escape characters, as follows:
4938
4939 "\\" single backslash
4940 "\n" newline
4941 "\r" carriage return
4942 "\t" tab
4943 "\"<octal digits> up to 3 octal digits specify one character
4944 "\x"<hex digits> up to 2 hexadecimal digits specify one character
4945
4946 If a backslash is followed by some other character, including a double-quote
4947 character, that character replaces the pair.
4948
4949 Quoting is necessary only if you want to make use of the backslash escapes to
4950 insert special characters, or if you need to specify a value with leading or
4951 trailing spaces. These cases are rare, so quoting is almost never needed in
4952 current versions of Exim. In versions of Exim before 3.14, quoting was required
4953 in order to continue lines, so you may come across older configuration files
4954 and examples that apparently quote unnecessarily.
4955
4956
4957 6.18 Expanded strings
4958 ---------------------
4959
4960 Some strings in the configuration file are subjected to string expansion, by
4961 which means various parts of the string may be changed according to the
4962 circumstances (see chapter 11). The input syntax for such strings is as just
4963 described; in particular, the handling of backslashes in quoted strings is done
4964 as part of the input process, before expansion takes place. However, backslash
4965 is also an escape character for the expander, so any backslashes that are
4966 required for that reason must be doubled if they are within a quoted
4967 configuration string.
4968
4969
4970 6.19 User and group names
4971 -------------------------
4972
4973 User and group names are specified as strings, using the syntax described
4974 above, but the strings are interpreted specially. A user or group name must
4975 either consist entirely of digits, or be a name that can be looked up using the
4976 getpwnam() or getgrnam() function, as appropriate.
4977
4978
4979 6.20 List construction
4980 ----------------------
4981
4982 The data for some configuration options is a list of items, with colon as the
4983 default separator. Many of these options are shown with type "string list" in
4984 the descriptions later in this document. Others are listed as "domain list",
4985 "host list", "address list", or "local part list". Syntactically, they are all
4986 the same; however, those other than "string list" are subject to particular
4987 kinds of interpretation, as described in chapter 10.
4988
4989 In all these cases, the entire list is treated as a single string as far as the
4990 input syntax is concerned. The trusted_users setting in section 6.17 above is
4991 an example. If a colon is actually needed in an item in a list, it must be
4992 entered as two colons. Leading and trailing white space on each item in a list
4993 is ignored. This makes it possible to include items that start with a colon,
4994 and in particular, certain forms of IPv6 address. For example, the list
4995
4996 local_interfaces = 127.0.0.1 : ::::1
4997
4998 contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
4999
5000 Note: Although leading and trailing white space is ignored in individual list
5001 items, it is not ignored when parsing the list. The space after the first colon
5002 in the example above is necessary. If it were not there, the list would be
5003 interpreted as the two items 127.0.0.1:: and 1.
5004
5005
5006 6.21 Changing list separators
5007 -----------------------------
5008
5009 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
5010 introduced to allow the separator character to be changed. If a list begins
5011 with a left angle bracket, followed by any punctuation character, that
5012 character is used instead of colon as the list separator. For example, the list
5013 above can be rewritten to use a semicolon separator like this:
5014
5015 local_interfaces = <; 127.0.0.1 ; ::1
5016
5017 This facility applies to all lists, with the exception of the list in
5018 log_file_path. It is recommended that the use of non-colon separators be
5019 confined to circumstances where they really are needed.
5020
5021 It is also possible to use newline and other control characters (those with
5022 code values less than 32, plus DEL) as separators in lists. Such separators
5023 must be provided literally at the time the list is processed. For options that
5024 are string-expanded, you can write the separator using a normal escape
5025 sequence. This will be processed by the expander before the string is
5026 interpreted as a list. For example, if a newline-separated list of domains is
5027 generated by a lookup, you can process it directly by a line such as this:
5028
5029 domains = <\n ${lookup mysql{.....}}
5030
5031 This avoids having to change the list separator in such data. You are unlikely
5032 to want to use a control character as a separator in an option that is not
5033 expanded, because the value is literal text. However, it can be done by giving
5034 the value in quotes. For example:
5035
5036 local_interfaces = "<\n 127.0.0.1 \n ::1"
5037
5038 Unlike printing character separators, which can be included in list items by
5039 doubling, it is not possible to include a control character as data when it is
5040 set as the separator. Two such characters in succession are interpreted as
5041 enclosing an empty list item.
5042
5043
5044 6.22 Empty items in lists
5045 -------------------------
5046
5047 An empty item at the end of a list is always ignored. In other words, trailing
5048 separator characters are ignored. Thus, the list in
5049
5050 senders = user@domain :
5051
5052 contains only a single item. If you want to include an empty string as one item
5053 in a list, it must not be the last item. For example, this list contains three
5054 items, the second of which is empty:
5055
5056 senders = user1@domain : : user2@domain
5057
5058 Note: There must be white space between the two colons, as otherwise they are
5059 interpreted as representing a single colon data character (and the list would
5060 then contain just one item). If you want to specify a list that contains just
5061 one, empty item, you can do it as in this example:
5062
5063 senders = :
5064
5065 In this case, the first item is empty, and the second is discarded because it
5066 is at the end of the list.
5067
5068
5069 6.23 Format of driver configurations
5070 ------------------------------------
5071
5072 There are separate parts in the configuration for defining routers, transports,
5073 and authenticators. In each part, you are defining a number of driver
5074 instances, each with its own set of options. Each driver instance is defined by
5075 a sequence of lines like this:
5076
5077 <instance name>:
5078 <option>
5079 ...
5080 <option>
5081
5082 In the following example, the instance name is localuser, and it is followed by
5083 three options settings:
5084
5085 localuser:
5086 driver = accept
5087 check_local_user
5088 transport = local_delivery
5089
5090 For each driver instance, you specify which Exim code module it uses - by the
5091 setting of the driver option - and (optionally) some configuration settings.
5092 For example, in the case of transports, if you want a transport to deliver with
5093 SMTP you would use the smtp driver; if you want to deliver to a local file you
5094 would use the appendfile driver. Each of the drivers is described in detail in
5095 its own separate chapter later in this manual.
5096
5097 You can have several routers, transports, or authenticators that are based on
5098 the same underlying driver (each must have a different instance name).
5099
5100 The order in which routers are defined is important, because addresses are
5101 passed to individual routers one by one, in order. The order in which
5102 transports are defined does not matter at all. The order in which
5103 authenticators are defined is used only when Exim, as a client, is searching
5104 them to find one that matches an authentication mechanism offered by the
5105 server.
5106
5107 Within a driver instance definition, there are two kinds of option: generic and
5108 private. The generic options are those that apply to all drivers of the same
5109 type (that is, all routers, all transports or all authenticators). The driver
5110 option is a generic option that must appear in every definition. The private
5111 options are special for each driver, and none need appear, because they all
5112 have default values.
5113
5114 The options may appear in any order, except that the driver option must precede
5115 any private options, since these depend on the particular driver. For this
5116 reason, it is recommended that driver always be the first option.
5117
5118 Driver instance names, which are used for reference in log entries and
5119 elsewhere, can be any sequence of letters, digits, and underscores (starting
5120 with a letter) and must be unique among drivers of the same type. A router and
5121 a transport (for example) can each have the same name, but no two router
5122 instances can have the same name. The name of a driver instance should not be
5123 confused with the name of the underlying driver module. For example, the
5124 configuration lines:
5125
5126 remote_smtp:
5127 driver = smtp
5128
5129 create an instance of the smtp transport driver whose name is remote_smtp. The
5130 same driver code can be used more than once, with different instance names and
5131 different option settings each time. A second instance of the smtp transport,
5132 with different options, might be defined thus:
5133
5134 special_smtp:
5135 driver = smtp
5136 port = 1234
5137 command_timeout = 10s
5138
5139 The names remote_smtp and special_smtp would be used to reference these
5140 transport instances from routers, and these names would appear in log lines.
5141
5142 Comment lines may be present in the middle of driver specifications. The full
5143 list of option settings for any particular driver instance, including all the
5144 defaulted values, can be extracted by making use of the -bP command line
5145 option.
5146
5147
5148
5149 ===============================================================================
5150 7. THE DEFAULT CONFIGURATION FILE
5151
5152 The default configuration file supplied with Exim as src/configure.default is
5153 sufficient for a host with simple mail requirements. As an introduction to the
5154 way Exim is configured, this chapter "walks through" the default configuration,
5155 giving brief explanations of the settings. Detailed descriptions of the options
5156 are given in subsequent chapters. The default configuration file itself
5157 contains extensive comments about ways you might want to modify the initial
5158 settings. However, note that there are many options that are not mentioned at
5159 all in the default configuration.
5160
5161
5162 7.1 Macros
5163 ----------
5164
5165 All macros should be defined before any options.
5166
5167 One macro is specified, but commented out, in the default configuration:
5168
5169 # ROUTER_SMARTHOST=MAIL.HOSTNAME.FOR.CENTRAL.SERVER.EXAMPLE
5170
5171 If all off-site mail is expected to be delivered to a "smarthost", then set the
5172 hostname here and uncomment the macro. This will affect which router is used
5173 later on. If this is left commented out, then Exim will perform direct-to-MX
5174 deliveries using a dnslookup router.
5175
5176 In addition to macros defined here, Exim includes a number of built-in macros
5177 to enable configuration to be guarded by a binary built with support for a
5178 given feature. See section 6.9 for more details.
5179
5180
5181 7.2 Main configuration settings
5182 -------------------------------
5183
5184 The main (global) configuration option settings section must always come first
5185 in the file, after the macros. The first thing you'll see in the file, after
5186 some initial comments, is the line
5187
5188 # primary_hostname =
5189
5190 This is a commented-out setting of the primary_hostname option. Exim needs to
5191 know the official, fully qualified name of your host, and this is where you can
5192 specify it. However, in most cases you do not need to set this option. When it
5193 is unset, Exim uses the uname() system function to obtain the host name.
5194
5195 The first three non-comment configuration lines are as follows:
5196
5197 domainlist local_domains = @
5198 domainlist relay_to_domains =
5199 hostlist relay_from_hosts = 127.0.0.1
5200
5201 These are not, in fact, option settings. They are definitions of two named
5202 domain lists and one named host list. Exim allows you to give names to lists of
5203 domains, hosts, and email addresses, in order to make it easier to manage the
5204 configuration file (see section 10.5).
5205
5206 The first line defines a domain list called local_domains; this is used later
5207 in the configuration to identify domains that are to be delivered on the local
5208 host.
5209
5210 There is just one item in this list, the string "@". This is a special form of
5211 entry which means "the name of the local host". Thus, if the local host is
5212 called a.host.example, mail to any.user@a.host.example is expected to be
5213 delivered locally. Because the local host's name is referenced indirectly, the
5214 same configuration file can be used on different hosts.
5215
5216 The second line defines a domain list called relay_to_domains, but the list
5217 itself is empty. Later in the configuration we will come to the part that
5218 controls mail relaying through the local host; it allows relaying to any
5219 domains in this list. By default, therefore, no relaying on the basis of a mail
5220 domain is permitted.
5221
5222 The third line defines a host list called relay_from_hosts. This list is used
5223 later in the configuration to permit relaying from any host or IP address that
5224 matches the list. The default contains just the IP address of the IPv4 loopback
5225 interface, which means that processes on the local host are able to submit mail
5226 for relaying by sending it over TCP/IP to that interface. No other hosts are
5227 permitted to submit messages for relaying.
5228
5229 Just to be sure there's no misunderstanding: at this point in the configuration
5230 we aren't actually setting up any controls. We are just defining some domains
5231 and hosts that will be used in the controls that are specified later.
5232
5233 The next two configuration lines are genuine option settings:
5234
5235 acl_smtp_rcpt = acl_check_rcpt
5236 acl_smtp_data = acl_check_data
5237
5238 These options specify Access Control Lists (ACLs) that are to be used during an
5239 incoming SMTP session for every recipient of a message (every RCPT command),
5240 and after the contents of the message have been received, respectively. The
5241 names of the lists are acl_check_rcpt and acl_check_data, and we will come to
5242 their definitions below, in the ACL section of the configuration. The RCPT ACL
5243 controls which recipients are accepted for an incoming message - if a
5244 configuration does not provide an ACL to check recipients, no SMTP mail can be
5245 accepted. The DATA ACL allows the contents of a message to be checked.
5246
5247 Two commented-out option settings are next:
5248
5249 # av_scanner = clamd:/tmp/clamd
5250 # spamd_address = 127.0.0.1 783
5251
5252 These are example settings that can be used when Exim is compiled with the
5253 content-scanning extension. The first specifies the interface to the virus
5254 scanner, and the second specifies the interface to SpamAssassin. Further
5255 details are given in chapter 44.
5256
5257 Three more commented-out option settings follow:
5258
5259 # tls_advertise_hosts = *
5260 # tls_certificate = /etc/ssl/exim.crt
5261 # tls_privatekey = /etc/ssl/exim.pem
5262
5263 These are example settings that can be used when Exim is compiled with support
5264 for TLS (aka SSL) as described in section 4.7. The first one specifies the list
5265 of clients that are allowed to use TLS when connecting to this server; in this
5266 case, the wildcard means all clients. The other options specify where Exim
5267 should find its TLS certificate and private key, which together prove the
5268 server's identity to any clients that connect. More details are given in
5269 chapter 42.
5270
5271 Another two commented-out option settings follow:
5272
5273 # daemon_smtp_ports = 25 : 465 : 587
5274 # tls_on_connect_ports = 465
5275
5276 These options provide better support for roaming users who wish to use this
5277 server for message submission. They are not much use unless you have turned on
5278 TLS (as described in the previous paragraph) and authentication (about which
5279 more in section 7.8). Mail submission from mail clients (MUAs) should be
5280 separate from inbound mail to your domain (MX delivery) for various good
5281 reasons (eg, ability to impose much saner TLS protocol and ciphersuite
5282 requirements without unintended consequences). RFC 6409 (previously 4409)
5283 specifies use of port 587 for SMTP Submission, which uses STARTTLS, so this is
5284 the "submission" port. RFC 8314 specifies use of port 465 as the "submissions"
5285 protocol, which should be used in preference to 587. You should also consider
5286 deploying SRV records to help clients find these ports. Older names for
5287 "submissions" are "smtps" and "ssmtp".
5288
5289 Two more commented-out options settings follow:
5290
5291 # qualify_domain =
5292 # qualify_recipient =
5293
5294 The first of these specifies a domain that Exim uses when it constructs a
5295 complete email address from a local login name. This is often needed when Exim
5296 receives a message from a local process. If you do not set qualify_domain, the
5297 value of primary_hostname is used. If you set both of these options, you can
5298 have different qualification domains for sender and recipient addresses. If you
5299 set only the first one, its value is used in both cases.
5300
5301 The following line must be uncommented if you want Exim to recognize addresses
5302 of the form user@[10.11.12.13] that is, with a "domain literal" (an IP address
5303 within square brackets) instead of a named domain.
5304
5305 # allow_domain_literals
5306
5307 The RFCs still require this form, but many people think that in the modern
5308 Internet it makes little sense to permit mail to be sent to specific hosts by
5309 quoting their IP addresses. This ancient format has been used by people who try
5310 to abuse hosts by using them for unwanted relaying. However, some people
5311 believe there are circumstances (for example, messages addressed to postmaster)
5312 where domain literals are still useful.
5313
5314 The next configuration line is a kind of trigger guard:
5315
5316 never_users = root
5317
5318 It specifies that no delivery must ever be run as the root user. The normal
5319 convention is to set up root as an alias for the system administrator. This
5320 setting is a guard against slips in the configuration. The list of users
5321 specified by never_users is not, however, the complete list; the build-time
5322 configuration in Local/Makefile has an option called FIXED_NEVER_USERS
5323 specifying a list that cannot be overridden. The contents of never_users are
5324 added to this list. By default FIXED_NEVER_USERS also specifies root.
5325
5326 When a remote host connects to Exim in order to send mail, the only information
5327 Exim has about the host's identity is its IP address. The next configuration
5328 line,
5329
5330 host_lookup = *
5331
5332 specifies that Exim should do a reverse DNS lookup on all incoming connections,
5333 in order to get a host name. This improves the quality of the logging
5334 information, but if you feel it is too expensive, you can remove it entirely,
5335 or restrict the lookup to hosts on "nearby" networks. Note that it is not
5336 always possible to find a host name from an IP address, because not all DNS
5337 reverse zones are maintained, and sometimes DNS servers are unreachable.
5338
5339 The next two lines are concerned with ident callbacks, as defined by RFC 1413
5340 (hence their names):
5341
5342 rfc1413_hosts = *
5343 rfc1413_query_timeout = 0s
5344
5345 These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
5346 Few hosts offer RFC1413 service these days; calls have to be terminated by a
5347 timeout and this needlessly delays the startup of an incoming SMTP connection.
5348 If you have hosts for which you trust RFC1413 and need this information, you
5349 can change this.
5350
5351 This line enables an efficiency SMTP option. It is negotiated by clients and
5352 not expected to cause problems but can be disabled if needed.
5353
5354 prdr_enable = true
5355
5356 When Exim receives messages over SMTP connections, it expects all addresses to
5357 be fully qualified with a domain, as required by the SMTP definition. However,
5358 if you are running a server to which simple clients submit messages, you may
5359 find that they send unqualified addresses. The two commented-out options:
5360
5361 # sender_unqualified_hosts =
5362 # recipient_unqualified_hosts =
5363
5364 show how you can specify hosts that are permitted to send unqualified sender
5365 and recipient addresses, respectively.
5366
5367 The log_selector option is used to increase the detail of logging over the
5368 default:
5369
5370 log_selector = +smtp_protocol_error +smtp_syntax_error \
5371 +tls_certificate_verified
5372
5373 The percent_hack_domains option is also commented out:
5374
5375 # percent_hack_domains =
5376
5377 It provides a list of domains for which the "percent hack" is to operate. This
5378 is an almost obsolete form of explicit email routing. If you do not know
5379 anything about it, you can safely ignore this topic.
5380
5381 The next two settings in the main part of the default configuration are
5382 concerned with messages that have been "frozen" on Exim's queue. When a message
5383 is frozen, Exim no longer continues to try to deliver it. Freezing occurs when
5384 a bounce message encounters a permanent failure because the sender address of
5385 the original message that caused the bounce is invalid, so the bounce cannot be
5386 delivered. This is probably the most common case, but there are also other
5387 conditions that cause freezing, and frozen messages are not always bounce
5388 messages.
5389
5390 ignore_bounce_errors_after = 2d
5391 timeout_frozen_after = 7d
5392
5393 The first of these options specifies that failing bounce messages are to be
5394 discarded after 2 days in the queue. The second specifies that any frozen
5395 message (whether a bounce message or not) is to be timed out (and discarded)
5396 after a week. In this configuration, the first setting ensures that no failing
5397 bounce message ever lasts a week.
5398
5399 Exim queues it's messages in a spool directory. If you expect to have large
5400 queues, you may consider using this option. It splits the spool directory into
5401 subdirectories to avoid file system degradation from many files in a single
5402 directory, resulting in better performance. Manual manipulation of queued
5403 messages becomes more complex (though fortunately not often needed).
5404
5405 # split_spool_directory = true
5406
5407 In an ideal world everybody follows the standards. For non-ASCII messages RFC
5408 2047 is a standard, allowing a maximum line length of 76 characters. Exim
5409 adheres that standard and won't process messages which violate this standard.
5410 (Even ${rfc2047:...} expansions will fail.) In particular, the Exim maintainers
5411 have had multiple reports of problems from Russian administrators of issues
5412 until they disable this check, because of some popular, yet buggy, mail
5413 composition software.
5414
5415 # check_rfc2047_length = false
5416
5417 If you need to be strictly RFC compliant you may wish to disable the 8BITMIME
5418 advertisement. Use this, if you exchange mails with systems that are not 8-bit
5419 clean.
5420
5421 # accept_8bitmime = false
5422
5423 Libraries you use may depend on specific environment settings. This imposes a
5424 security risk (e.g. PATH). There are two lists: keep_environment for the
5425 variables to import as they are, and add_environment for variables we want to
5426 set to a fixed value. Note that TZ is handled separately, by the $%timezone%$
5427 runtime option and by the TIMEZONE_DEFAULT buildtime option.
5428
5429 # keep_environment = ^LDAP
5430 # add_environment = PATH=/usr/bin::/bin
5431
5432
5433 7.3 ACL configuration
5434 ---------------------
5435
5436 In the default configuration, the ACL section follows the main configuration.
5437 It starts with the line
5438
5439 begin acl
5440
5441 and it contains the definitions of two ACLs, called acl_check_rcpt and
5442 acl_check_data, that were referenced in the settings of acl_smtp_rcpt and
5443 acl_smtp_data above.
5444
5445 The first ACL is used for every RCPT command in an incoming SMTP message. Each
5446 RCPT command specifies one of the message's recipients. The ACL statements are
5447 considered in order, until the recipient address is either accepted or
5448 rejected. The RCPT command is then accepted or rejected, according to the
5449 result of the ACL processing.
5450
5451 acl_check_rcpt:
5452
5453 This line, consisting of a name terminated by a colon, marks the start of the
5454 ACL, and names it.
5455
5456 accept hosts = :
5457
5458 This ACL statement accepts the recipient if the sending host matches the list.
5459 But what does that strange list mean? It doesn't actually contain any host
5460 names or IP addresses. The presence of the colon puts an empty item in the
5461 list; Exim matches this only if the incoming message did not come from a remote
5462 host, because in that case, the remote hostname is empty. The colon is
5463 important. Without it, the list itself is empty, and can never match anything.
5464
5465 What this statement is doing is to accept unconditionally all recipients in
5466 messages that are submitted by SMTP from local processes using the standard
5467 input and output (that is, not using TCP/IP). A number of MUAs operate in this
5468 manner.
5469
5470 deny message = Restricted characters in address
5471 domains = +local_domains
5472 local_parts = ^[.] : ^.*[@%!/|]
5473
5474 deny message = Restricted characters in address
5475 domains = !+local_domains
5476 local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
5477
5478 These statements are concerned with local parts that contain any of the
5479 characters "@", "%", "!", "/", "|", or dots in unusual places. Although these
5480 characters are entirely legal in local parts (in the case of "@" and leading
5481 dots, only if correctly quoted), they do not commonly occur in Internet mail
5482 addresses.
5483
5484 The first three have in the past been associated with explicitly routed
5485 addresses (percent is still sometimes used - see the percent_hack_domains
5486 option). Addresses containing these characters are regularly tried by spammers
5487 in an attempt to bypass relaying restrictions, and also by open relay testing
5488 programs. Unless you really need them it is safest to reject these characters
5489 at this early stage. This configuration is heavy-handed in rejecting these
5490 characters for all messages it accepts from remote hosts. This is a deliberate
5491 policy of being as safe as possible.
5492
5493 The first rule above is stricter, and is applied to messages that are addressed
5494 to one of the local domains handled by this host. This is implemented by the
5495 first condition, which restricts it to domains that are listed in the
5496 local_domains domain list. The "+" character is used to indicate a reference to
5497 a named list. In this configuration, there is just one domain in local_domains,
5498 but in general there may be many.
5499
5500 The second condition on the first statement uses two regular expressions to
5501 block local parts that begin with a dot or contain "@", "%", "!", "/", or "|".
5502 If you have local accounts that include these characters, you will have to
5503 modify this rule.
5504
5505 Empty components (two dots in a row) are not valid in RFC 2822, but Exim allows
5506 them because they have been encountered in practice. (Consider the common
5507 convention of local parts constructed as "
5508 first-initial.second-initial.family-name" when applied to someone like the
5509 author of Exim, who has no second initial.) However, a local part starting with
5510 a dot or containing "/../" can cause trouble if it is used as part of a
5511 filename (for example, for a mailing list). This is also true for local parts
5512 that contain slashes. A pipe symbol can also be troublesome if the local part
5513 is incorporated unthinkingly into a shell command line.
5514
5515 The second rule above applies to all other domains, and is less strict. This
5516 allows your own users to send outgoing messages to sites that use slashes and
5517 vertical bars in their local parts. It blocks local parts that begin with a
5518 dot, slash, or vertical bar, but allows these characters within the local part.
5519 However, the sequence "/../" is barred. The use of "@", "%", and "!" is
5520 blocked, as before. The motivation here is to prevent your users (or your
5521 users' viruses) from mounting certain kinds of attack on remote sites.
5522
5523 accept local_parts = postmaster
5524 domains = +local_domains
5525
5526 This statement, which has two conditions, accepts an incoming address if the
5527 local part is postmaster and the domain is one of those listed in the
5528 local_domains domain list. The "+" character is used to indicate a reference to
5529 a named list. In this configuration, there is just one domain in local_domains,
5530 but in general there may be many.
5531
5532 The presence of this statement means that mail to postmaster is never blocked
5533 by any of the subsequent tests. This can be helpful while sorting out problems
5534 in cases where the subsequent tests are incorrectly denying access.
5535
5536 require verify = sender
5537
5538 This statement requires the sender address to be verified before any subsequent
5539 ACL statement can be used. If verification fails, the incoming recipient
5540 address is refused. Verification consists of trying to route the address, to
5541 see if a bounce message could be delivered to it. In the case of remote
5542 addresses, basic verification checks only the domain, but callouts can be used
5543 for more verification if required. Section 43.44 discusses the details of
5544 address verification.
5545
5546 accept hosts = +relay_from_hosts
5547 control = submission
5548
5549 This statement accepts the address if the message is coming from one of the
5550 hosts that are defined as being allowed to relay through this host. Recipient
5551 verification is omitted here, because in many cases the clients are dumb MUAs
5552 that do not cope well with SMTP error responses. For the same reason, the
5553 second line specifies "submission mode" for messages that are accepted. This is
5554 described in detail in section 47.1; it causes Exim to fix messages that are
5555 deficient in some way, for example, because they lack a Date: header line. If
5556 you are actually relaying out from MTAs, you should probably add recipient
5557 verification here, and disable submission mode.
5558
5559 accept authenticated = *
5560 control = submission
5561
5562 This statement accepts the address if the client host has authenticated itself.
5563 Submission mode is again specified, on the grounds that such messages are most
5564 likely to come from MUAs. The default configuration does not define any
5565 authenticators, though it does include some nearly complete commented-out
5566 examples described in 7.8. This means that no client can in fact authenticate
5567 until you complete the authenticator definitions.
5568
5569 require message = relay not permitted
5570 domains = +local_domains : +relay_to_domains
5571
5572 This statement rejects the address if its domain is neither a local domain nor
5573 one of the domains for which this host is a relay.
5574
5575 require verify = recipient
5576
5577 This statement requires the recipient address to be verified; if verification
5578 fails, the address is rejected.
5579
5580 # deny message = rejected because $sender_host_address \
5581 # is in a black list at $dnslist_domain\n\
5582 # $dnslist_text
5583 # dnslists = black.list.example
5584 #
5585 # warn dnslists = black.list.example
5586 # add_header = X-Warning: $sender_host_address is in \
5587 # a black list at $dnslist_domain
5588 # log_message = found in $dnslist_domain
5589
5590 These commented-out lines are examples of how you could configure Exim to check
5591 sending hosts against a DNS black list. The first statement rejects messages
5592 from blacklisted hosts, whereas the second just inserts a warning header line.
5593
5594 # require verify = csa
5595
5596 This commented-out line is an example of how you could turn on client SMTP
5597 authorization (CSA) checking. Such checks do DNS lookups for special SRV
5598 records.
5599
5600 accept
5601
5602 The final statement in the first ACL unconditionally accepts any recipient
5603 address that has successfully passed all the previous tests.
5604
5605 acl_check_data:
5606
5607 This line marks the start of the second ACL, and names it. Most of the contents
5608 of this ACL are commented out:
5609
5610 # deny malware = *
5611 # message = This message contains a virus \
5612 # ($malware_name).
5613
5614 These lines are examples of how to arrange for messages to be scanned for
5615 viruses when Exim has been compiled with the content-scanning extension, and a
5616 suitable virus scanner is installed. If the message is found to contain a
5617 virus, it is rejected with the given custom error message.
5618
5619 # warn spam = nobody
5620 # message = X-Spam_score: $spam_score\n\
5621 # X-Spam_score_int: $spam_score_int\n\
5622 # X-Spam_bar: $spam_bar\n\
5623 # X-Spam_report: $spam_report
5624
5625 These lines are an example of how to arrange for messages to be scanned by
5626 SpamAssassin when Exim has been compiled with the content-scanning extension,
5627 and SpamAssassin has been installed. The SpamAssassin check is run with
5628 "nobody" as its user parameter, and the results are added to the message as a
5629 series of extra header line. In this case, the message is not rejected,
5630 whatever the spam score.
5631
5632 accept
5633
5634 This final line in the DATA ACL accepts the message unconditionally.
5635
5636
5637 7.4 Router configuration
5638 ------------------------
5639
5640 The router configuration comes next in the default configuration, introduced by
5641 the line
5642
5643 begin routers
5644
5645 Routers are the modules in Exim that make decisions about where to send
5646 messages. An address is passed to each router, in turn, until it is either
5647 accepted, or failed. This means that the order in which you define the routers
5648 matters. Each router is fully described in its own chapter later in this
5649 manual. Here we give only brief overviews.
5650
5651 # domain_literal:
5652 # driver = ipliteral
5653 # domains = !+local_domains
5654 # transport = remote_smtp
5655
5656 This router is commented out because the majority of sites do not want to
5657 support domain literal addresses (those of the form user@[10.9.8.7]). If you
5658 uncomment this router, you also need to uncomment the setting of
5659 allow_domain_literals in the main part of the configuration.
5660
5661 Which router is used next depends upon whether or not the ROUTER_SMARTHOST
5662 macro has been defined, per
5663
5664 .ifdef ROUTER_SMARTHOST
5665 smarthost:
5666 #...
5667 .else
5668 dnslookup:
5669 #...
5670 .endif
5671
5672 If ROUTER_SMARTHOST has been defined, either at the top of the file or on the
5673 command-line, then we route all non-local mail to that smarthost; otherwise,
5674 we'll perform DNS lookups for direct-to-MX lookup. Any mail which is to a local
5675 domain will skip these routers because of the domains option.
5676
5677 smarthost:
5678 driver = manualroute
5679 domains = ! +local_domains
5680 transport = smarthost_smtp
5681 route_data = ROUTER_SMARTHOST
5682 ignore_target_hosts = <; 0.0.0.0 ; 127.0.0.0/8 ; ::1
5683 no_more
5684
5685 This router only handles mail which is not to any local domains; this is
5686 specified by the line
5687
5688 domains = ! +local_domains
5689
5690 The domains option lists the domains to which this router applies, but the
5691 exclamation mark is a negation sign, so the router is used only for domains
5692 that are not in the domain list called local_domains (which was defined at the
5693 start of the configuration). The plus sign before local_domains indicates that
5694 it is referring to a named list. Addresses in other domains are passed on to
5695 the following routers.
5696
5697 The name of the router driver is manualroute because we are manually specifying
5698 how mail should be routed onwards, instead of using DNS MX. While the name of
5699 this router instance is arbitrary, the driver option must be one of the driver
5700 modules that is in the Exim binary.
5701
5702 With no pre-conditions other than domains, all mail for non-local domains will
5703 be handled by this router, and the no_more setting will ensure that no other
5704 routers will be used for messages matching the pre-conditions. See 3.12 for
5705 more on how the pre-conditions apply. For messages which are handled by this
5706 router, we provide a hostname to deliver to in route_data and the macro
5707 supplies the value; the address is then queued for the smarthost_smtp
5708 transport.
5709
5710 dnslookup:
5711 driver = dnslookup
5712 domains = ! +local_domains
5713 transport = remote_smtp
5714 ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
5715 no_more
5716
5717 The domains option behaves as per smarthost, above.
5718
5719 The name of the router driver is dnslookup, and is specified by the driver
5720 option. Do not be confused by the fact that the name of this router instance is
5721 the same as the name of the driver. The instance name is arbitrary, but the
5722 name set in the driver option must be one of the driver modules that is in the
5723 Exim binary.
5724
5725 The dnslookup router routes addresses by looking up their domains in the DNS in
5726 order to obtain a list of hosts to which the address is routed. If the router
5727 succeeds, the address is queued for the remote_smtp transport, as specified by
5728 the transport option. If the router does not find the domain in the DNS, no
5729 further routers are tried because of the no_more setting, so the address fails
5730 and is bounced.
5731
5732 The ignore_target_hosts option specifies a list of IP addresses that are to be
5733 entirely ignored. This option is present because a number of cases have been
5734 encountered where MX records in the DNS point to host names whose IP addresses
5735 are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). Completely ignoring
5736 these IP addresses causes Exim to fail to route the email address, so it
5737 bounces. Otherwise, Exim would log a routing problem, and continue to try to
5738 deliver the message periodically until the address timed out.
5739
5740 system_aliases:
5741 driver = redirect
5742 allow_fail
5743 allow_defer
5744 data = ${lookup{$local_part}lsearch{/etc/aliases}}
5745 # user = exim
5746 file_transport = address_file
5747 pipe_transport = address_pipe
5748
5749 Control reaches this and subsequent routers only for addresses in the local
5750 domains. This router checks to see whether the local part is defined as an
5751 alias in the /etc/aliases file, and if so, redirects it according to the data
5752 that it looks up from that file. If no data is found for the local part, the
5753 value of the data option is empty, causing the address to be passed to the next
5754 router.
5755
5756 /etc/aliases is a conventional name for the system aliases file that is often
5757 used. That is why it is referenced by from the default configuration file.
5758 However, you can change this by setting SYSTEM_ALIASES_FILE in Local/Makefile
5759 before building Exim.
5760
5761 userforward:
5762 driver = redirect
5763 check_local_user
5764 # local_part_suffix = +* : -*
5765 # local_part_suffix_optional
5766 file = $home/.forward
5767 # allow_filter
5768 no_verify
5769 no_expn
5770 check_ancestor
5771 file_transport = address_file
5772 pipe_transport = address_pipe
5773 reply_transport = address_reply
5774
5775 This is the most complicated router in the default configuration. It is another
5776 redirection router, but this time it is looking for forwarding data set up by
5777 individual users. The check_local_user setting specifies a check that the local
5778 part of the address is the login name of a local user. If it is not, the router
5779 is skipped. The two commented options that follow check_local_user, namely:
5780
5781 # local_part_suffix = +* : -*
5782 # local_part_suffix_optional
5783
5784 show how you can specify the recognition of local part suffixes. If the first
5785 is uncommented, a suffix beginning with either a plus or a minus sign, followed
5786 by any sequence of characters, is removed from the local part and placed in the
5787 variable $local_part_suffix. The second suffix option specifies that the
5788 presence of a suffix in the local part is optional. When a suffix is present,
5789 the check for a local login uses the local part with the suffix removed.
5790
5791 When a local user account is found, the file called .forward in the user's home
5792 directory is consulted. If it does not exist, or is empty, the router declines.
5793 Otherwise, the contents of .forward are interpreted as redirection data (see
5794 chapter 22 for more details).
5795
5796 Traditional .forward files contain just a list of addresses, pipes, or files.
5797 Exim supports this by default. However, if allow_filter is set (it is commented
5798 out by default), the contents of the file are interpreted as a set of Exim or
5799 Sieve filtering instructions, provided the file begins with "#Exim filter" or "
5800 #Sieve filter", respectively. User filtering is discussed in the separate
5801 document entitled Exim's interfaces to mail filtering.
5802
5803 The no_verify and no_expn options mean that this router is skipped when
5804 verifying addresses, or when running as a consequence of an SMTP EXPN command.
5805 There are two reasons for doing this:
5806
5807 1. Whether or not a local user has a .forward file is not really relevant when
5808 checking an address for validity; it makes sense not to waste resources
5809 doing unnecessary work.
5810
5811 2. More importantly, when Exim is verifying addresses or handling an EXPN
5812 command during an SMTP session, it is running as the Exim user, not as
5813 root. The group is the Exim group, and no additional groups are set up. It
5814 may therefore not be possible for Exim to read users' .forward files at
5815 this time.
5816
5817 The setting of check_ancestor prevents the router from generating a new address
5818 that is the same as any previous address that was redirected. (This works round
5819 a problem concerning a bad interaction between aliasing and forwarding - see
5820 section 22.5).
5821
5822 The final three option settings specify the transports that are to be used when
5823 forwarding generates a direct delivery to a file, or to a pipe, or sets up an
5824 auto-reply, respectively. For example, if a .forward file contains
5825
5826 a.nother@elsewhere.example, /home/spqr/archive
5827
5828 the delivery to /home/spqr/archive is done by running the address_file
5829 transport.
5830
5831 localuser:
5832 driver = accept
5833 check_local_user
5834 # local_part_suffix = +* : -*
5835 # local_part_suffix_optional
5836 transport = local_delivery
5837
5838 The final router sets up delivery into local mailboxes, provided that the local
5839 part is the name of a local login, by accepting the address and assigning it to
5840 the local_delivery transport. Otherwise, we have reached the end of the
5841 routers, so the address is bounced. The commented suffix settings fulfil the
5842 same purpose as they do for the userforward router.
5843
5844
5845 7.5 Transport configuration
5846 ---------------------------
5847
5848 Transports define mechanisms for actually delivering messages. They operate
5849 only when referenced from routers, so the order in which they are defined does
5850 not matter. The transports section of the configuration starts with
5851
5852 begin transports
5853
5854 Two remote transports and four local transports are defined.
5855
5856 remote_smtp:
5857 driver = smtp
5858 message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}}
5859 .ifdef _HAVE_DANE
5860 dnssec_request_domains = *
5861 hosts_try_dane = *
5862 .endif
5863 .ifdef _HAVE_PRDR
5864 hosts_try_prdr = *
5865 .endif
5866
5867 This transport is used for delivering messages over SMTP connections. The list
5868 of remote hosts comes from the router. The message_size_limit usage is a hack
5869 to avoid sending on messages with over-long lines. The built-in macro
5870 _HAVE_DANE guards configuration to try to use DNSSEC for all queries and to use
5871 DANE for delivery; see section 42.15 for more details.
5872
5873 The hosts_try_prdr option enables an efficiency SMTP option. It is negotiated
5874 between client and server and not expected to cause problems but can be
5875 disabled if needed. The built-in macro _HAVE_PRDR guards the use of the
5876 hosts_try_prdr configuration option.
5877
5878 The other remote transport is used when delivering to a specific smarthost with
5879 whom there must be some kind of existing relationship, instead of the usual
5880 federated system.
5881
5882 smarthost_smtp:
5883 driver = smtp
5884 message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}}
5885 multi_domain
5886 #
5887 .ifdef _HAVE_TLS
5888 # Comment out any of these which you have to, then file a Support
5889 # request with your smarthost provider to get things fixed:
5890 hosts_require_tls = *
5891 tls_verify_hosts = *
5892 # As long as tls_verify_hosts is enabled, this won't matter, but if you
5893 # have to comment it out then this will at least log whether you succeed
5894 # or not:
5895 tls_try_verify_hosts = *
5896 #
5897 # The SNI name should match the name which we'll expect to verify;
5898 # many mail systems don't use SNI and this doesn't matter, but if it does,
5899 # we need to send a name which the remote site will recognize.
5900 # This _should_ be the name which the smarthost operators specified as
5901 # the hostname for sending your mail to.
5902 tls_sni = ROUTER_SMARTHOST
5903 #
5904 .ifdef _HAVE_OPENSSL
5905 tls_require_ciphers = HIGH:!aNULL:@STRENGTH
5906 .endif
5907 .ifdef _HAVE_GNUTLS
5908 tls_require_ciphers = SECURE192:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1
5909 .endif
5910 .endif
5911 .ifdef _HAVE_PRDR
5912 hosts_try_prdr = *
5913 .endif
5914
5915 After the same message_size_limit hack, we then specify that this Transport can
5916 handle messages to multiple domains in one run. The assumption here is that
5917 you're routing all non-local mail to the same place and that place is happy to
5918 take all messages from you as quickly as possible. All other options depend
5919 upon built-in macros; if Exim was built without TLS support then no other
5920 options are defined. If TLS is available, then we configure "stronger than
5921 default" TLS ciphersuites and versions using the tls_require_ciphers option,
5922 where the value to be used depends upon the library providing TLS. Beyond that,
5923 the options adopt the stance that you should have TLS support available from
5924 your smarthost on today's Internet, so we turn on requiring TLS for the mail to
5925 be delivered, and requiring that the certificate be valid, and match the
5926 expected hostname. The tls_sni option can be used by service providers to
5927 select an appropriate certificate to present to you and here we re-use the
5928 ROUTER_SMARTHOST macro, because that is unaffected by CNAMEs present in DNS.
5929 You want to specify the hostname which you'll expect to validate for, and that
5930 should not be subject to insecure tampering via DNS results.
5931
5932 For the hosts_try_prdr option see the previous transport.
5933
5934 All other options are defaulted.
5935
5936 local_delivery:
5937 driver = appendfile
5938 file = /var/mail/$local_part
5939 delivery_date_add
5940 envelope_to_add
5941 return_path_add
5942 # group = mail
5943 # mode = 0660
5944
5945 This appendfile transport is used for local delivery to user mailboxes in
5946 traditional BSD mailbox format. By default it runs under the uid and gid of the
5947 local user, which requires the sticky bit to be set on the /var/mail directory.
5948 Some systems use the alternative approach of running mail deliveries under a
5949 particular group instead of using the sticky bit. The commented options show
5950 how this can be done.
5951
5952 Exim adds three headers to the message as it delivers it: Delivery-date:,
5953 Envelope-to: and Return-path:. This action is requested by the three
5954 similarly-named options above.
5955
5956 address_pipe:
5957 driver = pipe
5958 return_output
5959
5960 This transport is used for handling deliveries to pipes that are generated by
5961 redirection (aliasing or users' .forward files). The return_output option
5962 specifies that any output on stdout or stderr generated by the pipe is to be
5963 returned to the sender.
5964
5965 address_file:
5966 driver = appendfile
5967 delivery_date_add
5968 envelope_to_add
5969 return_path_add
5970
5971 This transport is used for handling deliveries to files that are generated by
5972 redirection. The name of the file is not specified in this instance of
5973 appendfile, because it comes from the redirect router.
5974
5975 address_reply:
5976 driver = autoreply
5977
5978 This transport is used for handling automatic replies generated by users'
5979 filter files.
5980
5981
5982 7.6 Default retry rule
5983 ----------------------
5984
5985 The retry section of the configuration file contains rules which affect the way
5986 Exim retries deliveries that cannot be completed at the first attempt. It is
5987 introduced by the line
5988
5989 begin retry
5990
5991 In the default configuration, there is just one rule, which applies to all
5992 errors:
5993
5994 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
5995
5996 This causes any temporarily failing address to be retried every 15 minutes for
5997 2 hours, then at intervals starting at one hour and increasing by a factor of
5998 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
5999 is not delivered after 4 days of temporary failure, it is bounced. The time is
6000 measured from first failure, not from the time the message was received.
6001
6002 If the retry section is removed from the configuration, or is empty (that is,
6003 if no retry rules are defined), Exim will not retry deliveries. This turns
6004 temporary errors into permanent errors.
6005
6006
6007 7.7 Rewriting configuration
6008 ---------------------------
6009
6010 The rewriting section of the configuration, introduced by
6011
6012 begin rewrite
6013
6014 contains rules for rewriting addresses in messages as they arrive. There are no
6015 rewriting rules in the default configuration file.
6016
6017
6018 7.8 Authenticators configuration
6019 --------------------------------
6020
6021 The authenticators section of the configuration, introduced by
6022
6023 begin authenticators
6024
6025 defines mechanisms for the use of the SMTP AUTH command. The default
6026 configuration file contains two commented-out example authenticators which
6027 support plaintext username/password authentication using the standard PLAIN
6028 mechanism and the traditional but non-standard LOGIN mechanism, with Exim
6029 acting as the server. PLAIN and LOGIN are enough to support most MUA software.
6030
6031 The example PLAIN authenticator looks like this:
6032
6033 #PLAIN:
6034 # driver = plaintext
6035 # server_set_id = $auth2
6036 # server_prompts = :
6037 # server_condition = Authentication is not yet configured
6038 # server_advertise_condition = ${if def:tls_in_cipher }
6039
6040 And the example LOGIN authenticator looks like this:
6041
6042 #LOGIN:
6043 # driver = plaintext
6044 # server_set_id = $auth1
6045 # server_prompts = <| Username: | Password:
6046 # server_condition = Authentication is not yet configured
6047 # server_advertise_condition = ${if def:tls_in_cipher }
6048
6049 The server_set_id option makes Exim remember the authenticated username in
6050 $authenticated_id, which can be used later in ACLs or routers. The
6051 server_prompts option configures the plaintext authenticator so that it
6052 implements the details of the specific authentication mechanism, i.e. PLAIN or
6053 LOGIN. The server_advertise_condition setting controls when Exim offers
6054 authentication to clients; in the examples, this is only when TLS or SSL has
6055 been started, so to enable the authenticators you also need to add support for
6056 TLS as described in section 7.2.
6057
6058 The server_condition setting defines how to verify that the username and
6059 password are correct. In the examples it just produces an error message. To
6060 make the authenticators work, you can use a string expansion expression like
6061 one of the examples in chapter 34.
6062
6063 Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
6064 usercode and password are in different positions. Chapter 34 covers both.
6065
6066
6067
6068 ===============================================================================
6069 8. REGULAR EXPRESSIONS
6070
6071 Exim supports the use of regular expressions in many of its options. It uses
6072 the PCRE regular expression library; this provides regular expression matching
6073 that is compatible with Perl 5. The syntax and semantics of regular expressions
6074 is discussed in online Perl manpages, in many Perl reference books, and also in
6075 Jeffrey Friedl's Mastering Regular Expressions, which is published by O'Reilly
6076 (see http://www.oreilly.com/catalog/regex2/).
6077
6078 The documentation for the syntax and semantics of the regular expressions that
6079 are supported by PCRE is included in the PCRE distribution, and no further
6080 description is included here. The PCRE functions are called from Exim using the
6081 default option settings (that is, with no PCRE options set), except that the
6082 PCRE_CASELESS option is set when the matching is required to be
6083 case-insensitive.
6084
6085 In most cases, when a regular expression is required in an Exim configuration,
6086 it has to start with a circumflex, in order to distinguish it from plain text
6087 or an "ends with" wildcard. In this example of a configuration setting, the
6088 second item in the colon-separated list is a regular expression.
6089
6090 domains = a.b.c : ^\\d{3} : *.y.z : ...
6091
6092 The doubling of the backslash is required because of string expansion that
6093 precedes interpretation - see section 11.1 for more discussion of this issue,
6094 and a way of avoiding the need for doubling backslashes. The regular expression
6095 that is eventually used in this example contains just one backslash. The
6096 circumflex is included in the regular expression, and has the normal effect of
6097 "anchoring" it to the start of the string that is being matched.
6098
6099 There are, however, two cases where a circumflex is not required for the
6100 recognition of a regular expression: these are the match condition in a string
6101 expansion, and the matches condition in an Exim filter file. In these cases,
6102 the relevant string is always treated as a regular expression; if it does not
6103 start with a circumflex, the expression is not anchored, and can match anywhere
6104 in the subject string.
6105
6106 In all cases, if you want a regular expression to match at the end of a string,
6107 you must code the $ metacharacter to indicate this. For example:
6108
6109 domains = ^\\d{3}\\.example
6110
6111 matches the domain 123.example, but it also matches 123.example.com. You need
6112 to use:
6113
6114 domains = ^\\d{3}\\.example\$
6115
6116 if you want example to be the top-level domain. The backslash before the $ is
6117 needed because string expansion also interprets dollar characters.
6118
6119
6120
6121 ===============================================================================
6122 9. FILE AND DATABASE LOOKUPS
6123
6124 Exim can be configured to look up data in files or databases as it processes
6125 messages. Two different kinds of syntax are used:
6126
6127 1. A string that is to be expanded may contain explicit lookup requests. These
6128 cause parts of the string to be replaced by data that is obtained from the
6129 lookup. Lookups of this type are conditional expansion items. Different
6130 results can be defined for the cases of lookup success and failure. See
6131 chapter 11, where string expansions are described in detail. The key for
6132 the lookup is specified as part of the string expansion.
6133
6134 2. Lists of domains, hosts, and email addresses can contain lookup requests as
6135 a way of avoiding excessively long linear lists. In this case, the data
6136 that is returned by the lookup is often (but not always) discarded; whether
6137 the lookup succeeds or fails is what really counts. These kinds of list are
6138 described in chapter 10. The key for the lookup is given by the context in
6139 which the list is expanded.
6140
6141 String expansions, lists, and lookups interact with each other in such a way
6142 that there is no order in which to describe any one of them that does not
6143 involve references to the others. Each of these three chapters makes more sense
6144 if you have read the other two first. If you are reading this for the first
6145 time, be aware that some of it will make a lot more sense after you have read
6146 chapters 10 and 11.
6147
6148
6149 9.1 Examples of different lookup syntax
6150 ---------------------------------------
6151
6152 It is easy to confuse the two different kinds of lookup, especially as the
6153 lists that may contain the second kind are always expanded before being
6154 processed as lists. Therefore, they may also contain lookups of the first kind.
6155 Be careful to distinguish between the following two examples:
6156
6157 domains = ${lookup{$sender_host_address}lsearch{/some/file}}
6158 domains = lsearch;/some/file
6159
6160 The first uses a string expansion, the result of which must be a domain list.
6161 No strings have been specified for a successful or a failing lookup; the
6162 defaults in this case are the looked-up data and an empty string, respectively.
6163 The expansion takes place before the string is processed as a list, and the
6164 file that is searched could contain lines like this:
6165
6166 192.168.3.4: domain1:domain2:...
6167 192.168.1.9: domain3:domain4:...
6168
6169 When the lookup succeeds, the result of the expansion is a list of domains (and
6170 possibly other types of item that are allowed in domain lists).
6171
6172 In the second example, the lookup is a single item in a domain list. It causes
6173 Exim to use a lookup to see if the domain that is being processed can be found
6174 in the file. The file could contains lines like this:
6175
6176 domain1:
6177 domain2:
6178
6179 Any data that follows the keys is not relevant when checking that the domain
6180 matches the list item.
6181
6182 It is possible, though no doubt confusing, to use both kinds of lookup at once.
6183 Consider a file containing lines like this:
6184
6185 192.168.5.6: lsearch;/another/file
6186
6187 If the value of $sender_host_address is 192.168.5.6, expansion of the first
6188 domains setting above generates the second setting, which therefore causes a
6189 second lookup to occur.
6190
6191 The rest of this chapter describes the different lookup types that are
6192 available. Any of them can be used in any part of the configuration where a
6193 lookup is permitted.
6194
6195
6196 9.2 Lookup types
6197 ----------------
6198
6199 Two different types of data lookup are implemented:
6200
6201 * The single-key type requires the specification of a file in which to look,
6202 and a single key to search for. The key must be a non-empty string for the
6203 lookup to succeed. The lookup type determines how the file is searched.
6204
6205 * The query-style type accepts a generalized database query. No particular
6206 key value is assumed by Exim for query-style lookups. You can use whichever
6207 Exim variables you need to construct the database query.
6208
6209 The code for each lookup type is in a separate source file that is included in
6210 the binary of Exim only if the corresponding compile-time option is set. The
6211 default settings in src/EDITME are:
6212
6213 LOOKUP_DBM=yes
6214 LOOKUP_LSEARCH=yes
6215
6216 which means that only linear searching and DBM lookups are included by default.
6217 For some types of lookup (e.g. SQL databases), you need to install appropriate
6218 libraries and header files before building Exim.
6219
6220
6221 9.3 Single-key lookup types
6222 ---------------------------
6223
6224 The following single-key lookup types are implemented:
6225
6226 * cdb: The given file is searched as a Constant DataBase file, using the key
6227 string without a terminating binary zero. The cdb format is designed for
6228 indexed files that are read frequently and never updated, except by total
6229 re-creation. As such, it is particularly suitable for large files
6230 containing aliases or other indexed data referenced by an MTA. Information
6231 about cdb and tools for building the files can be found in several places:
6232
6233 https://cr.yp.to/cdb.html
6234 http://www.corpit.ru/mjt/tinycdb.html
6235 https://packages.debian.org/stable/utils/freecdb
6236 https://github.com/philpennock/cdbtools (in Go)
6237
6238 A cdb distribution is not needed in order to build Exim with cdb support,
6239 because the code for reading cdb files is included directly in Exim itself.
6240 However, no means of building or testing cdb files is provided with Exim,
6241 so you need to obtain a cdb distribution in order to do this.
6242
6243 * dbm: Calls to DBM library functions are used to extract data from the given
6244 DBM file by looking up the record with the given key. A terminating binary
6245 zero is included in the key that is passed to the DBM library. See section
6246 4.4 for a discussion of DBM libraries.
6247
6248 For all versions of Berkeley DB, Exim uses the DB_HASH style of database
6249 when building DBM files using the exim_dbmbuild utility. However, when
6250 using Berkeley DB versions 3 or 4, it opens existing databases for reading
6251 with the DB_UNKNOWN option. This enables it to handle any of the types of
6252 database that the library supports, and can be useful for accessing DBM
6253 files created by other applications. (For earlier DB versions, DB_HASH is
6254 always used.)
6255
6256 * dbmjz: This is the same as dbm, except that the lookup key is interpreted
6257 as an Exim list; the elements of the list are joined together with ASCII
6258 NUL characters to form the lookup key. An example usage would be to
6259 authenticate incoming SMTP calls using the passwords from Cyrus SASL's /etc
6260 /sasldb2 file with the gsasl authenticator or Exim's own cram_md5
6261 authenticator.
6262
6263 * dbmnz: This is the same as dbm, except that a terminating binary zero is
6264 not included in the key that is passed to the DBM library. You may need
6265 this if you want to look up data in files that are created by or shared
6266 with some other application that does not use terminating zeros. For
6267 example, you need to use dbmnz rather than dbm if you want to authenticate
6268 incoming SMTP calls using the passwords from Courier's /etc/
6269 userdbshadow.dat file. Exim's utility program for creating DBM files (
6270 exim_dbmbuild) includes the zeros by default, but has an option to omit
6271 them (see section 53.9).
6272
6273 * dsearch: The given file must be a directory; this is searched for an entry
6274 whose name is the key by calling the lstat() function. The key may not
6275 contain any forward slash characters. If lstat() succeeds, the result of
6276 the lookup is the name of the entry, which may be a file, directory,
6277 symbolic link, or any other kind of directory entry. An example of how this
6278 lookup can be used to support virtual domains is given in section 50.7.
6279
6280 * iplsearch: The given file is a text file containing keys and data. A key is
6281 terminated by a colon or white space or the end of the line. The keys in
6282 the file must be IP addresses, or IP addresses with CIDR masks. Keys that
6283 involve IPv6 addresses must be enclosed in quotes to prevent the first
6284 internal colon being interpreted as a key terminator. For example:
6285
6286 1.2.3.4: data for 1.2.3.4
6287 192.168.0.0/16: data for 192.168.0.0/16
6288 "abcd::cdab": data for abcd::cdab
6289 "abcd:abcd::/32" data for abcd:abcd::/32
6290
6291 The key for an iplsearch lookup must be an IP address (without a mask). The
6292 file is searched linearly, using the CIDR masks where present, until a
6293 matching key is found. The first key that matches is used; there is no
6294 attempt to find a "best" match. Apart from the way the keys are matched,
6295 the processing for iplsearch is the same as for lsearch.
6296
6297 Warning 1: Unlike most other single-key lookup types, a file of data for
6298 iplsearch can not be turned into a DBM or cdb file, because those lookup
6299 types support only literal keys.
6300
6301 Warning 2: In a host list, you must always use net-iplsearch so that the
6302 implicit key is the host's IP address rather than its name (see section
6303 10.12).
6304
6305 * lsearch: The given file is a text file that is searched linearly for a line
6306 beginning with the search key, terminated by a colon or white space or the
6307 end of the line. The search is case-insensitive; that is, upper and lower
6308 case letters are treated as the same. The first occurrence of the key that
6309 is found in the file is used.
6310
6311 White space between the key and the colon is permitted. The remainder of
6312 the line, with leading and trailing white space removed, is the data. This
6313 can be continued onto subsequent lines by starting them with any amount of
6314 white space, but only a single space character is included in the data at
6315 such a junction. If the data begins with a colon, the key must be
6316 terminated by a colon, for example:
6317
6318 baduser: :fail:
6319
6320 Empty lines and lines beginning with # are ignored, even if they occur in
6321 the middle of an item. This is the traditional textual format of alias
6322 files. Note that the keys in an lsearch file are literal strings. There is
6323 no wildcarding of any kind.
6324
6325 In most lsearch files, keys are not required to contain colons or #
6326 characters, or white space. However, if you need this feature, it is
6327 available. If a key begins with a doublequote character, it is terminated
6328 only by a matching quote (or end of line), and the normal escaping rules
6329 apply to its contents (see section 6.17). An optional colon is permitted
6330 after quoted keys (exactly as for unquoted keys). There is no special
6331 handling of quotes for the data part of an lsearch line.
6332
6333 * nis: The given file is the name of a NIS map, and a NIS lookup is done with
6334 the given key, without a terminating binary zero. There is a variant called
6335 nis0 which does include the terminating binary zero in the key. This is
6336 reportedly needed for Sun-style alias files. Exim does not recognize NIS
6337 aliases; the full map names must be used.
6338
6339 * wildlsearch or nwildlsearch: These search a file linearly, like lsearch,
6340 but instead of being interpreted as a literal string, each key in the file
6341 may be wildcarded. The difference between these two lookup types is that
6342 for wildlsearch, each key in the file is string-expanded before being used,
6343 whereas for nwildlsearch, no expansion takes place.
6344
6345 Like lsearch, the testing is done case-insensitively. However, keys in the
6346 file that are regular expressions can be made case-sensitive by the use of
6347 "(-i)" within the pattern. The following forms of wildcard are recognized:
6348
6349 1. The string may begin with an asterisk to mean "ends with". For example:
6350
6351 *.a.b.c data for anything.a.b.c
6352 *fish data for anythingfish
6353
6354 2. The string may begin with a circumflex to indicate a regular
6355 expression. For example, for wildlsearch:
6356
6357 ^\N\d+\.a\.b\N data for <digits>.a.b
6358
6359 Note the use of "\N" to disable expansion of the contents of the
6360 regular expression. If you are using nwildlsearch, where the keys are
6361 not string-expanded, the equivalent entry is:
6362
6363 ^\d+\.a\.b data for <digits>.a.b
6364
6365 The case-insensitive flag is set at the start of compiling the regular
6366 expression, but it can be turned off by using "(-i)" at an appropriate
6367 point. For example, to make the entire pattern case-sensitive:
6368
6369 ^(?-i)\d+\.a\.b data for <digits>.a.b
6370
6371 If the regular expression contains white space or colon characters, you
6372 must either quote it (see lsearch above), or represent these characters
6373 in other ways. For example, "\s" can be used for white space and "\x3A"
6374 for a colon. This may be easier than quoting, because if you quote, you
6375 have to escape all the backslashes inside the quotes.
6376
6377 Note: It is not possible to capture substrings in a regular expression
6378 match for later use, because the results of all lookups are cached. If
6379 a lookup is repeated, the result is taken from the cache, and no actual
6380 pattern matching takes place. The values of all the numeric variables
6381 are unset after a (n)wildlsearch match.
6382
6383 3. Although I cannot see it being of much use, the general matching
6384 function that is used to implement (n)wildlsearch means that the string
6385 may begin with a lookup name terminated by a semicolon, and followed by
6386 lookup data. For example:
6387
6388 cdb;/some/file data for keys that match the file
6389
6390 The data that is obtained from the nested lookup is discarded.
6391
6392 Keys that do not match any of these patterns are interpreted literally. The
6393 continuation rules for the data are the same as for lsearch, and keys may
6394 be followed by optional colons.
6395
6396 Warning: Unlike most other single-key lookup types, a file of data for (n)
6397 wildlsearch can not be turned into a DBM or cdb file, because those lookup
6398 types support only literal keys.
6399
6400 * If Exim is built with SPF support, manual lookups can be done (as opposed
6401 to the standard ACL condition method. For details see section 57.4.
6402
6403
6404 9.4 Query-style lookup types
6405 ----------------------------
6406
6407 The supported query-style lookup types are listed below. Further details about
6408 many of them are given in later sections.
6409
6410 * dnsdb: This does a DNS search for one or more records whose domain names
6411 are given in the supplied query. The resulting data is the contents of the
6412 records. See section 9.10.
6413
6414 * ibase: This does a lookup in an InterBase database.
6415
6416 * ldap: This does an LDAP lookup using a query in the form of a URL, and
6417 returns attributes from a single entry. There is a variant called ldapm
6418 that permits values from multiple entries to be returned. A third variant
6419 called ldapdn returns the Distinguished Name of a single entry instead of
6420 any attribute values. See section 9.14.
6421
6422 * mysql: The format of the query is an SQL statement that is passed to a
6423 MySQL database. See section 9.21.
6424
6425 * nisplus: This does a NIS+ lookup using a query that can specify the name of
6426 the field to be returned. See section 9.20.
6427
6428 * oracle: The format of the query is an SQL statement that is passed to an
6429 Oracle database. See section 9.21.
6430
6431 * passwd is a query-style lookup with queries that are just user names. The
6432 lookup calls getpwnam() to interrogate the system password data, and on
6433 success, the result string is the same as you would get from an lsearch
6434 lookup on a traditional /etc/passwd file, though with "*" for the password
6435 value. For example:
6436
6437 *:42:42:King Rat:/home/kr:/bin/bash
6438
6439 * pgsql: The format of the query is an SQL statement that is passed to a
6440 PostgreSQL database. See section 9.21.
6441
6442 * redis: The format of the query is either a simple get or simple set, passed
6443 to a Redis database. See section 9.21.
6444
6445 * sqlite: The format of the query is a filename followed by an SQL statement
6446 that is passed to an SQLite database. See section 9.26.
6447
6448 * testdb: This is a lookup type that is used for testing Exim. It is not
6449 likely to be useful in normal operation.
6450
6451 * whoson: Whoson (http://whoson.sourceforge.net) is a protocol that allows a
6452 server to check whether a particular (dynamically allocated) IP address is
6453 currently allocated to a known (trusted) user and, optionally, to obtain
6454 the identity of the said user. For SMTP servers, Whoson was popular at one
6455 time for "POP before SMTP" authentication, but that approach has been
6456 superseded by SMTP authentication. In Exim, Whoson can be used to implement
6457 "POP before SMTP" checking using ACL statements such as
6458
6459 require condition = \
6460 ${lookup whoson {$sender_host_address}{yes}{no}}
6461
6462 The query consists of a single IP address. The value returned is the name
6463 of the authenticated user, which is stored in the variable $value. However,
6464 in this example, the data in $value is not used; the result of the lookup
6465 is one of the fixed strings "yes" or "no".
6466
6467
6468 9.5 Temporary errors in lookups
6469 -------------------------------
6470
6471 Lookup functions can return temporary error codes if the lookup cannot be
6472 completed. For example, an SQL or LDAP database might be unavailable. For this
6473 reason, it is not advisable to use a lookup that might do this for critical
6474 options such as a list of local domains.
6475
6476 When a lookup cannot be completed in a router or transport, delivery of the
6477 message (to the relevant address) is deferred, as for any other temporary
6478 error. In other circumstances Exim may assume the lookup has failed, or may
6479 give up altogether.
6480
6481
6482 9.6 Default values in single-key lookups
6483 ----------------------------------------
6484
6485 In this context, a "default value" is a value specified by the administrator
6486 that is to be used if a lookup fails.
6487
6488 Note: This section applies only to single-key lookups. For query-style lookups,
6489 the facilities of the query language must be used. An attempt to specify a
6490 default for a query-style lookup provokes an error.
6491
6492 If "*" is added to a single-key lookup type (for example, lsearch*) and the
6493 initial lookup fails, the key "*" is looked up in the file to provide a default
6494 value. See also the section on partial matching below.
6495
6496 Alternatively, if "*@" is added to a single-key lookup type (for example dbm*@)
6497 then, if the initial lookup fails and the key contains an @ character, a second
6498 lookup is done with everything before the last @ replaced by *. This makes it
6499 possible to provide per-domain defaults in alias files that include the domains
6500 in the keys. If the second lookup fails (or doesn't take place because there is
6501 no @ in the key), "*" is looked up. For example, a redirect router might
6502 contain:
6503
6504 data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}}
6505
6506 Suppose the address that is being processed is jane@eyre.example. Exim looks up
6507 these keys, in this order:
6508
6509 jane@eyre.example
6510 *@eyre.example
6511 *
6512
6513 The data is taken from whichever key it finds first. Note: In an lsearch file,
6514 this does not mean the first of these keys in the file. A complete scan is done
6515 for each key, and only if it is not found at all does Exim move on to try the
6516 next key.
6517
6518
6519 9.7 Partial matching in single-key lookups
6520 ------------------------------------------
6521
6522 The normal operation of a single-key lookup is to search the file for an exact
6523 match with the given key. However, in a number of situations where domains are
6524 being looked up, it is useful to be able to do partial matching. In this case,
6525 information in the file that has a key starting with "*." is matched by any
6526 domain that ends with the components that follow the full stop. For example, if
6527 a key in a DBM file is
6528
6529 *.dates.fict.example
6530
6531 then when partial matching is enabled this is matched by (amongst others)
6532 2001.dates.fict.example and 1984.dates.fict.example. It is also matched by
6533 dates.fict.example, if that does not appear as a separate key in the file.
6534
6535 Note: Partial matching is not available for query-style lookups. It is also not
6536 available for any lookup items in address lists (see section 10.19).
6537
6538 Partial matching is implemented by doing a series of separate lookups using
6539 keys constructed by modifying the original subject key. This means that it can
6540 be used with any of the single-key lookup types, provided that partial matching
6541 keys beginning with a special prefix (default "*.") are included in the data
6542 file. Keys in the file that do not begin with the prefix are matched only by
6543 unmodified subject keys when partial matching is in use.
6544
6545 Partial matching is requested by adding the string "partial-" to the front of
6546 the name of a single-key lookup type, for example, partial-dbm. When this is
6547 done, the subject key is first looked up unmodified; if that fails, "*." is
6548 added at the start of the subject key, and it is looked up again. If that
6549 fails, further lookups are tried with dot-separated components removed from the
6550 start of the subject key, one-by-one, and "*." added on the front of what
6551 remains.
6552
6553 A minimum number of two non-* components are required. This can be adjusted by
6554 including a number before the hyphen in the search type. For example,
6555 partial3-lsearch specifies a minimum of three non-* components in the modified
6556 keys. Omitting the number is equivalent to "partial2-". If the subject key is
6557 2250.dates.fict.example then the following keys are looked up when the minimum
6558 number of non-* components is two:
6559
6560 2250.dates.fict.example
6561 *.2250.dates.fict.example
6562 *.dates.fict.example
6563 *.fict.example
6564
6565 As soon as one key in the sequence is successfully looked up, the lookup
6566 finishes.
6567
6568 The use of "*." as the partial matching prefix is a default that can be
6569 changed. The motivation for this feature is to allow Exim to operate with file
6570 formats that are used by other MTAs. A different prefix can be supplied in
6571 parentheses instead of the hyphen after "partial". For example:
6572
6573 domains = partial(.)lsearch;/some/file
6574
6575 In this example, if the domain is a.b.c, the sequence of lookups is "a.b.c",
6576 ".a.b.c", and ".b.c" (the default minimum of 2 non-wild components is
6577 unchanged). The prefix may consist of any punctuation characters other than a
6578 closing parenthesis. It may be empty, for example:
6579
6580 domains = partial1()cdb;/some/file
6581
6582 For this example, if the domain is a.b.c, the sequence of lookups is "a.b.c",
6583 "b.c", and "c".
6584
6585 If "partial0" is specified, what happens at the end (when the lookup with just
6586 one non-wild component has failed, and the original key is shortened right down
6587 to the null string) depends on the prefix:
6588
6589 * If the prefix has zero length, the whole lookup fails.
6590
6591 * If the prefix has length 1, a lookup for just the prefix is done. For
6592 example, the final lookup for "partial0(.)" is for "." alone.
6593
6594 * Otherwise, if the prefix ends in a dot, the dot is removed, and the
6595 remainder is looked up. With the default prefix, therefore, the final
6596 lookup is for "*" on its own.
6597
6598 * Otherwise, the whole prefix is looked up.
6599
6600 If the search type ends in "*" or "*@" (see section 9.6 above), the search for
6601 an ultimate default that this implies happens after all partial lookups have
6602 failed. If "partial0" is specified, adding "*" to the search type has no effect
6603 with the default prefix, because the "*" key is already included in the
6604 sequence of partial lookups. However, there might be a use for lookup types
6605 such as "partial0(.)lsearch*".
6606
6607 The use of "*" in lookup partial matching differs from its use as a wildcard in
6608 domain lists and the like. Partial matching works only in terms of
6609 dot-separated components; a key such as "*fict.example" in a database file is
6610 useless, because the asterisk in a partial matching subject key is always
6611 followed by a dot.
6612
6613
6614 9.8 Lookup caching
6615 ------------------
6616
6617 Exim caches all lookup results in order to avoid needless repetition of
6618 lookups. However, because (apart from the daemon) Exim operates as a collection
6619 of independent, short-lived processes, this caching applies only within a
6620 single Exim process. There is no inter-process lookup caching facility.
6621
6622 For single-key lookups, Exim keeps the relevant files open in case there is
6623 another lookup that needs them. In some types of configuration this can lead to
6624 many files being kept open for messages with many recipients. To avoid hitting
6625 the operating system limit on the number of simultaneously open files, Exim
6626 closes the least recently used file when it needs to open more files than its
6627 own internal limit, which can be changed via the lookup_open_max option.
6628
6629 The single-key lookup files are closed and the lookup caches are flushed at
6630 strategic points during delivery - for example, after all routing is complete.
6631
6632
6633 9.9 Quoting lookup data
6634 -----------------------
6635
6636 When data from an incoming message is included in a query-style lookup, there
6637 is the possibility of special characters in the data messing up the syntax of
6638 the query. For example, a NIS+ query that contains
6639
6640 [name=$local_part]
6641
6642 will be broken if the local part happens to contain a closing square bracket.
6643 For NIS+, data can be enclosed in double quotes like this:
6644
6645 [name="$local_part"]
6646
6647 but this still leaves the problem of a double quote in the data. The rule for
6648 NIS+ is that double quotes must be doubled. Other lookup types have different
6649 rules, and to cope with the differing requirements, an expansion operator of
6650 the following form is provided:
6651
6652 ${quote_<lookup-type>:<string>}
6653
6654 For example, the safest way to write the NIS+ query is
6655
6656 [name="${quote_nisplus:$local_part}"]
6657
6658 See chapter 11 for full coverage of string expansions. The quote operator can
6659 be used for all lookup types, but has no effect for single-key lookups, since
6660 no quoting is ever needed in their key strings.
6661
6662
6663 9.10 More about dnsdb
6664 ---------------------
6665
6666 The dnsdb lookup type uses the DNS as its database. A simple query consists of
6667 a record type and a domain name, separated by an equals sign. For example, an
6668 expansion string could contain:
6669
6670 ${lookup dnsdb{mx=a.b.example}{$value}fail}
6671
6672 If the lookup succeeds, the result is placed in $value, which in this case is
6673 used on its own as the result. If the lookup does not succeed, the "fail"
6674 keyword causes a forced expansion failure - see section 11.4 for an explanation
6675 of what this means.
6676
6677 The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA
6678 and TXT, and, when Exim is compiled with IPv6 support, AAAA. If no type is
6679 given, TXT is assumed.
6680
6681 For any record type, if multiple records are found, the data is returned as a
6682 concatenation, with newline as the default separator. The order, of course,
6683 depends on the DNS resolver. You can specify a different separator character
6684 between multiple records by putting a right angle-bracket followed immediately
6685 by the new separator at the start of the query. For example:
6686
6687 ${lookup dnsdb{>: a=host1.example}}
6688
6689 It is permitted to specify a space as the separator character. Further white
6690 space is ignored. For lookup types that return multiple fields per record, an
6691 alternate field separator can be specified using a comma after the main
6692 separator character, followed immediately by the field separator.
6693
6694 When the type is PTR, the data can be an IP address, written as normal;
6695 inversion and the addition of in-addr.arpa or ip6.arpa happens automatically.
6696 For example:
6697
6698 ${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
6699
6700 If the data for a PTR record is not a syntactically valid IP address, it is not
6701 altered and nothing is added.
6702
6703 For an MX lookup, both the preference value and the host name are returned for
6704 each record, separated by a space. For an SRV lookup, the priority, weight,
6705 port, and host name are returned for each record, separated by spaces. The
6706 field separator can be modified as above.
6707
6708 For TXT records with multiple items of data, only the first item is returned,
6709 unless a field separator is specified. To concatenate items without a
6710 separator, use a semicolon instead. For SPF records the default behaviour is to
6711 concatenate multiple items without using a separator.
6712
6713 ${lookup dnsdb{>\n,: txt=a.b.example}}
6714 ${lookup dnsdb{>\n; txt=a.b.example}}
6715 ${lookup dnsdb{spf=example.org}}
6716
6717 It is permitted to specify a space as the separator character. Further white
6718 space is ignored.
6719
6720 For an SOA lookup, while no result is obtained the lookup is redone with
6721 successively more leading components dropped from the given domain. Only the
6722 primary-nameserver field is returned unless a field separator is specified.
6723
6724 ${lookup dnsdb{>:,; soa=a.b.example.com}}
6725
6726
6727 9.11 Dnsdb lookup modifiers
6728 ---------------------------
6729
6730 Modifiers for dnsdb lookups are given by optional keywords, each followed by a
6731 comma, that may appear before the record type.
6732
6733 The dnsdb lookup fails only if all the DNS lookups fail. If there is a
6734 temporary DNS error for any of them, the behaviour is controlled by a
6735 defer-option modifier. The possible keywords are "defer_strict", "defer_never",
6736 and "defer_lax". With "strict" behaviour, any temporary DNS error causes the
6737 whole lookup to defer. With "never" behaviour, a temporary DNS error is
6738 ignored, and the behaviour is as if the DNS lookup failed to find anything.
6739 With "lax" behaviour, all the queries are attempted, but a temporary DNS error
6740 causes the whole lookup to defer only if none of the other lookups succeed. The
6741 default is "lax", so the following lookups are equivalent:
6742
6743 ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
6744 ${lookup dnsdb{a=one.host.com:two.host.com}}
6745
6746 Thus, in the default case, as long as at least one of the DNS lookups yields
6747 some data, the lookup succeeds.
6748
6749 Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are
6750 "dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax"
6751 DNSSEC information is requested with the lookup. With "strict" a response from
6752 the DNS resolver that is not labelled as authenticated data is treated as
6753 equivalent to a temporary DNS error. The default is "never".
6754
6755 See also the $lookup_dnssec_authenticated variable.
6756
6757 Timeout for the dnsdb lookup can be controlled by a retrans modifier. The form
6758 is "retrans_VAL" where VAL is an Exim time specification (e.g. "5s"). The
6759 default value is set by the main configuration option dns_retrans.
6760
6761 Retries for the dnsdb lookup can be controlled by a retry modifier. The form if
6762 "retry_VAL" where VAL is an integer. The default count is set by the main
6763 configuration option dns_retry.
6764
6765 Dnsdb lookup results are cached within a single process (and its children). The
6766 cache entry lifetime is limited to the smallest time-to-live (TTL) value of the
6767 set of returned DNS records.
6768
6769
6770 9.12 Pseudo dnsdb record types
6771 ------------------------------
6772
6773 By default, both the preference value and the host name are returned for each
6774 MX record, separated by a space. If you want only host names, you can use the
6775 pseudo-type MXH:
6776
6777 ${lookup dnsdb{mxh=a.b.example}}
6778
6779 In this case, the preference values are omitted, and just the host names are
6780 returned.
6781
6782 Another pseudo-type is ZNS (for "zone NS"). It performs a lookup for NS records
6783 on the given domain, but if none are found, it removes the first component of
6784 the domain name, and tries again. This process continues until NS records are
6785 found or there are no more components left (or there is a DNS error). In other
6786 words, it may return the name servers for a top-level domain, but it never
6787 returns the root name servers. If there are no NS records for the top-level
6788 domain, the lookup fails. Consider these examples:
6789
6790 ${lookup dnsdb{zns=xxx.quercite.com}}
6791 ${lookup dnsdb{zns=xxx.edu}}
6792
6793 Assuming that in each case there are no NS records for the full domain name,
6794 the first returns the name servers for quercite.com, and the second returns the
6795 name servers for edu.
6796
6797 You should be careful about how you use this lookup because, unless the
6798 top-level domain does not exist, the lookup always returns some host names. The
6799 sort of use to which this might be put is for seeing if the name servers for a
6800 given domain are on a blacklist. You can probably assume that the name servers
6801 for the high-level domains such as com or co.uk are not going to be on such a
6802 list.
6803
6804 A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV
6805 records according to the CSA rules, which are described in section 43.50.
6806 Although dnsdb supports SRV lookups directly, this is not sufficient because of
6807 the extra parent domain search behaviour of CSA. The result of a successful
6808 lookup such as:
6809
6810 ${lookup dnsdb {csa=$sender_helo_name}}
6811
6812 has two space-separated fields: an authorization code and a target host name.
6813 The authorization code can be "Y" for yes, "N" for no, "X" for explicit
6814 authorization required but absent, or "?" for unknown.
6815
6816 The pseudo-type A+ performs an AAAA and then an A lookup. All results are
6817 returned; defer processing (see below) is handled separately for each lookup.
6818 Example:
6819
6820 ${lookup dnsdb {>; a+=$sender_helo_name}}
6821
6822
6823 9.13 Multiple dnsdb lookups
6824 ---------------------------
6825
6826 In the previous sections, dnsdb lookups for a single domain are described.
6827 However, you can specify a list of domains or IP addresses in a single dnsdb
6828 lookup. The list is specified in the normal Exim way, with colon as the default
6829 separator, but with the ability to change this. For example:
6830
6831 ${lookup dnsdb{one.domain.com:two.domain.com}}
6832 ${lookup dnsdb{a=one.host.com:two.host.com}}
6833 ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}}
6834
6835 In order to retain backwards compatibility, there is one special case: if the
6836 lookup type is PTR and no change of separator is specified, Exim looks to see
6837 if the rest of the string is precisely one IPv6 address. In this case, it does
6838 not treat it as a list.
6839
6840 The data from each lookup is concatenated, with newline separators by default,
6841 in the same way that multiple DNS records for a single item are handled. A
6842 different separator can be specified, as described above.
6843
6844
6845 9.14 More about LDAP
6846 --------------------
6847
6848 The original LDAP implementation came from the University of Michigan; this has
6849 become "Open LDAP", and there are now two different releases. Another
6850 implementation comes from Netscape, and Solaris 7 and subsequent releases
6851 contain inbuilt LDAP support. Unfortunately, though these are all compatible at
6852 the lookup function level, their error handling is different. For this reason
6853 it is necessary to set a compile-time variable when building Exim with LDAP, to
6854 indicate which LDAP library is in use. One of the following should appear in
6855 your Local/Makefile:
6856
6857 LDAP_LIB_TYPE=UMICHIGAN
6858 LDAP_LIB_TYPE=OPENLDAP1
6859 LDAP_LIB_TYPE=OPENLDAP2
6860 LDAP_LIB_TYPE=NETSCAPE
6861 LDAP_LIB_TYPE=SOLARIS
6862
6863 If LDAP_LIB_TYPE is not set, Exim assumes "OPENLDAP1", which has the same
6864 interface as the University of Michigan version.
6865
6866 There are three LDAP lookup types in Exim. These behave slightly differently in
6867 the way they handle the results of a query:
6868
6869 * ldap requires the result to contain just one entry; if there are more, it
6870 gives an error.
6871
6872 * ldapdn also requires the result to contain just one entry, but it is the
6873 Distinguished Name that is returned rather than any attribute values.
6874
6875 * ldapm permits the result to contain more than one entry; the attributes
6876 from all of them are returned.
6877
6878 For ldap and ldapm, if a query finds only entries with no attributes, Exim
6879 behaves as if the entry did not exist, and the lookup fails. The format of the
6880 data returned by a successful lookup is described in the next section. First we
6881 explain how LDAP queries are coded.
6882
6883
6884 9.15 Format of LDAP queries
6885 ---------------------------
6886
6887 An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
6888 the configuration of a redirect router one might have this setting:
6889
6890 data = ${lookup ldap \
6891 {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
6892 c=UK?mailbox?base?}}
6893
6894 The URL may begin with "ldap" or "ldaps" if your LDAP library supports secure
6895 (encrypted) LDAP connections. The second of these ensures that an encrypted TLS
6896 connection is used.
6897
6898 With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular
6899 LDAP connections, rather than the SSL-on-connect "ldaps". See the
6900 ldap_start_tls option.
6901
6902 Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly
6903 controlled. Every part of the TLS configuration can be configured by settings
6904 in exim.conf. Depending on the version of the client libraries installed on
6905 your system, some of the initialization may have required setting options in /
6906 etc/ldap.conf or ~/.ldaprc to get TLS working with self-signed certificates.
6907 This revealed a nuance where the current UID that exim was running as could
6908 affect which config files it read. With Exim 4.83, these methods become
6909 optional, only taking effect if not specifically set in exim.conf.
6910
6911
6912 9.16 LDAP quoting
6913 -----------------
6914
6915 Two levels of quoting are required in LDAP queries, the first for LDAP itself
6916 and the second because the LDAP query is represented as a URL. Furthermore,
6917 within an LDAP query, two different kinds of quoting are required. For this
6918 reason, there are two different LDAP-specific quoting operators.
6919
6920 The quote_ldap operator is designed for use on strings that are part of filter
6921 specifications. Conceptually, it first does the following conversions on the
6922 string:
6923
6924 * => \2A
6925 ( => \28
6926 ) => \29
6927 \ => \5C
6928
6929 in accordance with RFC 2254. The resulting string is then quoted according to
6930 the rules for URLs, that is, all non-alphanumeric characters except
6931
6932 ! $ ' - . _ ( ) * +
6933
6934 are converted to their hex values, preceded by a percent sign. For example:
6935
6936 ${quote_ldap: a(bc)*, a<yz>; }
6937
6938 yields
6939
6940 %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
6941
6942 Removing the URL quoting, this is (with a leading and a trailing space):
6943
6944 a\28bc\29\2A, a<yz>;
6945
6946 The quote_ldap_dn operator is designed for use on strings that are part of base
6947 DN specifications in queries. Conceptually, it first converts the string by
6948 inserting a backslash in front of any of the following characters:
6949
6950 , + " \ < > ;
6951
6952 It also inserts a backslash before any leading spaces or # characters, and
6953 before any trailing spaces. (These rules are in RFC 2253.) The resulting string
6954 is then quoted according to the rules for URLs. For example:
6955
6956 ${quote_ldap_dn: a(bc)*, a<yz>; }
6957
6958 yields
6959
6960 %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
6961
6962 Removing the URL quoting, this is (with a trailing space):
6963
6964 \ a(bc)*\, a\<yz\>\;\
6965
6966 There are some further comments about quoting in the section on LDAP
6967 authentication below.
6968
6969
6970 9.17 LDAP connections
6971 ---------------------
6972
6973 The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
6974 is in use, via a Unix domain socket. The example given above does not specify
6975 an LDAP server. A server that is reached by TCP/IP can be specified in a query
6976 by starting it with
6977
6978 ldap://<hostname>:<port>/...
6979
6980 If the port (and preceding colon) are omitted, the standard LDAP port (389) is
6981 used. When no server is specified in a query, a list of default servers is
6982 taken from the ldap_default_servers configuration option. This supplies a
6983 colon-separated list of servers which are tried in turn until one successfully
6984 handles a query, or there is a serious error. Successful handling either
6985 returns the requested data, or indicates that it does not exist. Serious errors
6986 are syntactical, or multiple values when only a single value is expected.
6987 Errors which cause the next server to be tried are connection failures, bind
6988 failures, and timeouts.
6989
6990 For each server name in the list, a port number can be given. The standard way
6991 of specifying a host and port is to use a colon separator (RFC 1738). Because
6992 ldap_default_servers is a colon-separated list, such colons have to be doubled.
6993 For example
6994
6995 ldap_default_servers = ldap1.example.com::145:ldap2.example.com
6996
6997 If ldap_default_servers is unset, a URL with no server name is passed to the
6998 LDAP library with no server name, and the library's default (normally the local
6999 host) is used.
7000
7001 If you are using the OpenLDAP library, you can connect to an LDAP server using
7002 a Unix domain socket instead of a TCP/IP connection. This is specified by using
7003 "ldapi" instead of "ldap" in LDAP queries. What follows here applies only to
7004 OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
7005 not available.
7006
7007 For this type of connection, instead of a host name for the server, a pathname
7008 for the socket is required, and the port number is not relevant. The pathname
7009 can be specified either as an item in ldap_default_servers, or inline in the
7010 query. In the former case, you can have settings such as
7011
7012 ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
7013
7014 When the pathname is given in the query, you have to escape the slashes as
7015 "%2F" to fit in with the LDAP URL syntax. For example:
7016
7017 ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
7018
7019 When Exim processes an LDAP lookup and finds that the "hostname" is really a
7020 pathname, it uses the Unix domain socket code, even if the query actually
7021 specifies "ldap" or "ldaps". In particular, no encryption is used for a socket
7022 connection. This behaviour means that you can use a setting of
7023 ldap_default_servers such as in the example above with traditional "ldap" or
7024 "ldaps" queries, and it will work. First, Exim tries a connection via the Unix
7025 domain socket; if that fails, it tries a TCP/IP connection to the backup host.
7026
7027 If an explicit "ldapi" type is given in a query when a host name is specified,
7028 an error is diagnosed. However, if there are more items in ldap_default_servers
7029 , they are tried. In other words:
7030
7031 * Using a pathname with "ldap" or "ldaps" forces the use of the Unix domain
7032 interface.
7033
7034 * Using "ldapi" with a host name causes an error.
7035
7036 Using "ldapi" with no host or path in the query, and no setting of
7037 ldap_default_servers, does whatever the library does by default.
7038
7039
7040 9.18 LDAP authentication and control information
7041 ------------------------------------------------
7042
7043 The LDAP URL syntax provides no way of passing authentication and other control
7044 information to the server. To make this possible, the URL in an LDAP query may
7045 be preceded by any number of <name>=<value> settings, separated by spaces. If a
7046 value contains spaces it must be enclosed in double quotes, and when double
7047 quotes are used, backslash is interpreted in the usual way inside them. The
7048 following names are recognized:
7049
7050 DEREFERENCE set the dereferencing parameter
7051 NETTIME set a timeout for a network operation
7052 USER set the DN, for authenticating the LDAP bind
7053 PASS set the password, likewise
7054 REFERRALS set the referrals parameter
7055 SERVERS set alternate server list for this query only
7056 SIZE set the limit for the number of entries returned
7057 TIME set the maximum waiting time for a query
7058
7059 The value of the DEREFERENCE parameter must be one of the words "never",
7060 "searching", "finding", or "always". The value of the REFERRALS parameter must
7061 be "follow" (the default) or "nofollow". The latter stops the LDAP library from
7062 trying to follow referrals issued by the LDAP server.
7063
7064 The name CONNECT is an obsolete name for NETTIME, retained for backwards
7065 compatibility. This timeout (specified as a number of seconds) is enforced from
7066 the client end for operations that can be carried out over a network.
7067 Specifically, it applies to network connections and calls to the ldap_result()
7068 function. If the value is greater than zero, it is used if
7069 LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or if
7070 LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape SDK 4.1). A
7071 value of zero forces an explicit setting of "no timeout" for Netscape SDK; for
7072 OpenLDAP no action is taken.
7073
7074 The TIME parameter (also a number of seconds) is passed to the server to set a
7075 server-side limit on the time taken to complete a search.
7076
7077 The SERVERS parameter allows you to specify an alternate list of ldap servers
7078 to use for an individual lookup. The global ldap_default_servers option
7079 provides a default list of ldap servers, and a single lookup can specify a
7080 single ldap server to use. But when you need to do a lookup with a list of
7081 servers that is different than the default list (maybe different order, maybe a
7082 completely different set of servers), the SERVERS parameter allows you to
7083 specify this alternate list (colon-separated).
7084
7085 Here is an example of an LDAP query in an Exim lookup that uses some of these
7086 values. This is a single line, folded to fit on the page:
7087
7088 ${lookup ldap
7089 {user="cn=manager,o=University of Cambridge,c=UK" pass=secret
7090 ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
7091 {$value}fail}
7092
7093 The encoding of spaces as "%20" is a URL thing which should not be done for any
7094 of the auxiliary data. Exim configuration settings that include lookups which
7095 contain password information should be preceded by "hide" to prevent non-admin
7096 users from using the -bP option to see their values.
7097
7098 The auxiliary data items may be given in any order. The default is no
7099 connection timeout (the system timeout is used), no user or password, no limit
7100 on the number of entries returned, and no time limit on queries.
7101
7102 When a DN is quoted in the USER= setting for LDAP authentication, Exim removes
7103 any URL quoting that it may contain before passing it LDAP. Apparently some
7104 libraries do this for themselves, but some do not. Removing the URL quoting has
7105 two advantages:
7106
7107 * It makes it possible to use the same quote_ldap_dn expansion for USER= DNs
7108 as with DNs inside actual queries.
7109
7110 * It permits spaces inside USER= DNs.
7111
7112 For example, a setting such as
7113
7114 USER=cn=${quote_ldap_dn:$1}
7115
7116 should work even if $1 contains spaces.
7117
7118 Expanded data for the PASS= value should be quoted using the quote expansion
7119 operator, rather than the LDAP quote operators. The only reason this field
7120 needs quoting is to ensure that it conforms to the Exim syntax, which does not
7121 allow unquoted spaces. For example:
7122
7123 PASS=${quote:$3}
7124
7125 The LDAP authentication mechanism can be used to check passwords as part of
7126 SMTP authentication. See the ldapauth expansion string condition in chapter 11.
7127
7128
7129 9.19 Format of data returned by LDAP
7130 ------------------------------------
7131
7132 The ldapdn lookup type returns the Distinguished Name from a single entry as a
7133 sequence of values, for example
7134
7135 cn=manager,o=University of Cambridge,c=UK
7136
7137 The ldap lookup type generates an error if more than one entry matches the
7138 search filter, whereas ldapm permits this case, and inserts a newline in the
7139 result between the data from different entries. It is possible for multiple
7140 values to be returned for both ldap and ldapm, but in the former case you know
7141 that whatever values are returned all came from a single entry in the
7142 directory.
7143
7144 In the common case where you specify a single attribute in your LDAP query, the
7145 result is not quoted, and does not contain the attribute name. If the attribute
7146 has multiple values, they are separated by commas. Any comma that is part of an
7147 attribute's value is doubled.
7148
7149 If you specify multiple attributes, the result contains space-separated, quoted
7150 strings, each preceded by the attribute name and an equals sign. Within the
7151 quotes, the quote character, backslash, and newline are escaped with
7152 backslashes, and commas are used to separate multiple values for the attribute.
7153 Any commas in attribute values are doubled (permitting treatment of the values
7154 as a comma-separated list). Apart from the escaping, the string within quotes
7155 takes the same form as the output when a single attribute is requested.
7156 Specifying no attributes is the same as specifying all of an entry's
7157 attributes.
7158
7159 Here are some examples of the output format. The first line of each pair is an
7160 LDAP query, and the second is the data that is returned. The attribute called
7161 attr1 has two values, one of them with an embedded comma, whereas attr2 has
7162 only one value. Both attributes are derived from attr (they have SUP attr in
7163 their schema definitions).
7164
7165 ldap:///o=base?attr1?sub?(uid=fred)
7166 value1.1,value1,,2
7167
7168 ldap:///o=base?attr2?sub?(uid=fred)
7169 value two
7170
7171 ldap:///o=base?attr?sub?(uid=fred)
7172 value1.1,value1,,2,value two
7173
7174 ldap:///o=base?attr1,attr2?sub?(uid=fred)
7175 attr1="value1.1,value1,,2" attr2="value two"
7176
7177 ldap:///o=base??sub?(uid=fred)
7178 objectClass="top" attr1="value1.1,value1,,2" attr2="value two"
7179
7180 You can make use of Exim's -be option to run expansion tests and thereby check
7181 the results of LDAP lookups. The extract operator in string expansions can be
7182 used to pick out individual fields from data that consists of key=value pairs.
7183 The listextract operator should be used to pick out individual values of
7184 attributes, even when only a single value is expected. The doubling of embedded
7185 commas allows you to use the returned data as a comma separated list (using the
7186 "<," syntax for changing the input list separator).
7187
7188
7189 9.20 More about NIS+
7190 --------------------
7191
7192 NIS+ queries consist of a NIS+ indexed name followed by an optional colon and
7193 field name. If this is given, the result of a successful query is the contents
7194 of the named field; otherwise the result consists of a concatenation of
7195 field-name=field-value pairs, separated by spaces. Empty values and values
7196 containing spaces are quoted. For example, the query
7197
7198 [name=mg1456],passwd.org_dir
7199
7200 might return the string
7201
7202 name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
7203 home=/home/mg1456 shell=/bin/bash shadow=""
7204
7205 (split over two lines here to fit on the page), whereas
7206
7207 [name=mg1456],passwd.org_dir:gcos
7208
7209 would just return
7210
7211 Martin Guerre
7212
7213 with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
7214 for the given indexed key. The effect of the quote_nisplus expansion operator
7215 is to double any quote characters within the text.
7216
7217
7218 9.21 SQL lookups
7219 ----------------
7220
7221 Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, Redis, and
7222 SQLite databases. Queries for these databases contain SQL statements, so an
7223 example might be
7224
7225 ${lookup mysql{select mailbox from users where id='userx'}\
7226 {$value}fail}
7227
7228 If the result of the query contains more than one field, the data for each
7229 field in the row is returned, preceded by its name, so the result of
7230
7231 ${lookup pgsql{select home,name from users where id='userx'}\
7232 {$value}}
7233
7234 might be
7235
7236 home=/home/userx name="Mister X"
7237
7238 Empty values and values containing spaces are double quoted, with embedded
7239 quotes escaped by a backslash. If the result of the query contains just one
7240 field, the value is passed back verbatim, without a field name, for example:
7241
7242 Mister X
7243
7244 If the result of the query yields more than one row, it is all concatenated,
7245 with a newline between the data for each row.
7246
7247
7248 9.22 More about MySQL, PostgreSQL, Oracle, InterBase, and Redis
7249 ---------------------------------------------------------------
7250
7251 If any MySQL, PostgreSQL, Oracle, InterBase or Redis lookups are used, the
7252 mysql_servers, pgsql_servers, oracle_servers, ibase_servers, or redis_servers
7253 option (as appropriate) must be set to a colon-separated list of server
7254 information. (For MySQL and PostgreSQL, the global option need not be set if
7255 all queries contain their own server information - see section 9.23.) For all
7256 but Redis each item in the list is a slash-separated list of four items: host
7257 name, database name, user name, and password. In the case of Oracle, the host
7258 name field is used for the "service name", and the database name field is not
7259 used and should be empty. For example:
7260
7261 hide oracle_servers = oracle.plc.example//userx/abcdwxyz
7262
7263 Because password data is sensitive, you should always precede the setting with
7264 "hide", to prevent non-admin users from obtaining the setting via the -bP
7265 option. Here is an example where two MySQL servers are listed:
7266
7267 hide mysql_servers = localhost/users/root/secret:\
7268 otherhost/users/root/othersecret
7269
7270 For MySQL and PostgreSQL, a host may be specified as <name>:<port> but because
7271 this is a colon-separated list, the colon has to be doubled. For each query,
7272 these parameter groups are tried in order until a connection is made and a
7273 query is successfully processed. The result of a query may be that no data is
7274 found, but that is still a successful query. In other words, the list of
7275 servers provides a backup facility, not a list of different places to look.
7276
7277 For Redis the global option need not be specified if all queries contain their
7278 own server information - see section 9.23. If specified, the option must be set
7279 to a colon-separated list of server information. Each item in the list is a
7280 slash-separated list of three items: host, database number, and password.
7281
7282 1. The host is required and may be either an IPv4 address and optional port
7283 number (separated by a colon, which needs doubling due to the higher-level
7284 list), or a Unix socket pathname enclosed in parentheses
7285
7286 2. The database number is optional; if present that number is selected in the
7287 backend
7288
7289 3. The password is optional; if present it is used to authenticate to the
7290 backend
7291
7292 The quote_mysql, quote_pgsql, and quote_oracle expansion operators convert
7293 newline, tab, carriage return, and backspace to \n, \t, \r, and \b
7294 respectively, and the characters single-quote, double-quote, and backslash
7295 itself are escaped with backslashes.
7296
7297 The quote_redis expansion operator escapes whitespace and backslash characters
7298 with a backslash.
7299
7300
7301 9.23 Specifying the server in the query
7302 ---------------------------------------
7303
7304 For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and
7305 InterBase), it is possible to specify a list of servers with an individual
7306 query. This is done by starting the query with
7307
7308 servers=server1:server2:server3:...;
7309
7310 Each item in the list may take one of two forms:
7311
7312 1. If it contains no slashes it is assumed to be just a host name. The
7313 appropriate global option (mysql_servers or pgsql_servers) is searched for
7314 a host of the same name, and the remaining parameters (database, user,
7315 password) are taken from there.
7316
7317 2. If it contains any slashes, it is taken as a complete parameter set.
7318
7319 The list of servers is used in exactly the same way as the global list. Once a
7320 connection to a server has happened and a query has been successfully executed,
7321 processing of the lookup ceases.
7322
7323 This feature is intended for use in master/slave situations where updates are
7324 occurring and you want to update the master rather than a slave. If the master
7325 is in the list as a backup for reading, you might have a global setting like
7326 this:
7327
7328 mysql_servers = slave1/db/name/pw:\
7329 slave2/db/name/pw:\
7330 master/db/name/pw
7331
7332 In an updating lookup, you could then write:
7333
7334 ${lookup mysql{servers=master; UPDATE ...} }
7335
7336 That query would then be sent only to the master server. If, on the other hand,
7337 the master is not to be used for reading, and so is not present in the global
7338 option, you can still update it by a query of this form:
7339
7340 ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} }
7341
7342
7343 9.24 Special MySQL features
7344 ---------------------------
7345
7346 For MySQL, an empty host name or the use of "localhost" in mysql_servers causes
7347 a connection to the server on the local host by means of a Unix domain socket.
7348 An alternate socket can be specified in parentheses. An option group name for
7349 MySQL option files can be specified in square brackets; the default value is
7350 "exim". The full syntax of each item in mysql_servers is:
7351
7352 <hostname>::<port>(<socket name>)[<option group>]/<database>/<user>/<password>
7353
7354 Any of the four sub-parts of the first field can be omitted. For normal use on
7355 the local host it can be left blank or set to just "localhost".
7356
7357 No database need be supplied - but if it is absent here, it must be given in
7358 the queries.
7359
7360 If a MySQL query is issued that does not request any data (an insert, update,
7361 or delete command), the result of the lookup is the number of rows affected.
7362
7363 Warning: This can be misleading. If an update does not actually change anything
7364 (for example, setting a field to the value it already has), the result is zero
7365 because no rows are affected.
7366
7367
7368 9.25 Special PostgreSQL features
7369 --------------------------------
7370
7371 PostgreSQL lookups can also use Unix domain socket connections to the database.
7372 This is usually faster and costs less CPU time than a TCP/IP connection.
7373 However it can be used only if the mail server runs on the same machine as the
7374 database server. A configuration line for PostgreSQL via Unix domain sockets
7375 looks like this:
7376
7377 hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
7378
7379 In other words, instead of supplying a host name, a path to the socket is
7380 given. The path name is enclosed in parentheses so that its slashes aren't
7381 visually confused with the delimiters for the other server parameters.
7382
7383 If a PostgreSQL query is issued that does not request any data (an insert,
7384 update, or delete command), the result of the lookup is the number of rows
7385 affected.
7386
7387
7388 9.26 More about SQLite
7389 ----------------------
7390
7391 SQLite is different to the other SQL lookups because a filename is required in
7392 addition to the SQL query. An SQLite database is a single file, and there is no
7393 daemon as in the other SQL databases. The interface to Exim requires the name
7394 of the file, as an absolute path, to be given at the start of the query. It is
7395 separated from the query by white space. This means that the path name cannot
7396 contain white space. Here is a lookup expansion example:
7397
7398 ${lookup sqlite {/some/thing/sqlitedb \
7399 select name from aliases where id='userx';}}
7400
7401 In a list, the syntax is similar. For example:
7402
7403 domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \
7404 select * from relays where ip='$sender_host_address';
7405
7406 The only character affected by the quote_sqlite operator is a single quote,
7407 which it doubles.
7408
7409 The SQLite library handles multiple simultaneous accesses to the database
7410 internally. Multiple readers are permitted, but only one process can update at
7411 once. Attempts to access the database while it is being updated are rejected
7412 after a timeout period, during which the SQLite library waits for the lock to
7413 be released. In Exim, the default timeout is set to 5 seconds, but it can be
7414 changed by means of the sqlite_lock_timeout option.
7415
7416
7417 9.27 More about Redis
7418 ---------------------
7419
7420 Redis is a non-SQL database. Commands are simple get and set. Examples:
7421
7422 ${lookup redis{set keyname ${quote_redis:objvalue plus}}}
7423 ${lookup redis{get keyname}}
7424
7425 As of release 4.91, "lightweight" support for Redis Cluster is available.
7426 Requires redis_servers list to contain all the servers in the cluster, all of
7427 which must be reachable from the running exim instance. If the cluster has
7428 master/slave replication, the list must contain all the master and slave
7429 servers.
7430
7431 When the Redis Cluster returns a "MOVED" response to a query, Exim does not
7432 immediately follow the redirection but treats the response as a DEFER, moving
7433 on to the next server in the redis_servers list until the correct server is
7434 reached.
7435
7436
7437
7438 ===============================================================================
7439 10. DOMAIN, HOST, ADDRESS, AND LOCAL PART LISTS
7440
7441 A number of Exim configuration options contain lists of domains, hosts, email
7442 addresses, or local parts. For example, the hold_domains option contains a list
7443 of domains whose delivery is currently suspended. These lists are also used as
7444 data in ACL statements (see chapter 43), and as arguments to expansion
7445 conditions such as match_domain.
7446
7447 Each item in one of these lists is a pattern to be matched against a domain,
7448 host, email address, or local part, respectively. In the sections below, the
7449 different types of pattern for each case are described, but first we cover some
7450 general facilities that apply to all four kinds of list.
7451
7452 Note that other parts of Exim use a string list which does not support all the
7453 complexity available in domain, host, address and local part lists.
7454
7455
7456 10.1 Expansion of lists
7457 -----------------------
7458
7459 Each list is expanded as a single string before it is used.
7460
7461 Exception: the router headers_remove option, where list-item splitting is done
7462 before string-expansion.
7463
7464 The result of expansion must be a list, possibly containing empty items, which
7465 is split up into separate items for matching. By default, colon is the
7466 separator character, but this can be varied if necessary. See sections 6.20 and
7467 6.22 for details of the list syntax; the second of these discusses the way to
7468 specify empty list items.
7469
7470 If the string expansion is forced to fail, Exim behaves as if the item it is
7471 testing (domain, host, address, or local part) is not in the list. Other
7472 expansion failures cause temporary errors.
7473
7474 If an item in a list is a regular expression, backslashes, dollars and possibly
7475 other special characters in the expression must be protected against
7476 misinterpretation by the string expander. The easiest way to do this is to use
7477 the "\N" expansion feature to indicate that the contents of the regular
7478 expression should not be expanded. For example, in an ACL you might have:
7479
7480 deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \
7481 ${lookup{$domain}lsearch{/badsenders/bydomain}}
7482
7483 The first item is a regular expression that is protected from expansion by "\
7484 N", whereas the second uses the expansion to obtain a list of unwanted senders
7485 based on the receiving domain.
7486
7487
7488 10.2 Negated items in lists
7489 ---------------------------
7490
7491 Items in a list may be positive or negative. Negative items are indicated by a
7492 leading exclamation mark, which may be followed by optional white space. A list
7493 defines a set of items (domains, etc). When Exim processes one of these lists,
7494 it is trying to find out whether a domain, host, address, or local part
7495 (respectively) is in the set that is defined by the list. It works like this:
7496
7497 The list is scanned from left to right. If a positive item is matched, the
7498 subject that is being checked is in the set; if a negative item is matched, the
7499 subject is not in the set. If the end of the list is reached without the
7500 subject having matched any of the patterns, it is in the set if the last item
7501 was a negative one, but not if it was a positive one. For example, the list in
7502
7503 domainlist relay_to_domains = !a.b.c : *.b.c
7504
7505 matches any domain ending in .b.c except for a.b.c. Domains that match neither
7506 a.b.c nor *.b.c do not match, because the last item in the list is positive.
7507 However, if the setting were
7508
7509 domainlist relay_to_domains = !a.b.c
7510
7511 then all domains other than a.b.c would match because the last item in the list
7512 is negative. In other words, a list that ends with a negative item behaves as
7513 if it had an extra item ":*" on the end.
7514
7515 Another way of thinking about positive and negative items in lists is to read
7516 the connector as "or" after a positive item and as "and" after a negative item.
7517
7518
7519 10.3 File names in lists
7520 ------------------------
7521
7522 If an item in a domain, host, address, or local part list is an absolute
7523 filename (beginning with a slash character), each line of the file is read and
7524 processed as if it were an independent item in the list, except that further
7525 filenames are not allowed, and no expansion of the data from the file takes
7526 place. Empty lines in the file are ignored, and the file may also contain
7527 comment lines:
7528
7529 * For domain and host lists, if a # character appears anywhere in a line of
7530 the file, it and all following characters are ignored.
7531
7532 * Because local parts may legitimately contain # characters, a comment in an
7533 address list or local part list file is recognized only if # is preceded by
7534 white space or the start of the line. For example:
7535
7536 not#comment@x.y.z # but this is a comment
7537
7538 Putting a filename in a list has the same effect as inserting each line of the
7539 file as an item in the list (blank lines and comments excepted). However, there
7540 is one important difference: the file is read each time the list is processed,
7541 so if its contents vary over time, Exim's behaviour changes.
7542
7543 If a filename is preceded by an exclamation mark, the sense of any match within
7544 the file is inverted. For example, if
7545
7546 hold_domains = !/etc/nohold-domains
7547
7548 and the file contains the lines
7549
7550 !a.b.c
7551 *.b.c
7552
7553 then a.b.c is in the set of domains defined by hold_domains, whereas any domain
7554 matching "*.b.c" is not.
7555
7556
7557 10.4 An lsearch file is not an out-of-line list
7558 -----------------------------------------------
7559
7560 As will be described in the sections that follow, lookups can be used in lists
7561 to provide indexed methods of checking list membership. There has been some
7562 confusion about the way lsearch lookups work in lists. Because an lsearch file
7563 contains plain text and is scanned sequentially, it is sometimes thought that
7564 it is allowed to contain wild cards and other kinds of non-constant pattern.
7565 This is not the case. The keys in an lsearch file are always fixed strings,
7566 just as for any other single-key lookup type.
7567
7568 If you want to use a file to contain wild-card patterns that form part of a
7569 list, just give the filename on its own, without a search type, as described in
7570 the previous section. You could also use the wildlsearch or nwildlsearch, but
7571 there is no advantage in doing this.
7572
7573
7574 10.5 Named lists
7575 ----------------
7576
7577 A list of domains, hosts, email addresses, or local parts can be given a name
7578 which is then used to refer to the list elsewhere in the configuration. This is
7579 particularly convenient if the same list is required in several different
7580 places. It also allows lists to be given meaningful names, which can improve
7581 the readability of the configuration. For example, it is conventional to define
7582 a domain list called local_domains for all the domains that are handled locally
7583 on a host, using a configuration line such as
7584
7585 domainlist local_domains = localhost:my.dom.example
7586
7587 Named lists are referenced by giving their name preceded by a plus sign, so,
7588 for example, a router that is intended to handle local domains would be
7589 configured with the line
7590
7591 domains = +local_domains
7592
7593 The first router in a configuration is often one that handles all domains
7594 except the local ones, using a configuration with a negated item like this:
7595
7596 dnslookup:
7597 driver = dnslookup
7598 domains = ! +local_domains
7599 transport = remote_smtp
7600 no_more
7601
7602 The four kinds of named list are created by configuration lines starting with
7603 the words domainlist, hostlist, addresslist, or localpartlist, respectively.
7604 Then there follows the name that you are defining, followed by an equals sign
7605 and the list itself. For example:
7606
7607 hostlist relay_from_hosts = 192.168.23.0/24 : my.friend.example
7608 addresslist bad_senders = cdb;/etc/badsenders
7609
7610 A named list may refer to other named lists:
7611
7612 domainlist dom1 = first.example : second.example
7613 domainlist dom2 = +dom1 : third.example
7614 domainlist dom3 = fourth.example : +dom2 : fifth.example
7615
7616 Warning: If the last item in a referenced list is a negative one, the effect
7617 may not be what you intended, because the negation does not propagate out to
7618 the higher level. For example, consider:
7619
7620 domainlist dom1 = !a.b
7621 domainlist dom2 = +dom1 : *.b
7622
7623 The second list specifies "either in the dom1 list or *.b". The first list
7624 specifies just "not a.b", so the domain x.y matches it. That means it matches
7625 the second list as well. The effect is not the same as
7626
7627 domainlist dom2 = !a.b : *.b
7628
7629 where x.y does not match. It's best to avoid negation altogether in referenced
7630 lists if you can.
7631
7632 Named lists may have a performance advantage. When Exim is routing an address
7633 or checking an incoming message, it caches the result of tests on named lists.
7634 So, if you have a setting such as
7635
7636 domains = +local_domains
7637
7638 on several of your routers or in several ACL statements, the actual test is
7639 done only for the first one. However, the caching works only if there are no
7640 expansions within the list itself or any sublists that it references. In other
7641 words, caching happens only for lists that are known to be the same each time
7642 they are referenced.
7643
7644 By default, there may be up to 16 named lists of each type. This limit can be
7645 extended by changing a compile-time variable. The use of domain and host lists
7646 is recommended for concepts such as local domains, relay domains, and relay
7647 hosts. The default configuration is set up like this.
7648
7649
7650 10.6 Named lists compared with macros
7651 -------------------------------------
7652
7653 At first sight, named lists might seem to be no different from macros in the
7654 configuration file. However, macros are just textual substitutions. If you
7655 write
7656
7657 ALIST = host1 : host2
7658 auth_advertise_hosts = !ALIST
7659
7660 it probably won't do what you want, because that is exactly the same as
7661
7662 auth_advertise_hosts = !host1 : host2
7663
7664 Notice that the second host name is not negated. However, if you use a host
7665 list, and write
7666
7667 hostlist alist = host1 : host2
7668 auth_advertise_hosts = ! +alist
7669
7670 the negation applies to the whole list, and so that is equivalent to
7671
7672 auth_advertise_hosts = !host1 : !host2
7673
7674
7675 10.7 Named list caching
7676 -----------------------
7677
7678 While processing a message, Exim caches the result of checking a named list if
7679 it is sure that the list is the same each time. In practice, this means that
7680 the cache operates only if the list contains no $ characters, which guarantees
7681 that it will not change when it is expanded. Sometimes, however, you may have
7682 an expanded list that you know will be the same each time within a given
7683 message. For example:
7684
7685 domainlist special_domains = \
7686 ${lookup{$sender_host_address}cdb{/some/file}}
7687
7688 This provides a list of domains that depends only on the sending host's IP
7689 address. If this domain list is referenced a number of times (for example, in
7690 several ACL lines, or in several routers) the result of the check is not cached
7691 by default, because Exim does not know that it is going to be the same list
7692 each time.
7693
7694 By appending "_cache" to "domainlist" you can tell Exim to go ahead and cache
7695 the result anyway. For example:
7696
7697 domainlist_cache special_domains = ${lookup{...
7698
7699 If you do this, you should be absolutely sure that caching is going to do the
7700 right thing in all cases. When in doubt, leave it out.
7701
7702
7703 10.8 Domain lists
7704 -----------------
7705
7706 Domain lists contain patterns that are to be matched against a mail domain. The
7707 following types of item may appear in domain lists:
7708
7709 * If a pattern consists of a single @ character, it matches the local host
7710 name, as set by the primary_hostname option (or defaulted). This makes it
7711 possible to use the same configuration file on several different hosts that
7712 differ only in their names.
7713
7714 * If a pattern consists of the string "@[]" it matches an IP address enclosed
7715 in square brackets (as in an email address that contains a domain literal),
7716 but only if that IP address is recognized as local for email routing
7717 purposes. The local_interfaces and extra_local_interfaces options can be
7718 used to control which of a host's several IP addresses are treated as
7719 local. In today's Internet, the use of domain literals is controversial.
7720
7721 * If a pattern consists of the string "@mx_any" it matches any domain that
7722 has an MX record pointing to the local host or to any host that is listed
7723 in hosts_treat_as_local. The items "@mx_primary" and "@mx_secondary" are
7724 similar, except that the first matches only when a primary MX target is the
7725 local host, and the second only when no primary MX target is the local
7726 host, but a secondary MX target is. "Primary" means an MX record with the
7727 lowest preference value - there may of course be more than one of them.
7728
7729 The MX lookup that takes place when matching a pattern of this type is
7730 performed with the resolver options for widening names turned off. Thus,
7731 for example, a single-component domain will not be expanded by adding the
7732 resolver's default domain. See the qualify_single and search_parents
7733 options of the dnslookup router for a discussion of domain widening.
7734
7735 Sometimes you may want to ignore certain IP addresses when using one of
7736 these patterns. You can specify this by following the pattern with "/ignore
7737 ="<ip list>, where <ip list> is a list of IP addresses. These addresses are
7738 ignored when processing the pattern (compare the ignore_target_hosts option
7739 on a router). For example:
7740
7741 domains = @mx_any/ignore=127.0.0.1
7742
7743 This example matches any domain that has an MX record pointing to one of
7744 the local host's IP addresses other than 127.0.0.1.
7745
7746 The list of IP addresses is in fact processed by the same code that
7747 processes host lists, so it may contain CIDR-coded network specifications
7748 and it may also contain negative items.
7749
7750 Because the list of IP addresses is a sublist within a domain list, you
7751 have to be careful about delimiters if there is more than one address. Like
7752 any other list, the default delimiter can be changed. Thus, you might have:
7753
7754 domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \
7755 an.other.domain : ...
7756
7757 so that the sublist uses semicolons for delimiters. When IPv6 addresses are
7758 involved, it is easiest to change the delimiter for the main list as well:
7759
7760 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
7761 an.other.domain ? ...
7762
7763 * If a pattern starts with an asterisk, the remaining characters of the
7764 pattern are compared with the terminating characters of the domain. The use
7765 of "*" in domain lists differs from its use in partial matching lookups. In
7766 a domain list, the character following the asterisk need not be a dot,
7767 whereas partial matching works only in terms of dot-separated components.
7768 For example, a domain list item such as "*key.ex" matches donkey.ex as well
7769 as cipher.key.ex.
7770
7771 * If a pattern starts with a circumflex character, it is treated as a regular
7772 expression, and matched against the domain using a regular expression
7773 matching function. The circumflex is treated as part of the regular
7774 expression. Email domains are case-independent, so this regular expression
7775 match is by default case-independent, but you can make it case-dependent by
7776 starting it with "(?-i)". References to descriptions of the syntax of
7777 regular expressions are given in chapter 8.
7778
7779 Warning: Because domain lists are expanded before being processed, you must
7780 escape any backslash and dollar characters in the regular expression, or
7781 use the special "\N" sequence (see chapter 11) to specify that it is not to
7782 be expanded (unless you really do want to build a regular expression by
7783 expansion, of course).
7784
7785 * If a pattern starts with the name of a single-key lookup type followed by a
7786 semicolon (for example, "dbm;" or "lsearch;"), the remainder of the pattern
7787 must be a filename in a suitable format for the lookup type. For example,
7788 for "cdb;" it must be an absolute path:
7789
7790 domains = cdb;/etc/mail/local_domains.cdb
7791
7792 The appropriate type of lookup is done on the file using the domain name as
7793 the key. In most cases, the data that is looked up is not used; Exim is
7794 interested only in whether or not the key is present in the file. However,
7795 when a lookup is used for the domains option on a router or a domains
7796 condition in an ACL statement, the data is preserved in the $domain_data
7797 variable and can be referred to in other router options or other statements
7798 in the same ACL.
7799
7800 * Any of the single-key lookup type names may be preceded by "partial"<n>"-",
7801 where the <n> is optional, for example,
7802
7803 domains = partial-dbm;/partial/domains
7804
7805 This causes partial matching logic to be invoked; a description of how this
7806 works is given in section 9.7.
7807
7808 * Any of the single-key lookup types may be followed by an asterisk. This
7809 causes a default lookup for a key consisting of a single asterisk to be
7810 done if the original lookup fails. This is not a useful feature when using
7811 a domain list to select particular domains (because any domain would
7812 match), but it might have value if the result of the lookup is being used
7813 via the $domain_data expansion variable.
7814
7815 * If the pattern starts with the name of a query-style lookup type followed
7816 by a semicolon (for example, "nisplus;" or "ldap;"), the remainder of the
7817 pattern must be an appropriate query for the lookup type, as described in
7818 chapter 9. For example:
7819
7820 hold_domains = mysql;select domain from holdlist \
7821 where domain = '${quote_mysql:$domain}';
7822
7823 In most cases, the data that is looked up is not used (so for an SQL query,
7824 for example, it doesn't matter what field you select). Exim is interested
7825 only in whether or not the query succeeds. However, when a lookup is used
7826 for the domains option on a router, the data is preserved in the
7827 $domain_data variable and can be referred to in other options.
7828
7829 * If none of the above cases apply, a caseless textual comparison is made
7830 between the pattern and the domain.
7831
7832 Here is an example that uses several different kinds of pattern:
7833
7834 domainlist funny_domains = \
7835 @ : \
7836 lib.unseen.edu : \
7837 *.foundation.fict.example : \
7838 \N^[1-2]\d{3}\.fict\.example$\N : \
7839 partial-dbm;/opt/data/penguin/book : \
7840 nis;domains.byname : \
7841 nisplus;[name=$domain,status=local],domains.org_dir
7842
7843 There are obvious processing trade-offs among the various matching modes. Using
7844 an asterisk is faster than a regular expression, and listing a few names
7845 explicitly probably is too. The use of a file or database lookup is expensive,
7846 but may be the only option if hundreds of names are required. Because the
7847 patterns are tested in order, it makes sense to put the most commonly matched
7848 patterns earlier.
7849
7850
7851 10.9 Host lists
7852 ---------------
7853
7854 Host lists are used to control what remote hosts are allowed to do. For
7855 example, some hosts may be allowed to use the local host as a relay, and some
7856 may be permitted to use the SMTP ETRN command. Hosts can be identified in two
7857 different ways, by name or by IP address. In a host list, some types of pattern
7858 are matched to a host name, and some are matched to an IP address. You need to
7859 be particularly careful with this when single-key lookups are involved, to
7860 ensure that the right value is being used as the key.
7861
7862
7863 10.10 Special host list patterns
7864 --------------------------------
7865
7866 If a host list item is the empty string, it matches only when no remote host is
7867 involved. This is the case when a message is being received from a local
7868 process using SMTP on the standard input, that is, when a TCP/IP connection is
7869 not used.
7870
7871 The special pattern "*" in a host list matches any host or no host. Neither the
7872 IP address nor the name is actually inspected.
7873
7874
7875 10.11 Host list patterns that match by IP address
7876 -------------------------------------------------
7877
7878 If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
7879 the incoming address actually appears in the IPv6 host as "::ffff:"<v4address>.
7880 When such an address is tested against a host list, it is converted into a
7881 traditional IPv4 address first. (Not all operating systems accept IPv4 calls on
7882 IPv6 sockets, as there have been some security concerns.)
7883
7884 The following types of pattern in a host list check the remote host by
7885 inspecting its IP address:
7886
7887 * If the pattern is a plain domain name (not a regular expression, not
7888 starting with *, not a lookup of any kind), Exim calls the operating system
7889 function to find the associated IP address(es). Exim uses the newer
7890 getipnodebyname() function when available, otherwise gethostbyname(). This
7891 typically causes a forward DNS lookup of the name. The result is compared
7892 with the IP address of the subject host.
7893
7894 If there is a temporary problem (such as a DNS timeout) with the host name
7895 lookup, a temporary error occurs. For example, if the list is being used in
7896 an ACL condition, the ACL gives a "defer" response, usually leading to a
7897 temporary SMTP error code. If no IP address can be found for the host name,
7898 what happens is described in section 10.14 below.
7899
7900 * If the pattern is "@", the primary host name is substituted and used as a
7901 domain name, as just described.
7902
7903 * If the pattern is an IP address, it is matched against the IP address of
7904 the subject host. IPv4 addresses are given in the normal "dotted-quad"
7905 notation. IPv6 addresses can be given in colon-separated format, but the
7906 colons have to be doubled so as not to be taken as item separators when the
7907 default list separator is used. IPv6 addresses are recognized even when
7908 Exim is compiled without IPv6 support. This means that if they appear in a
7909 host list on an IPv4-only host, Exim will not treat them as host names.
7910 They are just addresses that can never match a client host.
7911
7912 * If the pattern is "@[]", it matches the IP address of any IP interface on
7913 the local host. For example, if the local host is an IPv4 host with one
7914 interface address 10.45.23.56, these two ACL statements have the same
7915 effect:
7916
7917 accept hosts = 127.0.0.1 : 10.45.23.56
7918 accept hosts = @[]
7919
7920 * If the pattern is an IP address followed by a slash and a mask length (for
7921 example 10.11.42.0/24), it is matched against the IP address of the subject
7922 host under the given mask. This allows, an entire network of hosts to be
7923 included (or excluded) by a single item. The mask uses CIDR notation; it
7924 specifies the number of address bits that must match, starting from the
7925 most significant end of the address.
7926
7927 Note: The mask is not a count of addresses, nor is it the high number of a
7928 range of addresses. It is the number of bits in the network portion of the
7929 address. The above example specifies a 24-bit netmask, so it matches all
7930 256 addresses in the 10.11.42.0 network. An item such as
7931
7932 192.168.23.236/31
7933
7934 matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value
7935 of 32 for an IPv4 address is the same as no mask at all; just a single
7936 address matches.
7937
7938 Here is another example which shows an IPv4 and an IPv6 network:
7939
7940 recipient_unqualified_hosts = 192.168.0.0/16: \
7941 3ffe::ffff::836f::::/48
7942
7943 The doubling of list separator characters applies only when these items
7944 appear inline in a host list. It is not required when indirecting via a
7945 file. For example:
7946
7947 recipient_unqualified_hosts = /opt/exim/unqualnets
7948
7949 could make use of a file containing
7950
7951 172.16.0.0/12
7952 3ffe:ffff:836f::/48
7953
7954 to have exactly the same effect as the previous example. When listing IPv6
7955 addresses inline, it is usually more convenient to use the facility for
7956 changing separator characters. This list contains the same two networks:
7957
7958 recipient_unqualified_hosts = <; 172.16.0.0/12; \
7959 3ffe:ffff:836f::/48
7960
7961 The separator is changed to semicolon by the leading "<;" at the start of
7962 the list.
7963
7964
7965 10.12 Host list patterns for single-key lookups by host address
7966 ---------------------------------------------------------------
7967
7968 When a host is to be identified by a single-key lookup of its complete IP
7969 address, the pattern takes this form:
7970
7971 net-<single-key-search-type>;<search-data>
7972
7973 For example:
7974
7975 hosts_lookup = net-cdb;/hosts-by-ip.db
7976
7977 The text form of the IP address of the subject host is used as the lookup key.
7978 IPv6 addresses are converted to an unabbreviated form, using lower case
7979 letters, with dots as separators because colon is the key terminator in lsearch
7980 files. [Colons can in fact be used in keys in lsearch files by quoting the
7981 keys, but this is a facility that was added later.] The data returned by the
7982 lookup is not used.
7983
7984 Single-key lookups can also be performed using masked IP addresses, using
7985 patterns of this form:
7986
7987 net<number>-<single-key-search-type>;<search-data>
7988
7989 For example:
7990
7991 net24-dbm;/networks.db
7992
7993 The IP address of the subject host is masked using <number> as the mask length.
7994 A textual string is constructed from the masked value, followed by the mask,
7995 and this is used as the lookup key. For example, if the host's IP address is
7996 192.168.34.6, the key that is looked up for the above example is "192.168.34.0/
7997 24".
7998
7999 When an IPv6 address is converted to a string, dots are normally used instead
8000 of colons, so that keys in lsearch files need not contain colons (which
8001 terminate lsearch keys). This was implemented some time before the ability to
8002 quote keys was made available in lsearch files. However, the more recently
8003 implemented iplsearch files do require colons in IPv6 keys (notated using the
8004 quoting facility) so as to distinguish them from IPv4 keys. For this reason,
8005 when the lookup type is iplsearch, IPv6 addresses are converted using colons
8006 and not dots. In all cases, full, unabbreviated IPv6 addresses are always used.
8007
8008 Ideally, it would be nice to tidy up this anomalous situation by changing to
8009 colons in all cases, given that quoting is now available for lsearch. However,
8010 this would be an incompatible change that might break some existing
8011 configurations.
8012
8013 Warning: Specifying net32- (for an IPv4 address) or net128- (for an IPv6
8014 address) is not the same as specifying just net- without a number. In the
8015 former case the key strings include the mask value, whereas in the latter case
8016 the IP address is used on its own.
8017
8018
8019 10.13 Host list patterns that match by host name
8020 ------------------------------------------------
8021
8022 There are several types of pattern that require Exim to know the name of the
8023 remote host. These are either wildcard patterns or lookups by name. (If a
8024 complete hostname is given without any wildcarding, it is used to find an IP
8025 address to match against, as described in section 10.11 above.)
8026
8027 If the remote host name is not already known when Exim encounters one of these
8028 patterns, it has to be found from the IP address. Although many sites on the
8029 Internet are conscientious about maintaining reverse DNS data for their hosts,
8030 there are also many that do not do this. Consequently, a name cannot always be
8031 found, and this may lead to unwanted effects. Take care when configuring host
8032 lists with wildcarded name patterns. Consider what will happen if a name cannot
8033 be found.
8034
8035 Because of the problems of determining host names from IP addresses, matching
8036 against host names is not as common as matching against IP addresses.
8037
8038 By default, in order to find a host name, Exim first does a reverse DNS lookup;
8039 if no name is found in the DNS, the system function (gethostbyaddr() or
8040 getipnodebyaddr() if available) is tried. The order in which these lookups are
8041 done can be changed by setting the host_lookup_order option. For security, once
8042 Exim has found one or more names, it looks up the IP addresses for these names
8043 and compares them with the IP address that it started with. Only those names
8044 whose IP addresses match are accepted. Any other names are discarded. If no
8045 names are left, Exim behaves as if the host name cannot be found. In the most
8046 common case there is only one name and one IP address.
8047
8048 There are some options that control what happens if a host name cannot be
8049 found. These are described in section 10.14 below.
8050
8051 As a result of aliasing, hosts may have more than one name. When processing any
8052 of the following types of pattern, all the host's names are checked:
8053
8054 * If a pattern starts with "*" the remainder of the item must match the end
8055 of the host name. For example, "*.b.c" matches all hosts whose names end in
8056 .b.c. This special simple form is provided because this is a very common
8057 requirement. Other kinds of wildcarding require the use of a regular
8058 expression.
8059
8060 * If the item starts with "^" it is taken to be a regular expression which is
8061 matched against the host name. Host names are case-independent, so this
8062 regular expression match is by default case-independent, but you can make
8063 it case-dependent by starting it with "(?-i)". References to descriptions
8064 of the syntax of regular expressions are given in chapter 8. For example,
8065
8066 ^(a|b)\.c\.d$
8067
8068 is a regular expression that matches either of the two hosts a.c.d or b.c.d
8069 . When a regular expression is used in a host list, you must take care that
8070 backslash and dollar characters are not misinterpreted as part of the
8071 string expansion. The simplest way to do this is to use "\N" to mark that
8072 part of the string as non-expandable. For example:
8073
8074 sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
8075
8076 Warning: If you want to match a complete host name, you must include the
8077 "$" terminating metacharacter in the regular expression, as in the above
8078 example. Without it, a match at the start of the host name is all that is
8079 required.
8080
8081
8082 10.14 Behaviour when an IP address or name cannot be found
8083 ----------------------------------------------------------
8084
8085 While processing a host list, Exim may need to look up an IP address from a
8086 name (see section 10.11), or it may need to look up a host name from an IP
8087 address (see section 10.13). In either case, the behaviour when it fails to
8088 find the information it is seeking is the same.
8089
8090 Note: This section applies to permanent lookup failures. It does not apply to
8091 temporary DNS errors, whose handling is described in the next section.
8092
8093 Exim parses a host list from left to right. If it encounters a permanent lookup
8094 failure in any item in the host list before it has found a match, Exim treats
8095 it as a failure and the default behavior is as if the host does not match the
8096 list. This may not always be what you want to happen. To change Exim's
8097 behaviour, the special items "+include_unknown" or "+ignore_unknown" may appear
8098 in the list (at top level - they are not recognized in an indirected file).
8099
8100 * If any item that follows "+include_unknown" requires information that
8101 cannot found, Exim behaves as if the host does match the list. For example,
8102
8103 host_reject_connection = +include_unknown:*.enemy.ex
8104
8105 rejects connections from any host whose name matches "*.enemy.ex", and also
8106 any hosts whose name it cannot find.
8107
8108 * If any item that follows "+ignore_unknown" requires information that cannot
8109 be found, Exim ignores that item and proceeds to the rest of the list. For
8110 example:
8111
8112 accept hosts = +ignore_unknown : friend.example : \
8113 192.168.4.5
8114
8115 accepts from any host whose name is friend.example and from 192.168.4.5,
8116 whether or not its host name can be found. Without "+ignore_unknown", if no
8117 name can be found for 192.168.4.5, it is rejected.
8118
8119 Both "+include_unknown" and "+ignore_unknown" may appear in the same list. The
8120 effect of each one lasts until the next, or until the end of the list.
8121
8122
8123 10.15 Mixing wildcarded host names and addresses in host lists
8124 --------------------------------------------------------------
8125
8126 This section explains the host/ip processing logic with the same concepts as
8127 the previous section, but specifically addresses what happens when a wildcarded
8128 hostname is one of the items in the hostlist.
8129
8130 * If you have name lookups or wildcarded host names and IP addresses in the
8131 same host list, you should normally put the IP addresses first. For
8132 example, in an ACL you could have:
8133
8134 accept hosts = 10.9.8.7 : *.friend.example
8135
8136 The reason you normally would order it this way lies in the left-to-right
8137 way that Exim processes lists. It can test IP addresses without doing any
8138 DNS lookups, but when it reaches an item that requires a host name, it
8139 fails if it cannot find a host name to compare with the pattern. If the
8140 above list is given in the opposite order, the accept statement fails for a
8141 host whose name cannot be found, even if its IP address is 10.9.8.7.
8142
8143 * If you really do want to do the name check first, and still recognize the
8144 IP address, you can rewrite the ACL like this:
8145
8146 accept hosts = *.friend.example
8147 accept hosts = 10.9.8.7
8148
8149 If the first accept fails, Exim goes on to try the second one. See chapter
8150 43 for details of ACLs. Alternatively, you can use "+ignore_unknown", which
8151 was discussed in depth in the first example in this section.
8152
8153
8154 10.16 Temporary DNS errors when looking up host information
8155 -----------------------------------------------------------
8156
8157 A temporary DNS lookup failure normally causes a defer action (except when
8158 dns_again_means_nonexist converts it into a permanent error). However, host
8159 lists can include "+ignore_defer" and "+include_defer", analogous to
8160 "+ignore_unknown" and "+include_unknown", as described in the previous section.
8161 These options should be used with care, probably only in non-critical host
8162 lists such as whitelists.
8163
8164
8165 10.17 Host list patterns for single-key lookups by host name
8166 ------------------------------------------------------------
8167
8168 If a pattern is of the form
8169
8170 <single-key-search-type>;<search-data>
8171
8172 for example
8173
8174 dbm;/host/accept/list
8175
8176 a single-key lookup is performed, using the host name as its key. If the lookup
8177 succeeds, the host matches the item. The actual data that is looked up is not
8178 used.
8179
8180 Reminder: With this kind of pattern, you must have host names as keys in the
8181 file, not IP addresses. If you want to do lookups based on IP addresses, you
8182 must precede the search type with "net-" (see section 10.12). There is,
8183 however, no reason why you could not use two items in the same list, one doing
8184 an address lookup and one doing a name lookup, both using the same file.
8185
8186
8187 10.18 Host list patterns for query-style lookups
8188 ------------------------------------------------
8189
8190 If a pattern is of the form
8191
8192 <query-style-search-type>;<query>
8193
8194 the query is obeyed, and if it succeeds, the host matches the item. The actual
8195 data that is looked up is not used. The variables $sender_host_address and
8196 $sender_host_name can be used in the query. For example:
8197
8198 hosts_lookup = pgsql;\
8199 select ip from hostlist where ip='$sender_host_address'
8200
8201 The value of $sender_host_address for an IPv6 address contains colons. You can
8202 use the sg expansion item to change this if you need to. If you want to use
8203 masked IP addresses in database queries, you can use the mask expansion
8204 operator.
8205
8206 If the query contains a reference to $sender_host_name, Exim automatically
8207 looks up the host name if it has not already done so. (See section 10.13 for
8208 comments on finding host names.)
8209
8210 Historical note: prior to release 4.30, Exim would always attempt to find a
8211 host name before running the query, unless the search type was preceded by
8212 "net-". This is no longer the case. For backwards compatibility, "net-" is
8213 still recognized for query-style lookups, but its presence or absence has no
8214 effect. (Of course, for single-key lookups, "net-" is important. See section
8215 10.12.)
8216
8217
8218 10.19 Address lists
8219 -------------------
8220
8221 Address lists contain patterns that are matched against mail addresses. There
8222 is one special case to be considered: the sender address of a bounce message is
8223 always empty. You can test for this by providing an empty item in an address
8224 list. For example, you can set up a router to process bounce messages by using
8225 this option setting:
8226
8227 senders = :
8228
8229 The presence of the colon creates an empty item. If you do not provide any
8230 data, the list is empty and matches nothing. The empty sender can also be
8231 detected by a regular expression that matches an empty string, and by a
8232 query-style lookup that succeeds when $sender_address is empty.
8233
8234 Non-empty items in an address list can be straightforward email addresses. For
8235 example:
8236
8237 senders = jbc@askone.example : hs@anacreon.example
8238
8239 A certain amount of wildcarding is permitted. If a pattern contains an @
8240 character, but is not a regular expression and does not begin with a
8241 semicolon-terminated lookup type (described below), the local part of the
8242 subject address is compared with the local part of the pattern, which may start
8243 with an asterisk. If the local parts match, the domain is checked in exactly
8244 the same way as for a pattern in a domain list. For example, the domain can be
8245 wildcarded, refer to a named list, or be a lookup:
8246
8247 deny senders = *@*.spamming.site:\
8248 *@+hostile_domains:\
8249 bozo@partial-lsearch;/list/of/dodgy/sites:\
8250 *@dbm;/bad/domains.db
8251
8252 If a local part that begins with an exclamation mark is required, it has to be
8253 specified using a regular expression, because otherwise the exclamation mark is
8254 treated as a sign of negation, as is standard in lists.
8255
8256 If a non-empty pattern that is not a regular expression or a lookup does not
8257 contain an @ character, it is matched against the domain part of the subject
8258 address. The only two formats that are recognized this way are a literal
8259 domain, or a domain pattern that starts with *. In both these cases, the effect
8260 is the same as if "*@" preceded the pattern. For example:
8261
8262 deny senders = enemy.domain : *.enemy.domain
8263
8264 The following kinds of more complicated address list pattern can match any
8265 address, including the empty address that is characteristic of bounce message
8266 senders:
8267
8268 * If (after expansion) a pattern starts with "^", a regular expression match
8269 is done against the complete address, with the pattern as the regular
8270 expression. You must take care that backslash and dollar characters are not
8271 misinterpreted as part of the string expansion. The simplest way to do this
8272 is to use "\N" to mark that part of the string as non-expandable. For
8273 example:
8274
8275 deny senders = \N^.*this.*@example\.com$\N : \
8276 \N^\d{8}.+@spamhaus.example$\N : ...
8277
8278 The "\N" sequences are removed by the expansion, so these items do indeed
8279 start with "^" by the time they are being interpreted as address patterns.
8280
8281 * Complete addresses can be looked up by using a pattern that starts with a
8282 lookup type terminated by a semicolon, followed by the data for the lookup.
8283 For example:
8284
8285 deny senders = cdb;/etc/blocked.senders : \
8286 mysql;select address from blocked where \
8287 address='${quote_mysql:$sender_address}'
8288
8289 Both query-style and single-key lookup types can be used. For a single-key
8290 lookup type, Exim uses the complete address as the key. However, empty keys
8291 are not supported for single-key lookups, so a match against the empty
8292 address always fails. This restriction does not apply to query-style
8293 lookups.
8294
8295 Partial matching for single-key lookups (section 9.7) cannot be used, and
8296 is ignored if specified, with an entry being written to the panic log.
8297 However, you can configure lookup defaults, as described in section 9.6,
8298 but this is useful only for the "*@" type of default. For example, with
8299 this lookup:
8300
8301 accept senders = lsearch*@;/some/file
8302
8303 the file could contains lines like this:
8304
8305 user1@domain1.example
8306 *@domain2.example
8307
8308 and for the sender address nimrod@jaeger.example, the sequence of keys that
8309 are tried is:
8310
8311 nimrod@jaeger.example
8312 *@jaeger.example
8313 *
8314
8315 Warning 1: Do not include a line keyed by "*" in the file, because that
8316 would mean that every address matches, thus rendering the test useless.
8317
8318 Warning 2: Do not confuse these two kinds of item:
8319
8320 deny recipients = dbm*@;/some/file
8321 deny recipients = *@dbm;/some/file
8322
8323 The first does a whole address lookup, with defaulting, as just described,
8324 because it starts with a lookup type. The second matches the local part and
8325 domain independently, as described in a bullet point below.
8326
8327 The following kinds of address list pattern can match only non-empty addresses.
8328 If the subject address is empty, a match against any of these pattern types
8329 always fails.
8330
8331 * If a pattern starts with "@@" followed by a single-key lookup item (for
8332 example, "@@lsearch;/some/file"), the address that is being checked is
8333 split into a local part and a domain. The domain is looked up in the file.
8334 If it is not found, there is no match. If it is found, the data that is
8335 looked up from the file is treated as a colon-separated list of local part
8336 patterns, each of which is matched against the subject local part in turn.
8337
8338 The lookup may be a partial one, and/or one involving a search for a
8339 default keyed by "*" (see section 9.6). The local part patterns that are
8340 looked up can be regular expressions or begin with "*", or even be further
8341 lookups. They may also be independently negated. For example, with
8342
8343 deny senders = @@dbm;/etc/reject-by-domain
8344
8345 the data from which the DBM file is built could contain lines like
8346
8347 baddomain.com: !postmaster : *
8348
8349 to reject all senders except postmaster from that domain.
8350
8351 If a local part that actually begins with an exclamation mark is required,
8352 it has to be specified using a regular expression. In lsearch files, an
8353 entry may be split over several lines by indenting the second and
8354 subsequent lines, but the separating colon must still be included at line
8355 breaks. White space surrounding the colons is ignored. For example:
8356
8357 aol.com: spammer1 : spammer2 : ^[0-9]+$ :
8358 spammer3 : spammer4
8359
8360 As in all colon-separated lists in Exim, a colon can be included in an item
8361 by doubling.
8362
8363 If the last item in the list starts with a right angle-bracket, the
8364 remainder of the item is taken as a new key to look up in order to obtain a
8365 continuation list of local parts. The new key can be any sequence of
8366 characters. Thus one might have entries like
8367
8368 aol.com: spammer1 : spammer 2 : >*
8369 xyz.com: spammer3 : >*
8370 *: ^\d{8}$
8371
8372 in a file that was searched with @@dbm*, to specify a match for 8-digit
8373 local parts for all domains, in addition to the specific local parts listed
8374 for each domain. Of course, using this feature costs another lookup each
8375 time a chain is followed, but the effort needed to maintain the data is
8376 reduced.
8377
8378 It is possible to construct loops using this facility, and in order to
8379 catch them, the chains may be no more than fifty items long.
8380
8381 * The @@<lookup> style of item can also be used with a query-style lookup,
8382 but in this case, the chaining facility is not available. The lookup can
8383 only return a single list of local parts.
8384
8385 Warning: There is an important difference between the address list items in
8386 these two examples:
8387
8388 senders = +my_list
8389 senders = *@+my_list
8390
8391 In the first one, "my_list" is a named address list, whereas in the second
8392 example it is a named domain list.
8393
8394
8395 10.20 Case of letters in address lists
8396 --------------------------------------
8397
8398 Domains in email addresses are always handled caselessly, but for local parts
8399 case may be significant on some systems (see caseful_local_part for how Exim
8400 deals with this when routing addresses). However, RFC 2505 (Anti-Spam
8401 Recommendations for SMTP MTAs) suggests that matching of addresses to blocking
8402 lists should be done in a case-independent manner. Since most address lists in
8403 Exim are used for this kind of control, Exim attempts to do this by default.
8404
8405 The domain portion of an address is always lowercased before matching it to an
8406 address list. The local part is lowercased by default, and any string
8407 comparisons that take place are done caselessly. This means that the data in
8408 the address list itself, in files included as plain filenames, and in any file
8409 that is looked up using the "@@" mechanism, can be in any case. However, the
8410 keys in files that are looked up by a search type other than lsearch (which
8411 works caselessly) must be in lower case, because these lookups are not
8412 case-independent.
8413
8414 To allow for the possibility of caseful address list matching, if an item in an
8415 address list is the string "+caseful", the original case of the local part is
8416 restored for any comparisons that follow, and string comparisons are no longer
8417 case-independent. This does not affect the domain, which remains in lower case.
8418 However, although independent matches on the domain alone are still performed
8419 caselessly, regular expressions that match against an entire address become
8420 case-sensitive after "+caseful" has been seen.
8421
8422
8423 10.21 Local part lists
8424 ----------------------
8425
8426 Case-sensitivity in local part lists is handled in the same way as for address
8427 lists, as just described. The "+caseful" item can be used if required. In a
8428 setting of the local_parts option in a router with caseful_local_part set
8429 false, the subject is lowercased and the matching is initially
8430 case-insensitive. In this case, "+caseful" will restore case-sensitive matching
8431 in the local part list, but not elsewhere in the router. If caseful_local_part
8432 is set true in a router, matching in the local_parts option is case-sensitive
8433 from the start.
8434
8435 If a local part list is indirected to a file (see section 10.3), comments are
8436 handled in the same way as address lists - they are recognized only if the # is
8437 preceded by white space or the start of the line. Otherwise, local part lists
8438 are matched in the same way as domain lists, except that the special items that
8439 refer to the local host ("@", "@[]", "@mx_any", "@mx_primary", and
8440 "@mx_secondary") are not recognized. Refer to section 10.8 for details of the
8441 other available item types.
8442
8443
8444
8445 ===============================================================================
8446 11. STRING EXPANSIONS
8447
8448 Many strings in Exim's runtime configuration are expanded before use. Some of
8449 them are expanded every time they are used; others are expanded only once.
8450
8451 When a string is being expanded it is copied verbatim from left to right except
8452 when a dollar or backslash character is encountered. A dollar specifies the
8453 start of a portion of the string that is interpreted and replaced as described
8454 below in section 11.5 onwards. Backslash is used as an escape character, as
8455 described in the following section.
8456
8457 Whether a string is expanded depends upon the context. Usually this is solely
8458 dependent upon the option for which a value is sought; in this documentation,
8459 options for which string expansion is performed are marked with * after the
8460 data type. ACL rules always expand strings. A couple of expansion conditions do
8461 not expand some of the brace-delimited branches, for security reasons.
8462
8463
8464 11.1 Literal text in expanded strings
8465 -------------------------------------
8466
8467 An uninterpreted dollar can be included in an expanded string by putting a
8468 backslash in front of it. A backslash can be used to prevent any special
8469 character being treated specially in an expansion, including backslash itself.
8470 If the string appears in quotes in the configuration file, two backslashes are
8471 required because the quotes themselves cause interpretation of backslashes when
8472 the string is read in (see section 6.17).
8473
8474 A portion of the string can specified as non-expandable by placing it between
8475 two occurrences of "\N". This is particularly useful for protecting regular
8476 expressions, which often contain backslashes and dollar signs. For example:
8477
8478 deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
8479
8480 On encountering the first "\N", the expander copies subsequent characters
8481 without interpretation until it reaches the next "\N" or the end of the string.
8482
8483
8484 11.2 Character escape sequences in expanded strings
8485 ---------------------------------------------------
8486
8487 A backslash followed by one of the letters "n", "r", or "t" in an expanded
8488 string is recognized as an escape sequence for the character newline, carriage
8489 return, or tab, respectively. A backslash followed by up to three octal digits
8490 is recognized as an octal encoding for a single character, and a backslash
8491 followed by "x" and up to two hexadecimal digits is a hexadecimal encoding.
8492
8493 These escape sequences are also recognized in quoted strings when they are read
8494 in. Their interpretation in expansions as well is useful for unquoted strings,
8495 and for other cases such as looked-up strings that are then expanded.
8496
8497
8498 11.3 Testing string expansions
8499 ------------------------------
8500
8501 Many expansions can be tested by calling Exim with the -be option. This takes
8502 the command arguments, or lines from the standard input if there are no
8503 arguments, runs them through the string expansion code, and writes the results
8504 to the standard output. Variables based on configuration values are set up, but
8505 since no message is being processed, variables such as $local_part have no
8506 value. Nevertheless the -be option can be useful for checking out file and
8507 database lookups, and the use of expansion operators such as sg, substr and
8508 nhash.
8509
8510 Exim gives up its root privilege when it is called with the -be option, and
8511 instead runs under the uid and gid it was called with, to prevent users from
8512 using -be for reading files to which they do not have access.
8513
8514 If you want to test expansions that include variables whose values are taken
8515 from a message, there are two other options that can be used. The -bem option
8516 is like -be except that it is followed by a filename. The file is read as a
8517 message before doing the test expansions. For example:
8518
8519 exim -bem /tmp/test.message '$h_subject:'
8520
8521 The -Mset option is used in conjunction with -be and is followed by an Exim
8522 message identifier. For example:
8523
8524 exim -be -Mset 1GrA8W-0004WS-LQ '$recipients'
8525
8526 This loads the message from Exim's spool before doing the test expansions, and
8527 is therefore restricted to admin users.
8528
8529
8530 11.4 Forced expansion failure
8531 -----------------------------
8532
8533 A number of expansions that are described in the following section have
8534 alternative "true" and "false" substrings, enclosed in brace characters (which
8535 are sometimes called "curly brackets"). Which of the two strings is used
8536 depends on some condition that is evaluated as part of the expansion. If,
8537 instead of a "false" substring, the word "fail" is used (not in braces), the
8538 entire string expansion fails in a way that can be detected by the code that
8539 requested the expansion. This is called "forced expansion failure", and its
8540 consequences depend on the circumstances. In some cases it is no different from
8541 any other expansion failure, but in others a different action may be taken.
8542 Such variations are mentioned in the documentation of the option that is being
8543 expanded.
8544
8545
8546 11.5 Expansion items
8547 --------------------
8548
8549 The following items are recognized in expanded strings. White space may be used
8550 between sub-items that are keywords or substrings enclosed in braces inside an
8551 outer set of braces, to improve readability. Warning: Within braces, white
8552 space is significant.
8553
8554 $<variable name> or ${<variable name>}
8555
8556 Substitute the contents of the named variable, for example:
8557
8558 $local_part
8559 ${domain}
8560
8561 The second form can be used to separate the name from subsequent
8562 alphanumeric characters. This form (using braces) is available only for
8563 variables; it does not apply to message headers. The names of the variables
8564 are given in section 11.9 below. If the name of a non-existent variable is
8565 given, the expansion fails.
8566
8567 ${<op>:<string>}
8568
8569 The string is first itself expanded, and then the operation specified by <
8570 op> is applied to it. For example:
8571
8572 ${lc:$local_part}
8573
8574 The string starts with the first character after the colon, which may be
8575 leading white space. A list of operators is given in section 11.6 below.
8576 The operator notation is used for simple expansion items that have just one
8577 argument, because it reduces the number of braces and therefore makes the
8578 string easier to understand.
8579
8580 $bheader_<header name>: or $bh_<header name>:
8581
8582 This item inserts "basic" header lines. It is described with the header
8583 expansion item below.
8584
8585 ${acl{<name>}{<arg>}...}
8586
8587 The name and zero to nine argument strings are first expanded separately.
8588 The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
8589 in order. Any unused are made empty. The variable $acl_narg is set to the
8590 number of arguments. The named ACL (see chapter 43) is called and may use
8591 the variables; if another acl expansion is used the values are restored
8592 after it returns. If the ACL sets a value using a "message =" modifier and
8593 returns accept or deny, the value becomes the result of the expansion. If
8594 no message is set and the ACL returns accept or deny the expansion result
8595 is an empty string. If the ACL returns defer the result is a forced-fail.
8596 Otherwise the expansion fails.
8597
8598 ${authresults{<authserv-id>}}
8599
8600 This item returns a string suitable for insertion as an
8601 Authentication-Results" header line. The given <authserv-id> is included in
8602 the result; typically this will be a domain name identifying the system
8603 performing the authentications. Methods that might be present in the result
8604 include:
8605
8606 none
8607 iprev
8608 auth
8609 spf
8610 dkim
8611
8612 Example use (as an ACL modifier):
8613
8614 add_header = :at_start:${authresults {$primary_hostname}}
8615
8616 This is safe even if no authentication results are available.
8617
8618 ${certextract{<field>}{<certificate>}{<string2>}{<string3>}}
8619
8620 The <certificate> must be a variable of type certificate. The field name is
8621 expanded and used to retrieve the relevant field from the certificate.
8622 Supported fields are:
8623
8624 version
8625 serial_number
8626 subject RFC4514 DN
8627 issuer RFC4514 DN
8628 notbefore time
8629 notafter time
8630 sig_algorithm
8631 signature
8632 subj_altname tagged list
8633 ocsp_uri list
8634 crl_uri list
8635
8636 If the field is found, <string2> is expanded, and replaces the whole item;
8637 otherwise <string3> is used. During the expansion of <string2> the variable
8638 $value contains the value that has been extracted. Afterwards, it is
8639 restored to any previous value it might have had.
8640
8641 If {<string3>} is omitted, the item is replaced by an empty string if the
8642 key is not found. If {<string2>} is also omitted, the value that was
8643 extracted is used.
8644
8645 Some field names take optional modifiers, appended and separated by commas.
8646
8647 The field selectors marked as "RFC4514" above output a Distinguished Name
8648 string which is not quite parseable by Exim as a comma-separated tagged
8649 list (the exceptions being elements containing commas). RDN elements of a
8650 single type may be selected by a modifier of the type label; if so the
8651 expansion result is a list (newline-separated by default). The separator
8652 may be changed by another modifier of a right angle-bracket followed
8653 immediately by the new separator. Recognised RDN type labels include "CN",
8654 "O", "OU" and "DC".
8655
8656 The field selectors marked as "time" above take an optional modifier of
8657 "int" for which the result is the number of seconds since epoch. Otherwise
8658 the result is a human-readable string in the timezone selected by the main
8659 "timezone" option.
8660
8661 The field selectors marked as "list" above return a list, newline-separated
8662 by default, (embedded separator characters in elements are doubled). The
8663 separator may be changed by a modifier of a right angle-bracket followed
8664 immediately by the new separator.
8665
8666 The field selectors marked as "tagged" above prefix each list element with
8667 a type string and an equals sign. Elements of only one type may be selected
8668 by a modifier which is one of "dns", "uri" or "mail"; if so the element
8669 tags are omitted.
8670
8671 If not otherwise noted field values are presented in human-readable form.
8672
8673 ${dlfunc{<file>}{<function>}{<arg>}{<arg>}...}
8674
8675 This expansion dynamically loads and then calls a locally-written C
8676 function. This functionality is available only if Exim is compiled with
8677
8678 EXPAND_DLFUNC=yes
8679
8680 set in Local/Makefile. Once loaded, Exim remembers the dynamically loaded
8681 object so that it doesn't reload the same object file in the same Exim
8682 process (but of course Exim does start new processes frequently).
8683
8684 There may be from zero to eight arguments to the function. When compiling a
8685 local function that is to be called in this way, local_scan.h should be
8686 included. The Exim variables and functions that are defined by that API are
8687 also available for dynamically loaded functions. The function itself must
8688 have the following type:
8689
8690 int dlfunction(uschar **yield, int argc, uschar *argv[])
8691
8692 Where "uschar" is a typedef for "unsigned char" in local_scan.h. The
8693 function should return one of the following values:
8694
8695 "OK": Success. The string that is placed in the variable yield is put into
8696 the expanded string that is being built.
8697
8698 "FAIL": A non-forced expansion failure occurs, with the error message taken
8699 from yield, if it is set.
8700
8701 "FAIL_FORCED": A forced expansion failure occurs, with the error message
8702 taken from yield if it is set.
8703
8704 "ERROR": Same as "FAIL", except that a panic log entry is written.
8705
8706 When compiling a function that is to be used in this way with gcc, you need
8707 to add -shared to the gcc command. Also, in the Exim build-time
8708 configuration, you must add -export-dynamic to EXTRALIBS.
8709
8710 ${env{<key>}{<string1>}{<string2>}}
8711
8712 The key is first expanded separately, and leading and trailing white space
8713 removed. This is then searched for as a name in the environment. If a
8714 variable is found then its value is placed in $value and <string1> is
8715 expanded, otherwise <string2> is expanded.
8716
8717 Instead of {<string2>} the word "fail" (not in curly brackets) can appear,
8718 for example:
8719
8720 ${env{USER}{$value} fail }
8721
8722 This forces an expansion failure (see section 11.4); {<string1>} must be
8723 present for "fail" to be recognized.
8724
8725 If {<string2>} is omitted an empty string is substituted on search failure.
8726 If {<string1>} is omitted the search result is substituted on search
8727 success.
8728
8729 The environment is adjusted by the keep_environment and add_environment
8730 main section options.
8731
8732 ${extract{<key>}{<string1>}{<string2>}{<string3>}}
8733
8734 The key and <string1> are first expanded separately. Leading and trailing
8735 white space is removed from the key (but not from any of the strings). The
8736 key must not be empty and must not consist entirely of digits. The expanded
8737 <string1> must be of the form:
8738
8739 <key1> = <value1> <key2> = <value2> ...
8740
8741 where the equals signs and spaces (but not both) are optional. If any of
8742 the values contain white space, they must be enclosed in double quotes, and
8743 any values that are enclosed in double quotes are subject to escape
8744 processing as described in section 6.17. The expanded <string1> is searched
8745 for the value that corresponds to the key. The search is case-insensitive.
8746 If the key is found, <string2> is expanded, and replaces the whole item;
8747 otherwise <string3> is used. During the expansion of <string2> the variable
8748 $value contains the value that has been extracted. Afterwards, it is
8749 restored to any previous value it might have had.
8750
8751 If {<string3>} is omitted, the item is replaced by an empty string if the
8752 key is not found. If {<string2>} is also omitted, the value that was
8753 extracted is used. Thus, for example, these two expansions are identical,
8754 and yield "2001":
8755
8756 ${extract{gid}{uid=1984 gid=2001}}
8757 ${extract{gid}{uid=1984 gid=2001}{$value}}
8758
8759 Instead of {<string3>} the word "fail" (not in curly brackets) can appear,
8760 for example:
8761
8762 ${extract{Z}{A=... B=...}{$value} fail }
8763
8764 This forces an expansion failure (see section 11.4); {<string2>} must be
8765 present for "fail" to be recognized.
8766
8767 ${extract json{<key>}{<string1>}{<string2>}{<string3>}}
8768
8769 The key and <string1> are first expanded separately. Leading and trailing
8770 white space is removed from the key (but not from any of the strings). The
8771 key must not be empty and must not consist entirely of digits. The expanded
8772 <string1> must be of the form:
8773
8774 { <"key1"> : <value1> , <"key2"> , <value2> ... }
8775
8776 The braces, commas and colons, and the quoting of the member name are
8777 required; the spaces are optional. Matching of the key against the member
8778 names is done case-sensitively.
8779
8780 The results of matching are handled as above.
8781
8782 ${extract{<number>}{<separators>}{<string1>}{<string2>}{<string3>}}
8783
8784 The <number> argument must consist entirely of decimal digits, apart from
8785 leading and trailing white space, which is ignored. This is what
8786 distinguishes this form of extract from the previous kind. It behaves in
8787 the same way, except that, instead of extracting a named field, it extracts
8788 from <string1> the field whose number is given as the first argument. You
8789 can use $value in <string2> or "fail" instead of <string3> as before.
8790
8791 The fields in the string are separated by any one of the characters in the
8792 separator string. These may include space or tab characters. The first
8793 field is numbered one. If the number is negative, the fields are counted
8794 from the end of the string, with the rightmost one numbered -1. If the
8795 number given is zero, the entire string is returned. If the modulus of the
8796 number is greater than the number of fields in the string, the result is
8797 the expansion of <string3>, or the empty string if <string3> is not
8798 provided. For example:
8799
8800 ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}}
8801
8802 yields "42", and
8803
8804 ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}}
8805
8806 yields "99". Two successive separators mean that the field between them is
8807 empty (for example, the fifth field above).
8808
8809 ${extract json{<number>}}{<string1>}{<string2>}{<string3>}}
8810
8811 The <number> argument must consist entirely of decimal digits, apart from
8812 leading and trailing white space, which is ignored.
8813
8814 Field selection and result handling is as above; there is no choice of
8815 field separator.
8816
8817 ${filter{<string>}{<condition>}}
8818
8819 After expansion, <string> is interpreted as a list, colon-separated by
8820 default, but the separator can be changed in the usual way (6.21). For each
8821 item in this list, its value is place in $item, and then the condition is
8822 evaluated. If the condition is true, $item is added to the output as an
8823 item in a new list; if the condition is false, the item is discarded. The
8824 separator used for the output list is the same as the one used for the
8825 input, but a separator setting is not included in the output. For example:
8826
8827 ${filter{a:b:c}{!eq{$item}{b}}}
8828
8829 yields "a:c". At the end of the expansion, the value of $item is restored
8830 to what it was before. See also the map and reduce expansion items.
8831
8832 ${hash{<string1>}{<string2>}{<string3>}}
8833
8834 This is a textual hashing function, and was the first to be implemented in
8835 early versions of Exim. In current releases, there are other hashing
8836 functions (numeric, MD5, and SHA-1), which are described below.
8837
8838 The first two strings, after expansion, must be numbers. Call them <m> and
8839 <n>. If you are using fixed values for these numbers, that is, if <string1>
8840 and <string2> do not change when they are expanded, you can use the simpler
8841 operator notation that avoids some of the braces:
8842
8843 ${hash_<n>_<m>:<string>}
8844
8845 The second number is optional (in both notations). If <n> is greater than
8846 or equal to the length of the string, the expansion item returns the
8847 string. Otherwise it computes a new string of length <n> by applying a
8848 hashing function to the string. The new string consists of characters taken
8849 from the first <m> characters of the string
8850
8851 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
8852
8853 If <m> is not present the value 26 is used, so that only lower case letters
8854 appear. For example:
8855
8856 $hash{3}{monty}} yields jmg
8857 $hash{5}{monty}} yields monty
8858 $hash{4}{62}{monty python}} yields fbWx
8859
8860 $header_<header name>: or $h_<header name>:, $bheader_<header name>: or $bh_<
8861 header name>:, $lheader_<header name>: or $lh_<header name>:
8862
8863 "$rheader_<header name>: or $rh_<header name>:" Substitute the contents of
8864 the named message header line, for example
8865
8866 $header_reply-to:
8867
8868 The newline that terminates a header line is not included in the expansion,
8869 but internal newlines (caused by splitting the header line over several
8870 physical lines) may be present.
8871
8872 The difference between the four pairs of expansions is in the way the data
8873 in the header line is interpreted.
8874
8875 + rheader gives the original "raw" content of the header line, with no
8876 processing at all, and without the removal of leading and trailing
8877 white space.
8878
8879 + lheader gives a colon-separated list, one element per header when there
8880 are multiple headers with a given name. Any embedded colon characters
8881 within an element are doubled, so normal Exim list-processing
8882 facilities can be used. The terminating newline of each element is
8883 removed; in other respects the content is "raw".
8884
8885 + bheader removes leading and trailing white space, and then decodes
8886 base64 or quoted-printable MIME "words" within the header text, but
8887 does no character set translation. If decoding of what looks
8888 superficially like a MIME "word" fails, the raw string is returned. If
8889 decoding produces a binary zero character, it is replaced by a question
8890 mark - this is what Exim does for binary zeros that are actually
8891 received in header lines.
8892
8893 + header tries to translate the string as decoded by bheader to a
8894 standard character set. This is an attempt to produce the same string
8895 as would be displayed on a user's MUA. If translation fails, the
8896 bheader string is returned. Translation is attempted only on operating
8897 systems that support the iconv() function. This is indicated by the
8898 compile-time macro HAVE_ICONV in a system Makefile or in Local/Makefile
8899 .
8900
8901 In a filter file, the target character set for header can be specified by a
8902 command of the following form:
8903
8904 headers charset "UTF-8"
8905
8906 This command affects all references to $h_ (or $header_) expansions in
8907 subsequently obeyed filter commands. In the absence of this command, the
8908 target character set in a filter is taken from the setting of the
8909 headers_charset option in the runtime configuration. The value of this
8910 option defaults to the value of HEADERS_CHARSET in Local/Makefile. The
8911 ultimate default is ISO-8859-1.
8912
8913 Header names follow the syntax of RFC 2822, which states that they may
8914 contain any printing characters except space and colon. Consequently, curly
8915 brackets do not terminate header names, and should not be used to enclose
8916 them as if they were variables. Attempting to do so causes a syntax error.
8917
8918 Only header lines that are common to all copies of a message are visible to
8919 this mechanism. These are the original header lines that are received with
8920 the message, and any that are added by an ACL statement or by a system
8921 filter. Header lines that are added to a particular copy of a message by a
8922 router or transport are not accessible.
8923
8924 For incoming SMTP messages, no header lines are visible in ACLs that are
8925 obeyed before the data phase completes, because the header structure is not
8926 set up until the message is received. They are visible in DKIM, PRDR and
8927 DATA ACLs. Header lines that are added in a RCPT ACL (for example) are
8928 saved until the message's incoming header lines are available, at which
8929 point they are added. When any of the above ACLs ar running, however,
8930 header lines added by earlier ACLs are visible.
8931
8932 Upper case and lower case letters are synonymous in header names. If the
8933 following character is white space, the terminating colon may be omitted,
8934 but this is not recommended, because you may then forget it when it is
8935 needed. When white space terminates the header name, this white space is
8936 included in the expanded string. If the message does not contain the given
8937 header, the expansion item is replaced by an empty string. (See the def
8938 condition in section 11.7 for a means of testing for the existence of a
8939 header.)
8940
8941 If there is more than one header with the same name, they are all
8942 concatenated to form the substitution string, up to a maximum length of
8943 64K. Unless rheader is being used, leading and trailing white space is
8944 removed from each header before concatenation, and a completely empty
8945 header is ignored. A newline character is then inserted between non-empty
8946 headers, but there is no newline at the very end. For the header and
8947 bheader expansion, for those headers that contain lists of addresses, a
8948 comma is also inserted at the junctions between headers. This does not
8949 happen for the rheader expansion.
8950
8951 ${hmac{<hashname>}{<secret>}{<string>}}
8952
8953 This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
8954 shared secret and some text into a message authentication code, as
8955 specified in RFC 2104. This differs from "${md5:secret_text...}" or "$
8956 {sha1:secret_text...}" in that the hmac step adds a signature to the
8957 cryptographic hash, allowing for authentication that is not possible with
8958 MD5 or SHA-1 alone. The hash name must expand to either "md5" or "sha1" at
8959 present. For example:
8960
8961 ${hmac{md5}{somesecret}{$primary_hostname $tod_log}}
8962
8963 For the hostname mail.example.com and time 2002-10-17 11:30:59, this
8964 produces:
8965
8966 dd97e3ba5d1a61b5006108f8c8252953
8967
8968 As an example of how this might be used, you might put in the main part of
8969 an Exim configuration:
8970
8971 SPAMSCAN_SECRET=cohgheeLei2thahw
8972
8973 In a router or a transport you could then have:
8974
8975 headers_add = \
8976 X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \
8977 ${hmac{md5}{SPAMSCAN_SECRET}\
8978 {${primary_hostname},${message_exim_id},$h_message-id:}}
8979
8980 Then given a message, you can check where it was scanned by looking at the
8981 X-Spam-Scanned: header line. If you know the secret, you can check that
8982 this header line is authentic by recomputing the authentication code from
8983 the host name, message ID and the Message-id: header line. This can be done
8984 using Exim's -be option, or by other means, for example, by using the
8985 hmac_md5_hex() function in Perl.
8986
8987 ${if <condition> {<string1>}{<string2>}}
8988
8989 If <condition> is true, <string1> is expanded and replaces the whole item;
8990 otherwise <string2> is used. The available conditions are described in
8991 section 11.7 below. For example:
8992
8993 ${if eq {$local_part}{postmaster} {yes}{no} }
8994
8995 The second string need not be present; if it is not and the condition is
8996 not true, the item is replaced with nothing. Alternatively, the word "fail"
8997 may be present instead of the second string (without any curly brackets).
8998 In this case, the expansion is forced to fail if the condition is not true
8999 (see section 11.4).
9000
9001 If both strings are omitted, the result is the string "true" if the
9002 condition is true, and the empty string if the condition is false. This
9003 makes it less cumbersome to write custom ACL and router conditions. For
9004 example, instead of
9005
9006 condition = ${if >{$acl_m4}{3}{true}{false}}
9007
9008 you can use
9009
9010 condition = ${if >{$acl_m4}{3}}
9011
9012 ${imapfolder{<foldername>}}
9013
9014 This item converts a (possibly multilevel, or with non-ASCII characters)
9015 folder specification to a Maildir name for filesystem use. For information
9016 on internationalisation support see 59.2.
9017
9018 ${length{<string1>}{<string2>}}
9019
9020 The length item is used to extract the initial portion of a string. Both
9021 strings are expanded, and the first one must yield a number, <n>, say. If
9022 you are using a fixed value for the number, that is, if <string1> does not
9023 change when expanded, you can use the simpler operator notation that avoids
9024 some of the braces:
9025
9026 ${length_<n>:<string>}
9027
9028 The result of this item is either the first <n> bytes or the whole of <
9029 string2>, whichever is the shorter. Do not confuse length with strlen,
9030 which gives the length of a string. All measurement is done in bytes and is
9031 not UTF-8 aware.
9032
9033 ${listextract{<number>}{<string1>}{<string2>}{<string3>}}
9034
9035 The <number> argument must consist entirely of decimal digits, apart from
9036 an optional leading minus, and leading and trailing white space (which is
9037 ignored).
9038
9039 After expansion, <string1> is interpreted as a list, colon-separated by
9040 default, but the separator can be changed in the usual way (6.21).
9041
9042 The first field of the list is numbered one. If the number is negative, the
9043 fields are counted from the end of the list, with the rightmost one
9044 numbered -1. The numbered element of the list is extracted and placed in
9045 $value, then <string2> is expanded as the result.
9046
9047 If the modulus of the number is zero or greater than the number of fields
9048 in the string, the result is the expansion of <string3>.
9049
9050 For example:
9051
9052 ${listextract{2}{x:42:99}}
9053
9054 yields "42", and
9055
9056 ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
9057
9058 yields "result: 42".
9059
9060 If {<string3>} is omitted, an empty string is used for string3. If {<
9061 string2>} is also omitted, the value that was extracted is used. You can
9062 use "fail" instead of {<string3>} as in a string extract.
9063
9064 ${lookup{<key>} <search type> {<file>} {<string1>} {<string2>}}
9065
9066 This is the first of one of two different types of lookup item, which are
9067 both described in the next item.
9068
9069 ${lookup <search type> {<query>} {<string1>} {<string2>}}
9070
9071 The two forms of lookup item specify data lookups in files and databases,
9072 as discussed in chapter 9. The first form is used for single-key lookups,
9073 and the second is used for query-style lookups. The <key>, <file>, and <
9074 query> strings are expanded before use.
9075
9076 If there is any white space in a lookup item which is part of a filter
9077 command, a retry or rewrite rule, a routing rule for the manualroute
9078 router, or any other place where white space is significant, the lookup
9079 item must be enclosed in double quotes. The use of data lookups in users'
9080 filter files may be locked out by the system administrator.
9081
9082 If the lookup succeeds, <string1> is expanded and replaces the entire item.
9083 During its expansion, the variable $value contains the data returned by the
9084 lookup. Afterwards it reverts to the value it had previously (at the outer
9085 level it is empty). If the lookup fails, <string2> is expanded and replaces
9086 the entire item. If {<string2>} is omitted, the replacement is the empty
9087 string on failure. If <string2> is provided, it can itself be a nested
9088 lookup, thus providing a mechanism for looking up a default value when the
9089 original lookup fails.
9090
9091 If a nested lookup is used as part of <string1>, $value contains the data
9092 for the outer lookup while the parameters of the second lookup are
9093 expanded, and also while <string2> of the second lookup is expanded, should
9094 the second lookup fail. Instead of {<string2>} the word "fail" can appear,
9095 and in this case, if the lookup fails, the entire expansion is forced to
9096 fail (see section 11.4). If both {<string1>} and {<string2>} are omitted,
9097 the result is the looked up value in the case of a successful lookup, and
9098 nothing in the case of failure.
9099
9100 For single-key lookups, the string "partial" is permitted to precede the
9101 search type in order to do partial matching, and * or *@ may follow a
9102 search type to request default lookups if the key does not match (see
9103 sections 9.6 and 9.7 for details).
9104
9105 If a partial search is used, the variables $1 and $2 contain the wild and
9106 non-wild parts of the key during the expansion of the replacement text.
9107 They return to their previous values at the end of the lookup item.
9108
9109 This example looks up the postmaster alias in the conventional alias file:
9110
9111 ${lookup {postmaster} lsearch {/etc/aliases} {$value}}
9112
9113 This example uses NIS+ to look up the full name of the user corresponding
9114 to the local part of an address, forcing the expansion to fail if it is not
9115 found:
9116
9117 ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
9118 {$value}fail}
9119
9120 ${map{<string1>}{<string2>}}
9121
9122 After expansion, <string1> is interpreted as a list, colon-separated by
9123 default, but the separator can be changed in the usual way (6.21). For each
9124 item in this list, its value is place in $item, and then <string2> is
9125 expanded and added to the output as an item in a new list. The separator
9126 used for the output list is the same as the one used for the input, but a
9127 separator setting is not included in the output. For example:
9128
9129 ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}}
9130
9131 expands to "[a]:[b]:[c] (x)-(y)-(z)". At the end of the expansion, the
9132 value of $item is restored to what it was before. See also the filter and
9133 reduce expansion items.
9134
9135 ${nhash{<string1>}{<string2>}{<string3>}}
9136
9137 The three strings are expanded; the first two must yield numbers. Call them
9138 <n> and <m>. If you are using fixed values for these numbers, that is, if <
9139 string1> and <string2> do not change when they are expanded, you can use
9140 the simpler operator notation that avoids some of the braces:
9141
9142 ${nhash_<n>_<m>:<string>}
9143
9144 The second number is optional (in both notations). If there is only one
9145 number, the result is a number in the range 0-<n>-1. Otherwise, the string
9146 is processed by a div/mod hash function that returns two numbers, separated
9147 by a slash, in the ranges 0 to <n>-1 and 0 to <m>-1, respectively. For
9148 example,
9149
9150 ${nhash{8}{64}{supercalifragilisticexpialidocious}}
9151
9152 returns the string "6/33".
9153
9154 ${perl{<subroutine>}{<arg>}{<arg>}...}
9155
9156 This item is available only if Exim has been built to include an embedded
9157 Perl interpreter. The subroutine name and the arguments are first
9158 separately expanded, and then the Perl subroutine is called with those
9159 arguments. No additional arguments need be given; the maximum number
9160 permitted, including the name of the subroutine, is nine.
9161
9162 The return value of the subroutine is inserted into the expanded string,
9163 unless the return value is undef. In that case, the expansion fails in the
9164 same way as an explicit "fail" on a lookup item. The return value is a
9165 scalar. Whatever you return is evaluated in a scalar context. For example,
9166 if you return the name of a Perl vector, the return value is the size of
9167 the vector, not its contents.
9168
9169 If the subroutine exits by calling Perl's die function, the expansion fails
9170 with the error message that was passed to die. More details of the embedded
9171 Perl facility are given in chapter 12.
9172
9173 The redirect router has an option called forbid_filter_perl which locks out
9174 the use of this expansion item in filter files.
9175
9176 ${prvs{<address>}{<secret>}{<keynumber>}}
9177
9178 The first argument is a complete email address and the second is secret
9179 keystring. The third argument, specifying a key number, is optional. If
9180 absent, it defaults to 0. The result of the expansion is a prvs-signed
9181 email address, to be typically used with the return_path option on an smtp
9182 transport as part of a bounce address tag validation (BATV) scheme. For
9183 more discussion and an example, see section 43.51.
9184
9185 ${prvscheck{<address>}{<secret>}{<string>}}
9186
9187 This expansion item is the complement of the prvs item. It is used for
9188 checking prvs-signed addresses. If the expansion of the first argument does
9189 not yield a syntactically valid prvs-signed address, the whole item expands
9190 to the empty string. When the first argument does expand to a syntactically
9191 valid prvs-signed address, the second argument is expanded, with the
9192 prvs-decoded version of the address and the key number extracted from the
9193 address in the variables $prvscheck_address and $prvscheck_keynum,
9194 respectively.
9195
9196 These two variables can be used in the expansion of the second argument to
9197 retrieve the secret. The validity of the prvs-signed address is then
9198 checked against the secret. The result is stored in the variable
9199 $prvscheck_result, which is empty for failure or "1" for success.
9200
9201 The third argument is optional; if it is missing, it defaults to an empty
9202 string. This argument is now expanded. If the result is an empty string,
9203 the result of the expansion is the decoded version of the address. This is
9204 the case whether or not the signature was valid. Otherwise, the result of
9205 the expansion is the expansion of the third argument.
9206
9207 All three variables can be used in the expansion of the third argument.
9208 However, once the expansion is complete, only $prvscheck_result remains
9209 set. For more discussion and an example, see section 43.51.
9210
9211 ${readfile{<file name>}{<eol string>}}
9212
9213 The filename and end-of-line string are first expanded separately. The file
9214 is then read, and its contents replace the entire item. All newline
9215 characters in the file are replaced by the end-of-line string if it is
9216 present. Otherwise, newlines are left in the string. String expansion is
9217 not applied to the contents of the file. If you want this, you must wrap
9218 the item in an expand operator. If the file cannot be read, the string
9219 expansion fails.
9220
9221 The redirect router has an option called forbid_filter_readfile which locks
9222 out the use of this expansion item in filter files.
9223
9224 ${readsocket{<name>}{<request>}{<options>}{<eol string>}{<fail string>}}
9225
9226 This item inserts data from a Unix domain or TCP socket into the expanded
9227 string. The minimal way of using it uses just two arguments, as in these
9228 examples:
9229
9230 ${readsocket{/socket/name}{request string}}
9231 ${readsocket{inet:some.host:1234}{request string}}
9232
9233 For a Unix domain socket, the first substring must be the path to the
9234 socket. For an Internet socket, the first substring must contain "inet:"
9235 followed by a host name or IP address, followed by a colon and a port,
9236 which can be a number or the name of a TCP port in /etc/services. An IP
9237 address may optionally be enclosed in square brackets. This is best for
9238 IPv6 addresses. For example:
9239
9240 ${readsocket{inet:[::1]:1234}{request string}}
9241
9242 Only a single host name may be given, but if looking it up yields more than
9243 one IP address, they are each tried in turn until a connection is made. For
9244 both kinds of socket, Exim makes a connection, writes the request string
9245 unless it is an empty string; and no terminating NUL is ever sent) and
9246 reads from the socket until an end-of-file is read. A timeout of 5 seconds
9247 is applied. Additional, optional arguments extend what can be done.
9248 Firstly, you can vary the timeout. For example:
9249
9250 ${readsocket{/socket/name}{request string}{3s}}
9251
9252 The third argument is a list of options, of which the first element is the
9253 timeout and must be present if the argument is given. Further elements are
9254 options of form name=value. Two option types is currently recognised:
9255 shutdown and tls. The first defines whether (the default) or not a shutdown
9256 is done on the connection after sending the request. Example, to not do so
9257 (preferred, eg. by some webservers):
9258
9259 ${readsocket{/socket/name}{request string}{3s:shutdown=no}}
9260
9261 The second, tls, controls the use of TLS on the connection. Example:
9262
9263 ${readsocket{/socket/name}{request string}{3s:tls=yes}}
9264
9265 The default is to not use TLS. If it is enabled, a shutdown as descripbed
9266 above is never done.
9267
9268 A fourth argument allows you to change any newlines that are in the data
9269 that is read, in the same way as for readfile (see above). This example
9270 turns them into spaces:
9271
9272 ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }}
9273
9274 As with all expansions, the substrings are expanded before the processing
9275 happens. Errors in these sub-expansions cause the expansion to fail. In
9276 addition, the following errors can occur:
9277
9278 + Failure to create a socket file descriptor;
9279
9280 + Failure to connect the socket;
9281
9282 + Failure to write the request string;
9283
9284 + Timeout on reading from the socket.
9285
9286 By default, any of these errors causes the expansion to fail. However, if
9287 you supply a fifth substring, it is expanded and used when any of the above
9288 errors occurs. For example:
9289
9290 ${readsocket{/socket/name}{request string}{3s}{\n}\
9291 {socket failure}}
9292
9293 You can test for the existence of a Unix domain socket by wrapping this
9294 expansion in "${if exists", but there is a race condition between that test
9295 and the actual opening of the socket, so it is safer to use the fifth
9296 argument if you want to be absolutely sure of avoiding an expansion error
9297 for a non-existent Unix domain socket, or a failure to connect to an
9298 Internet socket.
9299
9300 The redirect router has an option called forbid_filter_readsocket which
9301 locks out the use of this expansion item in filter files.
9302
9303 ${reduce{<string1>}{<string2>}{<string3>}}
9304
9305 This operation reduces a list to a single, scalar string. After expansion,
9306 <string1> is interpreted as a list, colon-separated by default, but the
9307 separator can be changed in the usual way (6.21). Then <string2> is
9308 expanded and assigned to the $value variable. After this, each item in the
9309 <string1> list is assigned to $item, in turn, and <string3> is expanded for
9310 each of them. The result of that expansion is assigned to $value before the
9311 next iteration. When the end of the list is reached, the final value of
9312 $value is added to the expansion output. The reduce expansion item can be
9313 used in a number of ways. For example, to add up a list of numbers:
9314
9315 ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}}
9316
9317 The result of that expansion would be "6". The maximum of a list of numbers
9318 can be found:
9319
9320 ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}}
9321
9322 At the end of a reduce expansion, the values of $item and $value are
9323 restored to what they were before. See also the filter and map expansion
9324 items.
9325
9326 $rheader_<header name>: or $rh_<header name>:
9327
9328 This item inserts "raw" header lines. It is described with the header
9329 expansion item in section 11.5 above.
9330
9331 ${run{<command> <args>}{<string1>}{<string2>}}
9332
9333 The command and its arguments are first expanded as one string. The string
9334 is split apart into individual arguments by spaces, and then the command is
9335 run in a separate process, but under the same uid and gid. As in other
9336 command executions from Exim, a shell is not used by default. If the
9337 command requires a shell, you must explicitly code it.
9338
9339 Since the arguments are split by spaces, when there is a variable expansion
9340 which has an empty result, it will cause the situation that the argument
9341 will simply be omitted when the program is actually executed by Exim. If
9342 the script/program requires a specific number of arguments and the expanded
9343 variable could possibly result in this empty expansion, the variable must
9344 be quoted. This is more difficult if the expanded variable itself could
9345 result in a string containing quotes, because it would interfere with the
9346 quotes around the command arguments. A possible guard against this is to
9347 wrap the variable in the sg operator to change any quote marks to some
9348 other character.
9349
9350 The standard input for the command exists, but is empty. The standard
9351 output and standard error are set to the same file descriptor. If the
9352 command succeeds (gives a zero return code) <string1> is expanded and
9353 replaces the entire item; during this expansion, the standard output/error
9354 from the command is in the variable $value. If the command fails, <string2
9355 >, if present, is expanded and used. Once again, during the expansion, the
9356 standard output/error from the command is in the variable $value.
9357
9358 If <string2> is absent, the result is empty. Alternatively, <string2> can
9359 be the word "fail" (not in braces) to force expansion failure if the
9360 command does not succeed. If both strings are omitted, the result is
9361 contents of the standard output/error on success, and nothing on failure.
9362
9363 The standard output/error of the command is put in the variable $value. In
9364 this ACL example, the output of a command is logged for the admin to
9365 troubleshoot:
9366
9367 warn condition = ${run{/usr/bin/id}{yes}{no}}
9368 log_message = Output of id: $value
9369
9370 If the command requires shell idioms, such as the > redirect operator, the
9371 shell must be invoked directly, such as with:
9372
9373 ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}}
9374
9375 The return code from the command is put in the variable $runrc, and this
9376 remains set afterwards, so in a filter file you can do things like this:
9377
9378 if "${run{x y z}{}}$runrc" is 1 then ...
9379 elif $runrc is 2 then ...
9380 ...
9381 endif
9382
9383 If execution of the command fails (for example, the command does not
9384 exist), the return code is 127 - the same code that shells use for
9385 non-existent commands.
9386
9387 Warning: In a router or transport, you cannot assume the order in which
9388 option values are expanded, except for those preconditions whose order of
9389 testing is documented. Therefore, you cannot reliably expect to set $runrc
9390 by the expansion of one option, and use it in another.
9391
9392 The redirect router has an option called forbid_filter_run which locks out
9393 the use of this expansion item in filter files.
9394
9395 ${sg{<subject>}{<regex>}{<replacement>}}
9396
9397 This item works like Perl's substitution operator (s) with the global (/g)
9398 option; hence its name. However, unlike the Perl equivalent, Exim does not
9399 modify the subject string; instead it returns the modified string for
9400 insertion into the overall expansion. The item takes three arguments: the
9401 subject string, a regular expression, and a substitution string. For
9402 example:
9403
9404 ${sg{abcdefabcdef}{abc}{xyz}}
9405
9406 yields "xyzdefxyzdef". Because all three arguments are expanded before use,
9407 if any $, } or \ characters are required in the regular expression or in
9408 the substitution string, they have to be escaped. For example:
9409
9410 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
9411
9412 yields "defabc", and
9413
9414 ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
9415
9416 yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of
9417 the regular expression from string expansion.
9418
9419 The regular expression is compiled in 8-bit mode, working against bytes
9420 rather than any Unicode-aware character handling.
9421
9422 ${sort{<string>}{<comparator>}{<extractor>}}
9423
9424 After expansion, <string> is interpreted as a list, colon-separated by
9425 default, but the separator can be changed in the usual way (6.21). The <
9426 comparator> argument is interpreted as the operator of a two-argument
9427 expansion condition. The numeric operators plus ge, gt, le, lt (and ~i
9428 variants) are supported. The comparison should return true when applied to
9429 two values if the first value should sort before the second value. The <
9430 extractor> expansion is applied repeatedly to elements of the list, the
9431 element being placed in $item, to give values for comparison.
9432
9433 The item result is a sorted list, with the original list separator, of the
9434 list elements (in full) of the original.
9435
9436 Examples:
9437
9438 ${sort{3:2:1:4}{<}{$item}}
9439
9440 sorts a list of numbers, and
9441
9442 ${sort {${lookup dnsdb{>:,,mx=example.com}}} {<} {${listextract{1}{<,$item}}}}
9443
9444 will sort an MX lookup into priority order.
9445
9446 ${substr{<string1>}{<string2>}{<string3>}}
9447
9448 The three strings are expanded; the first two must yield numbers. Call them
9449 <n> and <m>. If you are using fixed values for these numbers, that is, if <
9450 string1> and <string2> do not change when they are expanded, you can use
9451 the simpler operator notation that avoids some of the braces:
9452
9453 ${substr_<n>_<m>:<string>}
9454
9455 The second number is optional (in both notations). If it is absent in the
9456 simpler format, the preceding underscore must also be omitted.
9457
9458 The substr item can be used to extract more general substrings than length.
9459 The first number, <n>, is a starting offset, and <m> is the length
9460 required. For example
9461
9462 ${substr{3}{2}{$local_part}}
9463
9464 If the starting offset is greater than the string length the result is the
9465 null string; if the length plus starting offset is greater than the string
9466 length, the result is the right-hand part of the string, starting from the
9467 given offset. The first byte (character) in the string has offset zero.
9468
9469 The substr expansion item can take negative offset values to count from the
9470 right-hand end of its operand. The last byte (character) is offset -1, the
9471 second-last is offset -2, and so on. Thus, for example,
9472
9473 ${substr{-5}{2}{1234567}}
9474
9475 yields "34". If the absolute value of a negative offset is greater than the
9476 length of the string, the substring starts at the beginning of the string,
9477 and the length is reduced by the amount of overshoot. Thus, for example,
9478
9479 ${substr{-5}{2}{12}}
9480
9481 yields an empty string, but
9482
9483 ${substr{-3}{2}{12}}
9484
9485 yields "1".
9486
9487 When the second number is omitted from substr, the remainder of the string
9488 is taken if the offset is positive. If it is negative, all bytes
9489 (characters) in the string preceding the offset point are taken. For
9490 example, an offset of -1 and no length, as in these semantically identical
9491 examples:
9492
9493 ${substr_-1:abcde}
9494 ${substr{-1}{abcde}}
9495
9496 yields all but the last character of the string, that is, "abcd".
9497
9498 All measurement is done in bytes and is not UTF-8 aware.
9499
9500 ${tr{<subject>}{<characters>}{<replacements>}}
9501
9502 This item does single-character (in bytes) translation on its subject
9503 string. The second argument is a list of characters to be translated in the
9504 subject string. Each matching character is replaced by the corresponding
9505 character from the replacement list. For example
9506
9507 ${tr{abcdea}{ac}{13}}
9508
9509 yields "1b3de1". If there are duplicates in the second character string,
9510 the last occurrence is used. If the third string is shorter than the
9511 second, its last character is replicated. However, if it is empty, no
9512 translation takes place.
9513
9514 All character handling is done in bytes and is not UTF-8 aware.
9515
9516
9517 11.6 Expansion operators
9518 ------------------------
9519
9520 For expansion items that perform transformations on a single argument string,
9521 the "operator" notation is used because it is simpler and uses fewer braces.
9522 The substring is first expanded before the operation is applied to it. The
9523 following operations can be performed:
9524
9525 ${address:<string>}
9526
9527 The string is interpreted as an RFC 2822 address, as it might appear in a
9528 header line, and the effective address is extracted from it. If the string
9529 does not parse successfully, the result is empty.
9530
9531 The parsing correctly handles SMTPUTF8 Unicode in the string.
9532
9533 ${addresses:<string>}
9534
9535 The string (after expansion) is interpreted as a list of addresses in RFC
9536 2822 format, such as can be found in a To: or Cc: header line. The
9537 operative address (local-part@domain) is extracted from each item, and the
9538 result of the expansion is a colon-separated list, with appropriate
9539 doubling of colons should any happen to be present in the email addresses.
9540 Syntactically invalid RFC2822 address items are omitted from the output.
9541
9542 It is possible to specify a character other than colon for the output
9543 separator by starting the string with > followed by the new separator
9544 character. For example:
9545
9546 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
9547
9548 expands to "ceo@up.stairs&sec@base.ment". The string is expanded first, so
9549 if the expanded string starts with >, it may change the output separator
9550 unintentionally. This can be avoided by setting the output separator
9551 explicitly:
9552
9553 ${addresses:>:$h_from:}
9554
9555 Compare the address (singular) expansion item, which extracts the working
9556 address from a single RFC2822 address. See the filter, map, and reduce
9557 items for ways of processing lists.
9558
9559 To clarify "list of addresses in RFC 2822 format" mentioned above, Exim
9560 follows a strict interpretation of header line formatting. Exim parses the
9561 bare, unquoted portion of an email address and if it finds a comma, treats
9562 it as an email address separator. For the example header line:
9563
9564 From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com>
9565
9566 The first example below demonstrates that Q-encoded email addresses are
9567 parsed properly if it is given the raw header (in this example,
9568 "$rheader_from:"). It does not see the comma because it's still encoded as
9569 "=2C". The second example below is passed the contents of "$header_from:",
9570 meaning it gets de-mimed. Exim sees the decoded "," so it treats it as two
9571 email addresses. The third example shows that the presence of a comma is
9572 skipped when it is quoted. The fourth example shows SMTPUTF8 handling.
9573
9574 # exim -be '${addresses:From: \
9575 =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}'
9576 user@example.com
9577 # exim -be '${addresses:From: Last, First <user@example.com>}'
9578 Last:user@example.com
9579 # exim -be '${addresses:From: "Last, First" <user@example.com>}'
9580 user@example.com
9581 # exim -be '${addresses:?????? <??????????@example.jp>}'
9582 ??????????@example.jp
9583
9584 ${base32:<digits>}
9585
9586 The string must consist entirely of decimal digits. The number is converted
9587 to base 32 and output as a (empty, for zero) string of characters. Only
9588 lowercase letters are used.
9589
9590 ${base32d:<base-32 digits>}
9591
9592 The string must consist entirely of base-32 digits. The number is converted
9593 to decimal and output as a string.
9594
9595 ${base62:<digits>}
9596
9597 The string must consist entirely of decimal digits. The number is converted
9598 to base 62 and output as a string of six characters, including leading
9599 zeros. In the few operating environments where Exim uses base 36 instead of
9600 base 62 for its message identifiers (because those systems do not have
9601 case-sensitive filenames), base 36 is used by this operator, despite its
9602 name. Note: Just to be absolutely clear: this is not base64 encoding.
9603
9604 ${base62d:<base-62 digits>}
9605
9606 The string must consist entirely of base-62 digits, or, in operating
9607 environments where Exim uses base 36 instead of base 62 for its message
9608 identifiers, base-36 digits. The number is converted to decimal and output
9609 as a string.
9610
9611 ${base64:<string>}
9612
9613 This operator converts a string into one that is base64 encoded.
9614
9615 If the string is a single variable of type certificate, returns the base64
9616 encoding of the DER form of the certificate.
9617
9618 ${base64d:<string>}
9619
9620 This operator converts a base64-encoded string into the un-coded form.
9621
9622 ${domain:<string>}
9623
9624 The string is interpreted as an RFC 2822 address and the domain is
9625 extracted from it. If the string does not parse successfully, the result is
9626 empty.
9627
9628 ${escape:<string>}
9629
9630 If the string contains any non-printing characters, they are converted to
9631 escape sequences starting with a backslash. Whether characters with the
9632 most significant bit set (so-called "8-bit characters") count as printing
9633 or not is controlled by the print_topbitchars option.
9634
9635 ${escape8bit:<string>}
9636
9637 If the string contains and characters with the most significant bit set,
9638 they are converted to escape sequences starting with a backslash.
9639 Backslashes and DEL characters are also converted.
9640
9641 ${eval:<string>} and ${eval10:<string>}
9642
9643 These items supports simple arithmetic and bitwise logical operations in
9644 expansion strings. The string (after expansion) must be a conventional
9645 arithmetic expression, but it is limited to basic arithmetic operators,
9646 bitwise logical operators, and parentheses. All operations are carried out
9647 using integer arithmetic. The operator priorities are as follows (the same
9648 as in the C programming language):
9649
9650 highest: not (~), negate (-)
9651 multiply (*), divide (/), remainder (%)
9652 plus (+), minus (-)
9653 shift-left (<<), shift-right (>>)
9654 and (&)
9655 xor (^)
9656 lowest: or (|)
9657
9658 Binary operators with the same priority are evaluated from left to right.
9659 White space is permitted before or after operators.
9660
9661 For eval, numbers may be decimal, octal (starting with "0") or hexadecimal
9662 (starting with "0x"). For eval10, all numbers are taken as decimal, even if
9663 they start with a leading zero; hexadecimal numbers are not permitted. This
9664 can be useful when processing numbers extracted from dates or times, which
9665 often do have leading zeros.
9666
9667 A number may be followed by "K", "M" or "G" to multiply it by 1024,
9668 1024*1024 or 1024*1024*1024, respectively. Negative numbers are supported.
9669 The result of the computation is a decimal representation of the answer
9670 (without "K", "M" or "G"). For example:
9671
9672 ${eval:1+1} yields 2
9673 ${eval:1+2*3} yields 7
9674 ${eval:(1+2)*3} yields 9
9675 ${eval:2+42%5} yields 4
9676 ${eval:0xc&5} yields 4
9677 ${eval:0xc|5} yields 13
9678 ${eval:0xc^5} yields 9
9679 ${eval:0xc>>1} yields 6
9680 ${eval:0xc<<1} yields 24
9681 ${eval:~255&0x1234} yields 4608
9682 ${eval:-(~255&0x1234)} yields -4608
9683
9684 As a more realistic example, in an ACL you might have
9685
9686 deny message = Too many bad recipients
9687 condition = \
9688 ${if and { \
9689 {>{$rcpt_count}{10}} \
9690 { \
9691 < \
9692 {$recipients_count} \
9693 {${eval:$rcpt_count/2}} \
9694 } \
9695 }{yes}{no}}
9696
9697 The condition is true if there have been more than 10 RCPT commands and
9698 fewer than half of them have resulted in a valid recipient.
9699
9700 ${expand:<string>}
9701
9702 The expand operator causes a string to be expanded for a second time. For
9703 example,
9704
9705 ${expand:${lookup{$domain}dbm{/some/file}{$value}}}
9706
9707 first looks up a string in a file while expanding the operand for expand,
9708 and then re-expands what it has found.
9709
9710 ${from_utf8:<string>}
9711
9712 The world is slowly moving towards Unicode, although there are no standards
9713 for email yet. However, other applications (including some databases) are
9714 starting to store data in Unicode, using UTF-8 encoding. This operator
9715 converts from a UTF-8 string to an ISO-8859-1 string. UTF-8 code values
9716 greater than 255 are converted to underscores. The input must be a valid
9717 UTF-8 string. If it is not, the result is an undefined sequence of bytes.
9718
9719 Unicode code points with values less than 256 are compatible with ASCII and
9720 ISO-8859-1 (also known as Latin-1). For example, character 169 is the
9721 copyright symbol in both cases, though the way it is encoded is different.
9722 In UTF-8, more than one byte is needed for characters with code values
9723 greater than 127, whereas ISO-8859-1 is a single-byte encoding (but thereby
9724 limited to 256 characters). This makes translation from UTF-8 to ISO-8859-1
9725 straightforward.
9726
9727 ${hash_<n>_<m>:<string>}
9728
9729 The hash operator is a simpler interface to the hashing function that can
9730 be used when the two parameters are fixed numbers (as opposed to strings
9731 that change when expanded). The effect is the same as
9732
9733 ${hash{<n>}{<m>}{<string>}}
9734
9735 See the description of the general hash item above for details. The
9736 abbreviation h can be used when hash is used as an operator.
9737
9738 ${hex2b64:<hexstring>}
9739
9740 This operator converts a hex string into one that is base64 encoded. This
9741 can be useful for processing the output of the various hashing functions.
9742
9743 ${hexquote:<string>}
9744
9745 This operator converts non-printable characters in a string into a hex
9746 escape form. Byte values between 33 (!) and 126 (~) inclusive are left as
9747 is, and other byte values are converted to "\xNN", for example, a byte
9748 value 127 is converted to "\x7f".
9749
9750 ${ipv6denorm:<string>}
9751
9752 This expands an IPv6 address to a full eight-element colon-separated set of
9753 hex digits including leading zeroes. A trailing ipv4-style dotted-decimal
9754 set is converted to hex. Pure IPv4 addresses are converted to IPv4-mapped
9755 IPv6.
9756
9757 ${ipv6norm:<string>}
9758
9759 This converts an IPv6 address to canonical form. Leading zeroes of groups
9760 are omitted, and the longest set of zero-valued groups is replaced with a
9761 double colon. A trailing ipv4-style dotted-decimal set is converted to hex.
9762 Pure IPv4 addresses are converted to IPv4-mapped IPv6.
9763
9764 ${lc:<string>}
9765
9766 This forces the letters in the string into lower-case, for example:
9767
9768 ${lc:$local_part}
9769
9770 Case is defined per the system C locale.
9771
9772 ${length_<number>:<string>}
9773
9774 The length operator is a simpler interface to the length function that can
9775 be used when the parameter is a fixed number (as opposed to a string that
9776 changes when expanded). The effect is the same as
9777
9778 ${length{<number>}{<string>}}
9779
9780 See the description of the general length item above for details. Note that
9781 length is not the same as strlen. The abbreviation l can be used when
9782 length is used as an operator. All measurement is done in bytes and is not
9783 UTF-8 aware.
9784
9785 ${listcount:<string>}
9786
9787 The string is interpreted as a list and the number of items is returned.
9788
9789 ${listnamed:<name>} and ${listnamed_<type>:<name>}
9790
9791 The name is interpreted as a named list and the content of the list is
9792 returned, expanding any referenced lists, re-quoting as needed for
9793 colon-separation. If the optional type is given it must be one of "a", "d",
9794 "h" or "l" and selects address-, domain-, host- or localpart- lists to
9795 search among respectively. Otherwise all types are searched in an undefined
9796 order and the first matching list is returned.
9797
9798 ${local_part:<string>}
9799
9800 The string is interpreted as an RFC 2822 address and the local part is
9801 extracted from it. If the string does not parse successfully, the result is
9802 empty. The parsing correctly handles SMTPUTF8 Unicode in the string.
9803
9804 ${mask:<IP address>/<bit count>}
9805
9806 If the form of the string to be operated on is not an IP address followed
9807 by a slash and an integer (that is, a network address in CIDR notation),
9808 the expansion fails. Otherwise, this operator converts the IP address to
9809 binary, masks off the least significant bits according to the bit count,
9810 and converts the result back to text, with mask appended. For example,
9811
9812 ${mask:10.111.131.206/28}
9813
9814 returns the string "10.111.131.192/28". Since this operation is expected to
9815 be mostly used for looking up masked addresses in files, the result for an
9816 IPv6 address uses dots to separate components instead of colons, because
9817 colon terminates a key string in lsearch files. So, for example,
9818
9819 ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99}
9820
9821 returns the string
9822
9823 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
9824
9825 Letters in IPv6 addresses are always output in lower case.
9826
9827 ${md5:<string>}
9828
9829 The md5 operator computes the MD5 hash value of the string, and returns it
9830 as a 32-digit hexadecimal number, in which any letters are in lower case.
9831
9832 If the string is a single variable of type certificate, returns the MD5
9833 hash fingerprint of the certificate.
9834
9835 ${nhash_<n>_<m>:<string>}
9836
9837 The nhash operator is a simpler interface to the numeric hashing function
9838 that can be used when the two parameters are fixed numbers (as opposed to
9839 strings that change when expanded). The effect is the same as
9840
9841 ${nhash{<n>}{<m>}{<string>}}
9842
9843 See the description of the general nhash item above for details.
9844
9845 ${quote:<string>}
9846
9847 The quote operator puts its argument into double quotes if it is an empty
9848 string or contains anything other than letters, digits, underscores, dots,
9849 and hyphens. Any occurrences of double quotes and backslashes are escaped
9850 with a backslash. Newlines and carriage returns are converted to "\n" and "
9851 \r", respectively For example,
9852
9853 ${quote:ab"*"cd}
9854
9855 becomes
9856
9857 "ab\"*\"cd"
9858
9859 The place where this is useful is when the argument is a substitution from
9860 a variable or a message header.
9861
9862 ${quote_local_part:<string>}
9863
9864 This operator is like quote, except that it quotes the string only if
9865 required to do so by the rules of RFC 2822 for quoting local parts. For
9866 example, a plus sign would not cause quoting (but it would for quote). If
9867 you are creating a new email address from the contents of $local_part (or
9868 any other unknown data), you should always use this operator.
9869
9870 This quoting determination is not SMTPUTF8-aware, thus quoting non-ASCII
9871 data will likely use the quoting form. Thus ${quote_local_part:??????} will
9872 always become "??????".
9873
9874 ${quote_<lookup-type>:<string>}
9875
9876 This operator applies lookup-specific quoting rules to the string. Each
9877 query-style lookup type has its own quoting rules which are described with
9878 the lookups in chapter 9. For example,
9879
9880 ${quote_ldap:two * two}
9881
9882 returns
9883
9884 two%20%5C2A%20two
9885
9886 For single-key lookup types, no quoting is ever necessary and this operator
9887 yields an unchanged string.
9888
9889 ${randint:<n>}
9890
9891 This operator returns a somewhat random number which is less than the
9892 supplied number and is at least 0. The quality of this randomness depends
9893 on how Exim was built; the values are not suitable for keying material. If
9894 Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. If Exim is
9895 linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used, for
9896 versions of GnuTLS with that function. Otherwise, the implementation may be
9897 arc4random(), random() seeded by srandomdev() or srandom(), or a custom
9898 implementation even weaker than random().
9899
9900 ${reverse_ip:<ipaddr>}
9901
9902 This operator reverses an IP address; for IPv4 addresses, the result is in
9903 dotted-quad decimal form, while for IPv6 addresses the result is in
9904 dotted-nibble hexadecimal form. In both cases, this is the "natural" form
9905 for DNS. For example,
9906
9907 ${reverse_ip:192.0.2.4}
9908 ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127}
9909
9910 returns
9911
9912 4.2.0.192
9913 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
9914
9915 ${rfc2047:<string>}
9916
9917 This operator encodes text according to the rules of RFC 2047. This is an
9918 encoding that is used in header lines to encode non-ASCII characters. It is
9919 assumed that the input string is in the encoding specified by the
9920 headers_charset option, which gets its default at build time. If the string
9921 contains only characters in the range 33-126, and no instances of the
9922 characters
9923
9924 ? = ( ) < > @ , ; : \ " . [ ] _
9925
9926 it is not modified. Otherwise, the result is the RFC 2047 encoding of the
9927 string, using as many "encoded words" as necessary to encode all the
9928 characters.
9929
9930 ${rfc2047d:<string>}
9931
9932 This operator decodes strings that are encoded as per RFC 2047. Binary zero
9933 bytes are replaced by question marks. Characters are converted into the
9934 character set defined by headers_charset. Overlong RFC 2047 "words" are not
9935 recognized unless check_rfc2047_length is set false.
9936
9937 Note: If you use $header_xxx: (or $h_xxx:) to access a header line, RFC
9938 2047 decoding is done automatically. You do not need to use this operator
9939 as well.
9940
9941 ${rxquote:<string>}
9942
9943 The rxquote operator inserts a backslash before any non-alphanumeric
9944 characters in its argument. This is useful when substituting the values of
9945 variables or headers inside regular expressions.
9946
9947 ${sha1:<string>}
9948
9949 The sha1 operator computes the SHA-1 hash value of the string, and returns
9950 it as a 40-digit hexadecimal number, in which any letters are in upper
9951 case.
9952
9953 If the string is a single variable of type certificate, returns the SHA-1
9954 hash fingerprint of the certificate.
9955
9956 ${sha256:<string>}
9957
9958 The sha256 operator computes the SHA-256 hash value of the string and
9959 returns it as a 64-digit hexadecimal number, in which any letters are in
9960 upper case.
9961
9962 If the string is a single variable of type certificate, returns the SHA-256
9963 hash fingerprint of the certificate.
9964
9965 ${sha3:<string>}, ${sha3_<n>:<string>}
9966
9967 The sha3 operator computes the SHA3-256 hash value of the string and
9968 returns it as a 64-digit hexadecimal number, in which any letters are in
9969 upper case.
9970
9971 If a number is appended, separated by an underbar, it specifies the output
9972 length. Values of 224, 256, 384 and 512 are accepted; with 256 being the
9973 default.
9974
9975 The sha3 expansion item is only supported if Exim has been compiled with
9976 GnuTLS 3.5.0 or later, or OpenSSL 1.1.1 or later. The macro
9977 "_CRYPTO_HASH_SHA3" will be defined if it is supported.
9978
9979 ${stat:<string>}
9980
9981 The string, after expansion, must be a file path. A call to the stat()
9982 function is made for this path. If stat() fails, an error occurs and the
9983 expansion fails. If it succeeds, the data from the stat replaces the item,
9984 as a series of <name>=<value> pairs, where the values are all numerical,
9985 except for the value of "smode". The names are: "mode" (giving the mode as
9986 a 4-digit octal number), "smode" (giving the mode in symbolic format as a
9987 10-character string, as for the ls command), "inode", "device", "links",
9988 "uid", "gid", "size", "atime", "mtime", and "ctime". You can extract
9989 individual fields using the extract expansion item.
9990
9991 The use of the stat expansion in users' filter files can be locked out by
9992 the system administrator. Warning: The file size may be incorrect on 32-bit
9993 systems for files larger than 2GB.
9994
9995 ${str2b64:<string>}
9996
9997 Now deprecated, a synonym for the base64 expansion operator.
9998
9999 ${strlen:<string>}
10000
10001 The item is replace by the length of the expanded string, expressed as a
10002 decimal number. Note: Do not confuse strlen with length. All measurement is
10003 done in bytes and is not UTF-8 aware.
10004
10005 ${substr_<start>_<length>:<string>}
10006
10007 The substr operator is a simpler interface to the substr function that can
10008 be used when the two parameters are fixed numbers (as opposed to strings
10009 that change when expanded). The effect is the same as
10010
10011 ${substr{<start>}{<length>}{<string>}}
10012
10013 See the description of the general substr item above for details. The
10014 abbreviation s can be used when substr is used as an operator. All
10015 measurement is done in bytes and is not UTF-8 aware.
10016
10017 ${time_eval:<string>}
10018
10019 This item converts an Exim time interval such as "2d4h5m" into a number of
10020 seconds.
10021
10022 ${time_interval:<string>}
10023
10024 The argument (after sub-expansion) must be a sequence of decimal digits
10025 that represents an interval of time as a number of seconds. It is converted
10026 into a number of larger units and output in Exim's normal time format, for
10027 example, "1w3d4h2m6s".
10028
10029 ${uc:<string>}
10030
10031 This forces the letters in the string into upper-case. Case is defined per
10032 the system C locale.
10033
10034 ${utf8clean:<string>}
10035
10036 This replaces any invalid utf-8 sequence in the string by the character "?
10037 ".
10038
10039 In versions of Exim before 4.92, this did not correctly do so for a
10040 truncated final codepoint's encoding, and the character would be silently
10041 dropped. If you must handle detection of this scenario across both sets of
10042 Exim behavior, the complexity will depend upon the task. For instance, to
10043 detect if the first character is multibyte and a 1-byte extraction can be
10044 successfully used as a path component (as is common for dividing up
10045 delivery folders), you might use:
10046
10047 condition = ${if inlist{${utf8clean:${length_1:$local_part}}}{:?}{yes}{no}}
10048
10049 (which will false-positive if the first character of the local part is a
10050 literal question mark).
10051
10052 ${utf8_domain_to_alabel:<string>}, ${utf8_domain_from_alabel:<string>}, $
10053 {utf8_localpart_to_alabel:<string>}, ${utf8_localpart_from_alabel:<string>}
10054
10055 These convert EAI mail name components between UTF-8 and a-label forms. For
10056 information on internationalisation support see 59.1.
10057
10058
10059 11.7 Expansion conditions
10060 -------------------------
10061
10062 The following conditions are available for testing by the ${if construct while
10063 expanding strings:
10064
10065 !<condition>
10066
10067 Preceding any condition with an exclamation mark negates the result of the
10068 condition.
10069
10070 <symbolic operator> {<string1>}{<string2>}
10071
10072 There are a number of symbolic operators for doing numeric comparisons.
10073 They are:
10074
10075 = equal
10076 == equal
10077 > greater
10078 >= greater or equal
10079 < less
10080 <= less or equal
10081
10082 For example:
10083
10084 ${if >{$message_size}{10M} ...
10085
10086 Note that the general negation operator provides for inequality testing.
10087 The two strings must take the form of optionally signed decimal integers,
10088 optionally followed by one of the letters "K", "M" or "G" (in either upper
10089 or lower case), signifying multiplication by 1024, 1024*1024 or
10090 1024*1024*1024, respectively. As a special case, the numerical value of an
10091 empty string is taken as zero.
10092
10093 In all cases, a relative comparator OP is testing if <string1> OP <string2
10094 >; the above example is checking if $message_size is larger than 10M, not
10095 if 10M is larger than $message_size.
10096
10097 acl {{<name>}{<arg1>}{<arg2>}...}
10098
10099 The name and zero to nine argument strings are first expanded separately.
10100 The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
10101 in order. Any unused are made empty. The variable $acl_narg is set to the
10102 number of arguments. The named ACL (see chapter 43) is called and may use
10103 the variables; if another acl expansion is used the values are restored
10104 after it returns. If the ACL sets a value using a "message =" modifier the
10105 variable $value becomes the result of the expansion, otherwise it is empty.
10106 If the ACL returns accept the condition is true; if deny, false. If the ACL
10107 returns defer the result is a forced-fail.
10108
10109 bool {<string>}
10110
10111 This condition turns a string holding a true or false representation into a
10112 boolean state. It parses "true", "false", "yes" and "no"
10113 (case-insensitively); also integer numbers map to true if non-zero, false
10114 if zero. An empty string is treated as false. Leading and trailing
10115 whitespace is ignored; thus a string consisting only of whitespace is
10116 false. All other string values will result in expansion failure.
10117
10118 When combined with ACL variables, this expansion condition will let you
10119 make decisions in one place and act on those decisions in another place.
10120 For example:
10121
10122 ${if bool{$acl_m_privileged_sender} ...
10123
10124 bool_lax {<string>}
10125
10126 Like bool, this condition turns a string into a boolean state. But where
10127 bool accepts a strict set of strings, bool_lax uses the same loose
10128 definition that the Router condition option uses. The empty string and the
10129 values "false", "no" and "0" map to false, all others map to true. Leading
10130 and trailing whitespace is ignored.
10131
10132 Note that where "bool{00}" is false, "bool_lax{00}" is true.
10133
10134 crypteq {<string1>}{<string2>}
10135
10136 This condition is included in the Exim binary if it is built to support any
10137 authentication mechanisms (see chapter 33). Otherwise, it is necessary to
10138 define SUPPORT_CRYPTEQ in Local/Makefile to get crypteq included in the
10139 binary.
10140
10141 The crypteq condition has two arguments. The first is encrypted and
10142 compared against the second, which is already encrypted. The second string
10143 may be in the LDAP form for storing encrypted strings, which starts with
10144 the encryption type in curly brackets, followed by the data. If the second
10145 string does not begin with "{" it is assumed to be encrypted with crypt()
10146 or crypt16() (see below), since such strings cannot begin with "{".
10147 Typically this will be a field from a password file. An example of an
10148 encrypted string in LDAP form is:
10149
10150 {md5}CY9rzUYh03PK3k6DJie09g==
10151
10152 If such a string appears directly in an expansion, the curly brackets have
10153 to be quoted, because they are part of the expansion syntax. For example:
10154
10155 ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
10156
10157 The following encryption types (whose names are matched case-independently)
10158 are supported:
10159
10160 + {md5} computes the MD5 digest of the first string, and expresses this
10161 as printable characters to compare with the remainder of the second
10162 string. If the length of the comparison string is 24, Exim assumes that
10163 it is base64 encoded (as in the above example). If the length is 32,
10164 Exim assumes that it is a hexadecimal encoding of the MD5 digest. If
10165 the length not 24 or 32, the comparison fails.
10166
10167 + {sha1} computes the SHA-1 digest of the first string, and expresses
10168 this as printable characters to compare with the remainder of the
10169 second string. If the length of the comparison string is 28, Exim
10170 assumes that it is base64 encoded. If the length is 40, Exim assumes
10171 that it is a hexadecimal encoding of the SHA-1 digest. If the length is
10172 not 28 or 40, the comparison fails.
10173
10174 + {crypt} calls the crypt() function, which traditionally used to use
10175 only the first eight characters of the password. However, in modern
10176 operating systems this is no longer true, and in many cases the entire
10177 password is used, whatever its length.
10178
10179 + {crypt16} calls the crypt16() function, which was originally created to
10180 use up to 16 characters of the password in some operating systems.
10181 Again, in modern operating systems, more characters may be used.
10182
10183 Exim has its own version of crypt16(), which is just a double call to crypt
10184 (). For operating systems that have their own version, setting HAVE_CRYPT16
10185 in Local/Makefile when building Exim causes it to use the operating system
10186 version instead of its own. This option is set by default in the
10187 OS-dependent Makefile for those operating systems that are known to support
10188 crypt16().
10189
10190 Some years after Exim's crypt16() was implemented, a user discovered that
10191 it was not using the same algorithm as some operating systems' versions. It
10192 turns out that as well as crypt16() there is a function called bigcrypt()
10193 in some operating systems. This may or may not use the same algorithm, and
10194 both of them may be different to Exim's built-in crypt16().
10195
10196 However, since there is now a move away from the traditional crypt()
10197 functions towards using SHA1 and other algorithms, tidying up this area of
10198 Exim is seen as very low priority.
10199
10200 If you do not put a encryption type (in curly brackets) in a crypteq
10201 comparison, the default is usually either "{crypt}" or "{crypt16}", as
10202 determined by the setting of DEFAULT_CRYPT in Local/Makefile. The default
10203 default is "{crypt}". Whatever the default, you can always use either
10204 function by specifying it explicitly in curly brackets.
10205
10206 def:<variable name>
10207
10208 The def condition must be followed by the name of one of the expansion
10209 variables defined in section 11.9. The condition is true if the variable
10210 does not contain the empty string. For example:
10211
10212 ${if def:sender_ident {from $sender_ident}}
10213
10214 Note that the variable name is given without a leading $ character. If the
10215 variable does not exist, the expansion fails.
10216
10217 def:header_<header name>: or def:h_<header name>:
10218
10219 This condition is true if a message is being processed and the named header
10220 exists in the message. For example,
10221
10222 ${if def:header_reply-to:{$h_reply-to:}{$h_from:}}
10223
10224 Note: No $ appears before header_ or h_ in the condition, and the header
10225 name must be terminated by a colon if white space does not follow.
10226
10227 eq {<string1>}{<string2>}, eqi {<string1>}{<string2>}
10228
10229 The two substrings are first expanded. The condition is true if the two
10230 resulting strings are identical. For eq the comparison includes the case of
10231 letters, whereas for eqi the comparison is case-independent, where case is
10232 defined per the system C locale.
10233
10234 exists {<file name>}
10235
10236 The substring is first expanded and then interpreted as an absolute path.
10237 The condition is true if the named file (or directory) exists. The
10238 existence test is done by calling the stat() function. The use of the
10239 exists test in users' filter files may be locked out by the system
10240 administrator.
10241
10242 first_delivery
10243
10244 This condition, which has no data, is true during a message's first
10245 delivery attempt. It is false during any subsequent delivery attempts.
10246
10247 forall{<a list>}{<a condition>}, forany{<a list>}{<a condition>}
10248
10249 These conditions iterate over a list. The first argument is expanded to
10250 form the list. By default, the list separator is a colon, but it can be
10251 changed by the normal method (6.21). The second argument is interpreted as
10252 a condition that is to be applied to each item in the list in turn. During
10253 the interpretation of the condition, the current list item is placed in a
10254 variable called $item.
10255
10256 + For forany, interpretation stops if the condition is true for any item,
10257 and the result of the whole condition is true. If the condition is
10258 false for all items in the list, the overall condition is false.
10259
10260 + For forall, interpretation stops if the condition is false for any
10261 item, and the result of the whole condition is false. If the condition
10262 is true for all items in the list, the overall condition is true.
10263
10264 Note that negation of forany means that the condition must be false for all
10265 items for the overall condition to succeed, and negation of forall means
10266 that the condition must be false for at least one item. In this example,
10267 the list separator is changed to a comma:
10268
10269 ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}}
10270
10271 The value of $item is saved and restored while forany or forall is being
10272 processed, to enable these expansion items to be nested.
10273
10274 To scan a named list, expand it with the listnamed operator.
10275
10276 ge {<string1>}{<string2>}, gei {<string1>}{<string2>}
10277
10278 The two substrings are first expanded. The condition is true if the first
10279 string is lexically greater than or equal to the second string. For ge the
10280 comparison includes the case of letters, whereas for gei the comparison is
10281 case-independent. Case and collation order are defined per the system C
10282 locale.
10283
10284 gt {<string1>}{<string2>}, gti {<string1>}{<string2>}
10285
10286 The two substrings are first expanded. The condition is true if the first
10287 string is lexically greater than the second string. For gt the comparison
10288 includes the case of letters, whereas for gti the comparison is
10289 case-independent. Case and collation order are defined per the system C
10290 locale.
10291
10292 inlist {<string1>}{<string2>}, inlisti {<string1>}{<string2>}
10293
10294 Both strings are expanded; the second string is treated as a list of simple
10295 strings; if the first string is a member of the second, then the condition
10296 is true. For the case-independent inlisti condition, case is defined per
10297 the system C locale.
10298
10299 These are simpler to use versions of the more powerful forany condition.
10300 Examples, and the forany equivalents:
10301
10302 ${if inlist{needle}{foo:needle:bar}}
10303 ${if forany{foo:needle:bar}{eq{$item}{needle}}}
10304 ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
10305 ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
10306
10307 isip {<string>}, isip4 {<string>}, isip6 {<string>}
10308
10309 The substring is first expanded, and then tested to see if it has the form
10310 of an IP address. Both IPv4 and IPv6 addresses are valid for isip, whereas
10311 isip4 and isip6 test specifically for IPv4 or IPv6 addresses.
10312
10313 For an IPv4 address, the test is for four dot-separated components, each of
10314 which consists of from one to three digits. For an IPv6 address, up to
10315 eight colon-separated components are permitted, each containing from one to
10316 four hexadecimal digits. There may be fewer than eight components if an
10317 empty component (adjacent colons) is present. Only one empty component is
10318 permitted.
10319
10320 Note: The checks used to be just on the form of the address; actual
10321 numerical values were not considered. Thus, for example, 999.999.999.999
10322 passed the IPv4 check. This is no longer the case.
10323
10324 The main use of these tests is to distinguish between IP addresses and host
10325 names, or between IPv4 and IPv6 addresses. For example, you could use
10326
10327 ${if isip4{$sender_host_address}...
10328
10329 to test which IP version an incoming SMTP connection is using.
10330
10331 ldapauth {<ldap query>}
10332
10333 This condition supports user authentication using LDAP. See section 9.14
10334 for details of how to use LDAP in lookups and the syntax of queries. For
10335 this use, the query must contain a user name and password. The query itself
10336 is not used, and can be empty. The condition is true if the password is not
10337 empty, and the user name and password are accepted by the LDAP server. An
10338 empty password is rejected without calling LDAP because LDAP binds with an
10339 empty password are considered anonymous regardless of the username, and
10340 will succeed in most configurations. See chapter 33 for details of SMTP
10341 authentication, and chapter 34 for an example of how this can be used.
10342
10343 le {<string1>}{<string2>}, lei {<string1>}{<string2>}
10344
10345 The two substrings are first expanded. The condition is true if the first
10346 string is lexically less than or equal to the second string. For le the
10347 comparison includes the case of letters, whereas for lei the comparison is
10348 case-independent. Case and collation order are defined per the system C
10349 locale.
10350
10351 lt {<string1>}{<string2>}, lti {<string1>}{<string2>}
10352
10353 The two substrings are first expanded. The condition is true if the first
10354 string is lexically less than the second string. For lt the comparison
10355 includes the case of letters, whereas for lti the comparison is
10356 case-independent. Case and collation order are defined per the system C
10357 locale.
10358
10359 match {<string1>}{<string2>}
10360
10361 The two substrings are first expanded. The second is then treated as a
10362 regular expression and applied to the first. Because of the pre-expansion,
10363 if the regular expression contains dollar, or backslash characters, they
10364 must be escaped. Care must also be taken if the regular expression contains
10365 braces (curly brackets). A closing brace must be escaped so that it is not
10366 taken as a premature termination of <string2>. The easiest approach is to
10367 use the "\N" feature to disable expansion of the regular expression. For
10368 example,
10369
10370 ${if match {$local_part}{\N^\d{3}\N} ...
10371
10372 If the whole expansion string is in double quotes, further escaping of
10373 backslashes is also required.
10374
10375 The condition is true if the regular expression match succeeds. The regular
10376 expression is not required to begin with a circumflex metacharacter, but if
10377 there is no circumflex, the expression is not anchored, and it may match
10378 anywhere in the subject, not just at the start. If you want the pattern to
10379 match at the end of the subject, you must include the "$" metacharacter at
10380 an appropriate point. All character handling is done in bytes and is not
10381 UTF-8 aware, but we might change this in a future Exim release.
10382
10383 At the start of an if expansion the values of the numeric variable
10384 substitutions $1 etc. are remembered. Obeying a match condition that
10385 succeeds causes them to be reset to the substrings of that condition and
10386 they will have these values during the expansion of the success string. At
10387 the end of the if expansion, the previous values are restored. After
10388 testing a combination of conditions using or, the subsequent values of the
10389 numeric variables are those of the condition that succeeded.
10390
10391 match_address {<string1>}{<string2>}
10392
10393 See match_local_part.
10394
10395 match_domain {<string1>}{<string2>}
10396
10397 See match_local_part.
10398
10399 match_ip {<string1>}{<string2>}
10400
10401 This condition matches an IP address to a list of IP address patterns. It
10402 must be followed by two argument strings. The first (after expansion) must
10403 be an IP address or an empty string. The second (not expanded) is a
10404 restricted host list that can match only an IP address, not a host name.
10405 For example:
10406
10407 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
10408
10409 The specific types of host list item that are permitted in the list are:
10410
10411 + An IP address, optionally with a CIDR mask.
10412
10413 + A single asterisk, which matches any IP address.
10414
10415 + An empty item, which matches only if the IP address is empty. This
10416 could be useful for testing for a locally submitted message or one from
10417 specific hosts in a single test such as
10418
10419 ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}}
10420
10421 where the first item in the list is the empty string.
10422
10423 + The item @[] matches any of the local host's interface addresses.
10424
10425 + Single-key lookups are assumed to be like "net-" style lookups in host
10426 lists, even if "net-" is not specified. There is never any attempt to
10427 turn the IP address into a host name. The most common type of linear
10428 search for match_ip is likely to be iplsearch, in which the file can
10429 contain CIDR masks. For example:
10430
10431 ${if match_ip{$sender_host_address}{iplsearch;/some/file}...
10432
10433 It is of course possible to use other kinds of lookup, and in such a
10434 case, you do need to specify the "net-" prefix if you want to specify a
10435 specific address mask, for example:
10436
10437 ${if match_ip{$sender_host_address}{net24-dbm;/some/file}...
10438
10439 However, unless you are combining a match_ip condition with others, it
10440 is just as easy to use the fact that a lookup is itself a condition,
10441 and write:
10442
10443 ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}...
10444
10445 Note that <string2> is not itself subject to string expansion, unless Exim
10446 was built with the EXPAND_LISTMATCH_RHS option.
10447
10448 Consult section 10.11 for further details of these patterns.
10449
10450 match_local_part {<string1>}{<string2>}
10451
10452 This condition, together with match_address and match_domain, make it
10453 possible to test domain, address, and local part lists within expansions.
10454 Each condition requires two arguments: an item and a list to match. A
10455 trivial example is:
10456
10457 ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
10458
10459 In each case, the second argument may contain any of the allowable items
10460 for a list of the appropriate type. Also, because the second argument is a
10461 standard form of list, it is possible to refer to a named list. Thus, you
10462 can use conditions like this:
10463
10464 ${if match_domain{$domain}{+local_domains}{...
10465
10466 For address lists, the matching starts off caselessly, but the "+caseful"
10467 item can be used, as in all address lists, to cause subsequent items to
10468 have their local parts matched casefully. Domains are always matched
10469 caselessly.
10470
10471 Note that <string2> is not itself subject to string expansion, unless Exim
10472 was built with the EXPAND_LISTMATCH_RHS option.
10473
10474 Note: Host lists are not supported in this way. This is because hosts have
10475 two identities: a name and an IP address, and it is not clear how to
10476 specify cleanly how such a test would work. However, IP addresses can be
10477 matched using match_ip.
10478
10479 pam {<string1>:<string2>:...}
10480
10481 Pluggable Authentication Modules (https://mirrors.edge.kernel.org/pub/linux
10482 /libs/pam/) are a facility that is available in the latest releases of
10483 Solaris and in some GNU/Linux distributions. The Exim support, which is
10484 intended for use in conjunction with the SMTP AUTH command, is available
10485 only if Exim is compiled with
10486
10487 SUPPORT_PAM=yes
10488
10489 in Local/Makefile. You probably need to add -lpam to EXTRALIBS, and in some
10490 releases of GNU/Linux -ldl is also needed.
10491
10492 The argument string is first expanded, and the result must be a
10493 colon-separated list of strings. Leading and trailing white space is
10494 ignored. The PAM module is initialized with the service name "exim" and the
10495 user name taken from the first item in the colon-separated data string (<
10496 string1>). The remaining items in the data string are passed over in
10497 response to requests from the authentication function. In the simple case
10498 there will only be one request, for a password, so the data consists of
10499 just two strings.
10500
10501 There can be problems if any of the strings are permitted to contain colon
10502 characters. In the usual way, these have to be doubled to avoid being taken
10503 as separators. If the data is being inserted from a variable, the sg
10504 expansion item can be used to double any existing colons. For example, the
10505 configuration of a LOGIN authenticator might contain this setting:
10506
10507 server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}}
10508
10509 For a PLAIN authenticator you could use:
10510
10511 server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}}
10512
10513 In some operating systems, PAM authentication can be done only from a
10514 process running as root. Since Exim is running as the Exim user when
10515 receiving messages, this means that PAM cannot be used directly in those
10516 systems.
10517
10518 pwcheck {<string1>:<string2>}
10519
10520 This condition supports user authentication using the Cyrus pwcheck daemon.
10521 This is one way of making it possible for passwords to be checked by a
10522 process that is not running as root. Note: The use of pwcheck is now
10523 deprecated. Its replacement is saslauthd (see below).
10524
10525 The pwcheck support is not included in Exim by default. You need to specify
10526 the location of the pwcheck daemon's socket in Local/Makefile before
10527 building Exim. For example:
10528
10529 CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck
10530
10531 You do not need to install the full Cyrus software suite in order to use
10532 the pwcheck daemon. You can compile and install just the daemon alone from
10533 the Cyrus SASL library. Ensure that exim is the only user that has access
10534 to the /var/pwcheck directory.
10535
10536 The pwcheck condition takes one argument, which must be the user name and
10537 password, separated by a colon. For example, in a LOGIN authenticator
10538 configuration, you might have this:
10539
10540 server_condition = ${if pwcheck{$auth1:$auth2}}
10541
10542 Again, for a PLAIN authenticator configuration, this would be:
10543
10544 server_condition = ${if pwcheck{$auth2:$auth3}}
10545
10546 queue_running
10547
10548 This condition, which has no data, is true during delivery attempts that
10549 are initiated by queue runner processes, and false otherwise.
10550
10551 radius {<authentication string>}
10552
10553 Radius authentication (RFC 2865) is supported in a similar way to PAM. You
10554 must set RADIUS_CONFIG_FILE in Local/Makefile to specify the location of
10555 the Radius client configuration file in order to build Exim with Radius
10556 support.
10557
10558 With just that one setting, Exim expects to be linked with the radiusclient
10559 library, using the original API. If you are using release 0.4.0 or later of
10560 this library, you need to set
10561
10562 RADIUS_LIB_TYPE=RADIUSCLIENTNEW
10563
10564 in Local/Makefile when building Exim. You can also link Exim with the
10565 libradius library that comes with FreeBSD. To do this, set
10566
10567 RADIUS_LIB_TYPE=RADLIB
10568
10569 in Local/Makefile, in addition to setting RADIUS_CONFIGURE_FILE. You may
10570 also have to supply a suitable setting in EXTRALIBS so that the Radius
10571 library can be found when Exim is linked.
10572
10573 The string specified by RADIUS_CONFIG_FILE is expanded and passed to the
10574 Radius client library, which calls the Radius server. The condition is true
10575 if the authentication is successful. For example:
10576
10577 server_condition = ${if radius{<arguments>}}
10578
10579 saslauthd {{<user>}{<password>}{<service>}{<realm>}}
10580
10581 This condition supports user authentication using the Cyrus saslauthd
10582 daemon. This replaces the older pwcheck daemon, which is now deprecated.
10583 Using this daemon is one way of making it possible for passwords to be
10584 checked by a process that is not running as root.
10585
10586 The saslauthd support is not included in Exim by default. You need to
10587 specify the location of the saslauthd daemon's socket in Local/Makefile
10588 before building Exim. For example:
10589
10590 CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux
10591
10592 You do not need to install the full Cyrus software suite in order to use
10593 the saslauthd daemon. You can compile and install just the daemon alone
10594 from the Cyrus SASL library.
10595
10596 Up to four arguments can be supplied to the saslauthd condition, but only
10597 two are mandatory. For example:
10598
10599 server_condition = ${if saslauthd{{$auth1}{$auth2}}}
10600
10601 The service and the realm are optional (which is why the arguments are
10602 enclosed in their own set of braces). For details of the meaning of the
10603 service and realm, and how to run the daemon, consult the Cyrus
10604 documentation.
10605
10606
10607 11.8 Combining expansion conditions
10608 -----------------------------------
10609
10610 Several conditions can be tested at once by combining them using the and and or
10611 combination conditions. Note that and and or are complete conditions on their
10612 own, and precede their lists of sub-conditions. Each sub-condition must be
10613 enclosed in braces within the overall braces that contain the list. No
10614 repetition of if is used.
10615
10616 or {{<cond1>}{<cond2>}...}
10617
10618 The sub-conditions are evaluated from left to right. The condition is true
10619 if any one of the sub-conditions is true. For example,
10620
10621 ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...
10622
10623 When a true sub-condition is found, the following ones are parsed but not
10624 evaluated. If there are several "match" sub-conditions the values of the
10625 numeric variables afterwards are taken from the first one that succeeds.
10626
10627 and {{<cond1>}{<cond2>}...}
10628
10629 The sub-conditions are evaluated from left to right. The condition is true
10630 if all of the sub-conditions are true. If there are several "match"
10631 sub-conditions, the values of the numeric variables afterwards are taken
10632 from the last one. When a false sub-condition is found, the following ones
10633 are parsed but not evaluated.
10634
10635
10636 11.9 Expansion variables
10637 ------------------------
10638
10639 This section contains an alphabetical list of all the expansion variables. Some
10640 of them are available only when Exim is compiled with specific options such as
10641 support for TLS or the content scanning extension.
10642
10643 $0, $1, etc
10644
10645 When a match expansion condition succeeds, these variables contain the
10646 captured substrings identified by the regular expression during subsequent
10647 processing of the success string of the containing if expansion item. In
10648 the expansion condition case they do not retain their values afterwards; in
10649 fact, their previous values are restored at the end of processing an if
10650 item. The numerical variables may also be set externally by some other
10651 matching process which precedes the expansion of the string. For example,
10652 the commands available in Exim filter files include an if command with its
10653 own regular expression matching condition.
10654
10655 $acl_arg1, $acl_arg2, etc
10656
10657 Within an acl condition, expansion condition or expansion item any
10658 arguments are copied to these variables, any unused variables being made
10659 empty.
10660
10661 $acl_c...
10662
10663 Values can be placed in these variables by the set modifier in an ACL. They
10664 can be given any name that starts with $acl_c and is at least six
10665 characters long, but the sixth character must be either a digit or an
10666 underscore. For example: $acl_c5, $acl_c_mycount. The values of the
10667 $acl_c... variables persist throughout the lifetime of an SMTP connection.
10668 They can be used to pass information between ACLs and between different
10669 invocations of the same ACL. When a message is received, the values of
10670 these variables are saved with the message, and can be accessed by filters,
10671 routers, and transports during subsequent delivery.
10672
10673 $acl_m...
10674
10675 These variables are like the $acl_c... variables, except that their values
10676 are reset after a message has been received. Thus, if several messages are
10677 received in one SMTP connection, $acl_m... values are not passed on from
10678 one message to the next, as $acl_c... values are. The $acl_m... variables
10679 are also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session.
10680 When a message is received, the values of these variables are saved with
10681 the message, and can be accessed by filters, routers, and transports during
10682 subsequent delivery.
10683
10684 $acl_narg
10685
10686 Within an acl condition, expansion condition or expansion item this
10687 variable has the number of arguments.
10688
10689 $acl_verify_message
10690
10691 After an address verification has failed, this variable contains the
10692 failure message. It retains its value for use in subsequent modifiers. The
10693 message can be preserved by coding like this:
10694
10695 warn !verify = sender
10696 set acl_m0 = $acl_verify_message
10697
10698 You can use $acl_verify_message during the expansion of the message or
10699 log_message modifiers, to include information about the verification
10700 failure.
10701
10702 $address_data
10703
10704 This variable is set by means of the address_data option in routers. The
10705 value then remains with the address while it is processed by subsequent
10706 routers and eventually a transport. If the transport is handling multiple
10707 addresses, the value from the first address is used. See chapter 15 for
10708 more details. Note: The contents of $address_data are visible in user
10709 filter files.
10710
10711 If $address_data is set when the routers are called from an ACL to verify a
10712 recipient address, the final value is still in the variable for subsequent
10713 conditions and modifiers of the ACL statement. If routing the address
10714 caused it to be redirected to just one address, the child address is also
10715 routed as part of the verification, and in this case the final value of
10716 $address_data is from the child's routing.
10717
10718 If $address_data is set when the routers are called from an ACL to verify a
10719 sender address, the final value is also preserved, but this time in
10720 $sender_address_data, to distinguish it from data from a recipient address.
10721
10722 In both cases (recipient and sender verification), the value does not
10723 persist after the end of the current ACL statement. If you want to preserve
10724 these values for longer, you can save them in ACL variables.
10725
10726 $address_file
10727
10728 When, as a result of aliasing, forwarding, or filtering, a message is
10729 directed to a specific file, this variable holds the name of the file when
10730 the transport is running. At other times, the variable is empty. For
10731 example, using the default configuration, if user r2d2 has a .forward file
10732 containing
10733
10734 /home/r2d2/savemail
10735
10736 then when the address_file transport is running, $address_file contains the
10737 text string "/home/r2d2/savemail". For Sieve filters, the value may be
10738 "inbox" or a relative folder name. It is then up to the transport
10739 configuration to generate an appropriate absolute path to the relevant
10740 file.
10741
10742 $address_pipe
10743
10744 When, as a result of aliasing or forwarding, a message is directed to a
10745 pipe, this variable holds the pipe command when the transport is running.
10746
10747 $auth1 - $auth3
10748
10749 These variables are used in SMTP authenticators (see chapters 34-41).
10750 Elsewhere, they are empty.
10751
10752 $authenticated_id
10753
10754 When a server successfully authenticates a client it may be configured to
10755 preserve some of the authentication information in the variable
10756 $authenticated_id (see chapter 33). For example, a user/password
10757 authenticator configuration might preserve the user name for use in the
10758 routers. Note that this is not the same information that is saved in
10759 $sender_host_authenticated.
10760
10761 When a message is submitted locally (that is, not over a TCP connection)
10762 the value of $authenticated_id is normally the login name of the calling
10763 process. However, a trusted user can override this by means of the -oMai
10764 command line option. This second case also sets up information used by the
10765 $authresults expansion item.
10766
10767 $authenticated_fail_id
10768
10769 When an authentication attempt fails, the variable $authenticated_fail_id
10770 will contain the failed authentication id. If more than one authentication
10771 id is attempted, it will contain only the last one. The variable is
10772 available for processing in the ACL's, generally the quit or notquit ACL. A
10773 message to a local recipient could still be accepted without requiring
10774 authentication, which means this variable could also be visible in all of
10775 the ACL's as well.
10776
10777 $authenticated_sender
10778
10779 When acting as a server, Exim takes note of the AUTH= parameter on an
10780 incoming SMTP MAIL command if it believes the sender is sufficiently
10781 trusted, as described in section 33.2. Unless the data is the string "<>",
10782 it is set as the authenticated sender of the message, and the value is
10783 available during delivery in the $authenticated_sender variable. If the
10784 sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the
10785 data.
10786
10787 When a message is submitted locally (that is, not over a TCP connection),
10788 the value of $authenticated_sender is an address constructed from the login
10789 name of the calling process and $qualify_domain, except that a trusted user
10790 can override this by means of the -oMas command line option.
10791
10792 $authentication_failed
10793
10794 This variable is set to "1" in an Exim server if a client issues an AUTH
10795 command that does not succeed. Otherwise it is set to "0". This makes it
10796 possible to distinguish between "did not try to authenticate" (
10797 $sender_host_authenticated is empty and $authentication_failed is set to
10798 "0") and "tried to authenticate but failed" ($sender_host_authenticated is
10799 empty and $authentication_failed is set to "1"). Failure includes any
10800 negative response to an AUTH command, including (for example) an attempt to
10801 use an undefined mechanism.
10802
10803 $av_failed
10804
10805 This variable is available when Exim is compiled with the content-scanning
10806 extension. It is set to "0" by default, but will be set to "1" if any
10807 problem occurs with the virus scanner (specified by av_scanner) during the
10808 ACL malware condition.
10809
10810 $body_linecount
10811
10812 When a message is being received or delivered, this variable contains the
10813 number of lines in the message's body. See also $message_linecount.
10814
10815 $body_zerocount
10816
10817 When a message is being received or delivered, this variable contains the
10818 number of binary zero bytes (ASCII NULs) in the message's body.
10819
10820 $bounce_recipient
10821
10822 This is set to the recipient address of a bounce message while Exim is
10823 creating it. It is useful if a customized bounce message text file is in
10824 use (see chapter 49).
10825
10826 $bounce_return_size_limit
10827
10828 This contains the value set in the bounce_return_size_limit option, rounded
10829 up to a multiple of 1000. It is useful when a customized error message text
10830 file is in use (see chapter 49).
10831
10832 $caller_gid
10833
10834 The real group id under which the process that called Exim was running.
10835 This is not the same as the group id of the originator of a message (see
10836 $originator_gid). If Exim re-execs itself, this variable in the new
10837 incarnation normally contains the Exim gid.
10838
10839 $caller_uid
10840
10841 The real user id under which the process that called Exim was running. This
10842 is not the same as the user id of the originator of a message (see
10843 $originator_uid). If Exim re-execs itself, this variable in the new
10844 incarnation normally contains the Exim uid.
10845
10846 $callout_address
10847
10848 After a callout for verification, spamd or malware daemon service, the
10849 address that was connected to.
10850
10851 $compile_number
10852
10853 The building process for Exim keeps a count of the number of times it has
10854 been compiled. This serves to distinguish different compilations of the
10855 same version of Exim.
10856
10857 $config_dir
10858
10859 The directory name of the main configuration file. That is, the content of
10860 $config_file with the last component stripped. The value does not contain
10861 the trailing slash. If $config_file does not contain a slash, $config_dir
10862 is ".".
10863
10864 $config_file
10865
10866 The name of the main configuration file Exim is using.
10867
10868 $dkim_verify_status
10869
10870 Results of DKIM verification. For details see section 57.3.
10871
10872 $dkim_cur_signer, $dkim_verify_reason, $dkim_domain, $dkim_identity,
10873 $dkim_selector, $dkim_algo, $dkim_canon_body, $dkim_canon_headers,
10874 $dkim_copiedheaders, $dkim_bodylength, $dkim_created, $dkim_expires,
10875 $dkim_headernames, $dkim_key_testing, $dkim_key_nosubdomains,
10876 $dkim_key_srvtype, $dkim_key_granularity, $dkim_key_notes, $dkim_key_length
10877
10878 These variables are only available within the DKIM ACL. For details see
10879 section 57.3.
10880
10881 $dkim_signers
10882
10883 When a message has been received this variable contains a colon-separated
10884 list of signer domains and identities for the message. For details see
10885 section 57.3.
10886
10887 $dnslist_domain, $dnslist_matched, $dnslist_text, $dnslist_value
10888
10889 When a DNS (black) list lookup succeeds, these variables are set to contain
10890 the following data from the lookup: the list's domain name, the key that
10891 was looked up, the contents of any associated TXT record, and the value
10892 from the main A record. See section 43.32 for more details.
10893
10894 $domain
10895
10896 When an address is being routed, or delivered on its own, this variable
10897 contains the domain. Uppercase letters in the domain are converted into
10898 lower case for $domain.
10899
10900 Global address rewriting happens when a message is received, so the value
10901 of $domain during routing and delivery is the value after rewriting.
10902 $domain is set during user filtering, but not during system filtering,
10903 because a message may have many recipients and the system filter is called
10904 just once.
10905
10906 When more than one address is being delivered at once (for example, several
10907 RCPT commands in one SMTP delivery), $domain is set only if they all have
10908 the same domain. Transports can be restricted to handling only one domain
10909 at a time if the value of $domain is required at transport time - this is
10910 the default for local transports. For further details of the environment in
10911 which local transports are run, see chapter 23.
10912
10913 At the end of a delivery, if all deferred addresses have the same domain,
10914 it is set in $domain during the expansion of delay_warning_condition.
10915
10916 The $domain variable is also used in some other circumstances:
10917
10918 + When an ACL is running for a RCPT command, $domain contains the domain
10919 of the recipient address. The domain of the sender address is in
10920 $sender_address_domain at both MAIL time and at RCPT time. $domain is
10921 not normally set during the running of the MAIL ACL. However, if the
10922 sender address is verified with a callout during the MAIL ACL, the
10923 sender domain is placed in $domain during the expansions of hosts,
10924 interface, and port in the smtp transport.
10925
10926 + When a rewrite item is being processed (see chapter 31), $domain
10927 contains the domain portion of the address that is being rewritten; it
10928 can be used in the expansion of the replacement address, for example,
10929 to rewrite domains by file lookup.
10930
10931 + With one important exception, whenever a domain list is being scanned,
10932 $domain contains the subject domain. Exception: When a domain list in a
10933 sender_domains condition in an ACL is being processed, the subject
10934 domain is in $sender_address_domain and not in $domain. It works this
10935 way so that, in a RCPT ACL, the sender domain list can be dependent on
10936 the recipient domain (which is what is in $domain at this time).
10937
10938 + When the smtp_etrn_command option is being expanded, $domain contains
10939 the complete argument of the ETRN command (see section 48.8).
10940
10941 $domain_data
10942
10943 When the domains option on a router matches a domain by means of a lookup,
10944 the data read by the lookup is available during the running of the router
10945 as $domain_data. In addition, if the driver routes the address to a
10946 transport, the value is available in that transport. If the transport is
10947 handling multiple addresses, the value from the first address is used.
10948
10949 $domain_data is also set when the domains condition in an ACL matches a
10950 domain by means of a lookup. The data read by the lookup is available
10951 during the rest of the ACL statement. In all other situations, this
10952 variable expands to nothing.
10953
10954 $exim_gid
10955
10956 This variable contains the numerical value of the Exim group id.
10957
10958 $exim_path
10959
10960 This variable contains the path to the Exim binary.
10961
10962 $exim_uid
10963
10964 This variable contains the numerical value of the Exim user id.
10965
10966 $exim_version
10967
10968 This variable contains the version string of the Exim build. The first
10969 character is a major version number, currently 4. Then after a dot, the
10970 next group of digits is a minor version number. There may be other
10971 characters following the minor version.
10972
10973 $header_<name>
10974
10975 This is not strictly an expansion variable. It is expansion syntax for
10976 inserting the message header line with the given name. Note that the name
10977 must be terminated by colon or white space, because it may contain a wide
10978 variety of characters. Note also that braces must not be used. See the full
10979 description in section 11.5 above.
10980
10981 $headers_added
10982
10983 Within an ACL this variable contains the headers added so far by the ACL
10984 modifier add_header (section 43.24). The headers are a newline-separated
10985 list.
10986
10987 $home
10988
10989 When the check_local_user option is set for a router, the user's home
10990 directory is placed in $home when the check succeeds. In particular, this
10991 means it is set during the running of users' filter files. A router may
10992 also explicitly set a home directory for use by a transport; this can be
10993 overridden by a setting on the transport itself.
10994
10995 When running a filter test via the -bf option, $home is set to the value of
10996 the environment variable HOME, which is subject to the keep_environment and
10997 add_environment main config options.
10998
10999 $host
11000
11001 If a router assigns an address to a transport (any transport), and passes a
11002 list of hosts with the address, the value of $host when the transport
11003 starts to run is the name of the first host on the list. Note that this
11004 applies both to local and remote transports.
11005
11006 For the smtp transport, if there is more than one host, the value of $host
11007 changes as the transport works its way through the list. In particular,
11008 when the smtp transport is expanding its options for encryption using TLS,
11009 or for specifying a transport filter (see chapter 24), $host contains the
11010 name of the host to which it is connected.
11011
11012 When used in the client part of an authenticator configuration (see chapter
11013 33), $host contains the name of the server to which the client is
11014 connected.
11015
11016 $host_address
11017
11018 This variable is set to the remote host's IP address whenever $host is set
11019 for a remote connection. It is also set to the IP address that is being
11020 checked when the ignore_target_hosts option is being processed.
11021
11022 $host_data
11023
11024 If a hosts condition in an ACL is satisfied by means of a lookup, the
11025 result of the lookup is made available in the $host_data variable. This
11026 allows you, for example, to do things like this:
11027
11028 deny hosts = net-lsearch;/some/file
11029 message = $host_data
11030
11031 $host_lookup_deferred
11032
11033 This variable normally contains "0", as does $host_lookup_failed. When a
11034 message comes from a remote host and there is an attempt to look up the
11035 host's name from its IP address, and the attempt is not successful, one of
11036 these variables is set to "1".
11037
11038 + If the lookup receives a definite negative response (for example, a DNS
11039 lookup succeeded, but no records were found), $host_lookup_failed is
11040 set to "1".
11041
11042 + If there is any kind of problem during the lookup, such that Exim
11043 cannot tell whether or not the host name is defined (for example, a
11044 timeout for a DNS lookup), $host_lookup_deferred is set to "1".
11045
11046 Looking up a host's name from its IP address consists of more than just a
11047 single reverse lookup. Exim checks that a forward lookup of at least one of
11048 the names it receives from a reverse lookup yields the original IP address.
11049 If this is not the case, Exim does not accept the looked up name(s), and
11050 $host_lookup_failed is set to "1". Thus, being able to find a name from an
11051 IP address (for example, the existence of a PTR record in the DNS) is not
11052 sufficient on its own for the success of a host name lookup. If the reverse
11053 lookup succeeds, but there is a lookup problem such as a timeout when
11054 checking the result, the name is not accepted, and $host_lookup_deferred is
11055 set to "1". See also $sender_host_name.
11056
11057 Performing these checks sets up information used by the $authresults
11058 expansion item.
11059
11060 $host_lookup_failed
11061
11062 See $host_lookup_deferred.
11063
11064 $host_port
11065
11066 This variable is set to the remote host's TCP port whenever $host is set
11067 for an outbound connection.
11068
11069 $initial_cwd
11070
11071 This variable contains the full path name of the initial working directory
11072 of the current Exim process. This may differ from the current working
11073 directory, as Exim changes this to "/" during early startup, and to
11074 $spool_directory later.
11075
11076 $inode
11077
11078 The only time this variable is set is while expanding the directory_file
11079 option in the appendfile transport. The variable contains the inode number
11080 of the temporary file which is about to be renamed. It can be used to
11081 construct a unique name for the file.
11082
11083 $interface_address
11084
11085 This is an obsolete name for $received_ip_address.
11086
11087 $interface_port
11088
11089 This is an obsolete name for $received_port.
11090
11091 $item
11092
11093 This variable is used during the expansion of forall and forany conditions
11094 (see section 11.7), and filter, map, and reduce items (see section 11.7).
11095 In other circumstances, it is empty.
11096
11097 $ldap_dn
11098
11099 This variable, which is available only when Exim is compiled with LDAP
11100 support, contains the DN from the last entry in the most recently
11101 successful LDAP lookup.
11102
11103 $load_average
11104
11105 This variable contains the system load average, multiplied by 1000 so that
11106 it is an integer. For example, if the load average is 0.21, the value of
11107 the variable is 210. The value is recomputed every time the variable is
11108 referenced.
11109
11110 $local_part
11111
11112 When an address is being routed, or delivered on its own, this variable
11113 contains the local part. When a number of addresses are being delivered
11114 together (for example, multiple RCPT commands in an SMTP session),
11115 $local_part is not set.
11116
11117 Global address rewriting happens when a message is received, so the value
11118 of $local_part during routing and delivery is the value after rewriting.
11119 $local_part is set during user filtering, but not during system filtering,
11120 because a message may have many recipients and the system filter is called
11121 just once.
11122
11123 If a local part prefix or suffix has been recognized, it is not included in
11124 the value of $local_part during routing and subsequent delivery. The values
11125 of any prefix or suffix are in $local_part_prefix and $local_part_suffix,
11126 respectively.
11127
11128 When a message is being delivered to a file, pipe, or autoreply transport
11129 as a result of aliasing or forwarding, $local_part is set to the local part
11130 of the parent address, not to the filename or command (see $address_file
11131 and $address_pipe).
11132
11133 When an ACL is running for a RCPT command, $local_part contains the local
11134 part of the recipient address.
11135
11136 When a rewrite item is being processed (see chapter 31), $local_part
11137 contains the local part of the address that is being rewritten; it can be
11138 used in the expansion of the replacement address, for example.
11139
11140 In all cases, all quoting is removed from the local part. For example, for
11141 both the addresses
11142
11143 "abc:xyz"@test.example
11144 abc\:xyz@test.example
11145
11146 the value of $local_part is
11147
11148 abc:xyz
11149
11150 If you use $local_part to create another address, you should always wrap it
11151 inside a quoting operator. For example, in a redirect router you could
11152 have:
11153
11154 data = ${quote_local_part:$local_part}@new.domain.example
11155
11156 Note: The value of $local_part is normally lower cased. If you want to
11157 process local parts in a case-dependent manner in a router, you can set the
11158 caseful_local_part option (see chapter 15).
11159
11160 $local_part_data
11161
11162 When the local_parts option on a router matches a local part by means of a
11163 lookup, the data read by the lookup is available during the running of the
11164 router as $local_part_data. In addition, if the driver routes the address
11165 to a transport, the value is available in that transport. If the transport
11166 is handling multiple addresses, the value from the first address is used.
11167
11168 $local_part_data is also set when the local_parts condition in an ACL
11169 matches a local part by means of a lookup. The data read by the lookup is
11170 available during the rest of the ACL statement. In all other situations,
11171 this variable expands to nothing.
11172
11173 $local_part_prefix
11174
11175 When an address is being routed or delivered, and a specific prefix for the
11176 local part was recognized, it is available in this variable, having been
11177 removed from $local_part.
11178
11179 $local_part_suffix
11180
11181 When an address is being routed or delivered, and a specific suffix for the
11182 local part was recognized, it is available in this variable, having been
11183 removed from $local_part.
11184
11185 $local_scan_data
11186
11187 This variable contains the text returned by the local_scan() function when
11188 a message is received. See chapter 45 for more details.
11189
11190 $local_user_gid
11191
11192 See $local_user_uid.
11193
11194 $local_user_uid
11195
11196 This variable and $local_user_gid are set to the uid and gid after the
11197 check_local_user router precondition succeeds. This means that their values
11198 are available for the remaining preconditions (senders, require_files, and
11199 condition), for the address_data expansion, and for any router-specific
11200 expansions. At all other times, the values in these variables are "(uid_t)
11201 (-1)" and "(gid_t)(-1)", respectively.
11202
11203 $localhost_number
11204
11205 This contains the expanded value of the localhost_number option. The
11206 expansion happens after the main options have been read.
11207
11208 $log_inodes
11209
11210 The number of free inodes in the disk partition where Exim's log files are
11211 being written. The value is recalculated whenever the variable is
11212 referenced. If the relevant file system does not have the concept of
11213 inodes, the value of is -1. See also the check_log_inodes option.
11214
11215 $log_space
11216
11217 The amount of free space (as a number of kilobytes) in the disk partition
11218 where Exim's log files are being written. The value is recalculated
11219 whenever the variable is referenced. If the operating system does not have
11220 the ability to find the amount of free space (only true for experimental
11221 systems), the space value is -1. See also the check_log_space option.
11222
11223 $lookup_dnssec_authenticated
11224
11225 This variable is set after a DNS lookup done by a dnsdb lookup expansion,
11226 dnslookup router or smtp transport. It will be empty if DNSSEC was not
11227 requested, "no" if the result was not labelled as authenticated data and
11228 "yes" if it was. Results that are labelled as authoritative answer that
11229 match the dns_trust_aa configuration variable count also as authenticated
11230 data.
11231
11232 $mailstore_basename
11233
11234 This variable is set only when doing deliveries in "mailstore" format in
11235 the appendfile transport. During the expansion of the mailstore_prefix,
11236 mailstore_suffix, message_prefix, and message_suffix options, it contains
11237 the basename of the files that are being written, that is, the name without
11238 the ".tmp", ".env", or ".msg" suffix. At all other times, this variable is
11239 empty.
11240
11241 $malware_name
11242
11243 This variable is available when Exim is compiled with the content-scanning
11244 extension. It is set to the name of the virus that was found when the ACL
11245 malware condition is true (see section 44.1).
11246
11247 $max_received_linelength
11248
11249 This variable contains the number of bytes in the longest line that was
11250 received as part of the message, not counting the line termination
11251 character(s). It is not valid if the spool_files_wireformat option is used.
11252
11253 $message_age
11254
11255 This variable is set at the start of a delivery attempt to contain the
11256 number of seconds since the message was received. It does not change during
11257 a single delivery attempt.
11258
11259 $message_body
11260
11261 This variable contains the initial portion of a message's body while it is
11262 being delivered, and is intended mainly for use in filter files. The
11263 maximum number of characters of the body that are put into the variable is
11264 set by the message_body_visible configuration option; the default is 500.
11265
11266 By default, newlines are converted into spaces in $message_body, to make it
11267 easier to search for phrases that might be split over a line break.
11268 However, this can be disabled by setting message_body_newlines to be true.
11269 Binary zeros are always converted into spaces.
11270
11271 $message_body_end
11272
11273 This variable contains the final portion of a message's body while it is
11274 being delivered. The format and maximum size are as for $message_body.
11275
11276 $message_body_size
11277
11278 When a message is being delivered, this variable contains the size of the
11279 body in bytes. The count starts from the character after the blank line
11280 that separates the body from the header. Newlines are included in the
11281 count. See also $message_size, $body_linecount, and $body_zerocount.
11282
11283 If the spool file is wireformat (see the spool_files_wireformat main
11284 option) the CRLF line-terminators are included in the count.
11285
11286 $message_exim_id
11287
11288 When a message is being received or delivered, this variable contains the
11289 unique message id that is generated and used by Exim to identify the
11290 message. An id is not created for a message until after its header has been
11291 successfully received. Note: This is not the contents of the Message-ID:
11292 header line; it is the local id that Exim assigns to the message, for
11293 example: "1BXTIK-0001yO-VA".
11294
11295 $message_headers
11296
11297 This variable contains a concatenation of all the header lines when a
11298 message is being processed, except for lines added by routers or
11299 transports. The header lines are separated by newline characters. Their
11300 contents are decoded in the same way as a header line that is inserted by
11301 bheader.
11302
11303 $message_headers_raw
11304
11305 This variable is like $message_headers except that no processing of the
11306 contents of header lines is done.
11307
11308 $message_id
11309
11310 This is an old name for $message_exim_id. It is now deprecated.
11311
11312 $message_linecount
11313
11314 This variable contains the total number of lines in the header and body of
11315 the message. Compare $body_linecount, which is the count for the body only.
11316 During the DATA and content-scanning ACLs, $message_linecount contains the
11317 number of lines received. Before delivery happens (that is, before filters,
11318 routers, and transports run) the count is increased to include the
11319 Received: header line that Exim standardly adds, and also any other header
11320 lines that are added by ACLs. The blank line that separates the message
11321 header from the body is not counted.
11322
11323 As with the special case of $message_size, during the expansion of the
11324 appendfile transport's maildir_tag option in maildir format, the value of
11325 $message_linecount is the precise size of the number of newlines in the
11326 file that has been written (minus one for the blank line between the header
11327 and the body).
11328
11329 Here is an example of the use of this variable in a DATA ACL:
11330
11331 deny message = Too many lines in message header
11332 condition = \
11333 ${if <{250}{${eval:$message_linecount - $body_linecount}}}
11334
11335 In the MAIL and RCPT ACLs, the value is zero because at that stage the
11336 message has not yet been received.
11337
11338 This variable is not valid if the spool_files_wireformat option is used.
11339
11340 $message_size
11341
11342 When a message is being processed, this variable contains its size in
11343 bytes. In most cases, the size includes those headers that were received
11344 with the message, but not those (such as Envelope-to:) that are added to
11345 individual deliveries as they are written. However, there is one special
11346 case: during the expansion of the maildir_tag option in the appendfile
11347 transport while doing a delivery in maildir format, the value of
11348 $message_size is the precise size of the file that has been written. See
11349 also $message_body_size, $body_linecount, and $body_zerocount.
11350
11351 While running a per message ACL (mail/rcpt/predata), $message_size contains
11352 the size supplied on the MAIL command, or -1 if no size was given. The
11353 value may not, of course, be truthful.
11354
11355 $mime_xxx
11356
11357 A number of variables whose names start with $mime are available when Exim
11358 is compiled with the content-scanning extension. For details, see section
11359 44.4.
11360
11361 $n0 - $n9
11362
11363 These variables are counters that can be incremented by means of the add
11364 command in filter files.
11365
11366 $original_domain
11367
11368 When a top-level address is being processed for delivery, this contains the
11369 same value as $domain. However, if a "child" address (for example,
11370 generated by an alias, forward, or filter file) is being processed, this
11371 variable contains the domain of the original address (lower cased). This
11372 differs from $parent_domain only when there is more than one level of
11373 aliasing or forwarding. When more than one address is being delivered in a
11374 single transport run, $original_domain is not set.
11375
11376 If a new address is created by means of a deliver command in a system
11377 filter, it is set up with an artificial "parent" address. This has the
11378 local part system-filter and the default qualify domain.
11379
11380 $original_local_part
11381
11382 When a top-level address is being processed for delivery, this contains the
11383 same value as $local_part, unless a prefix or suffix was removed from the
11384 local part, because $original_local_part always contains the full local
11385 part. When a "child" address (for example, generated by an alias, forward,
11386 or filter file) is being processed, this variable contains the full local
11387 part of the original address.
11388
11389 If the router that did the redirection processed the local part
11390 case-insensitively, the value in $original_local_part is in lower case.
11391 This variable differs from $parent_local_part only when there is more than
11392 one level of aliasing or forwarding. When more than one address is being
11393 delivered in a single transport run, $original_local_part is not set.
11394
11395 If a new address is created by means of a deliver command in a system
11396 filter, it is set up with an artificial "parent" address. This has the
11397 local part system-filter and the default qualify domain.
11398
11399 $originator_gid
11400
11401 This variable contains the value of $caller_gid that was set when the
11402 message was received. For messages received via the command line, this is
11403 the gid of the sending user. For messages received by SMTP over TCP/IP,
11404 this is normally the gid of the Exim user.
11405
11406 $originator_uid
11407
11408 The value of $caller_uid that was set when the message was received. For
11409 messages received via the command line, this is the uid of the sending
11410 user. For messages received by SMTP over TCP/IP, this is normally the uid
11411 of the Exim user.
11412
11413 $parent_domain
11414
11415 This variable is similar to $original_domain (see above), except that it
11416 refers to the immediately preceding parent address.
11417
11418 $parent_local_part
11419
11420 This variable is similar to $original_local_part (see above), except that
11421 it refers to the immediately preceding parent address.
11422
11423 $pid
11424
11425 This variable contains the current process id.
11426
11427 $pipe_addresses
11428
11429 This is not an expansion variable, but is mentioned here because the string
11430 "$pipe_addresses" is handled specially in the command specification for the
11431 pipe transport (chapter 29) and in transport filters (described under
11432 transport_filter in chapter 24). It cannot be used in general expansion
11433 strings, and provokes an "unknown variable" error if encountered.
11434
11435 $primary_hostname
11436
11437 This variable contains the value set by primary_hostname in the
11438 configuration file, or read by the uname() function. If uname() returns a
11439 single-component name, Exim calls gethostbyname() (or getipnodebyname()
11440 where available) in an attempt to acquire a fully qualified host name. See
11441 also $smtp_active_hostname.
11442
11443 $proxy_external_address, $proxy_external_port, $proxy_local_address,
11444 $proxy_local_port, $proxy_session
11445
11446 These variables are only available when built with Proxy Protocol or SOCKS5
11447 support. For details see chapter 58.1.
11448
11449 $prdr_requested
11450
11451 This variable is set to "yes" if PRDR was requested by the client for the
11452 current message, otherwise "no".
11453
11454 $prvscheck_address
11455
11456 This variable is used in conjunction with the prvscheck expansion item,
11457 which is described in sections 11.5 and 43.51.
11458
11459 $prvscheck_keynum
11460
11461 This variable is used in conjunction with the prvscheck expansion item,
11462 which is described in sections 11.5 and 43.51.
11463
11464 $prvscheck_result
11465
11466 This variable is used in conjunction with the prvscheck expansion item,
11467 which is described in sections 11.5 and 43.51.
11468
11469 $qualify_domain
11470
11471 The value set for the qualify_domain option in the configuration file.
11472
11473 $qualify_recipient
11474
11475 The value set for the qualify_recipient option in the configuration file,
11476 or if not set, the value of $qualify_domain.
11477
11478 $queue_name
11479
11480 The name of the spool queue in use; empty for the default queue.
11481
11482 $rcpt_count
11483
11484 When a message is being received by SMTP, this variable contains the number
11485 of RCPT commands received for the current message. If this variable is used
11486 in a RCPT ACL, its value includes the current command.
11487
11488 $rcpt_defer_count
11489
11490 When a message is being received by SMTP, this variable contains the number
11491 of RCPT commands in the current message that have previously been rejected
11492 with a temporary (4xx) response.
11493
11494 $rcpt_fail_count
11495
11496 When a message is being received by SMTP, this variable contains the number
11497 of RCPT commands in the current message that have previously been rejected
11498 with a permanent (5xx) response.
11499
11500 $received_count
11501
11502 This variable contains the number of Received: header lines in the message,
11503 including the one added by Exim (so its value is always greater than zero).
11504 It is available in the DATA ACL, the non-SMTP ACL, and while routing and
11505 delivering.
11506
11507 $received_for
11508
11509 If there is only a single recipient address in an incoming message, this
11510 variable contains that address when the Received: header line is being
11511 built. The value is copied after recipient rewriting has happened, but
11512 before the local_scan() function is run.
11513
11514 $received_ip_address
11515
11516 As soon as an Exim server starts processing an incoming TCP/IP connection,
11517 this variable is set to the address of the local IP interface, and
11518 $received_port is set to the local port number. (The remote IP address and
11519 port are in $sender_host_address and $sender_host_port.) When testing with
11520 -bh, the port value is -1 unless it has been set using the -oMi command
11521 line option.
11522
11523 As well as being useful in ACLs (including the "connect" ACL), these
11524 variable could be used, for example, to make the filename for a TLS
11525 certificate depend on which interface and/or port is being used for the
11526 incoming connection. The values of $received_ip_address and $received_port
11527 are saved with any messages that are received, thus making these variables
11528 available at delivery time. For outbound connections see
11529 $sending_ip_address.
11530
11531 $received_port
11532
11533 See $received_ip_address.
11534
11535 $received_protocol
11536
11537 When a message is being processed, this variable contains the name of the
11538 protocol by which it was received. Most of the names used by Exim are
11539 defined by RFCs 821, 2821, and 3848. They start with "smtp" (the client
11540 used HELO) or "esmtp" (the client used EHLO). This can be followed by "s"
11541 for secure (encrypted) and/or "a" for authenticated. Thus, for example, if
11542 the protocol is set to "esmtpsa", the message was received over an
11543 encrypted SMTP connection and the client was successfully authenticated.
11544
11545 Exim uses the protocol name "smtps" for the case when encryption is
11546 automatically set up on connection without the use of STARTTLS (see
11547 tls_on_connect_ports), and the client uses HELO to initiate the encrypted
11548 SMTP session. The name "smtps" is also used for the rare situation where
11549 the client initially uses EHLO, sets up an encrypted connection using
11550 STARTTLS, and then uses HELO afterwards.
11551
11552 The -oMr option provides a way of specifying a custom protocol name for
11553 messages that are injected locally by trusted callers. This is commonly
11554 used to identify messages that are being re-injected after some kind of
11555 scanning.
11556
11557 $received_time
11558
11559 This variable contains the date and time when the current message was
11560 received, as a number of seconds since the start of the Unix epoch.
11561
11562 $recipient_data
11563
11564 This variable is set after an indexing lookup success in an ACL recipients
11565 condition. It contains the data from the lookup, and the value remains set
11566 until the next recipients test. Thus, you can do things like this:
11567
11568 require recipients = cdb*@;/some/file
11569 deny some further test involving $recipient_data
11570
11571 Warning: This variable is set only when a lookup is used as an indexing
11572 method in the address list, using the semicolon syntax as in the example
11573 above. The variable is not set for a lookup that is used as part of the
11574 string expansion that all such lists undergo before being interpreted.
11575
11576 $recipient_verify_failure
11577
11578 In an ACL, when a recipient verification fails, this variable contains
11579 information about the failure. It is set to one of the following words:
11580
11581 + "qualify": The address was unqualified (no domain), and the message was
11582 neither local nor came from an exempted host.
11583
11584 + "route": Routing failed.
11585
11586 + "mail": Routing succeeded, and a callout was attempted; rejection
11587 occurred at or before the MAIL command (that is, on initial connection,
11588 HELO, or MAIL).
11589
11590 + "recipient": The RCPT command in a callout was rejected.
11591
11592 + "postmaster": The postmaster check in a callout was rejected.
11593
11594 The main use of this variable is expected to be to distinguish between
11595 rejections of MAIL and rejections of RCPT.
11596
11597 $recipients
11598
11599 This variable contains a list of envelope recipients for a message. A comma
11600 and a space separate the addresses in the replacement text. However, the
11601 variable is not generally available, to prevent exposure of Bcc recipients
11602 in unprivileged users' filter files. You can use $recipients only in these
11603 cases:
11604
11605 1. In a system filter file.
11606
11607 2. In the ACLs associated with the DATA command and with non-SMTP
11608 messages, that is, the ACLs defined by acl_smtp_predata, acl_smtp_data,
11609 acl_smtp_mime, acl_not_smtp_start, acl_not_smtp, and acl_not_smtp_mime.
11610
11611 3. From within a local_scan() function.
11612
11613 $recipients_count
11614
11615 When a message is being processed, this variable contains the number of
11616 envelope recipients that came with the message. Duplicates are not excluded
11617 from the count. While a message is being received over SMTP, the number
11618 increases for each accepted recipient. It can be referenced in an ACL.
11619
11620 $regex_match_string
11621
11622 This variable is set to contain the matching regular expression after a
11623 regex ACL condition has matched (see section 44.5).
11624
11625 $regex1, $regex2, etc
11626
11627 When a regex or mime_regex ACL condition succeeds, these variables contain
11628 the captured substrings identified by the regular expression.
11629
11630 $reply_address
11631
11632 When a message is being processed, this variable contains the contents of
11633 the Reply-To: header line if one exists and it is not empty, or otherwise
11634 the contents of the From: header line. Apart from the removal of leading
11635 white space, the value is not processed in any way. In particular, no RFC
11636 2047 decoding or character code translation takes place.
11637
11638 $return_path
11639
11640 When a message is being delivered, this variable contains the return path -
11641 the sender field that will be sent as part of the envelope. It is not
11642 enclosed in <> characters. At the start of routing an address, $return_path
11643 has the same value as $sender_address, but if, for example, an incoming
11644 message to a mailing list has been expanded by a router which specifies a
11645 different address for bounce messages, $return_path subsequently contains
11646 the new bounce address, whereas $sender_address always contains the
11647 original sender address that was received with the message. In other words,
11648 $sender_address contains the incoming envelope sender, and $return_path
11649 contains the outgoing envelope sender.
11650
11651 $return_size_limit
11652
11653 This is an obsolete name for $bounce_return_size_limit.
11654
11655 $router_name
11656
11657 During the running of a router this variable contains its name.
11658
11659 $runrc
11660
11661 This variable contains the return code from a command that is run by the $
11662 {run...} expansion item. Warning: In a router or transport, you cannot
11663 assume the order in which option values are expanded, except for those
11664 preconditions whose order of testing is documented. Therefore, you cannot
11665 reliably expect to set $runrc by the expansion of one option, and use it in
11666 another.
11667
11668 $self_hostname
11669
11670 When an address is routed to a supposedly remote host that turns out to be
11671 the local host, what happens is controlled by the self generic router
11672 option. One of its values causes the address to be passed to another
11673 router. When this happens, $self_hostname is set to the name of the local
11674 host that the original router encountered. In other circumstances its
11675 contents are null.
11676
11677 $sender_address
11678
11679 When a message is being processed, this variable contains the sender's
11680 address that was received in the message's envelope. The case of letters in
11681 the address is retained, in both the local part and the domain. For bounce
11682 messages, the value of this variable is the empty string. See also
11683 $return_path.
11684
11685 $sender_address_data
11686
11687 If $address_data is set when the routers are called from an ACL to verify a
11688 sender address, the final value is preserved in $sender_address_data, to
11689 distinguish it from data from a recipient address. The value does not
11690 persist after the end of the current ACL statement. If you want to preserve
11691 it for longer, you can save it in an ACL variable.
11692
11693 $sender_address_domain
11694
11695 The domain portion of $sender_address.
11696
11697 $sender_address_local_part
11698
11699 The local part portion of $sender_address.
11700
11701 $sender_data
11702
11703 This variable is set after a lookup success in an ACL senders condition or
11704 in a router senders option. It contains the data from the lookup, and the
11705 value remains set until the next senders test. Thus, you can do things like
11706 this:
11707
11708 require senders = cdb*@;/some/file
11709 deny some further test involving $sender_data
11710
11711 Warning: This variable is set only when a lookup is used as an indexing
11712 method in the address list, using the semicolon syntax as in the example
11713 above. The variable is not set for a lookup that is used as part of the
11714 string expansion that all such lists undergo before being interpreted.
11715
11716 $sender_fullhost
11717
11718 When a message is received from a remote host, this variable contains the
11719 host name and IP address in a single string. It ends with the IP address in
11720 square brackets, followed by a colon and a port number if the logging of
11721 ports is enabled. The format of the rest of the string depends on whether
11722 the host issued a HELO or EHLO SMTP command, and whether the host name was
11723 verified by looking up its IP address. (Looking up the IP address can be
11724 forced by the host_lookup option, independent of verification.) A plain
11725 host name at the start of the string is a verified host name; if this is
11726 not present, verification either failed or was not requested. A host name
11727 in parentheses is the argument of a HELO or EHLO command. This is omitted
11728 if it is identical to the verified host name or to the host's IP address in
11729 square brackets.
11730
11731 $sender_helo_dnssec
11732
11733 This boolean variable is true if a successful HELO verification was done
11734 using DNS information the resolver library stated was authenticated data.
11735
11736 $sender_helo_name
11737
11738 When a message is received from a remote host that has issued a HELO or
11739 EHLO command, the argument of that command is placed in this variable. It
11740 is also set if HELO or EHLO is used when a message is received using SMTP
11741 locally via the -bs or -bS options.
11742
11743 $sender_host_address
11744
11745 When a message is received from a remote host using SMTP, this variable
11746 contains that host's IP address. For locally non-SMTP submitted messages,
11747 it is empty.
11748
11749 $sender_host_authenticated
11750
11751 This variable contains the name (not the public name) of the authenticator
11752 driver that successfully authenticated the client from which the message
11753 was received. It is empty if there was no successful authentication. See
11754 also $authenticated_id.
11755
11756 $sender_host_dnssec
11757
11758 If an attempt to populate $sender_host_name has been made (by reference,
11759 hosts_lookup or otherwise) then this boolean will have been set true if,
11760 and only if, the resolver library states that both the reverse and forward
11761 DNS were authenticated data. At all other times, this variable is false.
11762
11763 It is likely that you will need to coerce DNSSEC support on in the resolver
11764 library, by setting:
11765
11766 dns_dnssec_ok = 1
11767
11768 Exim does not perform DNSSEC validation itself, instead leaving that to a
11769 validating resolver (e.g. unbound, or bind with suitable configuration).
11770
11771 If you have changed host_lookup_order so that "bydns" is not the first
11772 mechanism in the list, then this variable will be false.
11773
11774 This requires that your system resolver library support EDNS0 (and that
11775 DNSSEC flags exist in the system headers). If the resolver silently drops
11776 all EDNS0 options, then this will have no effect. OpenBSD's asr resolver is
11777 known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
11778
11779 $sender_host_name
11780
11781 When a message is received from a remote host, this variable contains the
11782 host's name as obtained by looking up its IP address. For messages received
11783 by other means, this variable is empty.
11784
11785 If the host name has not previously been looked up, a reference to
11786 $sender_host_name triggers a lookup (for messages from remote hosts). A
11787 looked up name is accepted only if it leads back to the original IP address
11788 via a forward lookup. If either the reverse or the forward lookup fails to
11789 find any data, or if the forward lookup does not yield the original IP
11790 address, $sender_host_name remains empty, and $host_lookup_failed is set to
11791 "1".
11792
11793 However, if either of the lookups cannot be completed (for example, there
11794 is a DNS timeout), $host_lookup_deferred is set to "1", and
11795 $host_lookup_failed remains set to "0".
11796
11797 Once $host_lookup_failed is set to "1", Exim does not try to look up the
11798 host name again if there is a subsequent reference to $sender_host_name in
11799 the same Exim process, but it does try again if $host_lookup_deferred is
11800 set to "1".
11801
11802 Exim does not automatically look up every calling host's name. If you want
11803 maximum efficiency, you should arrange your configuration so that it avoids
11804 these lookups altogether. The lookup happens only if one or more of the
11805 following are true:
11806
11807 + A string containing $sender_host_name is expanded.
11808
11809 + The calling host matches the list in host_lookup. In the default
11810 configuration, this option is set to *, so it must be changed if
11811 lookups are to be avoided. (In the code, the default for host_lookup is
11812 unset.)
11813
11814 + Exim needs the host name in order to test an item in a host list. The
11815 items that require this are described in sections 10.13 and 10.17.
11816
11817 + The calling host matches helo_try_verify_hosts or helo_verify_hosts. In
11818 this case, the host name is required to compare with the name quoted in
11819 any EHLO or HELO commands that the client issues.
11820
11821 + The remote host issues a EHLO or HELO command that quotes one of the
11822 domains in helo_lookup_domains. The default value of this option is
11823
11824 helo_lookup_domains = @ : @[]
11825
11826 which causes a lookup if a remote host (incorrectly) gives the server's
11827 name or IP address in an EHLO or HELO command.
11828
11829 $sender_host_port
11830
11831 When a message is received from a remote host, this variable contains the
11832 port number that was used on the remote host.
11833
11834 $sender_ident
11835
11836 When a message is received from a remote host, this variable contains the
11837 identification received in response to an RFC 1413 request. When a message
11838 has been received locally, this variable contains the login name of the
11839 user that called Exim.
11840
11841 $sender_rate_xxx
11842
11843 A number of variables whose names begin $sender_rate_ are set as part of
11844 the ratelimit ACL condition. Details are given in section 43.38.
11845
11846 $sender_rcvhost
11847
11848 This is provided specifically for use in Received: headers. It starts with
11849 either the verified host name (as obtained from a reverse DNS lookup) or,
11850 if there is no verified host name, the IP address in square brackets. After
11851 that there may be text in parentheses. When the first item is a verified
11852 host name, the first thing in the parentheses is the IP address in square
11853 brackets, followed by a colon and a port number if port logging is enabled.
11854 When the first item is an IP address, the port is recorded as "port=xxxx"
11855 inside the parentheses.
11856
11857 There may also be items of the form "helo=xxxx" if HELO or EHLO was used
11858 and its argument was not identical to the real host name or IP address, and
11859 "ident=xxxx" if an RFC 1413 ident string is available. If all three items
11860 are present in the parentheses, a newline and tab are inserted into the
11861 string, to improve the formatting of the Received: header.
11862
11863 $sender_verify_failure
11864
11865 In an ACL, when a sender verification fails, this variable contains
11866 information about the failure. The details are the same as for
11867 $recipient_verify_failure.
11868
11869 $sending_ip_address
11870
11871 This variable is set whenever an outgoing SMTP connection to another host
11872 has been set up. It contains the IP address of the local interface that is
11873 being used. This is useful if a host that has more than one IP address
11874 wants to take on different personalities depending on which one is being
11875 used. For incoming connections, see $received_ip_address.
11876
11877 $sending_port
11878
11879 This variable is set whenever an outgoing SMTP connection to another host
11880 has been set up. It contains the local port that is being used. For
11881 incoming connections, see $received_port.
11882
11883 $smtp_active_hostname
11884
11885 During an incoming SMTP session, this variable contains the value of the
11886 active host name, as specified by the smtp_active_hostname option. The
11887 value of $smtp_active_hostname is saved with any message that is received,
11888 so its value can be consulted during routing and delivery.
11889
11890 $smtp_command
11891
11892 During the processing of an incoming SMTP command, this variable contains
11893 the entire command. This makes it possible to distinguish between HELO and
11894 EHLO in the HELO ACL, and also to distinguish between commands such as
11895 these:
11896
11897 MAIL FROM:<>
11898 MAIL FROM: <>
11899
11900 For a MAIL command, extra parameters such as SIZE can be inspected. For a
11901 RCPT command, the address in $smtp_command is the original address before
11902 any rewriting, whereas the values in $local_part and $domain are taken from
11903 the address after SMTP-time rewriting.
11904
11905 $smtp_command_argument
11906
11907 While an ACL is running to check an SMTP command, this variable contains
11908 the argument, that is, the text that follows the command name, with leading
11909 white space removed. Following the introduction of $smtp_command, this
11910 variable is somewhat redundant, but is retained for backwards
11911 compatibility.
11912
11913 $smtp_command_history
11914
11915 A comma-separated list (with no whitespace) of the most-recent SMTP
11916 commands received, in time-order left to right. Only a limited number of
11917 commands are remembered.
11918
11919 $smtp_count_at_connection_start
11920
11921 This variable is set greater than zero only in processes spawned by the
11922 Exim daemon for handling incoming SMTP connections. The name is
11923 deliberately long, in order to emphasize what the contents are. When the
11924 daemon accepts a new connection, it increments this variable. A copy of the
11925 variable is passed to the child process that handles the connection, but
11926 its value is fixed, and never changes. It is only an approximation of how
11927 many incoming connections there actually are, because many other
11928 connections may come and go while a single connection is being processed.
11929 When a child process terminates, the daemon decrements its copy of the
11930 variable.
11931
11932 $sn0 - $sn9
11933
11934 These variables are copies of the values of the $n0 - $n9 accumulators that
11935 were current at the end of the system filter file. This allows a system
11936 filter file to set values that can be tested in users' filter files. For
11937 example, a system filter could set a value indicating how likely it is that
11938 a message is junk mail.
11939
11940 $spam_xxx
11941
11942 A number of variables whose names start with $spam are available when Exim
11943 is compiled with the content-scanning extension. For details, see section
11944 44.2.
11945
11946 $spf_header_comment, $spf_received, $spf_result, $spf_result_guessed,
11947 $spf_smtp_comment
11948
11949 These variables are only available if Exim is built with SPF support. For
11950 details see section 57.4.
11951
11952 $spool_directory
11953
11954 The name of Exim's spool directory.
11955
11956 $spool_inodes
11957
11958 The number of free inodes in the disk partition where Exim's spool files
11959 are being written. The value is recalculated whenever the variable is
11960 referenced. If the relevant file system does not have the concept of
11961 inodes, the value of is -1. See also the check_spool_inodes option.
11962
11963 $spool_space
11964
11965 The amount of free space (as a number of kilobytes) in the disk partition
11966 where Exim's spool files are being written. The value is recalculated
11967 whenever the variable is referenced. If the operating system does not have
11968 the ability to find the amount of free space (only true for experimental
11969 systems), the space value is -1. For example, to check in an ACL that there
11970 is at least 50 megabytes free on the spool, you could write:
11971
11972 condition = ${if > {$spool_space}{50000}}
11973
11974 See also the check_spool_space option.
11975
11976 $thisaddress
11977
11978 This variable is set only during the processing of the foranyaddress
11979 command in a filter file. Its use is explained in the description of that
11980 command, which can be found in the separate document entitled Exim's
11981 interfaces to mail filtering.
11982
11983 $tls_in_bits
11984
11985 Contains an approximation of the TLS cipher's bit-strength on the inbound
11986 connection; the meaning of this depends upon the TLS implementation used.
11987 If TLS has not been negotiated, the value will be 0. The value of this is
11988 automatically fed into the Cyrus SASL authenticator when acting as a
11989 server, to specify the "external SSF" (a SASL term).
11990
11991 The deprecated $tls_bits variable refers to the inbound side except when
11992 used in the context of an outbound SMTP delivery, when it refers to the
11993 outbound.
11994
11995 $tls_out_bits
11996
11997 Contains an approximation of the TLS cipher's bit-strength on an outbound
11998 SMTP connection; the meaning of this depends upon the TLS implementation
11999 used. If TLS has not been negotiated, the value will be 0.
12000
12001 $tls_in_ourcert
12002
12003 This variable refers to the certificate presented to the peer of an inbound
12004 connection when the message was received. It is only useful as the argument
12005 of a certextract expansion item, md5, sha1 or sha256 operator, or a def
12006 condition.
12007
12008 Note: Under versions of OpenSSL preceding 1.1.1, when a list of more than
12009 one file is used for tls_certificate, this variable is not reliable.
12010
12011 $tls_in_peercert
12012
12013 This variable refers to the certificate presented by the peer of an inbound
12014 connection when the message was received. It is only useful as the argument
12015 of a certextract expansion item, md5, sha1 or sha256 operator, or a def
12016 condition. If certificate verification fails it may refer to a failing
12017 chain element which is not the leaf.
12018
12019 $tls_out_ourcert
12020
12021 This variable refers to the certificate presented to the peer of an
12022 outbound connection. It is only useful as the argument of a certextract
12023 expansion item, md5, sha1 or sha256 operator, or a def condition.
12024
12025 $tls_out_peercert
12026
12027 This variable refers to the certificate presented by the peer of an
12028 outbound connection. It is only useful as the argument of a certextract
12029 expansion item, md5, sha1 or sha256 operator, or a def condition. If
12030 certificate verification fails it may refer to a failing chain element
12031 which is not the leaf.
12032
12033 $tls_in_certificate_verified
12034
12035 This variable is set to "1" if a TLS certificate was verified when the
12036 message was received, and "0" otherwise.
12037
12038 The deprecated $tls_certificate_verified variable refers to the inbound
12039 side except when used in the context of an outbound SMTP delivery, when it
12040 refers to the outbound.
12041
12042 $tls_out_certificate_verified
12043
12044 This variable is set to "1" if a TLS certificate was verified when an
12045 outbound SMTP connection was made, and "0" otherwise.
12046
12047 $tls_in_cipher
12048
12049 When a message is received from a remote host over an encrypted SMTP
12050 connection, this variable is set to the cipher suite that was negotiated,
12051 for example DES-CBC3-SHA. In other circumstances, in particular, for
12052 message received over unencrypted connections, the variable is empty.
12053 Testing $tls_in_cipher for emptiness is one way of distinguishing between
12054 encrypted and non-encrypted connections during ACL processing.
12055
12056 The deprecated $tls_cipher variable is the same as $tls_in_cipher during
12057 message reception, but in the context of an outward SMTP delivery taking
12058 place via the smtp transport becomes the same as $tls_out_cipher.
12059
12060 $tls_out_cipher
12061
12062 This variable is cleared before any outgoing SMTP connection is made, and
12063 then set to the outgoing cipher suite if one is negotiated. See chapter 42
12064 for details of TLS support and chapter 30 for details of the smtp
12065 transport.
12066
12067 $tls_out_dane
12068
12069 DANE active status. See section 42.15.
12070
12071 $tls_in_ocsp
12072
12073 When a message is received from a remote client connection the result of
12074 any OCSP request from the client is encoded in this variable:
12075
12076 0 OCSP proof was not requested (default value)
12077 1 No response to request
12078 2 Response not verified
12079 3 Verification failed
12080 4 Verification succeeded
12081
12082 $tls_out_ocsp
12083
12084 When a message is sent to a remote host connection the result of any OCSP
12085 request made is encoded in this variable. See $tls_in_ocsp for values.
12086
12087 $tls_in_peerdn
12088
12089 When a message is received from a remote host over an encrypted SMTP
12090 connection, and Exim is configured to request a certificate from the
12091 client, the value of the Distinguished Name of the certificate is made
12092 available in the $tls_in_peerdn during subsequent processing. If
12093 certificate verification fails it may refer to a failing chain element
12094 which is not the leaf.
12095
12096 The deprecated $tls_peerdn variable refers to the inbound side except when
12097 used in the context of an outbound SMTP delivery, when it refers to the
12098 outbound.
12099
12100 $tls_out_peerdn
12101
12102 When a message is being delivered to a remote host over an encrypted SMTP
12103 connection, and Exim is configured to request a certificate from the
12104 server, the value of the Distinguished Name of the certificate is made
12105 available in the $tls_out_peerdn during subsequent processing. If
12106 certificate verification fails it may refer to a failing chain element
12107 which is not the leaf.
12108
12109 $tls_in_sni
12110
12111 When a TLS session is being established, if the client sends the Server
12112 Name Indication extension, the value will be placed in this variable. If
12113 the variable appears in tls_certificate then this option and some others,
12114 described in 42.10, will be re-expanded early in the TLS session, to permit
12115 a different certificate to be presented (and optionally a different key to
12116 be used) to the client, based upon the value of the SNI extension.
12117
12118 The deprecated $tls_sni variable refers to the inbound side except when
12119 used in the context of an outbound SMTP delivery, when it refers to the
12120 outbound.
12121
12122 $tls_out_sni
12123
12124 During outbound SMTP deliveries, this variable reflects the value of the
12125 tls_sni option on the transport.
12126
12127 $tls_out_tlsa_usage
12128
12129 Bitfield of TLSA record types found. See section 42.15.
12130
12131 $tod_bsdinbox
12132
12133 The time of day and the date, in the format required for BSD-style mailbox
12134 files, for example: Thu Oct 17 17:14:09 1995.
12135
12136 $tod_epoch
12137
12138 The time and date as a number of seconds since the start of the Unix epoch.
12139
12140 $tod_epoch_l
12141
12142 The time and date as a number of microseconds since the start of the Unix
12143 epoch.
12144
12145 $tod_full
12146
12147 A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40
12148 +0100. The timezone is always given as a numerical offset from UTC, with
12149 positive values used for timezones that are ahead (east) of UTC, and
12150 negative values for those that are behind (west).
12151
12152 $tod_log
12153
12154 The time and date in the format used for writing Exim's log files, for
12155 example: 1995-10-12 15:32:29, but without a timezone.
12156
12157 $tod_logfile
12158
12159 This variable contains the date in the format yyyymmdd. This is the format
12160 that is used for datestamping log files when log_file_path contains the
12161 "%D" flag.
12162
12163 $tod_zone
12164
12165 This variable contains the numerical value of the local timezone, for
12166 example: -0500.
12167
12168 $tod_zulu
12169
12170 This variable contains the UTC date and time in "Zulu" format, as specified
12171 by ISO 8601, for example: 20030221154023Z.
12172
12173 $transport_name
12174
12175 During the running of a transport, this variable contains its name.
12176
12177 $value
12178
12179 This variable contains the result of an expansion lookup, extraction
12180 operation, or external command, as described above. It is also used during
12181 a reduce expansion.
12182
12183 $verify_mode
12184
12185 While a router or transport is being run in verify mode or for cutthrough
12186 delivery, contains "S" for sender-verification or "R" for
12187 recipient-verification. Otherwise, empty.
12188
12189 $version_number
12190
12191 The version number of Exim.
12192
12193 $warn_message_delay
12194
12195 This variable is set only during the creation of a message warning about a
12196 delivery delay. Details of its use are explained in section 49.2.
12197
12198 $warn_message_recipients
12199
12200 This variable is set only during the creation of a message warning about a
12201 delivery delay. Details of its use are explained in section 49.2.
12202
12203
12204
12205 ===============================================================================
12206 12. EMBEDDED PERL
12207
12208 Exim can be built to include an embedded Perl interpreter. When this is done,
12209 Perl subroutines can be called as part of the string expansion process. To make
12210 use of the Perl support, you need version 5.004 or later of Perl installed on
12211 your system. To include the embedded interpreter in the Exim binary, include
12212 the line
12213
12214 EXIM_PERL = perl.o
12215
12216 in your Local/Makefile and then build Exim in the normal way.
12217
12218
12219 12.1 Setting up so Perl can be used
12220 -----------------------------------
12221
12222 Access to Perl subroutines is via a global configuration option called
12223 perl_startup and an expansion string operator ${perl ...}. If there is no
12224 perl_startup option in the Exim configuration file then no Perl interpreter is
12225 started and there is almost no overhead for Exim (since none of the Perl
12226 library will be paged in unless used). If there is a perl_startup option then
12227 the associated value is taken to be Perl code which is executed in a newly
12228 created Perl interpreter.
12229
12230 The value of perl_startup is not expanded in the Exim sense, so you do not need
12231 backslashes before any characters to escape special meanings. The option should
12232 usually be something like
12233
12234 perl_startup = do '/etc/exim.pl'
12235
12236 where /etc/exim.pl is Perl code which defines any subroutines you want to use
12237 from Exim. Exim can be configured either to start up a Perl interpreter as soon
12238 as it is entered, or to wait until the first time it is needed. Starting the
12239 interpreter at the beginning ensures that it is done while Exim still has its
12240 setuid privilege, but can impose an unnecessary overhead if Perl is not in fact
12241 used in a particular run. Also, note that this does not mean that Exim is
12242 necessarily running as root when Perl is called at a later time. By default,
12243 the interpreter is started only when it is needed, but this can be changed in
12244 two ways:
12245
12246 * Setting perl_at_start (a boolean option) in the configuration requests a
12247 startup when Exim is entered.
12248
12249 * The command line option -ps also requests a startup when Exim is entered,
12250 overriding the setting of perl_at_start.
12251
12252 There is also a command line option -pd (for delay) which suppresses the
12253 initial startup, even if perl_at_start is set.
12254
12255 * To provide more security executing Perl code via the embedded Perl
12256 interpreter, the perl_taintmode option can be set. This enables the taint
12257 mode of the Perl interpreter. You are encouraged to set this option to a
12258 true value. To avoid breaking existing installations, it defaults to false.
12259
12260
12261 12.2 Calling Perl subroutines
12262 -----------------------------
12263
12264 When the configuration file includes a perl_startup option you can make use of
12265 the string expansion item to call the Perl subroutines that are defined by the
12266 perl_startup code. The operator is used in any of the following forms:
12267
12268 ${perl{foo}}
12269 ${perl{foo}{argument}}
12270 ${perl{foo}{argument1}{argument2} ... }
12271
12272 which calls the subroutine foo with the given arguments. A maximum of eight
12273 arguments may be passed. Passing more than this results in an expansion failure
12274 with an error message of the form
12275
12276 Too many arguments passed to Perl subroutine "foo" (max is 8)
12277
12278 The return value of the Perl subroutine is evaluated in a scalar context before
12279 it is passed back to Exim to be inserted into the expanded string. If the
12280 return value is undef, the expansion is forced to fail in the same way as an
12281 explicit "fail" on an if or lookup item. If the subroutine aborts by obeying
12282 Perl's die function, the expansion fails with the error message that was passed
12283 to die.
12284
12285
12286 12.3 Calling Exim functions from Perl
12287 -------------------------------------
12288
12289 Within any Perl code called from Exim, the function Exim::expand_string() is
12290 available to call back into Exim's string expansion function. For example, the
12291 Perl code
12292
12293 my $lp = Exim::expand_string('$local_part');
12294
12295 makes the current Exim $local_part available in the Perl variable $lp. Note
12296 those are single quotes and not double quotes to protect against $local_part
12297 being interpolated as a Perl variable.
12298
12299 If the string expansion is forced to fail by a "fail" item, the result of
12300 Exim::expand_string() is undef. If there is a syntax error in the expansion
12301 string, the Perl call from the original expansion string fails with an
12302 appropriate error message, in the same way as if die were used.
12303
12304 Two other Exim functions are available for use from within Perl code.
12305 Exim::debug_write() writes a string to the standard error stream if Exim's
12306 debugging is enabled. If you want a newline at the end, you must supply it.
12307 Exim::log_write() writes a string to Exim's main log, adding a leading
12308 timestamp. In this case, you should not supply a terminating newline.
12309
12310
12311 12.4 Use of standard output and error by Perl
12312 ---------------------------------------------
12313
12314 You should not write to the standard error or output streams from within your
12315 Perl code, as it is not defined how these are set up. In versions of Exim
12316 before 4.50, it is possible for the standard output or error to refer to the
12317 SMTP connection during message reception via the daemon. Writing to this stream
12318 is certain to cause chaos. From Exim 4.50 onwards, the standard output and
12319 error streams are connected to /dev/null in the daemon. The chaos is avoided,
12320 but the output is lost.
12321
12322 The Perl warn statement writes to the standard error stream by default. Calls
12323 to warn may be embedded in Perl modules that you use, but over which you have
12324 no control. When Exim starts up the Perl interpreter, it arranges for output
12325 from the warn statement to be written to the Exim main log. You can change this
12326 by including appropriate Perl magic somewhere in your Perl code. For example,
12327 to discard warn output completely, you need this:
12328
12329 $SIG{__WARN__} = sub { };
12330
12331 Whenever a warn is obeyed, the anonymous subroutine is called. In this example,
12332 the code for the subroutine is empty, so it does nothing, but you can include
12333 any Perl code that you like. The text of the warn message is passed as the
12334 first subroutine argument.
12335
12336
12337
12338 ===============================================================================
12339 13. STARTING THE DAEMON AND THE USE OF NETWORK INTERFACES
12340
12341 A host that is connected to a TCP/IP network may have one or more physical
12342 hardware network interfaces. Each of these interfaces may be configured as one
12343 or more "logical" interfaces, which are the entities that a program actually
12344 works with. Each of these logical interfaces is associated with an IP address.
12345 In addition, TCP/IP software supports "loopback" interfaces (127.0.0.1 in IPv4
12346 and ::1 in IPv6), which do not use any physical hardware. Exim requires
12347 knowledge about the host's interfaces for use in three different circumstances:
12348
12349 1. When a listening daemon is started, Exim needs to know which interfaces and
12350 ports to listen on.
12351
12352 2. When Exim is routing an address, it needs to know which IP addresses are
12353 associated with local interfaces. This is required for the correct
12354 processing of MX lists by removing the local host and others with the same
12355 or higher priority values. Also, Exim needs to detect cases when an address
12356 is routed to an IP address that in fact belongs to the local host. Unless
12357 the self router option or the allow_localhost option of the smtp transport
12358 is set (as appropriate), this is treated as an error situation.
12359
12360 3. When Exim connects to a remote host, it may need to know which interface to
12361 use for the outgoing connection.
12362
12363 Exim's default behaviour is likely to be appropriate in the vast majority of
12364 cases. If your host has only one interface, and you want all its IP addresses
12365 to be treated in the same way, and you are using only the standard SMTP port,
12366 you should not need to take any special action. The rest of this chapter does
12367 not apply to you.
12368
12369 In a more complicated situation you may want to listen only on certain
12370 interfaces, or on different ports, and for this reason there are a number of
12371 options that can be used to influence Exim's behaviour. The rest of this
12372 chapter describes how they operate.
12373
12374 When a message is received over TCP/IP, the interface and port that were
12375 actually used are set in $received_ip_address and $received_port.
12376
12377
12378 13.1 Starting a listening daemon
12379 --------------------------------
12380
12381 When a listening daemon is started (by means of the -bd command line option),
12382 the interfaces and ports on which it listens are controlled by the following
12383 options:
12384
12385 * daemon_smtp_ports contains a list of default ports or service names. (For
12386 backward compatibility, this option can also be specified in the singular.)
12387
12388 * local_interfaces contains list of interface IP addresses on which to
12389 listen. Each item may optionally also specify a port.
12390
12391 The default list separator in both cases is a colon, but this can be changed as
12392 described in section 6.21. When IPv6 addresses are involved, it is usually best
12393 to change the separator to avoid having to double all the colons. For example:
12394
12395 local_interfaces = <; 127.0.0.1 ; \
12396 192.168.23.65 ; \
12397 ::1 ; \
12398 3ffe:ffff:836f::fe86:a061
12399
12400 There are two different formats for specifying a port along with an IP address
12401 in local_interfaces:
12402
12403 1. The port is added onto the address with a dot separator. For example, to
12404 listen on port 1234 on two different IP addresses:
12405
12406 local_interfaces = <; 192.168.23.65.1234 ; \
12407 3ffe:ffff:836f::fe86:a061.1234
12408
12409 2. The IP address is enclosed in square brackets, and the port is added with a
12410 colon separator, for example:
12411
12412 local_interfaces = <; [192.168.23.65]:1234 ; \
12413 [3ffe:ffff:836f::fe86:a061]:1234
12414
12415 When a port is not specified, the value of daemon_smtp_ports is used. The
12416 default setting contains just one port:
12417
12418 daemon_smtp_ports = smtp
12419
12420 If more than one port is listed, each interface that does not have its own port
12421 specified listens on all of them. Ports that are listed in daemon_smtp_ports
12422 can be identified either by name (defined in /etc/services) or by number.
12423 However, when ports are given with individual IP addresses in local_interfaces,
12424 only numbers (not names) can be used.
12425
12426
12427 13.2 Special IP listening addresses
12428 -----------------------------------
12429
12430 The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted as
12431 "all IPv4 interfaces" and "all IPv6 interfaces", respectively. In each case,
12432 Exim tells the TCP/IP stack to "listen on all IPvx interfaces" instead of
12433 setting up separate listening sockets for each interface. The default value of
12434 local_interfaces is
12435
12436 local_interfaces = 0.0.0.0
12437
12438 when Exim is built without IPv6 support; otherwise it is:
12439
12440 local_interfaces = <; ::0 ; 0.0.0.0
12441
12442 Thus, by default, Exim listens on all available interfaces, on the SMTP port.
12443
12444
12445 13.3 Overriding local_interfaces and daemon_smtp_ports
12446 ------------------------------------------------------
12447
12448 The -oX command line option can be used to override the values of
12449 daemon_smtp_ports and/or local_interfaces for a particular daemon instance.
12450 Another way of doing this would be to use macros and the -D option. However,
12451 -oX can be used by any admin user, whereas modification of the runtime
12452 configuration by -D is allowed only when the caller is root or exim.
12453
12454 The value of -oX is a list of items. The default colon separator can be changed
12455 in the usual way (6.21) if required. If there are any items that do not contain
12456 dots or colons (that is, are not IP addresses), the value of daemon_smtp_ports
12457 is replaced by the list of those items. If there are any items that do contain
12458 dots or colons, the value of local_interfaces is replaced by those items. Thus,
12459 for example,
12460
12461 -oX 1225
12462
12463 overrides daemon_smtp_ports, but leaves local_interfaces unchanged, whereas
12464
12465 -oX 192.168.34.5.1125
12466
12467 overrides local_interfaces, leaving daemon_smtp_ports unchanged. (However,
12468 since local_interfaces now contains no items without ports, the value of
12469 daemon_smtp_ports is no longer relevant in this example.)
12470
12471
12472 13.4 Support for the submissions (aka SSMTP or SMTPS) protocol
12473 --------------------------------------------------------------
12474
12475 Exim supports the use of TLS-on-connect, used by mail clients in the
12476 "submissions" protocol, historically also known as SMTPS or SSMTP. For some
12477 years, IETF Standards Track documents only blessed the STARTTLS-based
12478 Submission service (port 587) while common practice was to support the same
12479 feature set on port 465, but using TLS-on-connect. If your installation needs
12480 to provide service to mail clients (Mail User Agents, MUAs) then you should
12481 provide service on both the 587 and the 465 TCP ports.
12482
12483 If the tls_on_connect_ports option is set to a list of port numbers or service
12484 names, connections to those ports must first establish TLS, before proceeding
12485 to the application layer use of the SMTP protocol.
12486
12487 The common use of this option is expected to be
12488
12489 tls_on_connect_ports = 465
12490
12491 per RFC 8314. There is also a command line option -tls-on-connect, which forces
12492 all ports to behave in this way when a daemon is started.
12493
12494 Warning: Setting tls_on_connect_ports does not of itself cause the daemon to
12495 listen on those ports. You must still specify them in daemon_smtp_ports,
12496 local_interfaces, or the -oX option. (This is because tls_on_connect_ports
12497 applies to inetd connections as well as to connections via the daemon.)
12498
12499
12500 13.5 IPv6 address scopes
12501 ------------------------
12502
12503 IPv6 addresses have "scopes", and a host with multiple hardware interfaces can,
12504 in principle, have the same link-local IPv6 address on different interfaces.
12505 Thus, additional information is needed, over and above the IP address, to
12506 distinguish individual interfaces. A convention of using a percent sign
12507 followed by something (often the interface name) has been adopted in some
12508 cases, leading to addresses like this:
12509
12510 fe80::202:b3ff:fe03:45c1%eth0
12511
12512 To accommodate this usage, a percent sign followed by an arbitrary string is
12513 allowed at the end of an IPv6 address. By default, Exim calls getaddrinfo() to
12514 convert a textual IPv6 address for actual use. This function recognizes the
12515 percent convention in operating systems that support it, and it processes the
12516 address appropriately. Unfortunately, some older libraries have problems with
12517 getaddrinfo(). If
12518
12519 IPV6_USE_INET_PTON=yes
12520
12521 is set in Local/Makefile (or an OS-dependent Makefile) when Exim is built, Exim
12522 uses inet_pton() to convert a textual IPv6 address for actual use, instead of
12523 getaddrinfo(). (Before version 4.14, it always used this function.) Of course,
12524 this means that the additional functionality of getaddrinfo() - recognizing
12525 scoped addresses - is lost.
12526
12527
12528 13.6 Disabling IPv6
12529 -------------------
12530
12531 Sometimes it happens that an Exim binary that was compiled with IPv6 support is
12532 run on a host whose kernel does not support IPv6. The binary will fall back to
12533 using IPv4, but it may waste resources looking up AAAA records, and trying to
12534 connect to IPv6 addresses, causing delays to mail delivery. If you set the
12535 disable_ipv6 option true, even if the Exim binary has IPv6 support, no IPv6
12536 activities take place. AAAA records are never looked up, and any IPv6 addresses
12537 that are listed in local_interfaces, data for the manualroute router, etc. are
12538 ignored. If IP literals are enabled, the ipliteral router declines to handle
12539 IPv6 literal addresses.
12540
12541 On the other hand, when IPv6 is in use, there may be times when you want to
12542 disable it for certain hosts or domains. You can use the dns_ipv4_lookup option
12543 to globally suppress the lookup of AAAA records for specified domains, and you
12544 can use the ignore_target_hosts generic router option to ignore IPv6 addresses
12545 in an individual router.
12546
12547
12548 13.7 Examples of starting a listening daemon
12549 --------------------------------------------
12550
12551 The default case in an IPv6 environment is
12552
12553 daemon_smtp_ports = smtp
12554 local_interfaces = <; ::0 ; 0.0.0.0
12555
12556 This specifies listening on the smtp port on all IPv6 and IPv4 interfaces.
12557 Either one or two sockets may be used, depending on the characteristics of the
12558 TCP/IP stack. (This is complicated and messy; for more information, read the
12559 comments in the daemon.c source file.)
12560
12561 To specify listening on ports 25 and 26 on all interfaces:
12562
12563 daemon_smtp_ports = 25 : 26
12564
12565 (leaving local_interfaces at the default setting) or, more explicitly:
12566
12567 local_interfaces = <; ::0.25 ; ::0.26 \
12568 0.0.0.0.25 ; 0.0.0.0.26
12569
12570 To listen on the default port on all IPv4 interfaces, and on port 26 on the
12571 IPv4 loopback address only:
12572
12573 local_interfaces = 0.0.0.0 : 127.0.0.1.26
12574
12575 To specify listening on the default port on specific interfaces only:
12576
12577 local_interfaces = 10.0.0.67 : 192.168.34.67
12578
12579 Warning: Such a setting excludes listening on the loopback interfaces.
12580
12581
12582 13.8 Recognizing the local host
12583 -------------------------------
12584
12585 The local_interfaces option is also used when Exim needs to determine whether
12586 or not an IP address refers to the local host. That is, the IP addresses of all
12587 the interfaces on which a daemon is listening are always treated as local.
12588
12589 For this usage, port numbers in local_interfaces are ignored. If either of the
12590 items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of available
12591 interfaces from the operating system, and extracts the relevant (that is, IPv4
12592 or IPv6) addresses to use for checking.
12593
12594 Some systems set up large numbers of virtual interfaces in order to provide
12595 many virtual web servers. In this situation, you may want to listen for email
12596 on only a few of the available interfaces, but nevertheless treat all
12597 interfaces as local when routing. You can do this by setting
12598 extra_local_interfaces to a list of IP addresses, possibly including the "all"
12599 wildcard values. These addresses are recognized as local, but are not used for
12600 listening. Consider this example:
12601
12602 local_interfaces = <; 127.0.0.1 ; ::1 ; \
12603 192.168.53.235 ; \
12604 3ffe:2101:12:1:a00:20ff:fe86:a061
12605
12606 extra_local_interfaces = <; ::0 ; 0.0.0.0
12607
12608 The daemon listens on the loopback interfaces and just one IPv4 and one IPv6
12609 address, but all available interface addresses are treated as local when Exim
12610 is routing.
12611
12612 In some environments the local host name may be in an MX list, but with an IP
12613 address that is not assigned to any local interface. In other cases it may be
12614 desirable to treat other host names as if they referred to the local host. Both
12615 these cases can be handled by setting the hosts_treat_as_local option. This
12616 contains host names rather than IP addresses. When a host is referenced during
12617 routing, either via an MX record or directly, it is treated as the local host
12618 if its name matches hosts_treat_as_local, or if any of its IP addresses match
12619 local_interfaces or extra_local_interfaces.
12620
12621
12622 13.9 Delivering to a remote host
12623 --------------------------------
12624
12625 Delivery to a remote host is handled by the smtp transport. By default, it
12626 allows the system's TCP/IP functions to choose which interface to use (if there
12627 is more than one) when connecting to a remote host. However, the interface
12628 option can be set to specify which interface is used. See the description of
12629 the smtp transport in chapter 30 for more details.
12630
12631
12632
12633 ===============================================================================
12634 14. MAIN CONFIGURATION
12635
12636 The first part of the runtime configuration file contains three types of item:
12637
12638 * Macro definitions: These lines start with an upper case letter. See section
12639 6.4 for details of macro processing.
12640
12641 * Named list definitions: These lines start with one of the words
12642 "domainlist", "hostlist", "addresslist", or "localpartlist". Their use is
12643 described in section 10.5.
12644
12645 * Main configuration settings: Each setting occupies one line of the file
12646 (with possible continuations). If any setting is preceded by the word
12647 "hide", the -bP command line option displays its value to admin users only.
12648 See section 6.11 for a description of the syntax of these option settings.
12649
12650 This chapter specifies all the main configuration options, along with their
12651 types and default values. For ease of finding a particular option, they appear
12652 in alphabetical order in section 14.23 below. However, because there are now so
12653 many options, they are first listed briefly in functional groups, as an aid to
12654 finding the name of the option you are looking for. Some options are listed in
12655 more than one group.
12656
12657
12658 14.1 Miscellaneous
12659 ------------------
12660
12661 bi_command to run for -bi command line option
12662 debug_store do extra internal checks
12663 disable_ipv6 do no IPv6 processing
12664 keep_malformed for broken files - should not happen
12665 localhost_number for unique message ids in clusters
12666 message_body_newlines retain newlines in $message_body
12667 message_body_visible how much to show in $message_body
12668 mua_wrapper run in "MUA wrapper" mode
12669 print_topbitchars top-bit characters are printing
12670 spool_wireformat use wire-format spool data files when possible
12671 timezone force time zone
12672
12673
12674 14.2 Exim parameters
12675 --------------------
12676
12677 exim_group override compiled-in value
12678 exim_path override compiled-in value
12679 exim_user override compiled-in value
12680 primary_hostname default from uname()
12681 split_spool_directory use multiple directories
12682 spool_directory override compiled-in value
12683
12684
12685 14.3 Privilege controls
12686 -----------------------
12687
12688 admin_groups groups that are Exim admin users
12689 commandline_checks_require_admin require admin for various checks
12690 deliver_drop_privilege drop root for delivery processes
12691 local_from_check insert Sender: if necessary
12692 local_from_prefix for testing From: for local sender
12693 local_from_suffix for testing From: for local sender
12694 local_sender_retain keep Sender: from untrusted user
12695 never_users do not run deliveries as these
12696 prod_requires_admin forced delivery requires admin user
12697 queue_list_requires_admin queue listing requires admin user
12698 trusted_groups groups that are trusted
12699 trusted_users users that are trusted
12700
12701
12702 14.4 Logging
12703 ------------
12704
12705 event_action custom logging
12706 hosts_connection_nolog exemption from connect logging
12707 log_file_path override compiled-in value
12708 log_selector set/unset optional logging
12709 log_timezone add timezone to log lines
12710 message_logs create per-message logs
12711 preserve_message_logs after message completion
12712 process_log_path for SIGUSR1 and exiwhat
12713 slow_lookup_log control logging of slow DNS lookups
12714 syslog_duplication controls duplicate log lines on syslog
12715 syslog_facility set syslog "facility" field
12716 syslog_pid pid in syslog lines
12717 syslog_processname set syslog "ident" field
12718 syslog_timestamp timestamp syslog lines
12719 write_rejectlog control use of message log
12720
12721
12722 14.5 Frozen messages
12723 --------------------
12724
12725 auto_thaw sets time for retrying frozen messages
12726 freeze_tell send message when freezing
12727 move_frozen_messages to another directory
12728 timeout_frozen_after keep frozen messages only so long
12729
12730
12731 14.6 Data lookups
12732 -----------------
12733
12734 ibase_servers InterBase servers
12735 ldap_ca_cert_dir dir of CA certs to verify LDAP server's
12736 ldap_ca_cert_file file of CA certs to verify LDAP server's
12737 ldap_cert_file client cert file for LDAP
12738 ldap_cert_key client key file for LDAP
12739 ldap_cipher_suite TLS negotiation preference control
12740 ldap_default_servers used if no server in query
12741 ldap_require_cert action to take without LDAP server cert
12742 ldap_start_tls require TLS within LDAP
12743 ldap_version set protocol version
12744 lookup_open_max lookup files held open
12745 mysql_servers default MySQL servers
12746 oracle_servers Oracle servers
12747 pgsql_servers default PostgreSQL servers
12748 sqlite_lock_timeout as it says
12749
12750
12751 14.7 Message ids
12752 ----------------
12753
12754 message_id_header_domain used to build Message-ID: header
12755 message_id_header_text ditto
12756
12757
12758 14.8 Embedded Perl Startup
12759 --------------------------
12760
12761 perl_at_start always start the interpreter
12762 perl_startup code to obey when starting Perl
12763 perl_taintmode enable taint mode in Perl
12764
12765
12766 14.9 Daemon
12767 -----------
12768
12769 daemon_smtp_ports default ports
12770 daemon_startup_retries number of times to retry
12771 daemon_startup_sleep time to sleep between tries
12772 extra_local_interfaces not necessarily listened on
12773 local_interfaces on which to listen, with optional ports
12774 pid_file_path override compiled-in value
12775 queue_run_max maximum simultaneous queue runners
12776
12777
12778 14.10 Resource control
12779 ----------------------
12780
12781 check_log_inodes before accepting a message
12782 check_log_space before accepting a message
12783 check_spool_inodes before accepting a message
12784 check_spool_space before accepting a message
12785 deliver_queue_load_max no queue deliveries if load high
12786 queue_only_load queue incoming if load high
12787 queue_only_load_latch don't re-evaluate load for each message
12788 queue_run_max maximum simultaneous queue runners
12789 remote_max_parallel parallel SMTP delivery per message
12790 smtp_accept_max simultaneous incoming connections
12791 smtp_accept_max_nonmail non-mail commands
12792 smtp_accept_max_nonmail_hosts hosts to which the limit applies
12793 smtp_accept_max_per_connection messages per connection
12794 smtp_accept_max_per_host connections from one host
12795 smtp_accept_queue queue mail if more connections
12796 smtp_accept_queue_per_connection queue if more messages per connection
12797 smtp_accept_reserve only reserve hosts if more connections
12798 smtp_check_spool_space from SIZE on MAIL command
12799 smtp_connect_backlog passed to TCP/IP stack
12800 smtp_load_reserve SMTP from reserved hosts if load high
12801 smtp_reserve_hosts these are the reserve hosts
12802
12803
12804 14.11 Policy controls
12805 ---------------------
12806
12807 acl_not_smtp ACL for non-SMTP messages
12808 acl_not_smtp_mime ACL for non-SMTP MIME parts
12809 acl_not_smtp_start ACL for start of non-SMTP message
12810 acl_smtp_auth ACL for AUTH
12811 acl_smtp_connect ACL for connection
12812 acl_smtp_data ACL for DATA
12813 acl_smtp_data_prdr ACL for DATA, per-recipient
12814 acl_smtp_dkim ACL for DKIM verification
12815 acl_smtp_etrn ACL for ETRN
12816 acl_smtp_expn ACL for EXPN
12817 acl_smtp_helo ACL for EHLO or HELO
12818 acl_smtp_mail ACL for MAIL
12819 acl_smtp_mailauth ACL for AUTH on MAIL command
12820 acl_smtp_mime ACL for MIME parts
12821 acl_smtp_notquit ACL for non-QUIT terminations
12822 acl_smtp_predata ACL for start of data
12823 acl_smtp_quit ACL for QUIT
12824 acl_smtp_rcpt ACL for RCPT
12825 acl_smtp_starttls ACL for STARTTLS
12826 acl_smtp_vrfy ACL for VRFY
12827 av_scanner specify virus scanner
12828 check_rfc2047_length check length of RFC 2047 "encoded words"
12829 dns_cname_loops follow CNAMEs returned by resolver
12830 dns_csa_search_limit control CSA parent search depth
12831 dns_csa_use_reverse en/disable CSA IP reverse search
12832 header_maxsize total size of message header
12833 header_line_maxsize individual header line limit
12834 helo_accept_junk_hosts allow syntactic junk from these hosts
12835 helo_allow_chars allow illegal chars in HELO names
12836 helo_lookup_domains lookup hostname for these HELO names
12837 helo_try_verify_hosts HELO soft-checked for these hosts
12838 helo_verify_hosts HELO hard-checked for these hosts
12839 host_lookup host name looked up for these hosts
12840 host_lookup_order order of DNS and local name lookups
12841 hosts_proxy use proxy protocol for these hosts
12842 host_reject_connection reject connection from these hosts
12843 hosts_treat_as_local useful in some cluster configurations
12844 local_scan_timeout timeout for local_scan()
12845 message_size_limit for all messages
12846 percent_hack_domains recognize %-hack for these domains
12847 spamd_address set interface to SpamAssassin
12848 strict_acl_vars object to unset ACL variables
12849
12850
12851 14.12 Callout cache
12852 -------------------
12853
12854 callout_domain_negative_expire timeout for negative domain cache item
12855 callout_domain_positive_expire timeout for positive domain cache item
12856 callout_negative_expire timeout for negative address cache item
12857 callout_positive_expire timeout for positive address cache item
12858 callout_random_local_part string to use for "random" testing
12859
12860
12861 14.13 TLS
12862 ---------
12863
12864 gnutls_compat_mode use GnuTLS compatibility mode
12865 gnutls_allow_auto_pkcs11 allow GnuTLS to autoload PKCS11 modules
12866 openssl_options adjust OpenSSL compatibility options
12867 tls_advertise_hosts advertise TLS to these hosts
12868 tls_certificate location of server certificate
12869 tls_crl certificate revocation list
12870 tls_dh_max_bits clamp D-H bit count suggestion
12871 tls_dhparam DH parameters for server
12872 tls_eccurve EC curve selection for server
12873 tls_ocsp_file location of server certificate status proof
12874 tls_on_connect_ports specify SSMTP (SMTPS) ports
12875 tls_privatekey location of server private key
12876 tls_remember_esmtp don't reset after starting TLS
12877 tls_require_ciphers specify acceptable ciphers
12878 tls_try_verify_hosts try to verify client certificate
12879 tls_verify_certificates expected client certificates
12880 tls_verify_hosts insist on client certificate verify
12881
12882
12883 14.14 Local user handling
12884 -------------------------
12885
12886 finduser_retries useful in NIS environments
12887 gecos_name used when creating Sender:
12888 gecos_pattern ditto
12889 max_username_length for systems that truncate
12890 unknown_login used when no login name found
12891 unknown_username ditto
12892 uucp_from_pattern for recognizing "From " lines
12893 uucp_from_sender ditto
12894
12895
12896 14.15 All incoming messages (SMTP and non-SMTP)
12897 -----------------------------------------------
12898
12899 header_maxsize total size of message header
12900 header_line_maxsize individual header line limit
12901 message_size_limit applies to all messages
12902 percent_hack_domains recognize %-hack for these domains
12903 received_header_text expanded to make Received:
12904 received_headers_max for mail loop detection
12905 recipients_max limit per message
12906 recipients_max_reject permanently reject excess recipients
12907
12908
12909 14.16 Non-SMTP incoming messages
12910 --------------------------------
12911
12912 receive_timeout for non-SMTP messages
12913
12914
12915 14.17 Incoming SMTP messages
12916 ----------------------------
12917
12918 See also the Policy controls section above.
12919
12920 dkim_verify_signers DKIM domain for which DKIM ACL is run
12921 host_lookup host name looked up for these hosts
12922 host_lookup_order order of DNS and local name lookups
12923 recipient_unqualified_hosts may send unqualified recipients
12924 rfc1413_hosts make ident calls to these hosts
12925 rfc1413_query_timeout zero disables ident calls
12926 sender_unqualified_hosts may send unqualified senders
12927 smtp_accept_keepalive some TCP/IP magic
12928 smtp_accept_max simultaneous incoming connections
12929 smtp_accept_max_nonmail non-mail commands
12930 smtp_accept_max_nonmail_hosts hosts to which the limit applies
12931 smtp_accept_max_per_connection messages per connection
12932 smtp_accept_max_per_host connections from one host
12933 smtp_accept_queue queue mail if more connections
12934 smtp_accept_queue_per_connection queue if more messages per connection
12935 smtp_accept_reserve only reserve hosts if more connections
12936 smtp_active_hostname host name to use in messages
12937 smtp_banner text for welcome banner
12938 smtp_check_spool_space from SIZE on MAIL command
12939 smtp_connect_backlog passed to TCP/IP stack
12940 smtp_enforce_sync of SMTP command/responses
12941 smtp_etrn_command what to run for ETRN
12942 smtp_etrn_serialize only one at once
12943 smtp_load_reserve only reserve hosts if this load
12944 smtp_max_unknown_commands before dropping connection
12945 smtp_ratelimit_hosts apply ratelimiting to these hosts
12946 smtp_ratelimit_mail ratelimit for MAIL commands
12947 smtp_ratelimit_rcpt ratelimit for RCPT commands
12948 smtp_receive_timeout per command or data line
12949 smtp_reserve_hosts these are the reserve hosts
12950 smtp_return_error_details give detail on rejections
12951
12952
12953 14.18 SMTP extensions
12954 ---------------------
12955
12956 accept_8bitmime advertise 8BITMIME
12957 auth_advertise_hosts advertise AUTH to these hosts
12958 chunking_advertise_hosts advertise CHUNKING to these hosts
12959 dsn_advertise_hosts advertise DSN extensions to these hosts
12960 ignore_fromline_hosts allow "From " from these hosts
12961 ignore_fromline_local allow "From " from local SMTP
12962 pipelining_advertise_hosts advertise pipelining to these hosts
12963 prdr_enable advertise PRDR to all hosts
12964 smtputf8_advertise_hosts advertise SMTPUTF8 to these hosts
12965 tls_advertise_hosts advertise TLS to these hosts
12966
12967
12968 14.19 Processing messages
12969 -------------------------
12970
12971 allow_domain_literals recognize domain literal syntax
12972 allow_mx_to_ip allow MX to point to IP address
12973 allow_utf8_domains in addresses
12974 check_rfc2047_length check length of RFC 2047 "encoded words"
12975 delivery_date_remove from incoming messages
12976 envelope_to_remove from incoming messages
12977 extract_addresses_remove_arguments affects -t processing
12978 headers_charset default for translations
12979 qualify_domain default for senders
12980 qualify_recipient default for recipients
12981 return_path_remove from incoming messages
12982 strip_excess_angle_brackets in addresses
12983 strip_trailing_dot at end of addresses
12984 untrusted_set_sender untrusted can set envelope sender
12985
12986
12987 14.20 System filter
12988 -------------------
12989
12990 system_filter locate system filter
12991 system_filter_directory_transport transport for delivery to a directory
12992 system_filter_file_transport transport for delivery to a file
12993 system_filter_group group for filter running
12994 system_filter_pipe_transport transport for delivery to a pipe
12995 system_filter_reply_transport transport for autoreply delivery
12996 system_filter_user user for filter running
12997
12998
12999 14.21 Routing and delivery
13000 --------------------------
13001
13002 disable_ipv6 do no IPv6 processing
13003 dns_again_means_nonexist for broken domains
13004 dns_check_names_pattern pre-DNS syntax check
13005 dns_dnssec_ok parameter for resolver
13006 dns_ipv4_lookup only v4 lookup for these domains
13007 dns_retrans parameter for resolver
13008 dns_retry parameter for resolver
13009 dns_trust_aa DNS zones trusted as authentic
13010 dns_use_edns0 parameter for resolver
13011 hold_domains hold delivery for these domains
13012 local_interfaces for routing checks
13013 queue_domains no immediate delivery for these
13014 queue_only no immediate delivery at all
13015 queue_only_file no immediate delivery if file exists
13016 queue_only_load no immediate delivery if load is high
13017 queue_only_load_latch don't re-evaluate load for each message
13018 queue_only_override allow command line to override
13019 queue_run_in_order order of arrival
13020 queue_run_max of simultaneous queue runners
13021 queue_smtp_domains no immediate SMTP delivery for these
13022 remote_max_parallel parallel SMTP delivery per message
13023 remote_sort_domains order of remote deliveries
13024 retry_data_expire timeout for retry data
13025 retry_interval_max safety net for retry rules
13026
13027
13028 14.22 Bounce and warning messages
13029 ---------------------------------
13030
13031 bounce_message_file content of bounce
13032 bounce_message_text content of bounce
13033 bounce_return_body include body if returning message
13034 bounce_return_linesize_limit limit on returned message line length
13035 bounce_return_message include original message in bounce
13036 bounce_return_size_limit limit on returned message
13037 bounce_sender_authentication send authenticated sender with bounce
13038 dsn_from set From: contents in bounces
13039 errors_copy copy bounce messages
13040 errors_reply_to Reply-to: in bounces
13041 delay_warning time schedule
13042 delay_warning_condition condition for warning messages
13043 ignore_bounce_errors_after discard undeliverable bounces
13044 smtp_return_error_details give detail on rejections
13045 warn_message_file content of warning message
13046
13047
13048 14.23 Alphabetical list of main options
13049 ---------------------------------------
13050
13051 Those options that undergo string expansion before use are marked with *.
13052
13053 +-----------------------------------------------------+
13054 |accept_8bitmime|Use: main|Type: boolean|Default: true|
13055 +-----------------------------------------------------+
13056
13057 This option causes Exim to send 8BITMIME in its response to an SMTP EHLO
13058 command, and to accept the BODY= parameter on MAIL commands. However, though
13059 Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to
13060 do anything special with messages received by this route.
13061
13062 Historically Exim kept this option off by default, but the maintainers feel
13063 that in today's Internet, this causes more problems than it solves. It now
13064 defaults to true. A more detailed analysis of the issues is provided by Dan
13065 Bernstein:
13066
13067 https://cr.yp.to/smtp/8bitmime.html
13068
13069 To log received 8BITMIME status use
13070
13071 log_selector = +8bitmime
13072
13073 +---------------------------------------------------+
13074 |acl_not_smtp|Use: main|Type: string*|Default: unset|
13075 +---------------------------------------------------+
13076
13077 This option defines the ACL that is run when a non-SMTP message has been read
13078 and is on the point of being accepted. See chapter 43 for further details.
13079
13080 +--------------------------------------------------------+
13081 |acl_not_smtp_mime|Use: main|Type: string*|Default: unset|
13082 +--------------------------------------------------------+
13083
13084 This option defines the ACL that is run for individual MIME parts of non-SMTP
13085 messages. It operates in exactly the same way as acl_smtp_mime operates for
13086 SMTP messages.
13087
13088 +---------------------------------------------------------+
13089 |acl_not_smtp_start|Use: main|Type: string*|Default: unset|
13090 +---------------------------------------------------------+
13091
13092 This option defines the ACL that is run before Exim starts reading a non-SMTP
13093 message. See chapter 43 for further details.
13094
13095 +----------------------------------------------------+
13096 |acl_smtp_auth|Use: main|Type: string*|Default: unset|
13097 +----------------------------------------------------+
13098
13099 This option defines the ACL that is run when an SMTP AUTH command is received.
13100 See chapter 43 for further details.
13101
13102 +-------------------------------------------------------+
13103 |acl_smtp_connect|Use: main|Type: string*|Default: unset|
13104 +-------------------------------------------------------+
13105
13106 This option defines the ACL that is run when an SMTP connection is received.
13107 See chapter 43 for further details.
13108
13109 +----------------------------------------------------+
13110 |acl_smtp_data|Use: main|Type: string*|Default: unset|
13111 +----------------------------------------------------+
13112
13113 This option defines the ACL that is run after an SMTP DATA command has been
13114 processed and the message itself has been received, but before the final
13115 acknowledgment is sent. See chapter 43 for further details.
13116
13117 +----------------------------------------------------------+
13118 |acl_smtp_data_prdr|Use: main|Type: string*|Default: accept|
13119 +----------------------------------------------------------+
13120
13121 This option defines the ACL that, if the PRDR feature has been negotiated, is
13122 run for each recipient after an SMTP DATA command has been processed and the
13123 message itself has been received, but before the acknowledgment is sent. See
13124 chapter 43 for further details.
13125
13126 +----------------------------------------------------+
13127 |acl_smtp_dkim|Use: main|Type: string*|Default: unset|
13128 +----------------------------------------------------+
13129
13130 This option defines the ACL that is run for each DKIM signature (by default, or
13131 as specified in the dkim_verify_signers option) of a received message. See
13132 section 57.3 for further details.
13133
13134 +----------------------------------------------------+
13135 |acl_smtp_etrn|Use: main|Type: string*|Default: unset|
13136 +----------------------------------------------------+
13137
13138 This option defines the ACL that is run when an SMTP ETRN command is received.
13139 See chapter 43 for further details.
13140
13141 +----------------------------------------------------+
13142 |acl_smtp_expn|Use: main|Type: string*|Default: unset|
13143 +----------------------------------------------------+
13144
13145 This option defines the ACL that is run when an SMTP EXPN command is received.
13146 See chapter 43 for further details.
13147
13148 +----------------------------------------------------+
13149 |acl_smtp_helo|Use: main|Type: string*|Default: unset|
13150 +----------------------------------------------------+
13151
13152 This option defines the ACL that is run when an SMTP EHLO or HELO command is
13153 received. See chapter 43 for further details.
13154
13155 +----------------------------------------------------+
13156 |acl_smtp_mail|Use: main|Type: string*|Default: unset|
13157 +----------------------------------------------------+
13158
13159 This option defines the ACL that is run when an SMTP MAIL command is received.
13160 See chapter 43 for further details.
13161
13162 +--------------------------------------------------------+
13163 |acl_smtp_mailauth|Use: main|Type: string*|Default: unset|
13164 +--------------------------------------------------------+
13165
13166 This option defines the ACL that is run when there is an AUTH parameter on a
13167 MAIL command. See chapter 43 for details of ACLs, and chapter 33 for details of
13168 authentication.
13169
13170 +----------------------------------------------------+
13171 |acl_smtp_mime|Use: main|Type: string*|Default: unset|
13172 +----------------------------------------------------+
13173
13174 This option is available when Exim is built with the content-scanning
13175 extension. It defines the ACL that is run for each MIME part in a message. See
13176 section 44.4 for details.
13177
13178 +-------------------------------------------------------+
13179 |acl_smtp_notquit|Use: main|Type: string*|Default: unset|
13180 +-------------------------------------------------------+
13181
13182 This option defines the ACL that is run when an SMTP session ends without a
13183 QUIT command being received. See chapter 43 for further details.
13184
13185 +-------------------------------------------------------+
13186 |acl_smtp_predata|Use: main|Type: string*|Default: unset|
13187 +-------------------------------------------------------+
13188
13189 This option defines the ACL that is run when an SMTP DATA command is received,
13190 before the message itself is received. See chapter 43 for further details.
13191
13192 +----------------------------------------------------+
13193 |acl_smtp_quit|Use: main|Type: string*|Default: unset|
13194 +----------------------------------------------------+
13195
13196 This option defines the ACL that is run when an SMTP QUIT command is received.
13197 See chapter 43 for further details.
13198
13199 +----------------------------------------------------+
13200 |acl_smtp_rcpt|Use: main|Type: string*|Default: unset|
13201 +----------------------------------------------------+
13202
13203 This option defines the ACL that is run when an SMTP RCPT command is received.
13204 See chapter 43 for further details.
13205
13206 +--------------------------------------------------------+
13207 |acl_smtp_starttls|Use: main|Type: string*|Default: unset|
13208 +--------------------------------------------------------+
13209
13210 This option defines the ACL that is run when an SMTP STARTTLS command is
13211 received. See chapter 43 for further details.
13212
13213 +----------------------------------------------------+
13214 |acl_smtp_vrfy|Use: main|Type: string*|Default: unset|
13215 +----------------------------------------------------+
13216
13217 This option defines the ACL that is run when an SMTP VRFY command is received.
13218 See chapter 43 for further details.
13219
13220 +----------------------------------------------------------+
13221 |add_environment|Use: main|Type: string list|Default: empty|
13222 +----------------------------------------------------------+
13223
13224 This option allows to set individual environment variables that the currently
13225 linked libraries and programs in child processes use. See 29.4 for the
13226 environment of pipe transports.
13227
13228 +--------------------------------------------------------+
13229 |admin_groups|Use: main|Type: string list*|Default: unset|
13230 +--------------------------------------------------------+
13231
13232 This option is expanded just once, at the start of Exim's processing. If the
13233 current group or any of the supplementary groups of an Exim caller is in this
13234 colon-separated list, the caller has admin privileges. If all your system
13235 programmers are in a specific group, for example, you can give them all Exim
13236 admin privileges by putting that group in admin_groups. However, this does not
13237 permit them to read Exim's spool files (whose group owner is the Exim gid). To
13238 permit this, you have to add individuals to the Exim group.
13239
13240 +------------------------------------------------------------+
13241 |allow_domain_literals|Use: main|Type: boolean|Default: false|
13242 +------------------------------------------------------------+
13243
13244 If this option is set, the RFC 2822 domain literal format is permitted in email
13245 addresses. The option is not set by default, because the domain literal format
13246 is not normally required these days, and few people know about it. It has,
13247 however, been exploited by mail abusers.
13248
13249 Unfortunately, it seems that some DNS black list maintainers are using this
13250 format to report black listing to postmasters. If you want to accept messages
13251 addressed to your hosts by IP address, you need to set allow_domain_literals
13252 true, and also to add "@[]" to the list of local domains (defined in the named
13253 domain list local_domains in the default configuration). This "magic string"
13254 matches the domain literal form of all the local host's IP addresses.
13255
13256 +-----------------------------------------------------+
13257 |allow_mx_to_ip|Use: main|Type: boolean|Default: false|
13258 +-----------------------------------------------------+
13259
13260 It appears that more and more DNS zone administrators are breaking the rules
13261 and putting domain names that look like IP addresses on the right hand side of
13262 MX records. Exim follows the rules and rejects this, giving an error message
13263 that explains the misconfiguration. However, some other MTAs support this
13264 practice, so to avoid "Why can't Exim do this?" complaints, allow_mx_to_ip
13265 exists, in order to enable this heinous activity. It is not recommended, except
13266 when you have no other choice.
13267
13268 +---------------------------------------------------------+
13269 |allow_utf8_domains|Use: main|Type: boolean|Default: false|
13270 +---------------------------------------------------------+
13271
13272 Lots of discussion is going on about internationalized domain names. One camp
13273 is strongly in favour of just using UTF-8 characters, and it seems that at
13274 least two other MTAs permit this. This option allows Exim users to experiment
13275 if they wish.
13276
13277 If it is set true, Exim's domain parsing function allows valid UTF-8
13278 multicharacters to appear in domain name components, in addition to letters,
13279 digits, and hyphens. However, just setting this option is not enough; if you
13280 want to look up these domain names in the DNS, you must also adjust the value
13281 of dns_check_names_pattern to match the extended form. A suitable setting is:
13282
13283 dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\
13284 (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$
13285
13286 Alternatively, you can just disable this feature by setting
13287
13288 dns_check_names_pattern =
13289
13290 That is, set the option to an empty string so that no check is done.
13291
13292 +----------------------------------------------------------+
13293 |auth_advertise_hosts|Use: main|Type: host list*|Default: *|
13294 +----------------------------------------------------------+
13295
13296 If any server authentication mechanisms are configured, Exim advertises them in
13297 response to an EHLO command only if the calling host matches this list.
13298 Otherwise, Exim does not advertise AUTH. Exim does not accept AUTH commands
13299 from clients to which it has not advertised the availability of AUTH. The
13300 advertising of individual authentication mechanisms can be controlled by the
13301 use of the server_advertise_condition generic authenticator option on the
13302 individual authenticators. See chapter 33 for further details.
13303
13304 Certain mail clients (for example, Netscape) require the user to provide a name
13305 and password for authentication if AUTH is advertised, even though it may not
13306 be needed (the host may accept messages from hosts on its local LAN without
13307 authentication, for example). The auth_advertise_hosts option can be used to
13308 make these clients more friendly by excluding them from the set of hosts to
13309 which Exim advertises AUTH.
13310
13311 If you want to advertise the availability of AUTH only when the connection is
13312 encrypted using TLS, you can make use of the fact that the value of this option
13313 is expanded, with a setting like this:
13314
13315 auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}}
13316
13317 If $tls_in_cipher is empty, the session is not encrypted, and the result of the
13318 expansion is empty, thus matching no hosts. Otherwise, the result of the
13319 expansion is *, which matches all hosts.
13320
13321 +------------------------------------------+
13322 |auto_thaw|Use: main|Type: time|Default: 0s|
13323 +------------------------------------------+
13324
13325 If this option is set to a time greater than zero, a queue runner will try a
13326 new delivery attempt on any frozen message, other than a bounce message, if
13327 this much time has passed since it was frozen. This may result in the message
13328 being re-frozen if nothing has changed since the last attempt. It is a way of
13329 saying "keep on trying, even though there are big problems".
13330
13331 Note: This is an old option, which predates timeout_frozen_after and
13332 ignore_bounce_errors_after. It is retained for compatibility, but it is not
13333 thought to be very useful any more, and its use should probably be avoided.
13334
13335 +----------------------------------------------------+
13336 |av_scanner|Use: main|Type: string|Default: see below|
13337 +----------------------------------------------------+
13338
13339 This option is available if Exim is built with the content-scanning extension.
13340 It specifies which anti-virus scanner to use. The default value is:
13341
13342 sophie:/var/run/sophie
13343
13344 If the value of av_scanner starts with a dollar character, it is expanded
13345 before use. See section 44.1 for further details.
13346
13347 +------------------------------------------------+
13348 |bi_command|Use: main|Type: string|Default: unset|
13349 +------------------------------------------------+
13350
13351 This option supplies the name of a command that is run when Exim is called with
13352 the -bi option (see chapter 5). The string value is just the command name, it
13353 is not a complete command line. If an argument is required, it must come from
13354 the -oA command line option.
13355
13356 +---------------------------------------------------------+
13357 |bounce_message_file|Use: main|Type: string|Default: unset|
13358 +---------------------------------------------------------+
13359
13360 This option defines a template file containing paragraphs of text to be used
13361 for constructing bounce messages. Details of the file's contents are given in
13362 chapter 49. See also warn_message_file.
13363
13364 +---------------------------------------------------------+
13365 |bounce_message_text|Use: main|Type: string|Default: unset|
13366 +---------------------------------------------------------+
13367
13368 When this option is set, its contents are included in the default bounce
13369 message immediately after "This message was created automatically by mail
13370 delivery software." It is not used if bounce_message_file is set.
13371
13372 +--------------------------------------------------------+
13373 |bounce_return_body|Use: main|Type: boolean|Default: true|
13374 +--------------------------------------------------------+
13375
13376 This option controls whether the body of an incoming message is included in a
13377 bounce message when bounce_return_message is true. The default setting causes
13378 the entire message, both header and body, to be returned (subject to the value
13379 of bounce_return_size_limit). If this option is false, only the message header
13380 is included. In the case of a non-SMTP message containing an error that is
13381 detected during reception, only those header lines preceding the point at which
13382 the error was detected are returned.
13383
13384 +-----------------------------------------------------------------+
13385 |bounce_return_linesize_limit|Use: main|Type: integer|Default: 998|
13386 +-----------------------------------------------------------------+
13387
13388 This option sets a limit in bytes on the line length of messages that are
13389 returned to senders due to delivery problems, when bounce_return_message is
13390 true. The default value corresponds to RFC limits. If the message being
13391 returned has lines longer than this value it is treated as if the
13392 bounce_return_size_limit (below) restriction was exceeded.
13393
13394 The option also applies to bounces returned when an error is detected during
13395 reception of a message. In this case lines from the original are truncated.
13396
13397 The option does not apply to messages generated by an autoreply transport.
13398
13399 +-----------------------------------------------------------+
13400 |bounce_return_message|Use: main|Type: boolean|Default: true|
13401 +-----------------------------------------------------------+
13402
13403 If this option is set false, none of the original message is included in bounce
13404 messages generated by Exim. See also bounce_return_size_limit and
13405 bounce_return_body.
13406
13407 +--------------------------------------------------------------+
13408 |bounce_return_size_limit|Use: main|Type: integer|Default: 100K|
13409 +--------------------------------------------------------------+
13410
13411 This option sets a limit in bytes on the size of messages that are returned to
13412 senders as part of bounce messages when bounce_return_message is true. The
13413 limit should be less than the value of the global message_size_limit and of any
13414 message_size_limit settings on transports, to allow for the bounce text that
13415 Exim generates. If this option is set to zero there is no limit.
13416
13417 When the body of any message that is to be included in a bounce message is
13418 greater than the limit, it is truncated, and a comment pointing this out is
13419 added at the top. The actual cutoff may be greater than the value given, owing
13420 to the use of buffering for transferring the message in chunks (typically 8K in
13421 size). The idea is to save bandwidth on those undeliverable 15-megabyte
13422 messages.
13423
13424 +------------------------------------------------------------------+
13425 |bounce_sender_authentication|Use: main|Type: string|Default: unset|
13426 +------------------------------------------------------------------+
13427
13428 This option provides an authenticated sender address that is sent with any
13429 bounce messages generated by Exim that are sent over an authenticated SMTP
13430 connection. A typical setting might be:
13431
13432 bounce_sender_authentication = mailer-daemon@my.domain.example
13433
13434 which would cause bounce messages to be sent using the SMTP command:
13435
13436 MAIL FROM:<> AUTH=mailer-daemon@my.domain.example
13437
13438 The value of bounce_sender_authentication must always be a complete email
13439 address.
13440
13441 +---------------------------------------------------------------+
13442 |callout_domain_negative_expire|Use: main|Type: time|Default: 3h|
13443 +---------------------------------------------------------------+
13444
13445 This option specifies the expiry time for negative callout cache data for a
13446 domain. See section 43.45 for details of callout verification, and section
13447 43.47 for details of the caching.
13448
13449 +---------------------------------------------------------------+
13450 |callout_domain_positive_expire|Use: main|Type: time|Default: 7d|
13451 +---------------------------------------------------------------+
13452
13453 This option specifies the expiry time for positive callout cache data for a
13454 domain. See section 43.45 for details of callout verification, and section
13455 43.47 for details of the caching.
13456
13457 +--------------------------------------------------------+
13458 |callout_negative_expire|Use: main|Type: time|Default: 2h|
13459 +--------------------------------------------------------+
13460
13461 This option specifies the expiry time for negative callout cache data for an
13462 address. See section 43.45 for details of callout verification, and section
13463 43.47 for details of the caching.
13464
13465 +---------------------------------------------------------+
13466 |callout_positive_expire|Use: main|Type: time|Default: 24h|
13467 +---------------------------------------------------------+
13468
13469 This option specifies the expiry time for positive callout cache data for an
13470 address. See section 43.45 for details of callout verification, and section
13471 43.47 for details of the caching.
13472
13473 +--------------------------------------------------------------------+
13474 |callout_random_local_part|Use: main|Type: string*|Default: see below|
13475 +--------------------------------------------------------------------+
13476
13477 This option defines the "random" local part that can be used as part of callout
13478 verification. The default value is
13479
13480 $primary_hostname-$tod_epoch-testing
13481
13482 See section 43.46 for details of how this value is used.
13483
13484 +-----------------------------------------------------+
13485 |check_log_inodes|Use: main|Type: integer|Default: 100|
13486 +-----------------------------------------------------+
13487
13488 See check_spool_space below.
13489
13490 +----------------------------------------------------+
13491 |check_log_space|Use: main|Type: integer|Default: 10M|
13492 +----------------------------------------------------+
13493
13494 See check_spool_space below.
13495
13496 +----------------------------------------------------------+
13497 |check_rfc2047_length|Use: main|Type: boolean|Default: true|
13498 +----------------------------------------------------------+
13499
13500 RFC 2047 defines a way of encoding non-ASCII characters in headers using a
13501 system of "encoded words". The RFC specifies a maximum length for an encoded
13502 word; strings to be encoded that exceed this length are supposed to use
13503 multiple encoded words. By default, Exim does not recognize encoded words that
13504 exceed the maximum length. However, it seems that some software, in violation
13505 of the RFC, generates overlong encoded words. If check_rfc2047_length is set
13506 false, Exim recognizes encoded words of any length.
13507
13508 +-------------------------------------------------------+
13509 |check_spool_inodes|Use: main|Type: integer|Default: 100|
13510 +-------------------------------------------------------+
13511
13512 See check_spool_space below.
13513
13514 +------------------------------------------------------+
13515 |check_spool_space|Use: main|Type: integer|Default: 10M|
13516 +------------------------------------------------------+
13517
13518 The four check_... options allow for checking of disk resources before a
13519 message is accepted.
13520
13521 When any of these options are nonzero, they apply to all incoming messages. If
13522 you want to apply different checks to different kinds of message, you can do so
13523 by testing the variables $log_inodes, $log_space, $spool_inodes, and
13524 $spool_space in an ACL with appropriate additional conditions.
13525
13526 check_spool_space and check_spool_inodes check the spool partition if either
13527 value is greater than zero, for example:
13528
13529 check_spool_space = 100M
13530 check_spool_inodes = 100
13531
13532 The spool partition is the one that contains the directory defined by
13533 SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit.
13534
13535 check_log_space and check_log_inodes check the partition in which log files are
13536 written if either is greater than zero. These should be set only if
13537 log_file_path and spool_directory refer to different partitions.
13538
13539 If there is less space or fewer inodes than requested, Exim refuses to accept
13540 incoming mail. In the case of SMTP input this is done by giving a 452 temporary
13541 error response to the MAIL command. If ESMTP is in use and there was a SIZE
13542 parameter on the MAIL command, its value is added to the check_spool_space
13543 value, and the check is performed even if check_spool_space is zero, unless
13544 no_smtp_check_spool_space is set.
13545
13546 The values for check_spool_space and check_log_space are held as a number of
13547 kilobytes (though specified in bytes). If a non-multiple of 1024 is specified,
13548 it is rounded up.
13549
13550 For non-SMTP input and for batched SMTP input, the test is done at start-up; on
13551 failure a message is written to stderr and Exim exits with a non-zero code, as
13552 it obviously cannot send an error message of any kind.
13553
13554 There is a slight performance penalty for these checks. Versions of Exim
13555 preceding 4.88 had these disabled by default; high-rate installations confident
13556 they will never run out of resources may wish to deliberately disable them.
13557
13558 +--------------------------------------------------------------+
13559 |chunking_advertise_hosts|Use: main|Type: host list*|Default: *|
13560 +--------------------------------------------------------------+
13561
13562 The CHUNKING extension (RFC3030) will be advertised in the EHLO message to
13563 these hosts. Hosts may use the BDAT command as an alternate to DATA.
13564
13565 +-------------------------------------------------------------------------+
13566 |commandline_checks_require_admin|Use: main|Type: boolean|Default: "false"|
13567 +-------------------------------------------------------------------------+
13568
13569 This option restricts various basic checking features to require an
13570 administrative user. This affects most of the -b* options, such as -be.
13571
13572 +----------------------------------------------------+
13573 |debug_store|Use: main|Type: boolean|Default: "false"|
13574 +----------------------------------------------------+
13575
13576 This option, when true, enables extra checking in Exim's internal memory
13577 management. For use when a memory corruption issue is being investigated, it
13578 should normally be left as default.
13579
13580 +--------------------------------------------------------+
13581 |daemon_smtp_ports|Use: main|Type: string|Default: "smtp"|
13582 +--------------------------------------------------------+
13583
13584 This option specifies one or more default SMTP ports on which the Exim daemon
13585 listens. See chapter 13 for details of how it is used. For backward
13586 compatibility, daemon_smtp_port (singular) is a synonym.
13587
13588 +---------------------------------------------------------+
13589 |daemon_startup_retries|Use: main|Type: integer|Default: 9|
13590 +---------------------------------------------------------+
13591
13592 This option, along with daemon_startup_sleep, controls the retrying done by the
13593 daemon at startup when it cannot immediately bind a listening socket (typically
13594 because the socket is already in use): daemon_startup_retries defines the
13595 number of retries after the first failure, and daemon_startup_sleep defines the
13596 length of time to wait between retries.
13597
13598 +------------------------------------------------------+
13599 |daemon_startup_sleep|Use: main|Type: time|Default: 30s|
13600 +------------------------------------------------------+
13601
13602 See daemon_startup_retries.
13603
13604 +----------------------------------------------------+
13605 |delay_warning|Use: main|Type: time list|Default: 24h|
13606 +----------------------------------------------------+
13607
13608 When a message is delayed, Exim sends a warning message to the sender at
13609 intervals specified by this option. The data is a colon-separated list of times
13610 after which to send warning messages. If the value of the option is an empty
13611 string or a zero time, no warnings are sent. Up to 10 times may be given. If a
13612 message has been in the queue for longer than the last time, the last interval
13613 between the times is used to compute subsequent warning times. For example,
13614 with
13615
13616 delay_warning = 4h:8h:24h
13617
13618 the first message is sent after 4 hours, the second after 8 hours, and the
13619 third one after 24 hours. After that, messages are sent every 16 hours, because
13620 that is the interval between the last two times on the list. If you set just
13621 one time, it specifies the repeat interval. For example, with:
13622
13623 delay_warning = 6h
13624
13625 messages are repeated every six hours. To stop warnings after a given time, set
13626 a very large time at the end of the list. For example:
13627
13628 delay_warning = 2h:12h:99d
13629
13630 Note that the option is only evaluated at the time a delivery attempt fails,
13631 which depends on retry and queue-runner configuration. Typically retries will
13632 be configured more frequently than warning messages.
13633
13634 +------------------------------------------------------------------+
13635 |delay_warning_condition|Use: main|Type: string*|Default: see below|
13636 +------------------------------------------------------------------+
13637
13638 The string is expanded at the time a warning message might be sent. If all the
13639 deferred addresses have the same domain, it is set in $domain during the
13640 expansion. Otherwise $domain is empty. If the result of the expansion is a
13641 forced failure, an empty string, or a string matching any of "0", "no" or
13642 "false" (the comparison being done caselessly) then the warning message is not
13643 sent. The default is:
13644
13645 delay_warning_condition = ${if or {\
13646 { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\
13647 { match{$h_precedence:}{(?i)bulk|list|junk} }\
13648 { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\
13649 } {no}{yes}}
13650
13651 This suppresses the sending of warnings for messages that contain List-ID:,
13652 List-Post:, or List-Subscribe: headers, or have "bulk", "list" or "junk" in a
13653 Precedence: header, or have "auto-generated" or "auto-replied" in an
13654 Auto-Submitted: header.
13655
13656 +-------------------------------------------------------------+
13657 |deliver_drop_privilege|Use: main|Type: boolean|Default: false|
13658 +-------------------------------------------------------------+
13659
13660 If this option is set true, Exim drops its root privilege at the start of a
13661 delivery process, and runs as the Exim user throughout. This severely restricts
13662 the kinds of local delivery that are possible, but is viable in certain types
13663 of configuration. There is a discussion about the use of root privilege in
13664 chapter 55.
13665
13666 +-----------------------------------------------------------------+
13667 |deliver_queue_load_max|Use: main|Type: fixed-point|Default: unset|
13668 +-----------------------------------------------------------------+
13669
13670 When this option is set, a queue run is abandoned if the system load average
13671 becomes greater than the value of the option. The option has no effect on
13672 ancient operating systems on which Exim cannot determine the load average. See
13673 also queue_only_load and smtp_load_reserve.
13674
13675 +----------------------------------------------------------+
13676 |delivery_date_remove|Use: main|Type: boolean|Default: true|
13677 +----------------------------------------------------------+
13678
13679 Exim's transports have an option for adding a Delivery-date: header to a
13680 message when it is delivered, in exactly the same way as Return-path: is
13681 handled. Delivery-date: records the actual time of delivery. Such headers
13682 should not be present in incoming messages, and this option causes them to be
13683 removed at the time the message is received, to avoid any problems that might
13684 occur when a delivered message is subsequently sent on to some other recipient.
13685
13686 +----------------------------------------------------+
13687 |disable_fsync|Use: main|Type: boolean|Default: false|
13688 +----------------------------------------------------+
13689
13690 This option is available only if Exim was built with the compile-time option
13691 ENABLE_DISABLE_FSYNC. When this is not set, a reference to disable_fsync in a
13692 runtime configuration generates an "unknown option" error. You should not build
13693 Exim with ENABLE_DISABLE_FSYNC or set disable_fsync unless you really, really,
13694 really understand what you are doing. No pre-compiled distributions of Exim
13695 should ever make this option available.
13696
13697 When disable_fsync is set true, Exim no longer calls fsync() to force updated
13698 files' data to be written to disc before continuing. Unexpected events such as
13699 crashes and power outages may cause data to be lost or scrambled. Here be
13700 Dragons. Beware.
13701
13702 +---------------------------------------------------+
13703 |disable_ipv6|Use: main|Type: boolean|Default: false|
13704 +---------------------------------------------------+
13705
13706 If this option is set true, even if the Exim binary has IPv6 support, no IPv6
13707 activities take place. AAAA records are never looked up, and any IPv6 addresses
13708 that are listed in local_interfaces, data for the manualroute router, etc. are
13709 ignored. If IP literals are enabled, the ipliteral router declines to handle
13710 IPv6 literal addresses.
13711
13712 +-----------------------------------------------------------------------+
13713 |dkim_verify_signers|Use: main|Type: domain list*|Default: $dkim_signers|
13714 +-----------------------------------------------------------------------+
13715
13716 This option gives a list of DKIM domains for which the DKIM ACL is run. It is
13717 expanded after the message is received; by default it runs the ACL once for
13718 each signature in the message. See section 57.3.
13719
13720 +--------------------------------------------------------------------+
13721 |dns_again_means_nonexist|Use: main|Type: domain list*|Default: unset|
13722 +--------------------------------------------------------------------+
13723
13724 DNS lookups give a "try again" response for the DNS errors "non-authoritative
13725 host not found" and "SERVERFAIL". This can cause Exim to keep trying to deliver
13726 a message, or to give repeated temporary errors to incoming mail. Sometimes the
13727 effect is caused by a badly set up name server and may persist for a long time.
13728 If a domain which exhibits this problem matches anything in
13729 dns_again_means_nonexist, it is treated as if it did not exist. This option
13730 should be used with care. You can make it apply to reverse lookups by a setting
13731 such as this:
13732
13733 dns_again_means_nonexist = *.in-addr.arpa
13734
13735 This option applies to all DNS lookups that Exim does. It also applies when the
13736 gethostbyname() or getipnodebyname() functions give temporary errors, since
13737 these are most likely to be caused by DNS lookup problems. The dnslookup router
13738 has some options of its own for controlling what happens when lookups for MX or
13739 SRV records give temporary errors. These more specific options are applied
13740 after this global option.
13741
13742 +-----------------------------------------------------------------+
13743 |dns_check_names_pattern|Use: main|Type: string|Default: see below|
13744 +-----------------------------------------------------------------+
13745
13746 When this option is set to a non-empty string, it causes Exim to check domain
13747 names for characters that are not allowed in host names before handing them to
13748 the DNS resolver, because some resolvers give temporary errors for names that
13749 contain unusual characters. If a domain name contains any unwanted characters,
13750 a "not found" result is forced, and the resolver is not called. The check is
13751 done by matching the domain name against a regular expression, which is the
13752 value of this option. The default pattern is
13753
13754 dns_check_names_pattern = \
13755 (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$
13756
13757 which permits only letters, digits, slashes, and hyphens in components, but
13758 they must start and end with a letter or digit. Slashes are not, in fact,
13759 permitted in host names, but they are found in certain NS records (which can be
13760 accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you
13761 must modify this pattern, or set the option to an empty string.
13762
13763 +-------------------------------------------------------+
13764 |dns_csa_search_limit|Use: main|Type: integer|Default: 5|
13765 +-------------------------------------------------------+
13766
13767 This option controls the depth of parental searching for CSA SRV records in the
13768 DNS, as described in more detail in section 43.50.
13769
13770 +---------------------------------------------------------+
13771 |dns_csa_use_reverse|Use: main|Type: boolean|Default: true|
13772 +---------------------------------------------------------+
13773
13774 This option controls whether or not an IP address, given as a CSA domain, is
13775 reversed and looked up in the reverse DNS, as described in more detail in
13776 section 43.50.
13777
13778 +--------------------------------------------------+
13779 |dns_cname_loops|Use: main|Type: integer|Default: 1|
13780 +--------------------------------------------------+
13781
13782 This option controls the following of CNAME chains, needed if the resolver does
13783 not do it internally. As of 2018 most should, and the default can be left. If
13784 you have an ancient one, a value of 10 is likely needed.
13785
13786 The default value of one CNAME-follow is needed thanks to the observed return
13787 for an MX request, given no MX presence but a CNAME to an A, of the CNAME.
13788
13789 +-------------------------------------------------+
13790 |dns_dnssec_ok|Use: main|Type: integer|Default: -1|
13791 +-------------------------------------------------+
13792
13793 If this option is set to a non-negative number then Exim will initialise the
13794 DNS resolver library to either use or not use DNSSEC, overriding the system
13795 default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on.
13796
13797 If the resolver library does not support DNSSEC then this option has no effect.
13798
13799 +-----------------------------------------------------------+
13800 |dns_ipv4_lookup|Use: main|Type: domain list*|Default: unset|
13801 +-----------------------------------------------------------+
13802
13803 When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks
13804 for IPv6 address records (AAAA records) as well as IPv4 address records (A
13805 records) when trying to find IP addresses for hosts, unless the host's domain
13806 matches this list.
13807
13808 This is a fudge to help with name servers that give big delays or otherwise do
13809 not work for the AAAA record type. In due course, when the world's name servers
13810 have all been upgraded, there should be no need for this option.
13811
13812 +--------------------------------------------+
13813 |dns_retrans|Use: main|Type: time|Default: 0s|
13814 +--------------------------------------------+
13815
13816 The options dns_retrans and dns_retry can be used to set the retransmission and
13817 retry parameters for DNS lookups. Values of zero (the defaults) leave the
13818 system default settings unchanged. The first value is the time between retries,
13819 and the second is the number of retries. It isn't totally clear exactly how
13820 these settings affect the total time a DNS lookup may take. I haven't found any
13821 documentation about timeouts on DNS lookups; these parameter values are
13822 available in the external resolver interface structure, but nowhere does it
13823 seem to describe how they are used or what you might want to set in them. See
13824 also the slow_lookup_log option.
13825
13826 +--------------------------------------------+
13827 |dns_retry|Use: main|Type: integer|Default: 0|
13828 +--------------------------------------------+
13829
13830 See dns_retrans above.
13831
13832 +--------------------------------------------------------+
13833 |dns_trust_aa|Use: main|Type: domain list*|Default: unset|
13834 +--------------------------------------------------------+
13835
13836 If this option is set then lookup results marked with the AA bit (Authoritative
13837 Answer) are trusted the same way as if they were DNSSEC-verified. The authority
13838 section's name of the answer must match with this expanded domain list.
13839
13840 Use this option only if you talk directly to a resolver that is authoritative
13841 for some zones and does not set the AD (Authentic Data) bit in the answer. Some
13842 DNS servers may have an configuration option to mark the answers from their own
13843 zones as verified (they set the AD bit). Others do not have this option. It is
13844 considered as poor practice using a resolver that is an authoritative server
13845 for some zones.
13846
13847 Use this option only if you really have to (e.g. if you want to use DANE for
13848 remote delivery to a server that is listed in the DNS zones that your resolver
13849 is authoritative for).
13850
13851 If the DNS answer packet has the AA bit set and contains resource record in the
13852 answer section, the name of the first NS record appearing in the authority
13853 section is compared against the list. If the answer packet is authoritative but
13854 the answer section is empty, the name of the first SOA record in the
13855 authoritative section is used instead.
13856
13857 +-------------------------------------------------+
13858 |dns_use_edns0|Use: main|Type: integer|Default: -1|
13859 +-------------------------------------------------+
13860
13861 If this option is set to a non-negative number then Exim will initialise the
13862 DNS resolver library to either use or not use EDNS0 extensions, overriding the
13863 system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0 on.
13864
13865 If the resolver library does not support EDNS0 then this option has no effect.
13866
13867 OpenBSD's asr resolver routines are known to ignore the EDNS0 option; this
13868 means that DNSSEC will not work with Exim on that platform either, unless Exim
13869 is linked against an alternative DNS client library.
13870
13871 +----------------------------------------------+
13872 |drop_cr|Use: main|Type: boolean|Default: false|
13873 +----------------------------------------------+
13874
13875 This is an obsolete option that is now a no-op. It used to affect the way Exim
13876 handled CR and LF characters in incoming messages. What happens now is
13877 described in section 47.2.
13878
13879 +-------------------------------------------------------------+
13880 |dsn_advertise_hosts|Use: main|Type: host list*|Default: unset|
13881 +-------------------------------------------------------------+
13882
13883 DSN extensions (RFC3461) will be advertised in the EHLO message to, and
13884 accepted from, these hosts. Hosts may use the NOTIFY and ENVID options on RCPT
13885 TO commands, and RET and ORCPT options on MAIL FROM commands. A NOTIFY=SUCCESS
13886 option requests success-DSN messages. A NOTIFY= option with no argument
13887 requests that no delay or failure DSNs are sent.
13888
13889 +---------------------------------------------------+
13890 |dsn_from|Use: main|Type: string*|Default: see below|
13891 +---------------------------------------------------+
13892
13893 This option can be used to vary the contents of From: header lines in bounces
13894 and other automatically generated messages ("Delivery Status Notifications" -
13895 hence the name of the option). The default setting is:
13896
13897 dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain>
13898
13899 The value is expanded every time it is needed. If the expansion fails, a panic
13900 is logged, and the default value is used.
13901
13902 +--------------------------------------------------------+
13903 |envelope_to_remove|Use: main|Type: boolean|Default: true|
13904 +--------------------------------------------------------+
13905
13906 Exim's transports have an option for adding an Envelope-to: header to a message
13907 when it is delivered, in exactly the same way as Return-path: is handled.
13908 Envelope-to: records the original recipient address from the message's envelope
13909 that caused the delivery to happen. Such headers should not be present in
13910 incoming messages, and this option causes them to be removed at the time the
13911 message is received, to avoid any problems that might occur when a delivered
13912 message is subsequently sent on to some other recipient.
13913
13914 +-------------------------------------------------------+
13915 |errors_copy|Use: main|Type: string list*|Default: unset|
13916 +-------------------------------------------------------+
13917
13918 Setting this option causes Exim to send bcc copies of bounce messages that it
13919 generates to other addresses. Note: This does not apply to bounce messages
13920 coming from elsewhere. The value of the option is a colon-separated list of
13921 items. Each item consists of a pattern, terminated by white space, followed by
13922 a comma-separated list of email addresses. If a pattern contains spaces, it
13923 must be enclosed in double quotes.
13924
13925 Each pattern is processed in the same way as a single item in an address list
13926 (see section 10.19). When a pattern matches the recipient of the bounce
13927 message, the message is copied to the addresses on the list. The items are
13928 scanned in order, and once a matching one is found, no further items are
13929 examined. For example:
13930
13931 errors_copy = spqr@mydomain postmaster@mydomain.example :\
13932 rqps@mydomain hostmaster@mydomain.example,\
13933 postmaster@mydomain.example
13934
13935 The address list is expanded before use. The expansion variables $local_part
13936 and $domain are set from the original recipient of the error message, and if
13937 there was any wildcard matching in the pattern, the expansion variables $0, $1,
13938 etc. are set in the normal way.
13939
13940 +-----------------------------------------------------+
13941 |errors_reply_to|Use: main|Type: string|Default: unset|
13942 +-----------------------------------------------------+
13943
13944 By default, Exim's bounce and delivery warning messages contain the header line
13945
13946 From: Mail Delivery System <Mailer-Daemon@qualify-domain>
13947
13948 where qualify-domain is the value of the qualify_domain option. A warning
13949 message that is generated by the quota_warn_message option in an appendfile
13950 transport may contain its own From: header line that overrides the default.
13951
13952 Experience shows that people reply to bounce messages. If the errors_reply_to
13953 option is set, a Reply-To: header is added to bounce and warning messages. For
13954 example:
13955
13956 errors_reply_to = postmaster@my.domain.example
13957
13958 The value of the option is not expanded. It must specify a valid RFC 2822
13959 address. However, if a warning message that is generated by the
13960 quota_warn_message option in an appendfile transport contain its own Reply-To:
13961 header line, the value of the errors_reply_to option is not used.
13962
13963 +---------------------------------------------------+
13964 |event_action|Use: main|Type: string*|Default: unset|
13965 +---------------------------------------------------+
13966
13967 This option declares a string to be expanded for Exim's events mechanism. For
13968 details see chapter 60.
13969
13970 +------------------------------------------------------------------+
13971 |exim_group|Use: main|Type: string|Default: compile-time configured|
13972 +------------------------------------------------------------------+
13973
13974 This option changes the gid under which Exim runs when it gives up root
13975 privilege. The default value is compiled into the binary. The value of this
13976 option is used only when exim_user is also set. Unless it consists entirely of
13977 digits, the string is looked up using getgrnam(), and failure causes a
13978 configuration error. See chapter 55 for a discussion of security issues.
13979
13980 +---------------------------------------------------+
13981 |exim_path|Use: main|Type: string|Default: see below|
13982 +---------------------------------------------------+
13983
13984 This option specifies the path name of the Exim binary, which is used when Exim
13985 needs to re-exec itself. The default is set up to point to the file exim in the
13986 directory configured at compile time by the BIN_DIRECTORY setting. It is
13987 necessary to change exim_path if, exceptionally, Exim is run from some other
13988 place. Warning: Do not use a macro to define the value of this option, because
13989 you will break those Exim utilities that scan the configuration file to find
13990 where the binary is. (They then use the -bP option to extract option settings
13991 such as the value of spool_directory.)
13992
13993 +-----------------------------------------------------------------+
13994 |exim_user|Use: main|Type: string|Default: compile-time configured|
13995 +-----------------------------------------------------------------+
13996
13997 This option changes the uid under which Exim runs when it gives up root
13998 privilege. The default value is compiled into the binary. Ownership of the run
13999 time configuration file and the use of the -C and -D command line options is
14000 checked against the values in the binary, not what is set here.
14001
14002 Unless it consists entirely of digits, the string is looked up using getpwnam()
14003 , and failure causes a configuration error. If exim_group is not also supplied,
14004 the gid is taken from the result of getpwnam() if it is used. See chapter 55
14005 for a discussion of security issues.
14006
14007 +-----------------------------------------------------------------+
14008 |extra_local_interfaces|Use: main|Type: string list|Default: unset|
14009 +-----------------------------------------------------------------+
14010
14011 This option defines network interfaces that are to be considered local when
14012 routing, but which are not used for listening by the daemon. See section 13.8
14013 for details.
14014
14015 +------------------------------------------------------------------------+
14016 |extract_addresses_remove_arguments|Use: main|Type: boolean|Default: true|
14017 +------------------------------------------------------------------------+
14018
14019 According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses
14020 are present on the command line when the -t option is used to build an envelope
14021 from a message's To:, Cc: and Bcc: headers, the command line addresses are
14022 removed from the recipients list. This is also how Smail behaves. However,
14023 other Sendmail documentation (the O'Reilly book) states that command line
14024 addresses are added to those obtained from the header lines. When
14025 extract_addresses_remove_arguments is true (the default), Exim subtracts
14026 argument headers. If it is set false, Exim adds rather than removes argument
14027 addresses.
14028
14029 +---------------------------------------------------+
14030 |finduser_retries|Use: main|Type: integer|Default: 0|
14031 +---------------------------------------------------+
14032
14033 On systems running NIS or other schemes in which user and group information is
14034 distributed from a remote system, there can be times when getpwnam() and
14035 related functions fail, even when given valid data, because things time out.
14036 Unfortunately these failures cannot be distinguished from genuine "not found"
14037 errors. If finduser_retries is set greater than zero, Exim will try that many
14038 extra times to find a user or a group, waiting for one second between retries.
14039
14040 You should not set this option greater than zero if your user information is in
14041 a traditional /etc/passwd file, because it will cause Exim needlessly to search
14042 the file multiple times for non-existent users, and also cause delay.
14043
14044 +-----------------------------------------------------------------------+
14045 |freeze_tell|Use: main|Type: string list, comma separated|Default: unset|
14046 +-----------------------------------------------------------------------+
14047
14048 On encountering certain errors, or when configured to do so in a system filter,
14049 ACL, or special router, Exim freezes a message. This means that no further
14050 delivery attempts take place until an administrator thaws the message, or the
14051 auto_thaw, ignore_bounce_errors_after, or timeout_frozen_after feature cause it
14052 to be processed. If freeze_tell is set, Exim generates a warning message
14053 whenever it freezes something, unless the message it is freezing is a
14054 locally-generated bounce message. (Without this exception there is the
14055 possibility of looping.) The warning message is sent to the addresses supplied
14056 as the comma-separated value of this option. If several of the message's
14057 addresses cause freezing, only a single message is sent. If the freezing was
14058 automatic, the reason(s) for freezing can be found in the message log. If you
14059 configure freezing in a filter or ACL, you must arrange for any logging that
14060 you require.
14061
14062 +-------------------------------------------------+
14063 |gecos_name|Use: main|Type: string*|Default: unset|
14064 +-------------------------------------------------+
14065
14066 Some operating systems, notably HP-UX, use the "gecos" field in the system
14067 password file to hold other information in addition to users' real names. Exim
14068 looks up this field for use when it is creating Sender: or From: headers. If
14069 either gecos_pattern or gecos_name are unset, the contents of the field are
14070 used unchanged, except that, if an ampersand is encountered, it is replaced by
14071 the user's login name with the first character forced to upper case, since this
14072 is a convention that is observed on many systems.
14073
14074 When these options are set, gecos_pattern is treated as a regular expression
14075 that is to be applied to the field (again with & replaced by the login name),
14076 and if it matches, gecos_name is expanded and used as the user's name.
14077
14078 Numeric variables such as $1, $2, etc. can be used in the expansion to pick up
14079 sub-fields that were matched by the pattern. In HP-UX, where the user's name
14080 terminates at the first comma, the following can be used:
14081
14082 gecos_pattern = ([^,]*)
14083 gecos_name = $1
14084
14085 +---------------------------------------------------+
14086 |gecos_pattern|Use: main|Type: string|Default: unset|
14087 +---------------------------------------------------+
14088
14089 See gecos_name above.
14090
14091 +---------------------------------------------------------+
14092 |gnutls_compat_mode|Use: main|Type: boolean|Default: unset|
14093 +---------------------------------------------------------+
14094
14095 This option controls whether GnuTLS is used in compatibility mode in an Exim
14096 server. This reduces security slightly, but improves interworking with older
14097 implementations of TLS.
14098
14099 +---------------------------------------------------------------+
14100 |gnutls_allow_auto_pkcs11|Use: main|Type: boolean|Default: unset|
14101 +---------------------------------------------------------------+
14102
14103 This option will let GnuTLS (2.12.0 or later) autoload PKCS11 modules with the
14104 p11-kit configuration files in /etc/pkcs11/modules/.
14105
14106 See https://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for
14107 documentation.
14108
14109 +---------------------------------------------------------+
14110 |headers_charset|Use: main|Type: string|Default: see below|
14111 +---------------------------------------------------------+
14112
14113 This option sets a default character set for translating from encoded MIME
14114 "words" in header lines, when referenced by an $h_xxx expansion item. The
14115 default is the value of HEADERS_CHARSET in Local/Makefile. The ultimate default
14116 is ISO-8859-1. For more details see the description of header insertions in
14117 section 11.5.
14118
14119 +---------------------------------------------------------+
14120 |header_maxsize|Use: main|Type: integer|Default: see below|
14121 +---------------------------------------------------------+
14122
14123 This option controls the overall maximum size of a message's header section.
14124 The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for
14125 that is 1M. Messages with larger header sections are rejected.
14126
14127 +------------------------------------------------------+
14128 |header_line_maxsize|Use: main|Type: integer|Default: 0|
14129 +------------------------------------------------------+
14130
14131 This option limits the length of any individual header line in a message, after
14132 all the continuations have been joined together. Messages with individual
14133 header lines that are longer than the limit are rejected. The default value of
14134 zero means "no limit".
14135
14136 +----------------------------------------------------------------+
14137 |helo_accept_junk_hosts|Use: main|Type: host list*|Default: unset|
14138 +----------------------------------------------------------------+
14139
14140 Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and
14141 gives an error response for invalid data. Unfortunately, there are some SMTP
14142 clients that send syntactic junk. They can be accommodated by setting this
14143 option. Note that this is a syntax check only. See helo_verify_hosts if you
14144 want to do semantic checking. See also helo_allow_chars for a way of extending
14145 the permitted character set.
14146
14147 +------------------------------------------------------+
14148 |helo_allow_chars|Use: main|Type: string|Default: unset|
14149 +------------------------------------------------------+
14150
14151 This option can be set to a string of rogue characters that are permitted in
14152 all EHLO and HELO names in addition to the standard letters, digits, hyphens,
14153 and dots. If you really must allow underscores, you can set
14154
14155 helo_allow_chars = _
14156
14157 Note that the value is one string, not a list.
14158
14159 +-----------------------------------------------------------------+
14160 |helo_lookup_domains|Use: main|Type: domain list*|Default: "@:@[]"|
14161 +-----------------------------------------------------------------+
14162
14163 If the domain given by a client in a HELO or EHLO command matches this list, a
14164 reverse lookup is done in order to establish the host's true name. The default
14165 forces a lookup if the client host gives the server's name or any of its IP
14166 addresses (in brackets), something that broken clients have been seen to do.
14167
14168 +---------------------------------------------------------------+
14169 |helo_try_verify_hosts|Use: main|Type: host list*|Default: unset|
14170 +---------------------------------------------------------------+
14171
14172 By default, Exim just checks the syntax of HELO and EHLO commands (see
14173 helo_accept_junk_hosts and helo_allow_chars). However, some sites like to do
14174 more extensive checking of the data supplied by these commands. The ACL
14175 condition "verify = helo" is provided to make this possible. Formerly, it was
14176 necessary also to set this option (helo_try_verify_hosts) to force the check to
14177 occur. From release 4.53 onwards, this is no longer necessary. If the check has
14178 not been done before "verify = helo" is encountered, it is done at that time.
14179 Consequently, this option is obsolete. Its specification is retained here for
14180 backwards compatibility.
14181
14182 When an EHLO or HELO command is received, if the calling host matches
14183 helo_try_verify_hosts, Exim checks that the host name given in the HELO or EHLO
14184 command either:
14185
14186 * is an IP literal matching the calling address of the host, or
14187
14188 * matches the host name that Exim obtains by doing a reverse lookup of the
14189 calling host address, or
14190
14191 * when looked up in DNS yields the calling host address.
14192
14193 However, the EHLO or HELO command is not rejected if any of the checks fail.
14194 Processing continues, but the result of the check is remembered, and can be
14195 detected later in an ACL by the "verify = helo" condition.
14196
14197 If DNS was used for successful verification, the variable $helo_verify_dnssec
14198 records the DNSSEC status of the lookups.
14199
14200 +-----------------------------------------------------------+
14201 |helo_verify_hosts|Use: main|Type: host list*|Default: unset|
14202 +-----------------------------------------------------------+
14203
14204 Like helo_try_verify_hosts, this option is obsolete, and retained only for
14205 backwards compatibility. For hosts that match this option, Exim checks the host
14206 name given in the HELO or EHLO in the same way as for helo_try_verify_hosts. If
14207 the check fails, the HELO or EHLO command is rejected with a 550 error, and
14208 entries are written to the main and reject logs. If a MAIL command is received
14209 before EHLO or HELO, it is rejected with a 503 error.
14210
14211 +--------------------------------------------------------+
14212 |hold_domains|Use: main|Type: domain list*|Default: unset|
14213 +--------------------------------------------------------+
14214
14215 This option allows mail for particular domains to be held in the queue
14216 manually. The option is overridden if a message delivery is forced with the -M,
14217 -qf, -Rf or -Sf options, and also while testing or verifying addresses using
14218 -bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing
14219 or delivery for that address is done, and it is deferred every time the message
14220 is looked at.
14221
14222 This option is intended as a temporary operational measure for delaying the
14223 delivery of mail while some problem is being sorted out, or some new
14224 configuration tested. If you just want to delay the processing of some domains
14225 until a queue run occurs, you should use queue_domains or queue_smtp_domains,
14226 not hold_domains.
14227
14228 A setting of hold_domains does not override Exim's code for removing messages
14229 from the queue if they have been there longer than the longest retry time in
14230 any retry rule. If you want to hold messages for longer than the normal retry
14231 times, insert a dummy retry rule with a long retry time.
14232
14233 +-----------------------------------------------------+
14234 |host_lookup|Use: main|Type: host list*|Default: unset|
14235 +-----------------------------------------------------+
14236
14237 Exim does not look up the name of a calling host from its IP address unless it
14238 is required to compare against some host list, or the host matches
14239 helo_try_verify_hosts or helo_verify_hosts, or the host matches this option
14240 (which normally contains IP addresses rather than host names). The default
14241 configuration file contains
14242
14243 host_lookup = *
14244
14245 which causes a lookup to happen for all hosts. If the expense of these lookups
14246 is felt to be too great, the setting can be changed or removed.
14247
14248 After a successful reverse lookup, Exim does a forward lookup on the name it
14249 has obtained, to verify that it yields the IP address that it started with. If
14250 this check fails, Exim behaves as if the name lookup failed.
14251
14252 After any kind of failure, the host name (in $sender_host_name) remains unset,
14253 and $host_lookup_failed is set to the string "1". See also
14254 dns_again_means_nonexist, helo_lookup_domains, and "verify =
14255 reverse_host_lookup" in ACLs.
14256
14257 +---------------------------------------------------------------------+
14258 |host_lookup_order|Use: main|Type: string list|Default: "bydns:byaddr"|
14259 +---------------------------------------------------------------------+
14260
14261 This option specifies the order of different lookup methods when Exim is trying
14262 to find a host name from an IP address. The default is to do a DNS lookup
14263 first, and then to try a local lookup (using gethostbyaddr() or equivalent) if
14264 that fails. You can change the order of these lookups, or omit one entirely, if
14265 you want.
14266
14267 Warning: The "byaddr" method does not always yield aliases when there are
14268 multiple PTR records in the DNS and the IP address is not listed in /etc/hosts.
14269 Different operating systems give different results in this case. That is why
14270 the default tries a DNS lookup first.
14271
14272 +----------------------------------------------------------------+
14273 |host_reject_connection|Use: main|Type: host list*|Default: unset|
14274 +----------------------------------------------------------------+
14275
14276 If this option is set, incoming SMTP calls from the hosts listed are rejected
14277 as soon as the connection is made. This option is obsolete, and retained only
14278 for backward compatibility, because nowadays the ACL specified by
14279 acl_smtp_connect can also reject incoming connections immediately.
14280
14281 The ability to give an immediate rejection (either by this option or using an
14282 ACL) is provided for use in unusual cases. Many hosts will just try again,
14283 sometimes without much delay. Normally, it is better to use an ACL to reject
14284 incoming messages at a later stage, such as after RCPT commands. See chapter 43
14285 .
14286
14287 +----------------------------------------------------------------+
14288 |hosts_connection_nolog|Use: main|Type: host list*|Default: unset|
14289 +----------------------------------------------------------------+
14290
14291 This option defines a list of hosts for which connection logging does not
14292 happen, even though the smtp_connection log selector is set. For example, you
14293 might want not to log SMTP connections from local processes, or from 127.0.0.1,
14294 or from your local LAN. This option is consulted in the main loop of the
14295 daemon; you should therefore strive to restrict its value to a short inline
14296 list of IP addresses and networks. To disable logging SMTP connections from
14297 local processes, you must create a host list with an empty item. For example:
14298
14299 hosts_connection_nolog = :
14300
14301 If the smtp_connection log selector is not set, this option has no effect.
14302
14303 +-----------------------------------------------------+
14304 |hosts_proxy|Use: main|Type: host list*|Default: unset|
14305 +-----------------------------------------------------+
14306
14307 This option enables use of Proxy Protocol proxies for incoming connections. For
14308 details see section 58.1.
14309
14310 +----------------------------------------------------------------+
14311 |hosts_treat_as_local|Use: main|Type: domain list*|Default: unset|
14312 +----------------------------------------------------------------+
14313
14314 If this option is set, any host names that match the domain list are treated as
14315 if they were the local host when Exim is scanning host lists obtained from MX
14316 records or other sources. Note that the value of this option is a domain list,
14317 not a host list, because it is always used to check host names, not IP
14318 addresses.
14319
14320 This option also applies when Exim is matching the special items "@mx_any",
14321 "@mx_primary", and "@mx_secondary" in a domain list (see section 10.8), and
14322 when checking the hosts option in the smtp transport for the local host (see
14323 the allow_localhost option in that transport). See also local_interfaces,
14324 extra_local_interfaces, and chapter 13, which contains a discussion about local
14325 network interfaces and recognizing the local host.
14326
14327 +--------------------------------------------------------+
14328 |ibase_servers|Use: main|Type: string list|Default: unset|
14329 +--------------------------------------------------------+
14330
14331 This option provides a list of InterBase servers and associated connection
14332 data, to be used in conjunction with ibase lookups (see section 9.22). The
14333 option is available only if Exim has been built with InterBase support.
14334
14335 +------------------------------------------------------------+
14336 |ignore_bounce_errors_after|Use: main|Type: time|Default: 10w|
14337 +------------------------------------------------------------+
14338
14339 This option affects the processing of bounce messages that cannot be delivered,
14340 that is, those that suffer a permanent delivery failure. (Bounce messages that
14341 suffer temporary delivery failures are of course retried in the usual way.)
14342
14343 After a permanent delivery failure, bounce messages are frozen, because there
14344 is no sender to whom they can be returned. When a frozen bounce message has
14345 been in the queue for more than the given time, it is unfrozen at the next
14346 queue run, and a further delivery is attempted. If delivery fails again, the
14347 bounce message is discarded. This makes it possible to keep failed bounce
14348 messages around for a shorter time than the normal maximum retry time for
14349 frozen messages. For example,
14350
14351 ignore_bounce_errors_after = 12h
14352
14353 retries failed bounce message deliveries after 12 hours, discarding any further
14354 failures. If the value of this option is set to a zero time period, bounce
14355 failures are discarded immediately. Setting a very long time (as in the default
14356 value) has the effect of disabling this option. For ways of automatically
14357 dealing with other kinds of frozen message, see auto_thaw and
14358 timeout_frozen_after.
14359
14360 +---------------------------------------------------------------+
14361 |ignore_fromline_hosts|Use: main|Type: host list*|Default: unset|
14362 +---------------------------------------------------------------+
14363
14364 Some broken SMTP clients insist on sending a UUCP-like "From " line before the
14365 headers of a message. By default this is treated as the start of the message's
14366 body, which means that any following headers are not recognized as such. Exim
14367 can be made to ignore it by setting ignore_fromline_hosts to match those hosts
14368 that insist on sending it. If the sender is actually a local process rather
14369 than a remote host, and is using -bs to inject the messages,
14370 ignore_fromline_local must be set to achieve this effect.
14371
14372 +------------------------------------------------------------+
14373 |ignore_fromline_local|Use: main|Type: boolean|Default: false|
14374 +------------------------------------------------------------+
14375
14376 See ignore_fromline_hosts above.
14377
14378 +-----------------------------------------------------------+
14379 |keep_environment|Use: main|Type: string list|Default: unset|
14380 +-----------------------------------------------------------+
14381
14382 This option contains a string list of environment variables to keep. You have
14383 to trust these variables or you have to be sure that these variables do not
14384 impose any security risk. Keep in mind that during the startup phase Exim is
14385 running with an effective UID 0 in most installations. As the default value is
14386 an empty list, the default environment for using libraries, running embedded
14387 Perl code, or running external binaries is empty, and does not not even contain
14388 PATH or HOME.
14389
14390 Actually the list is interpreted as a list of patterns (10.1), except that it
14391 is not expanded first.
14392
14393 WARNING: Macro substitution is still done first, so having a macro FOO and
14394 having FOO_HOME in your keep_environment option may have unexpected results.
14395 You may work around this using a regular expression that does not match the
14396 macro name: ^[F]OO_HOME$.
14397
14398 Current versions of Exim issue a warning during startup if you do not mention
14399 keep_environment in your runtime configuration file and if your current
14400 environment is not empty. Future versions may not issue that warning anymore.
14401
14402 See the add_environment main config option for a way to set environment
14403 variables to a fixed value. The environment for pipe transports is handled
14404 separately, see section 29.4 for details.
14405
14406 +-----------------------------------------------+
14407 |keep_malformed|Use: main|Type: time|Default: 4d|
14408 +-----------------------------------------------+
14409
14410 This option specifies the length of time to keep messages whose spool files
14411 have been corrupted in some way. This should, of course, never happen. At the
14412 next attempt to deliver such a message, it gets removed. The incident is
14413 logged.
14414
14415 +------------------------------------------------------+
14416 |ldap_ca_cert_dir|Use: main|Type: string|Default: unset|
14417 +------------------------------------------------------+
14418
14419 This option indicates which directory contains CA certificates for verifying a
14420 TLS certificate presented by an LDAP server. While Exim does not provide a
14421 default value, your SSL library may. Analogous to tls_verify_certificates but
14422 as a client-side option for LDAP and constrained to be a directory.
14423
14424 +-------------------------------------------------------+
14425 |ldap_ca_cert_file|Use: main|Type: string|Default: unset|
14426 +-------------------------------------------------------+
14427
14428 This option indicates which file contains CA certificates for verifying a TLS
14429 certificate presented by an LDAP server. While Exim does not provide a default
14430 value, your SSL library may. Analogous to tls_verify_certificates but as a
14431 client-side option for LDAP and constrained to be a file.
14432
14433 +----------------------------------------------------+
14434 |ldap_cert_file|Use: main|Type: string|Default: unset|
14435 +----------------------------------------------------+
14436
14437 This option indicates which file contains an TLS client certificate which Exim
14438 should present to the LDAP server during TLS negotiation. Should be used
14439 together with ldap_cert_key.
14440
14441 +---------------------------------------------------+
14442 |ldap_cert_key|Use: main|Type: string|Default: unset|
14443 +---------------------------------------------------+
14444
14445 This option indicates which file contains the secret/private key to use to
14446 prove identity to the LDAP server during TLS negotiation. Should be used
14447 together with ldap_cert_file, which contains the identity to be proven.
14448
14449 +-------------------------------------------------------+
14450 |ldap_cipher_suite|Use: main|Type: string|Default: unset|
14451 +-------------------------------------------------------+
14452
14453 This controls the TLS cipher-suite negotiation during TLS negotiation with the
14454 LDAP server. See 42.4 for more details of the format of cipher-suite options
14455 with OpenSSL (as used by LDAP client libraries).
14456
14457 +---------------------------------------------------------------+
14458 |ldap_default_servers|Use: main|Type: string list|Default: unset|
14459 +---------------------------------------------------------------+
14460
14461 This option provides a list of LDAP servers which are tried in turn when an
14462 LDAP query does not contain a server. See section 9.15 for details of LDAP
14463 queries. This option is available only when Exim has been built with LDAP
14464 support.
14465
14466 +--------------------------------------------------------+
14467 |ldap_require_cert|Use: main|Type: string|Default: unset.|
14468 +--------------------------------------------------------+
14469
14470 This should be one of the values "hard", "demand", "allow", "try" or "never". A
14471 value other than one of these is interpreted as "never". See the entry
14472 "TLS_REQCERT" in your system man page for ldap.conf(5). Although Exim does not
14473 set a default, the LDAP library probably defaults to hard/demand.
14474
14475 +-----------------------------------------------------+
14476 |ldap_start_tls|Use: main|Type: boolean|Default: false|
14477 +-----------------------------------------------------+
14478
14479 If set, Exim will attempt to negotiate TLS with the LDAP server when connecting
14480 on a regular LDAP port. This is the LDAP equivalent of SMTP's "STARTTLS". This
14481 is distinct from using "ldaps", which is the LDAP form of SSL-on-connect. In
14482 the event of failure to negotiate TLS, the action taken is controlled by
14483 ldap_require_cert. This option is ignored for "ldapi" connections.
14484
14485 +---------------------------------------------------+
14486 |ldap_version|Use: main|Type: integer|Default: unset|
14487 +---------------------------------------------------+
14488
14489 This option can be used to force Exim to set a specific protocol version for
14490 LDAP. If it option is unset, it is shown by the -bP command line option as -1.
14491 When this is the case, the default is 3 if LDAP_VERSION3 is defined in the LDAP
14492 headers; otherwise it is 2. This option is available only when Exim has been
14493 built with LDAP support.
14494
14495 +------------------------------------------------------+
14496 |local_from_check|Use: main|Type: boolean|Default: true|
14497 +------------------------------------------------------+
14498
14499 When a message is submitted locally (that is, not over a TCP/IP connection) by
14500 an untrusted user, Exim removes any existing Sender: header line, and checks
14501 that the From: header line matches the login of the calling user and the domain
14502 specified by qualify_domain.
14503
14504 Note: An unqualified address (no domain) in the From: header in a locally
14505 submitted message is automatically qualified by Exim, unless the -bnq command
14506 line option is used.
14507
14508 You can use local_from_prefix and local_from_suffix to permit affixes on the
14509 local part. If the From: header line does not match, Exim adds a Sender: header
14510 with an address constructed from the calling user's login and the default
14511 qualify domain.
14512
14513 If local_from_check is set false, the From: header check is disabled, and no
14514 Sender: header is ever added. If, in addition, you want to retain Sender:
14515 header lines supplied by untrusted users, you must also set local_sender_retain
14516 to be true.
14517
14518 These options affect only the header lines in the message. The envelope sender
14519 is still forced to be the login id at the qualify domain unless
14520 untrusted_set_sender permits the user to supply an envelope sender.
14521
14522 For messages received over TCP/IP, an ACL can specify "submission mode" to
14523 request similar header line checking. See section 47.16, which has more details
14524 about Sender: processing.
14525
14526 +-------------------------------------------------------+
14527 |local_from_prefix|Use: main|Type: string|Default: unset|
14528 +-------------------------------------------------------+
14529
14530 When Exim checks the From: header line of locally submitted messages for
14531 matching the login id (see local_from_check above), it can be configured to
14532 ignore certain prefixes and suffixes in the local part of the address. This is
14533 done by setting local_from_prefix and/or local_from_suffix to appropriate
14534 lists, in the same form as the local_part_prefix and local_part_suffix router
14535 options (see chapter 15). For example, if
14536
14537 local_from_prefix = *-
14538
14539 is set, a From: line containing
14540
14541 From: anything-user@your.domain.example
14542
14543 will not cause a Sender: header to be added if user@your.domain.example matches
14544 the actual sender address that is constructed from the login name and qualify
14545 domain.
14546
14547 +-------------------------------------------------------+
14548 |local_from_suffix|Use: main|Type: string|Default: unset|
14549 +-------------------------------------------------------+
14550
14551 See local_from_prefix above.
14552
14553 +---------------------------------------------------------------+
14554 |local_interfaces|Use: main|Type: string list|Default: see below|
14555 +---------------------------------------------------------------+
14556
14557 This option controls which network interfaces are used by the daemon for
14558 listening; they are also used to identify the local host when routing. Chapter
14559 13 contains a full description of this option and the related options
14560 daemon_smtp_ports, extra_local_interfaces, hosts_treat_as_local, and
14561 tls_on_connect_ports. The default value for local_interfaces is
14562
14563 local_interfaces = 0.0.0.0
14564
14565 when Exim is built without IPv6 support; otherwise it is
14566
14567 local_interfaces = <; ::0 ; 0.0.0.0
14568
14569 +---------------------------------------------------+
14570 |local_scan_timeout|Use: main|Type: time|Default: 5m|
14571 +---------------------------------------------------+
14572
14573 This timeout applies to the local_scan() function (see chapter 45). Zero means
14574 "no timeout". If the timeout is exceeded, the incoming message is rejected with
14575 a temporary error if it is an SMTP message. For a non-SMTP message, the message
14576 is dropped and Exim ends with a non-zero code. The incident is logged on the
14577 main and reject logs.
14578
14579 +----------------------------------------------------------+
14580 |local_sender_retain|Use: main|Type: boolean|Default: false|
14581 +----------------------------------------------------------+
14582
14583 When a message is submitted locally (that is, not over a TCP/IP connection) by
14584 an untrusted user, Exim removes any existing Sender: header line. If you do not
14585 want this to happen, you must set local_sender_retain, and you must also set
14586 local_from_check to be false (Exim will complain if you do not). See also the
14587 ACL modifier "control = suppress_local_fixups". Section 47.16 has more details
14588 about Sender: processing.
14589
14590 +-------------------------------------------------------+
14591 |localhost_number|Use: main|Type: string*|Default: unset|
14592 +-------------------------------------------------------+
14593
14594 Exim's message ids are normally unique only within the local host. If
14595 uniqueness among a set of hosts is required, each host must set a different
14596 value for the localhost_number option. The string is expanded immediately after
14597 reading the configuration file (so that a number can be computed from the host
14598 name, for example) and the result of the expansion must be a number in the
14599 range 0-16 (or 0-10 on operating systems with case-insensitive file systems).
14600 This is available in subsequent string expansions via the variable
14601 $localhost_number. When localhost_number is set, the final two characters of
14602 the message id, instead of just being a fractional part of the time, are
14603 computed from the time and the local host number as described in section 3.4.
14604
14605 +-----------------------------------------------------------------------+
14606 |log_file_path|Use: main|Type: string list*|Default: set at compile time|
14607 +-----------------------------------------------------------------------+
14608
14609 This option sets the path which is used to determine the names of Exim's log
14610 files, or indicates that logging is to be to syslog, or both. It is expanded
14611 when Exim is entered, so it can, for example, contain a reference to the host
14612 name. If no specific path is set for the log files at compile or runtime, or if
14613 the option is unset at runtime (i.e. "log_file_path = ") they are written in a
14614 sub-directory called log in Exim's spool directory. Chapter 52 contains further
14615 details about Exim's logging, and section 52.1 describes how the contents of
14616 log_file_path are used. If this string is fixed at your installation (contains
14617 no expansion variables) it is recommended that you do not set this option in
14618 the configuration file, but instead supply the path using LOG_FILE_PATH in
14619 Local/Makefile so that it is available to Exim for logging errors detected
14620 early on - in particular, failure to read the configuration file.
14621
14622 +--------------------------------------------------+
14623 |log_selector|Use: main|Type: string|Default: unset|
14624 +--------------------------------------------------+
14625
14626 This option can be used to reduce or increase the number of things that Exim
14627 writes to its log files. Its argument is made up of names preceded by plus or
14628 minus characters. For example:
14629
14630 log_selector = +arguments -retry_defer
14631
14632 A list of possible names and what they control is given in the chapter on
14633 logging, in section 52.15.
14634
14635 +---------------------------------------------------+
14636 |log_timezone|Use: main|Type: boolean|Default: false|
14637 +---------------------------------------------------+
14638
14639 By default, the timestamps on log lines are in local time without the timezone.
14640 This means that if your timezone changes twice a year, the timestamps in log
14641 lines are ambiguous for an hour when the clocks go back. One way of avoiding
14642 this problem is to set the timezone to UTC. An alternative is to set
14643 log_timezone true. This turns on the addition of the timezone offset to
14644 timestamps in log lines. Turning on this option can add quite a lot to the size
14645 of log files because each line is extended by 6 characters. Note that the
14646 $tod_log variable contains the log timestamp without the zone, but there is
14647 another variable called $tod_zone that contains just the timezone offset.
14648
14649 +---------------------------------------------------+
14650 |lookup_open_max|Use: main|Type: integer|Default: 25|
14651 +---------------------------------------------------+
14652
14653 This option limits the number of simultaneously open files for single-key
14654 lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally
14655 keeps these files open during routing, because often the same file is required
14656 several times. If the limit is reached, Exim closes the least recently used
14657 file. Note that if you are using the ndbm library, it actually opens two files
14658 for each logical DBM database, though it still counts as one for the purposes
14659 of lookup_open_max. If you are getting "too many open files" errors with NDBM,
14660 you need to reduce the value of lookup_open_max.
14661
14662 +------------------------------------------------------+
14663 |max_username_length|Use: main|Type: integer|Default: 0|
14664 +------------------------------------------------------+
14665
14666 Some operating systems are broken in that they truncate long arguments to
14667 getpwnam() to eight characters, instead of returning "no such user". If this
14668 option is set greater than zero, any attempt to call getpwnam() with an
14669 argument that is longer behaves as if getpwnam() failed.
14670
14671 +---------------------------------------------------------+
14672 |message_body_newlines|Use: main|Type: bool|Default: false|
14673 +---------------------------------------------------------+
14674
14675 By default, newlines in the message body are replaced by spaces when setting
14676 the $message_body and $message_body_end expansion variables. If this option is
14677 set true, this no longer happens.
14678
14679 +---------------------------------------------------------+
14680 |message_body_visible|Use: main|Type: integer|Default: 500|
14681 +---------------------------------------------------------+
14682
14683 This option specifies how much of a message's body is to be included in the
14684 $message_body and $message_body_end expansion variables.
14685
14686 +---------------------------------------------------------------+
14687 |message_id_header_domain|Use: main|Type: string*|Default: unset|
14688 +---------------------------------------------------------------+
14689
14690 If this option is set, the string is expanded and used as the right hand side
14691 (domain) of the Message-ID: header that Exim creates if a locally-originated
14692 incoming message does not have one. "Locally-originated" means "not received
14693 over TCP/IP." Otherwise, the primary host name is used. Only letters, digits,
14694 dot and hyphen are accepted; any other characters are replaced by hyphens. If
14695 the expansion is forced to fail, or if the result is an empty string, the
14696 option is ignored.
14697
14698 +-------------------------------------------------------------+
14699 |message_id_header_text|Use: main|Type: string*|Default: unset|
14700 +-------------------------------------------------------------+
14701
14702 If this variable is set, the string is expanded and used to augment the text of
14703 the Message-id: header that Exim creates if a locally-originated incoming
14704 message does not have one. The text of this header is required by RFC 2822 to
14705 take the form of an address. By default, Exim uses its internal message id as
14706 the local part, and the primary host name as the domain. If this option is set,
14707 it is expanded, and provided the expansion is not forced to fail, and does not
14708 yield an empty string, the result is inserted into the header immediately
14709 before the @, separated from the internal message id by a dot. Any characters
14710 that are illegal in an address are automatically converted into hyphens. This
14711 means that variables such as $tod_log can be used, because the spaces and
14712 colons will become hyphens.
14713
14714 +--------------------------------------------------+
14715 |message_logs|Use: main|Type: boolean|Default: true|
14716 +--------------------------------------------------+
14717
14718 If this option is turned off, per-message log files are not created in the
14719 msglog spool sub-directory. This reduces the amount of disk I/O required by
14720 Exim, by reducing the number of files involved in handling a message from a
14721 minimum of four (header spool file, body spool file, delivery journal, and
14722 per-message log) to three. The other major I/O activity is Exim's main log,
14723 which is not affected by this option.
14724
14725 +-------------------------------------------------------+
14726 |message_size_limit|Use: main|Type: string*|Default: 50M|
14727 +-------------------------------------------------------+
14728
14729 This option limits the maximum size of message that Exim will process. The
14730 value is expanded for each incoming connection so, for example, it can be made
14731 to depend on the IP address of the remote host for messages arriving via TCP/
14732 IP. After expansion, the value must be a sequence of decimal digits, optionally
14733 followed by K or M.
14734
14735 Note: This limit cannot be made to depend on a message's sender or any other
14736 properties of an individual message, because it has to be advertised in the
14737 server's response to EHLO. String expansion failure causes a temporary error. A
14738 value of zero means no limit, but its use is not recommended. See also
14739 bounce_return_size_limit.
14740
14741 Incoming SMTP messages are failed with a 552 error if the limit is exceeded;
14742 locally-generated messages either get a stderr message or a delivery failure
14743 message to the sender, depending on the -oe setting. Rejection of an oversized
14744 message is logged in both the main and the reject logs. See also the generic
14745 transport option message_size_limit, which limits the size of message that an
14746 individual transport can process.
14747
14748 If you use a virus-scanner and set this option to to a value larger than the
14749 maximum size that your virus-scanner is configured to support, you may get
14750 failures triggered by large mails. The right size to configure for the
14751 virus-scanner depends upon what data is passed and the options in use but it's
14752 probably safest to just set it to a little larger than this value. E.g., with a
14753 default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
14754 some problems may result.
14755
14756 A value of 0 will disable size limit checking; Exim will still advertise the
14757 SIZE extension in an EHLO response, but without a limit, so as to permit SMTP
14758 clients to still indicate the message size along with the MAIL verb.
14759
14760 +-----------------------------------------------------------+
14761 |move_frozen_messages|Use: main|Type: boolean|Default: false|
14762 +-----------------------------------------------------------+
14763
14764 This option, which is available only if Exim has been built with the setting
14765
14766 SUPPORT_MOVE_FROZEN_MESSAGES=yes
14767
14768 in Local/Makefile, causes frozen messages and their message logs to be moved
14769 from the input and msglog directories on the spool to Finput and Fmsglog,
14770 respectively. There is currently no support in Exim or the standard utilities
14771 for handling such moved messages, and they do not show up in lists generated by
14772 -bp or by the Exim monitor.
14773
14774 +--------------------------------------------------+
14775 |mua_wrapper|Use: main|Type: boolean|Default: false|
14776 +--------------------------------------------------+
14777
14778 Setting this option true causes Exim to run in a very restrictive mode in which
14779 it passes messages synchronously to a smart host. Chapter 51 contains a full
14780 description of this facility.
14781
14782 +--------------------------------------------------------+
14783 |mysql_servers|Use: main|Type: string list|Default: unset|
14784 +--------------------------------------------------------+
14785
14786 This option provides a list of MySQL servers and associated connection data, to
14787 be used in conjunction with mysql lookups (see section 9.22). The option is
14788 available only if Exim has been built with MySQL support.
14789
14790 +-------------------------------------------------------+
14791 |never_users|Use: main|Type: string list*|Default: unset|
14792 +-------------------------------------------------------+
14793
14794 This option is expanded just once, at the start of Exim's processing. Local
14795 message deliveries are normally run in processes that are setuid to the
14796 recipient, and remote deliveries are normally run under Exim's own uid and gid.
14797 It is usually desirable to prevent any deliveries from running as root, as a
14798 safety precaution.
14799
14800 When Exim is built, an option called FIXED_NEVER_USERS can be set to a list of
14801 users that must not be used for local deliveries. This list is fixed in the
14802 binary and cannot be overridden by the configuration file. By default, it
14803 contains just the single user name "root". The never_users runtime option can
14804 be used to add more users to the fixed list.
14805
14806 If a message is to be delivered as one of the users on the fixed list or the
14807 never_users list, an error occurs, and delivery is deferred. A common example
14808 is
14809
14810 never_users = root:daemon:bin
14811
14812 Including root is redundant if it is also on the fixed list, but it does no
14813 harm. This option overrides the pipe_as_creator option of the pipe transport
14814 driver.
14815
14816 +-----------------------------------------------------------------------------+
14817 |openssl_options| Use: | Type: string | Default: +no_sslv2 +single_dh_use|
14818 | | main | list | +no_ticket|
14819 +-----------------------------------------------------------------------------+
14820
14821 This option allows an administrator to adjust the SSL options applied by
14822 OpenSSL to connections. It is given as a space-separated list of items, each
14823 one to be +added or -subtracted from the current value.
14824
14825 This option is only available if Exim is built against OpenSSL. The values
14826 available for this option vary according to the age of your OpenSSL install.
14827 The "all" value controls a subset of flags which are available, typically the
14828 bug workaround options. The SSL_CTX_set_options man page will list the values
14829 known on your system and Exim should support all the "bug workaround" options
14830 and many of the "modifying" options. The Exim names lose the leading "SSL_OP_"
14831 and are lower-cased.
14832
14833 Note that adjusting the options can have severe impact upon the security of SSL
14834 as used by Exim. It is possible to disable safety checks and shoot yourself in
14835 the foot in various unpleasant ways. This option should not be adjusted
14836 lightly. An unrecognised item will be detected at startup, by invoking Exim
14837 with the -bV flag.
14838
14839 The option affects Exim operating both as a server and as a client.
14840
14841 Historical note: prior to release 4.80, Exim defaulted this value to
14842 "+dont_insert_empty_fragments", which may still be needed for compatibility
14843 with some clients, but which lowers security by increasing exposure to some now
14844 infamous attacks.
14845
14846 Examples:
14847
14848 # Make both old MS and old Eudora happy:
14849 openssl_options = -all +microsoft_big_sslv3_buffer \
14850 +dont_insert_empty_fragments
14851
14852 # Disable older protocol versions:
14853 openssl_options = +no_sslv2 +no_sslv3
14854
14855 Possible options may include:
14856
14857 * "all"
14858
14859 * "allow_unsafe_legacy_renegotiation"
14860
14861 * "cipher_server_preference"
14862
14863 * "dont_insert_empty_fragments"
14864
14865 * "ephemeral_rsa"
14866
14867 * "legacy_server_connect"
14868
14869 * "microsoft_big_sslv3_buffer"
14870
14871 * "microsoft_sess_id_bug"
14872
14873 * "msie_sslv2_rsa_padding"
14874
14875 * "netscape_challenge_bug"
14876
14877 * "netscape_reuse_cipher_change_bug"
14878
14879 * "no_compression"
14880
14881 * "no_session_resumption_on_renegotiation"
14882
14883 * "no_sslv2"
14884
14885 * "no_sslv3"
14886
14887 * "no_ticket"
14888
14889 * "no_tlsv1"
14890
14891 * "no_tlsv1_1"
14892
14893 * "no_tlsv1_2"
14894
14895 * "safari_ecdhe_ecdsa_bug"
14896
14897 * "single_dh_use"
14898
14899 * "single_ecdh_use"
14900
14901 * "ssleay_080_client_dh_bug"
14902
14903 * "sslref2_reuse_cert_type_bug"
14904
14905 * "tls_block_padding_bug"
14906
14907 * "tls_d5_bug"
14908
14909 * "tls_rollback_bug"
14910
14911 As an aside, the "safari_ecdhe_ecdsa_bug" item is a misnomer and affects all
14912 clients connecting using the MacOS SecureTransport TLS facility prior to MacOS
14913 10.8.4, including email clients. If you see old MacOS clients failing to
14914 negotiate TLS then this option value might help, provided that your OpenSSL
14915 release is new enough to contain this work-around. This may be a situation
14916 where you have to upgrade OpenSSL to get buggy clients working.
14917
14918 +---------------------------------------------------------+
14919 |oracle_servers|Use: main|Type: string list|Default: unset|
14920 +---------------------------------------------------------+
14921
14922 This option provides a list of Oracle servers and associated connection data,
14923 to be used in conjunction with oracle lookups (see section 9.22). The option is
14924 available only if Exim has been built with Oracle support.
14925
14926 +----------------------------------------------------------------+
14927 |percent_hack_domains|Use: main|Type: domain list*|Default: unset|
14928 +----------------------------------------------------------------+
14929
14930 The "percent hack" is the convention whereby a local part containing a percent
14931 sign is re-interpreted as a new email address, with the percent replaced by @.
14932 This is sometimes called "source routing", though that term is also applied to
14933 RFC 2822 addresses that begin with an @ character. If this option is set, Exim
14934 implements the percent facility for those domains listed, but no others. This
14935 happens before an incoming SMTP address is tested against an ACL.
14936
14937 Warning: The "percent hack" has often been abused by people who are trying to
14938 get round relaying restrictions. For this reason, it is best avoided if at all
14939 possible. Unfortunately, a number of less security-conscious MTAs implement it
14940 unconditionally. If you are running Exim on a gateway host, and routing mail
14941 through to internal MTAs without processing the local parts, it is a good idea
14942 to reject recipient addresses with percent characters in their local parts.
14943 Exim's default configuration does this.
14944
14945 +----------------------------------------------------+
14946 |perl_at_start|Use: main|Type: boolean|Default: false|
14947 +----------------------------------------------------+
14948
14949 This option is available only when Exim is built with an embedded Perl
14950 interpreter. See chapter 12 for details of its use.
14951
14952 +--------------------------------------------------+
14953 |perl_startup|Use: main|Type: string|Default: unset|
14954 +--------------------------------------------------+
14955
14956 This option is available only when Exim is built with an embedded Perl
14957 interpreter. See chapter 12 for details of its use.
14958
14959 +---------------------------------------------------+
14960 |perl_startup|Use: main|Type: boolean|Default: false|
14961 +---------------------------------------------------+
14962
14963 This Option enables the taint mode of the embedded Perl interpreter.
14964
14965 +--------------------------------------------------------+
14966 |pgsql_servers|Use: main|Type: string list|Default: unset|
14967 +--------------------------------------------------------+
14968
14969 This option provides a list of PostgreSQL servers and associated connection
14970 data, to be used in conjunction with pgsql lookups (see section 9.22). The
14971 option is available only if Exim has been built with PostgreSQL support.
14972
14973 +------------------------------------------------------------------+
14974 |pid_file_path|Use: main|Type: string*|Default: set at compile time|
14975 +------------------------------------------------------------------+
14976
14977 This option sets the name of the file to which the Exim daemon writes its
14978 process id. The string is expanded, so it can contain, for example, references
14979 to the host name:
14980
14981 pid_file_path = /var/log/$primary_hostname/exim.pid
14982
14983 If no path is set, the pid is written to the file exim-daemon.pid in Exim's
14984 spool directory. The value set by the option can be overridden by the -oP
14985 command line option. A pid file is not written if a "non-standard" daemon is
14986 run by means of the -oX option, unless a path is explicitly supplied by -oP.
14987
14988 +----------------------------------------------------------------+
14989 |pipelining_advertise_hosts|Use: main|Type: host list*|Default: *|
14990 +----------------------------------------------------------------+
14991
14992 This option can be used to suppress the advertisement of the SMTP PIPELINING
14993 extension to specific hosts. See also the no_pipelining control in section
14994 43.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim
14995 server enforces strict synchronization for each SMTP command and response. When
14996 PIPELINING is advertised, Exim assumes that clients will use it; "out of order"
14997 commands that are "expected" do not count as protocol errors (see
14998 smtp_max_synprot_errors).
14999
15000 +--------------------------------------------------+
15001 |prdr_enable|Use: main|Type: boolean|Default: false|
15002 +--------------------------------------------------+
15003
15004 This option can be used to enable the Per-Recipient Data Response extension to
15005 SMTP, defined by Eric Hall. If the option is set, PRDR is advertised by Exim
15006 when operating as a server. If the client requests PRDR, and more than one
15007 recipient, for a message an additional ACL is called for each recipient after
15008 the message content is received. See section 43.9.
15009
15010 +------------------------------------------------------------+
15011 |preserve_message_logs|Use: main|Type: boolean|Default: false|
15012 +------------------------------------------------------------+
15013
15014 If this option is set, message log files are not deleted when messages are
15015 completed. Instead, they are moved to a sub-directory of the spool directory
15016 called msglog.OLD, where they remain available for statistical or debugging
15017 purposes. This is a dangerous option to set on systems with any appreciable
15018 volume of mail. Use with care!
15019
15020 +----------------------------------------------------------+
15021 |primary_hostname|Use: main|Type: string|Default: see below|
15022 +----------------------------------------------------------+
15023
15024 This specifies the name of the current host. It is used in the default EHLO or
15025 HELO command for outgoing SMTP messages (changeable via the helo_data option in
15026 the smtp transport), and as the default for qualify_domain. The value is also
15027 used by default in some SMTP response messages from an Exim server. This can be
15028 changed dynamically by setting smtp_active_hostname.
15029
15030 If primary_hostname is not set, Exim calls uname() to find the host name. If
15031 this fails, Exim panics and dies. If the name returned by uname() contains only
15032 one component, Exim passes it to gethostbyname() (or getipnodebyname() when
15033 available) in order to obtain the fully qualified version. The variable
15034 $primary_hostname contains the host name, whether set explicitly by this
15035 option, or defaulted.
15036
15037 +--------------------------------------------------------+
15038 |print_topbitchars|Use: main|Type: boolean|Default: false|
15039 +--------------------------------------------------------+
15040
15041 By default, Exim considers only those characters whose codes lie in the range
15042 32-126 to be printing characters. In a number of circumstances (for example,
15043 when writing log entries) non-printing characters are converted into escape
15044 sequences, primarily to avoid messing up the layout. If print_topbitchars is
15045 set, code values of 128 and above are also considered to be printing
15046 characters.
15047
15048 This option also affects the header syntax checks performed by the autoreply
15049 transport, and whether Exim uses RFC 2047 encoding of the user's full name when
15050 constructing From: and Sender: addresses (as described in section 47.18).
15051 Setting this option can cause Exim to generate eight bit message headers that
15052 do not conform to the standards.
15053
15054 +------------------------------------------------------+
15055 |process_log_path|Use: main|Type: string|Default: unset|
15056 +------------------------------------------------------+
15057
15058 This option sets the name of the file to which an Exim process writes its
15059 "process log" when sent a USR1 signal. This is used by the exiwhat utility
15060 script. If this option is unset, the file called exim-process.info in Exim's
15061 spool directory is used. The ability to specify the name explicitly can be
15062 useful in environments where two different Exims are running, using different
15063 spool directories.
15064
15065 +---------------------------------------------------------+
15066 |prod_requires_admin|Use: main|Type: boolean|Default: true|
15067 +---------------------------------------------------------+
15068
15069 The -M, -R, and -q command-line options require the caller to be an admin user
15070 unless prod_requires_admin is set false. See also queue_list_requires_admin and
15071 commandline_checks_require_admin.
15072
15073 +--------------------------------------------------------+
15074 |qualify_domain|Use: main|Type: string|Default: see below|
15075 +--------------------------------------------------------+
15076
15077 This option specifies the domain name that is added to any envelope sender
15078 addresses that do not have a domain qualification. It also applies to recipient
15079 addresses if qualify_recipient is not set. Unqualified addresses are accepted
15080 by default only for locally-generated messages. Qualification is also applied
15081 to addresses in header lines such as From: and To: for locally-generated
15082 messages, unless the -bnq command line option is used.
15083
15084 Messages from external sources must always contain fully qualified addresses,
15085 unless the sending host matches sender_unqualified_hosts or
15086 recipient_unqualified_hosts (as appropriate), in which case incoming addresses
15087 are qualified with qualify_domain or qualify_recipient as necessary.
15088 Internally, Exim always works with fully qualified envelope addresses. If
15089 qualify_domain is not set, it defaults to the primary_hostname value.
15090
15091 +-----------------------------------------------------------+
15092 |qualify_recipient|Use: main|Type: string|Default: see below|
15093 +-----------------------------------------------------------+
15094
15095 This option allows you to specify a different domain for qualifying recipient
15096 addresses to the one that is used for senders. See qualify_domain above.
15097
15098 +---------------------------------------------------------+
15099 |queue_domains|Use: main|Type: domain list*|Default: unset|
15100 +---------------------------------------------------------+
15101
15102 This option lists domains for which immediate delivery is not required. A
15103 delivery process is started whenever a message is received, but only those
15104 domains that do not match are processed. All other deliveries wait until the
15105 next queue run. See also hold_domains and queue_smtp_domains.
15106
15107 +---------------------------------------------------------------+
15108 |queue_list_requires_admin|Use: main|Type: boolean|Default: true|
15109 +---------------------------------------------------------------+
15110
15111 The -bp command-line option, which lists the messages that are on the queue,
15112 requires the caller to be an admin user unless queue_list_requires_admin is set
15113 false. See also prod_requires_admin and commandline_checks_require_admin.
15114
15115 +-------------------------------------------------+
15116 |queue_only|Use: main|Type: boolean|Default: false|
15117 +-------------------------------------------------+
15118
15119 If queue_only is set, a delivery process is not automatically started whenever
15120 a message is received. Instead, the message waits in the queue for the next
15121 queue run. Even if queue_only is false, incoming messages may not get delivered
15122 immediately when certain conditions (such as heavy load) occur.
15123
15124 The -odq command line has the same effect as queue_only. The -odb and -odi
15125 command line options override queue_only unless queue_only_override is set
15126 false. See also queue_only_file, queue_only_load, and smtp_accept_queue.
15127
15128 +-----------------------------------------------------+
15129 |queue_only_file|Use: main|Type: string|Default: unset|
15130 +-----------------------------------------------------+
15131
15132 This option can be set to a colon-separated list of absolute path names, each
15133 one optionally preceded by "smtp". When Exim is receiving a message, it tests
15134 for the existence of each listed path using a call to stat(). For each path
15135 that exists, the corresponding queueing option is set. For paths with no
15136 prefix, queue_only is set; for paths prefixed by "smtp", queue_smtp_domains is
15137 set to match all domains. So, for example,
15138
15139 queue_only_file = smtp/some/file
15140
15141 causes Exim to behave as if queue_smtp_domains were set to "*" whenever /some/
15142 file exists.
15143
15144 +----------------------------------------------------------+
15145 |queue_only_load|Use: main|Type: fixed-point|Default: unset|
15146 +----------------------------------------------------------+
15147
15148 If the system load average is higher than this value, incoming messages from
15149 all sources are queued, and no automatic deliveries are started. If this
15150 happens during local or remote SMTP input, all subsequent messages received on
15151 the same SMTP connection are queued by default, whatever happens to the load in
15152 the meantime, but this can be changed by setting queue_only_load_latch false.
15153
15154 Deliveries will subsequently be performed by queue runner processes. This
15155 option has no effect on ancient operating systems on which Exim cannot
15156 determine the load average. See also deliver_queue_load_max and
15157 smtp_load_reserve.
15158
15159 +-----------------------------------------------------------+
15160 |queue_only_load_latch|Use: main|Type: boolean|Default: true|
15161 +-----------------------------------------------------------+
15162
15163 When this option is true (the default), once one message has been queued
15164 because the load average is higher than the value set by queue_only_load, all
15165 subsequent messages received on the same SMTP connection are also queued. This
15166 is a deliberate choice; even though the load average may fall below the
15167 threshold, it doesn't seem right to deliver later messages on the same
15168 connection when not delivering earlier ones. However, there are special
15169 circumstances such as very long-lived connections from scanning appliances
15170 where this is not the best strategy. In such cases, queue_only_load_latch
15171 should be set false. This causes the value of the load average to be
15172 re-evaluated for each message.
15173
15174 +---------------------------------------------------------+
15175 |queue_only_override|Use: main|Type: boolean|Default: true|
15176 +---------------------------------------------------------+
15177
15178 When this option is true, the -odx command line options override the setting of
15179 queue_only or queue_only_file in the configuration file. If queue_only_override
15180 is set false, the -odx options cannot be used to override; they are accepted,
15181 but ignored.
15182
15183 +---------------------------------------------------------+
15184 |queue_run_in_order|Use: main|Type: boolean|Default: false|
15185 +---------------------------------------------------------+
15186
15187 If this option is set, queue runs happen in order of message arrival instead of
15188 in an arbitrary order. For this to happen, a complete list of the entire queue
15189 must be set up before the deliveries start. When the queue is all held in a
15190 single directory (the default), a single list is created for both the ordered
15191 and the non-ordered cases. However, if split_spool_directory is set, a single
15192 list is not created when queue_run_in_order is false. In this case, the
15193 sub-directories are processed one at a time (in a random order), and this
15194 avoids setting up one huge list for the whole queue. Thus, setting
15195 queue_run_in_order with split_spool_directory may degrade performance when the
15196 queue is large, because of the extra work in setting up the single, large list.
15197 In most situations, queue_run_in_order should not be set.
15198
15199 +-------------------------------------------------+
15200 |queue_run_max|Use: main|Type: integer*|Default: 5|
15201 +-------------------------------------------------+
15202
15203 This controls the maximum number of queue runner processes that an Exim daemon
15204 can run simultaneously. This does not mean that it starts them all at once, but
15205 rather that if the maximum number are still running when the time comes to
15206 start another one, it refrains from starting another one. This can happen with
15207 very large queues and/or very sluggish deliveries. This option does not,
15208 however, interlock with other processes, so additional queue runners can be
15209 started by other means, or by killing and restarting the daemon.
15210
15211 Setting this option to zero does not suppress queue runs; rather, it disables
15212 the limit, allowing any number of simultaneous queue runner processes to be
15213 run. If you do not want queue runs to occur, omit the -qxx setting on the
15214 daemon's command line.
15215
15216 To set limits for different named queues use an expansion depending on the
15217 $queue_name variable.
15218
15219 +--------------------------------------------------------------+
15220 |queue_smtp_domains|Use: main|Type: domain list*|Default: unset|
15221 +--------------------------------------------------------------+
15222
15223 When this option is set, a delivery process is started whenever a message is
15224 received, routing is performed, and local deliveries take place. However, if
15225 any SMTP deliveries are required for domains that match queue_smtp_domains,
15226 they are not immediately delivered, but instead the message waits in the queue
15227 for the next queue run. Since routing of the message has taken place, Exim
15228 knows to which remote hosts it must be delivered, and so when the queue run
15229 happens, multiple messages for the same host are delivered over a single SMTP
15230 connection. The -odqs command line option causes all SMTP deliveries to be
15231 queued in this way, and is equivalent to setting queue_smtp_domains to "*". See
15232 also hold_domains and queue_domains.
15233
15234 +------------------------------------------------+
15235 |receive_timeout|Use: main|Type: time|Default: 0s|
15236 +------------------------------------------------+
15237
15238 This option sets the timeout for accepting a non-SMTP message, that is, the
15239 maximum time that Exim waits when reading a message on the standard input. If
15240 the value is zero, it will wait forever. This setting is overridden by the -or
15241 command line option. The timeout for incoming SMTP messages is controlled by
15242 smtp_receive_timeout.
15243
15244 +---------------------------------------------------------------+
15245 |received_header_text|Use: main|Type: string*|Default: see below|
15246 +---------------------------------------------------------------+
15247
15248 This string defines the contents of the Received: message header that is added
15249 to each message, except for the timestamp, which is automatically added on at
15250 the end (preceded by a semicolon). The string is expanded each time it is used.
15251 If the expansion yields an empty string, no Received: header line is added to
15252 the message. Otherwise, the string should start with the text "Received:" and
15253 conform to the RFC 2822 specification for Received: header lines. The default
15254 setting is:
15255
15256 received_header_text = Received: \
15257 ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\
15258 {${if def:sender_ident \
15259 {from ${quote_local_part:$sender_ident} }}\
15260 ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
15261 by $primary_hostname \
15262 ${if def:received_protocol {with $received_protocol}} \
15263 ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\
15264 (Exim $version_number)\n\t\
15265 ${if def:sender_address \
15266 {(envelope-from <$sender_address>)\n\t}}\
15267 id $message_exim_id\
15268 ${if def:received_for {\n\tfor $received_for}}
15269
15270 The reference to the TLS cipher is omitted when Exim is built without TLS
15271 support. The use of conditional expansions ensures that this works for both
15272 locally generated messages and messages received from remote hosts, giving
15273 header lines such as the following:
15274
15275 Received: from scrooge.carol.example ([192.168.12.25] ident=root)
15276 by marley.carol.example with esmtp (Exim 4.00)
15277 (envelope-from <bob@carol.example>)
15278 id 16IOWa-00019l-00
15279 for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000
15280 Received: by scrooge.carol.example with local (Exim 4.00)
15281 id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000
15282
15283 Until the body of the message has been received, the timestamp is the time when
15284 the message started to be received. Once the body has arrived, and all policy
15285 checks have taken place, the timestamp is updated to the time at which the
15286 message was accepted.
15287
15288 +--------------------------------------------------------+
15289 |received_headers_max|Use: main|Type: integer|Default: 30|
15290 +--------------------------------------------------------+
15291
15292 When a message is to be delivered, the number of Received: headers is counted,
15293 and if it is greater than this parameter, a mail loop is assumed to have
15294 occurred, the delivery is abandoned, and an error message is generated. This
15295 applies to both local and remote deliveries.
15296
15297 +---------------------------------------------------------------------+
15298 |recipient_unqualified_hosts|Use: main|Type: host list*|Default: unset|
15299 +---------------------------------------------------------------------+
15300
15301 This option lists those hosts from which Exim is prepared to accept unqualified
15302 recipient addresses in message envelopes. The addresses are made fully
15303 qualified by the addition of the qualify_recipient value. This option also
15304 affects message header lines. Exim does not reject unqualified recipient
15305 addresses in headers, but it qualifies them only if the message came from a
15306 host that matches recipient_unqualified_hosts, or if the message was submitted
15307 locally (not using TCP/IP), and the -bnq option was not set.
15308
15309 +-------------------------------------------------+
15310 |recipients_max|Use: main|Type: integer|Default: 0|
15311 +-------------------------------------------------+
15312
15313 If this option is set greater than zero, it specifies the maximum number of
15314 original recipients for any message. Additional recipients that are generated
15315 by aliasing or forwarding do not count. SMTP messages get a 452 response for
15316 all recipients over the limit; earlier recipients are delivered as normal.
15317 Non-SMTP messages with too many recipients are failed, and no deliveries are
15318 done.
15319
15320 Note: The RFCs specify that an SMTP server should accept at least 100 RCPT
15321 commands in a single message.
15322
15323 +------------------------------------------------------------+
15324 |recipients_max_reject|Use: main|Type: boolean|Default: false|
15325 +------------------------------------------------------------+
15326
15327 If this option is set true, Exim rejects SMTP messages containing too many
15328 recipients by giving 552 errors to the surplus RCPT commands, and a 554 error
15329 to the eventual DATA command. Otherwise (the default) it gives a 452 error to
15330 the surplus RCPT commands and accepts the message on behalf of the initial set
15331 of recipients. The remote server should then re-send the message for the
15332 remaining recipients at a later time.
15333
15334 +------------------------------------------------------+
15335 |remote_max_parallel|Use: main|Type: integer|Default: 2|
15336 +------------------------------------------------------+
15337
15338 This option controls parallel delivery of one message to a number of remote
15339 hosts. If the value is less than 2, parallel delivery is disabled, and Exim
15340 does all the remote deliveries for a message one by one. Otherwise, if a single
15341 message has to be delivered to more than one remote host, or if several copies
15342 have to be sent to the same remote host, up to remote_max_parallel deliveries
15343 are done simultaneously. If more than remote_max_parallel deliveries are
15344 required, the maximum number of processes are started, and as each one
15345 finishes, another is begun. The order of starting processes is the same as if
15346 sequential delivery were being done, and can be controlled by the
15347 remote_sort_domains option. If parallel delivery takes place while running with
15348 debugging turned on, the debugging output from each delivery process is tagged
15349 with its process id.
15350
15351 This option controls only the maximum number of parallel deliveries for one
15352 message in one Exim delivery process. Because Exim has no central queue
15353 manager, there is no way of controlling the total number of simultaneous
15354 deliveries if the configuration allows a delivery attempt as soon as a message
15355 is received.
15356
15357 If you want to control the total number of deliveries on the system, you need
15358 to set the queue_only option. This ensures that all incoming messages are added
15359 to the queue without starting a delivery process. Then set up an Exim daemon to
15360 start queue runner processes at appropriate intervals (probably fairly often,
15361 for example, every minute), and limit the total number of queue runners by
15362 setting the queue_run_max parameter. Because each queue runner delivers only
15363 one message at a time, the maximum number of deliveries that can then take
15364 place at once is queue_run_max multiplied by remote_max_parallel.
15365
15366 If it is purely remote deliveries you want to control, use queue_smtp_domains
15367 instead of queue_only. This has the added benefit of doing the SMTP routing
15368 before queueing, so that several messages for the same host will eventually get
15369 delivered down the same connection.
15370
15371 +---------------------------------------------------------------+
15372 |remote_sort_domains|Use: main|Type: domain list*|Default: unset|
15373 +---------------------------------------------------------------+
15374
15375 When there are a number of remote deliveries for a message, they are sorted by
15376 domain into the order given by this list. For example,
15377
15378 remote_sort_domains = *.cam.ac.uk:*.uk
15379
15380 would attempt to deliver to all addresses in the cam.ac.uk domain first, then
15381 to those in the uk domain, then to any others.
15382
15383 +--------------------------------------------------+
15384 |retry_data_expire|Use: main|Type: time|Default: 7d|
15385 +--------------------------------------------------+
15386
15387 This option sets a "use before" time on retry information in Exim's hints
15388 database. Any older retry data is ignored. This means that, for example, once a
15389 host has not been tried for 7 days, Exim behaves as if it has no knowledge of
15390 past failures.
15391
15392 +----------------------------------------------------+
15393 |retry_interval_max|Use: main|Type: time|Default: 24h|
15394 +----------------------------------------------------+
15395
15396 Chapter 32 describes Exim's mechanisms for controlling the intervals between
15397 delivery attempts for messages that cannot be delivered straight away. This
15398 option sets an overall limit to the length of time between retries. It cannot
15399 be set greater than 24 hours; any attempt to do so forces the default value.
15400
15401 +--------------------------------------------------------+
15402 |return_path_remove|Use: main|Type: boolean|Default: true|
15403 +--------------------------------------------------------+
15404
15405 RFC 2821, section 4.4, states that an SMTP server must insert a Return-path:
15406 header line into a message when it makes a "final delivery". The Return-path:
15407 header preserves the sender address as received in the MAIL command. This
15408 description implies that this header should not be present in an incoming
15409 message. If return_path_remove is true, any existing Return-path: headers are
15410 removed from messages at the time they are received. Exim's transports have
15411 options for adding Return-path: headers at the time of delivery. They are
15412 normally used only for final local deliveries.
15413
15414 +-------------------------------------------------------+
15415 |return_size_limit|Use: main|Type: integer|Default: 100K|
15416 +-------------------------------------------------------+
15417
15418 This option is an obsolete synonym for bounce_return_size_limit.
15419
15420 +-----------------------------------------------------+
15421 |rfc1413_hosts|Use: main|Type: host list*|Default: @[]|
15422 +-----------------------------------------------------+
15423
15424 RFC 1413 identification calls are made to any client host which matches an item
15425 in the list. The default value specifies just this host, being any local
15426 interface for the system.
15427
15428 +------------------------------------------------------+
15429 |rfc1413_query_timeout|Use: main|Type: time|Default: 0s|
15430 +------------------------------------------------------+
15431
15432 This sets the timeout on RFC 1413 identification calls. If it is set to zero,
15433 no RFC 1413 calls are ever made.
15434
15435 +------------------------------------------------------------------+
15436 |sender_unqualified_hosts|Use: main|Type: host list*|Default: unset|
15437 +------------------------------------------------------------------+
15438
15439 This option lists those hosts from which Exim is prepared to accept unqualified
15440 sender addresses. The addresses are made fully qualified by the addition of
15441 qualify_domain. This option also affects message header lines. Exim does not
15442 reject unqualified addresses in headers that contain sender addresses, but it
15443 qualifies them only if the message came from a host that matches
15444 sender_unqualified_hosts, or if the message was submitted locally (not using
15445 TCP/IP), and the -bnq option was not set.
15446
15447 +----------------------------------------------------------+
15448 |set_environment|Use: main|Type: string list|Default: empty|
15449 +----------------------------------------------------------+
15450
15451 This option allows to set individual environment variables that the currently
15452 linked libraries and programs in child processes use. The default list is
15453 empty,
15454
15455 +--------------------------------------------------+
15456 |slow_lookup_log|Use: main|Type: integer|Default: 0|
15457 +--------------------------------------------------+
15458
15459 This option controls logging of slow lookups. If the value is nonzero it is
15460 taken as a number of milliseconds and lookups taking longer than this are
15461 logged. Currently this applies only to DNS lookups.
15462
15463 +-----------------------------------------------------------+
15464 |smtp_accept_keepalive|Use: main|Type: boolean|Default: true|
15465 +-----------------------------------------------------------+
15466
15467 This option controls the setting of the SO_KEEPALIVE option on incoming TCP/IP
15468 socket connections. When set, it causes the kernel to probe idle connections
15469 periodically, by sending packets with "old" sequence numbers. The other end of
15470 the connection should send an acknowledgment if the connection is still okay or
15471 a reset if the connection has been aborted. The reason for doing this is that
15472 it has the beneficial effect of freeing up certain types of connection that can
15473 get stuck when the remote host is disconnected without tidying up the TCP/IP
15474 call properly. The keepalive mechanism takes several hours to detect
15475 unreachable hosts.
15476
15477 +---------------------------------------------------+
15478 |smtp_accept_max|Use: main|Type: integer|Default: 20|
15479 +---------------------------------------------------+
15480
15481 This option specifies the maximum number of simultaneous incoming SMTP calls
15482 that Exim will accept. It applies only to the listening daemon; there is no
15483 control (in Exim) when incoming SMTP is being handled by inetd. If the value is
15484 set to zero, no limit is applied. However, it is required to be non-zero if
15485 either smtp_accept_max_per_host or smtp_accept_queue is set. See also
15486 smtp_accept_reserve and smtp_load_reserve.
15487
15488 A new SMTP connection is immediately rejected if the smtp_accept_max limit has
15489 been reached. If not, Exim first checks smtp_accept_max_per_host. If that limit
15490 has not been reached for the client host, smtp_accept_reserve and
15491 smtp_load_reserve are then checked before accepting the connection.
15492
15493 +-----------------------------------------------------------+
15494 |smtp_accept_max_nonmail|Use: main|Type: integer|Default: 10|
15495 +-----------------------------------------------------------+
15496
15497 Exim counts the number of "non-mail" commands in an SMTP session, and drops the
15498 connection if there are too many. This option defines "too many". The check
15499 catches some denial-of-service attacks, repeated failing AUTHs, or a mad client
15500 looping sending EHLO, for example. The check is applied only if the client host
15501 matches smtp_accept_max_nonmail_hosts.
15502
15503 When a new message is expected, one occurrence of RSET is not counted. This
15504 allows a client to send one RSET between messages (this is not necessary, but
15505 some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO,
15506 and one occurrence of STARTTLS between messages. After starting up a TLS
15507 session, another EHLO is expected, and so it too is not counted. The first
15508 occurrence of AUTH in a connection, or immediately following STARTTLS is not
15509 counted. Otherwise, all commands other than MAIL, RCPT, DATA, and QUIT are
15510 counted.
15511
15512 +-------------------------------------------------------------------+
15513 |smtp_accept_max_nonmail_hosts|Use: main|Type: host list*|Default: *|
15514 +-------------------------------------------------------------------+
15515
15516 You can control which hosts are subject to the smtp_accept_max_nonmail check by
15517 setting this option. The default value makes it apply to all hosts. By changing
15518 the value, you can exclude any badly-behaved hosts that you have to live with.
15519
15520 +--------------------------------------------------------------------+
15521 |smtp_accept_max_per_connection|Use: main|Type: integer|Default: 1000|
15522 +--------------------------------------------------------------------+
15523
15524 The value of this option limits the number of MAIL commands that Exim is
15525 prepared to accept over a single SMTP connection, whether or not each command
15526 results in the transfer of a message. After the limit is reached, a 421
15527 response is given to subsequent MAIL commands. This limit is a safety
15528 precaution against a client that goes mad (incidents of this type have been
15529 seen).
15530
15531 +---------------------------------------------------------------+
15532 |smtp_accept_max_per_host|Use: main|Type: string*|Default: unset|
15533 +---------------------------------------------------------------+
15534
15535 This option restricts the number of simultaneous IP connections from a single
15536 host (strictly, from a single IP address) to the Exim daemon. The option is
15537 expanded, to enable different limits to be applied to different hosts by
15538 reference to $sender_host_address. Once the limit is reached, additional
15539 connection attempts from the same host are rejected with error code 421. This
15540 is entirely independent of smtp_accept_reserve. The option's default value of
15541 zero imposes no limit. If this option is set greater than zero, it is required
15542 that smtp_accept_max be non-zero.
15543
15544 Warning: When setting this option you should not use any expansion
15545 constructions that take an appreciable amount of time. The expansion and test
15546 happen in the main daemon loop, in order to reject additional connections
15547 without forking additional processes (otherwise a denial-of-service attack
15548 could cause a vast number or processes to be created). While the daemon is
15549 doing this processing, it cannot accept any other incoming connections.
15550
15551 +----------------------------------------------------+
15552 |smtp_accept_queue|Use: main|Type: integer|Default: 0|
15553 +----------------------------------------------------+
15554
15555 If the number of simultaneous incoming SMTP connections being handled via the
15556 listening daemon exceeds this value, messages received by SMTP are just placed
15557 in the queue; no delivery processes are started automatically. The count is
15558 fixed at the start of an SMTP connection. It cannot be updated in the
15559 subprocess that receives messages, and so the queueing or not queueing applies
15560 to all messages received in the same connection.
15561
15562 A value of zero implies no limit, and clearly any non-zero value is useful only
15563 if it is less than the smtp_accept_max value (unless that is zero). See also
15564 queue_only, queue_only_load, queue_smtp_domains, and the various -odx command
15565 line options.
15566
15567 +--------------------------------------------------------------------+
15568 |smtp_accept_queue_per_connection|Use: main|Type: integer|Default: 10|
15569 +--------------------------------------------------------------------+
15570
15571 This option limits the number of delivery processes that Exim starts
15572 automatically when receiving messages via SMTP, whether via the daemon or by
15573 the use of -bs or -bS. If the value of the option is greater than zero, and the
15574 number of messages received in a single SMTP session exceeds this number,
15575 subsequent messages are placed in the queue, but no delivery processes are
15576 started. This helps to limit the number of Exim processes when a server
15577 restarts after downtime and there is a lot of mail waiting for it on other
15578 systems. On large systems, the default should probably be increased, and on
15579 dial-in client systems it should probably be set to zero (that is, disabled).
15580
15581 +------------------------------------------------------+
15582 |smtp_accept_reserve|Use: main|Type: integer|Default: 0|
15583 +------------------------------------------------------+
15584
15585 When smtp_accept_max is set greater than zero, this option specifies a number
15586 of SMTP connections that are reserved for connections from the hosts that are
15587 specified in smtp_reserve_hosts. The value set in smtp_accept_max includes this
15588 reserve pool. The specified hosts are not restricted to this number of
15589 connections; the option specifies a minimum number of connection slots for
15590 them, not a maximum. It is a guarantee that this group of hosts can always get
15591 at least smtp_accept_reserve connections. However, the limit specified by
15592 smtp_accept_max_per_host is still applied to each individual host.
15593
15594 For example, if smtp_accept_max is set to 50 and smtp_accept_reserve is set to
15595 5, once there are 45 active connections (from any hosts), new connections are
15596 accepted only from hosts listed in smtp_reserve_hosts, provided the other
15597 criteria for acceptance are met.
15598
15599 +-----------------------------------------------------------+
15600 |smtp_active_hostname|Use: main|Type: string*|Default: unset|
15601 +-----------------------------------------------------------+
15602
15603 This option is provided for multi-homed servers that want to masquerade as
15604 several different hosts. At the start of an incoming SMTP connection, its value
15605 is expanded and used instead of the value of $primary_hostname in SMTP
15606 responses. For example, it is used as domain name in the response to an
15607 incoming HELO or EHLO command.
15608
15609 The active hostname is placed in the $smtp_active_hostname variable, which is
15610 saved with any messages that are received. It is therefore available for use in
15611 routers and transports when the message is later delivered.
15612
15613 If this option is unset, or if its expansion is forced to fail, or if the
15614 expansion results in an empty string, the value of $primary_hostname is used.
15615 Other expansion failures cause a message to be written to the main and panic
15616 logs, and the SMTP command receives a temporary error. Typically, the value of
15617 smtp_active_hostname depends on the incoming interface address. For example:
15618
15619 smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\
15620 {cox.mydomain}{box.mydomain}}
15621
15622 Although $smtp_active_hostname is primarily concerned with incoming messages,
15623 it is also used as the default for HELO commands in callout verification if
15624 there is no remote transport from which to obtain a helo_data value.
15625
15626 +------------------------------------------------------+
15627 |smtp_banner|Use: main|Type: string*|Default: see below|
15628 +------------------------------------------------------+
15629
15630 This string, which is expanded every time it is used, is output as the initial
15631 positive response to an SMTP connection. The default setting is:
15632
15633 smtp_banner = $smtp_active_hostname ESMTP Exim \
15634 $version_number $tod_full
15635
15636 Failure to expand the string causes a panic error. If you want to create a
15637 multiline response to the initial SMTP connection, use "\n" in the string at
15638 appropriate points, but not at the end. Note that the 220 code is not included
15639 in this string. Exim adds it automatically (several times in the case of a
15640 multiline response).
15641
15642 +------------------------------------------------------------+
15643 |smtp_check_spool_space|Use: main|Type: boolean|Default: true|
15644 +------------------------------------------------------------+
15645
15646 When this option is set, if an incoming SMTP session encounters the SIZE option
15647 on a MAIL command, it checks that there is enough space in the spool
15648 directory's partition to accept a message of that size, while still leaving
15649 free the amount specified by check_spool_space (even if that value is zero). If
15650 there isn't enough space, a temporary error code is returned.
15651
15652 +--------------------------------------------------------+
15653 |smtp_connect_backlog|Use: main|Type: integer|Default: 20|
15654 +--------------------------------------------------------+
15655
15656 This option specifies a maximum number of waiting SMTP connections. Exim passes
15657 this value to the TCP/IP system when it sets up its listener. Once this number
15658 of connections are waiting for the daemon's attention, subsequent connection
15659 attempts are refused at the TCP/IP level. At least, that is what the manuals
15660 say; in some circumstances such connection attempts have been observed to time
15661 out instead. For large systems it is probably a good idea to increase the value
15662 (to 50, say). It also gives some protection against denial-of-service attacks
15663 by SYN flooding.
15664
15665 +-------------------------------------------------------+
15666 |smtp_enforce_sync|Use: main|Type: boolean|Default: true|
15667 +-------------------------------------------------------+
15668
15669 The SMTP protocol specification requires the client to wait for a response from
15670 the server at certain points in the dialogue. Without PIPELINING these
15671 synchronization points are after every command; with PIPELINING they are fewer,
15672 but they still exist.
15673
15674 Some spamming sites send out a complete set of SMTP commands without waiting
15675 for any response. Exim protects against this by rejecting a message if the
15676 client has sent further input when it should not have. The error response "554
15677 SMTP synchronization error" is sent, and the connection is dropped. Testing for
15678 this error cannot be perfect because of transmission delays (unexpected input
15679 may be on its way but not yet received when Exim checks). However, it does
15680 detect many instances.
15681
15682 The check can be globally disabled by setting smtp_enforce_sync false. If you
15683 want to disable the check selectively (for example, only for certain hosts),
15684 you can do so by an appropriate use of a control modifier in an ACL (see
15685 section 43.22). See also pipelining_advertise_hosts.
15686
15687 +--------------------------------------------------------+
15688 |smtp_etrn_command|Use: main|Type: string*|Default: unset|
15689 +--------------------------------------------------------+
15690
15691 If this option is set, the given command is run whenever an SMTP ETRN command
15692 is received from a host that is permitted to issue such commands (see chapter
15693 43). The string is split up into separate arguments which are independently
15694 expanded. The expansion variable $domain is set to the argument of the ETRN
15695 command, and no syntax checking is done on it. For example:
15696
15697 smtp_etrn_command = /etc/etrn_command $domain \
15698 $sender_host_address
15699
15700 A new process is created to run the command, but Exim does not wait for it to
15701 complete. Consequently, its status cannot be checked. If the command cannot be
15702 run, a line is written to the panic log, but the ETRN caller still receives a
15703 250 success response. Exim is normally running under its own uid when receiving
15704 SMTP, so it is not possible for it to change the uid before running the
15705 command.
15706
15707 +---------------------------------------------------------+
15708 |smtp_etrn_serialize|Use: main|Type: boolean|Default: true|
15709 +---------------------------------------------------------+
15710
15711 When this option is set, it prevents the simultaneous execution of more than
15712 one identical command as a result of ETRN in an SMTP connection. See section
15713 48.8 for details.
15714
15715 +------------------------------------------------------------+
15716 |smtp_load_reserve|Use: main|Type: fixed-point|Default: unset|
15717 +------------------------------------------------------------+
15718
15719 If the system load average ever gets higher than this, incoming SMTP calls are
15720 accepted only from those hosts that match an entry in smtp_reserve_hosts. If
15721 smtp_reserve_hosts is not set, no incoming SMTP calls are accepted when the
15722 load is over the limit. The option has no effect on ancient operating systems
15723 on which Exim cannot determine the load average. See also
15724 deliver_queue_load_max and queue_only_load.
15725
15726 +----------------------------------------------------------+
15727 |smtp_max_synprot_errors|Use: main|Type: integer|Default: 3|
15728 +----------------------------------------------------------+
15729
15730 Exim rejects SMTP commands that contain syntax or protocol errors. In
15731 particular, a syntactically invalid email address, as in this command:
15732
15733 RCPT TO:<abc xyz@a.b.c>
15734
15735 causes immediate rejection of the command, before any other tests are done.
15736 (The ACL cannot be run if there is no valid address to set up for it.) An
15737 example of a protocol error is receiving RCPT before MAIL. If there are too
15738 many syntax or protocol errors in one SMTP session, the connection is dropped.
15739 The limit is set by this option.
15740
15741 When the PIPELINING extension to SMTP is in use, some protocol errors are
15742 "expected", for instance, a RCPT command after a rejected MAIL command. Exim
15743 assumes that PIPELINING will be used if it advertises it (see
15744 pipelining_advertise_hosts), and in this situation, "expected" errors do not
15745 count towards the limit.
15746
15747 +------------------------------------------------------------+
15748 |smtp_max_unknown_commands|Use: main|Type: integer|Default: 3|
15749 +------------------------------------------------------------+
15750
15751 If there are too many unrecognized commands in an incoming SMTP session, an
15752 Exim server drops the connection. This is a defence against some kinds of abuse
15753 that subvert web clients into making connections to SMTP ports; in these
15754 circumstances, a number of non-SMTP command lines are sent first.
15755
15756 +--------------------------------------------------------------+
15757 |smtp_ratelimit_hosts|Use: main|Type: host list*|Default: unset|
15758 +--------------------------------------------------------------+
15759
15760 Some sites find it helpful to be able to limit the rate at which certain hosts
15761 can send them messages, and the rate at which an individual message can specify
15762 recipients.
15763
15764 Exim has two rate-limiting facilities. This section describes the older
15765 facility, which can limit rates within a single connection. The newer ratelimit
15766 ACL condition can limit rates across all connections. See section 43.38 for
15767 details of the newer facility.
15768
15769 When a host matches smtp_ratelimit_hosts, the values of smtp_ratelimit_mail and
15770 smtp_ratelimit_rcpt are used to control the rate of acceptance of MAIL and RCPT
15771 commands in a single SMTP session, respectively. Each option, if set, must
15772 contain a set of four comma-separated values:
15773
15774 * A threshold, before which there is no rate limiting.
15775
15776 * An initial time delay. Unlike other times in Exim, numbers with decimal
15777 fractional parts are allowed here.
15778
15779 * A factor by which to increase the delay each time.
15780
15781 * A maximum value for the delay. This should normally be less than 5 minutes,
15782 because after that time, the client is liable to timeout the SMTP command.
15783
15784 For example, these settings have been used successfully at the site which first
15785 suggested this feature, for controlling mail from their customers:
15786
15787 smtp_ratelimit_mail = 2,0.5s,1.05,4m
15788 smtp_ratelimit_rcpt = 4,0.25s,1.015,4m
15789
15790 The first setting specifies delays that are applied to MAIL commands after two
15791 have been received over a single connection. The initial delay is 0.5 seconds,
15792 increasing by a factor of 1.05 each time. The second setting applies delays to
15793 RCPT commands when more than four occur in a single message.
15794
15795 +---------------------------------------------------------+
15796 |smtp_ratelimit_mail|Use: main|Type: string|Default: unset|
15797 +---------------------------------------------------------+
15798
15799 See smtp_ratelimit_hosts above.
15800
15801 +---------------------------------------------------------+
15802 |smtp_ratelimit_rcpt|Use: main|Type: string|Default: unset|
15803 +---------------------------------------------------------+
15804
15805 See smtp_ratelimit_hosts above.
15806
15807 +------------------------------------------------------+
15808 |smtp_receive_timeout|Use: main|Type: time*|Default: 5m|
15809 +------------------------------------------------------+
15810
15811 This sets a timeout value for SMTP reception. It applies to all forms of SMTP
15812 input, including batch SMTP. If a line of input (either an SMTP command or a
15813 data line) is not received within this time, the SMTP connection is dropped and
15814 the message is abandoned. A line is written to the log containing one of the
15815 following messages:
15816
15817 SMTP command timeout on connection from...
15818 SMTP data timeout on connection from...
15819
15820 The former means that Exim was expecting to read an SMTP command; the latter
15821 means that it was in the DATA phase, reading the contents of a message.
15822
15823 If the first character of the option is a "$" the option is expanded before use
15824 and may depend on $sender_host_name, $sender_host_address and $sender_host_port
15825 .
15826
15827 The value set by this option can be overridden by the -os command-line option.
15828 A setting of zero time disables the timeout, but this should never be used for
15829 SMTP over TCP/IP. (It can be useful in some cases of local input using -bs or
15830 -bS.) For non-SMTP input, the reception timeout is controlled by
15831 receive_timeout and -or.
15832
15833 +------------------------------------------------------------+
15834 |smtp_reserve_hosts|Use: main|Type: host list*|Default: unset|
15835 +------------------------------------------------------------+
15836
15837 This option defines hosts for which SMTP connections are reserved; see
15838 smtp_accept_reserve and smtp_load_reserve above.
15839
15840 +----------------------------------------------------------------+
15841 |smtp_return_error_details|Use: main|Type: boolean|Default: false|
15842 +----------------------------------------------------------------+
15843
15844 In the default state, Exim uses bland messages such as "Administrative
15845 prohibition" when it rejects SMTP commands for policy reasons. Many sysadmins
15846 like this because it gives away little information to spammers. However, some
15847 other sysadmins who are applying strict checking policies want to give out much
15848 fuller information about failures. Setting smtp_return_error_details true
15849 causes Exim to be more forthcoming. For example, instead of "Administrative
15850 prohibition", it might give:
15851
15852 550-Rejected after DATA: '>' missing at end of address:
15853 550 failing address in "From" header is: <user@dom.ain
15854
15855 +--------------------------------------------------------------+
15856 |smtputf8_advertise_hosts|Use: main|Type: host list*|Default: *|
15857 +--------------------------------------------------------------+
15858
15859 When Exim is built with support for internationalised mail names, the
15860 availability thereof is advertised in response to EHLO only to those client
15861 hosts that match this option. See chapter 59 for details of Exim's support for
15862 internationalisation.
15863
15864 +-----------------------------------------------------------+
15865 |spamd_address|Use: main|Type: string|Default: 127.0.0.1 783|
15866 +-----------------------------------------------------------+
15867
15868 This option is available when Exim is compiled with the content-scanning
15869 extension. It specifies how Exim connects to SpamAssassin's spamd daemon. See
15870 section 44.2 for more details.
15871
15872 +--------------------------------------------------------------------+
15873 |spf_guess|Use: main|Type: string|Default: v=spf1 a/24 mx/24 ptr ?all|
15874 +--------------------------------------------------------------------+
15875
15876 This option is available when Exim is compiled with SPF support. See section
15877 57.4 for more details.
15878
15879 +------------------------------------------------------------+
15880 |split_spool_directory|Use: main|Type: boolean|Default: false|
15881 +------------------------------------------------------------+
15882
15883 If this option is set, it causes Exim to split its input directory into 62
15884 subdirectories, each with a single alphanumeric character as its name. The
15885 sixth character of the message id is used to allocate messages to
15886 subdirectories; this is the least significant base-62 digit of the time of
15887 arrival of the message.
15888
15889 Splitting up the spool in this way may provide better performance on systems
15890 where there are long mail queues, by reducing the number of files in any one
15891 directory. The msglog directory is also split up in a similar way to the input
15892 directory; however, if preserve_message_logs is set, all old msglog files are
15893 still placed in the single directory msglog.OLD.
15894
15895 It is not necessary to take any special action for existing messages when
15896 changing split_spool_directory. Exim notices messages that are in the "wrong"
15897 place, and continues to process them. If the option is turned off after a
15898 period of being on, the subdirectories will eventually empty and be
15899 automatically deleted.
15900
15901 When split_spool_directory is set, the behaviour of queue runner processes
15902 changes. Instead of creating a list of all messages in the queue, and then
15903 trying to deliver each one, in turn, it constructs a list of those in one
15904 sub-directory and tries to deliver them, before moving on to the next
15905 sub-directory. The sub-directories are processed in a random order. This
15906 spreads out the scanning of the input directories, and uses less memory. It is
15907 particularly beneficial when there are lots of messages in the queue. However,
15908 if queue_run_in_order is set, none of this new processing happens. The entire
15909 queue has to be scanned and sorted before any deliveries can start.
15910
15911 +--------------------------------------------------------------------+
15912 |spool_directory|Use: main|Type: string*|Default: set at compile time|
15913 +--------------------------------------------------------------------+
15914
15915 This defines the directory in which Exim keeps its spool, that is, the messages
15916 it is waiting to deliver. The default value is taken from the compile-time
15917 configuration setting, if there is one. If not, this option must be set. The
15918 string is expanded, so it can contain, for example, a reference to
15919 $primary_hostname.
15920
15921 If the spool directory name is fixed on your installation, it is recommended
15922 that you set it at build time rather than from this option, particularly if the
15923 log files are being written to the spool directory (see log_file_path).
15924 Otherwise log files cannot be used for errors that are detected early on, such
15925 as failures in the configuration file.
15926
15927 By using this option to override the compiled-in path, it is possible to run
15928 tests of Exim without using the standard spool.
15929
15930 +-------------------------------------------------------+
15931 |spool_wireformat|Use: main|Type: boolean|Default: false|
15932 +-------------------------------------------------------+
15933
15934 If this option is set, Exim may for some messages use an alternative format for
15935 data-files in the spool which matches the wire format. Doing this permits more
15936 efficient message reception and transmission. Currently it is only done for
15937 messages received using the ESMTP CHUNKING option.
15938
15939 The following variables will not have useful values:
15940
15941 $max_received_linelength
15942 $body_linecount
15943 $body_zerocount
15944
15945 Users of the local_scan() API (see 45), and any external programs which are
15946 passed a reference to a message data file (except via the "regex", "malware" or
15947 "spam") ACL conditions) will need to be aware of the different formats
15948 potentially available.
15949
15950 Using any of the ACL conditions noted will negate the reception benefit (as a
15951 Unix-mbox-format file is constructed for them). The transmission benefit is
15952 maintained.
15953
15954 +----------------------------------------------------+
15955 |sqlite_lock_timeout|Use: main|Type: time|Default: 5s|
15956 +----------------------------------------------------+
15957
15958 This option controls the timeout that the sqlite lookup uses when trying to
15959 access an SQLite database. See section 9.26 for more details.
15960
15961 +------------------------------------------------------+
15962 |strict_acl_vars|Use: main|Type: boolean|Default: false|
15963 +------------------------------------------------------+
15964
15965 This option controls what happens if a syntactically valid but undefined ACL
15966 variable is referenced. If it is false (the default), an empty string is
15967 substituted; if it is true, an error is generated. See section 43.19 for
15968 details of ACL variables.
15969
15970 +------------------------------------------------------------------+
15971 |strip_excess_angle_brackets|Use: main|Type: boolean|Default: false|
15972 +------------------------------------------------------------------+
15973
15974 If this option is set, redundant pairs of angle brackets round "route-addr"
15975 items in addresses are stripped. For example, <<xxx@a.b.c.d>> is treated as
15976 <xxx@a.b.c.d>. If this is in the envelope and the message is passed on to
15977 another MTA, the excess angle brackets are not passed on. If this option is not
15978 set, multiple pairs of angle brackets cause a syntax error.
15979
15980 +---------------------------------------------------------+
15981 |strip_trailing_dot|Use: main|Type: boolean|Default: false|
15982 +---------------------------------------------------------+
15983
15984 If this option is set, a trailing dot at the end of a domain in an address is
15985 ignored. If this is in the envelope and the message is passed on to another
15986 MTA, the dot is not passed on. If this option is not set, a dot at the end of a
15987 domain causes a syntax error. However, addresses in header lines are checked
15988 only when an ACL requests header syntax checking.
15989
15990 +--------------------------------------------------------+
15991 |syslog_duplication|Use: main|Type: boolean|Default: true|
15992 +--------------------------------------------------------+
15993
15994 When Exim is logging to syslog, it writes the log lines for its three separate
15995 logs at different syslog priorities so that they can in principle be separated
15996 on the logging hosts. Some installations do not require this separation, and in
15997 those cases, the duplication of certain log lines is a nuisance. If
15998 syslog_duplication is set false, only one copy of any particular log line is
15999 written to syslog. For lines that normally go to both the main log and the
16000 reject log, the reject log version (possibly containing message header lines)
16001 is written, at LOG_NOTICE priority. Lines that normally go to both the main and
16002 the panic log are written at the LOG_ALERT priority.
16003
16004 +-----------------------------------------------------+
16005 |syslog_facility|Use: main|Type: string|Default: unset|
16006 +-----------------------------------------------------+
16007
16008 This option sets the syslog "facility" name, used when Exim is logging to
16009 syslog. The value must be one of the strings "mail", "user", "news", "uucp",
16010 "daemon", or "localx" where x is a digit between 0 and 7. If this option is
16011 unset, "mail" is used. See chapter 52 for details of Exim's logging.
16012
16013 +------------------------------------------------+
16014 |syslog_pid|Use: main|Type: boolean|Default: true|
16015 +------------------------------------------------+
16016
16017 If syslog_pid is set false, the PID on Exim's log lines are omitted when these
16018 lines are sent to syslog. (Syslog normally prefixes the log lines with the PID
16019 of the logging process automatically.) You need to enable the "+pid" log
16020 selector item, if you want Exim to write it's PID into the logs.) See chapter
16021 52 for details of Exim's logging.
16022
16023 +---------------------------------------------------------+
16024 |syslog_processname|Use: main|Type: string|Default: "exim"|
16025 +---------------------------------------------------------+
16026
16027 This option sets the syslog "ident" name, used when Exim is logging to syslog.
16028 The value must be no longer than 32 characters. See chapter 52 for details of
16029 Exim's logging.
16030
16031 +------------------------------------------------------+
16032 |syslog_timestamp|Use: main|Type: boolean|Default: true|
16033 +------------------------------------------------------+
16034
16035 If syslog_timestamp is set false, the timestamps on Exim's log lines are
16036 omitted when these lines are sent to syslog. See chapter 52 for details of
16037 Exim's logging.
16038
16039 +----------------------------------------------------+
16040 |system_filter|Use: main|Type: string*|Default: unset|
16041 +----------------------------------------------------+
16042
16043 This option specifies an Exim filter file that is applied to all messages at
16044 the start of each delivery attempt, before any routing is done. System filters
16045 must be Exim filters; they cannot be Sieve filters. If the system filter
16046 generates any deliveries to files or pipes, or any new mail messages, the
16047 appropriate system_filter_..._transport option(s) must be set, to define which
16048 transports are to be used. Details of this facility are given in chapter 46. A
16049 forced expansion failure results in no filter operation.
16050
16051 +------------------------------------------------------------------------+
16052 |system_filter_directory_transport|Use: main|Type: string*|Default: unset|
16053 +------------------------------------------------------------------------+
16054
16055 This sets the name of the transport driver that is to be used when the save
16056 command in a system message filter specifies a path ending in "/", implying
16057 delivery of each message into a separate file in some directory. During the
16058 delivery, the variable $address_file contains the path name.
16059
16060 +-------------------------------------------------------------------+
16061 |system_filter_file_transport|Use: main|Type: string*|Default: unset|
16062 +-------------------------------------------------------------------+
16063
16064 This sets the name of the transport driver that is to be used when the save
16065 command in a system message filter specifies a path not ending in "/". During
16066 the delivery, the variable $address_file contains the path name.
16067
16068 +---------------------------------------------------------+
16069 |system_filter_group|Use: main|Type: string|Default: unset|
16070 +---------------------------------------------------------+
16071
16072 This option is used only when system_filter_user is also set. It sets the gid
16073 under which the system filter is run, overriding any gid that is associated
16074 with the user. The value may be numerical or symbolic.
16075
16076 +-------------------------------------------------------------------+
16077 |system_filter_pipe_transport|Use: main|Type: string*|Default: unset|
16078 +-------------------------------------------------------------------+
16079
16080 This specifies the transport driver that is to be used when a pipe command is
16081 used in a system filter. During the delivery, the variable $address_pipe
16082 contains the pipe command.
16083
16084 +--------------------------------------------------------------------+
16085 |system_filter_reply_transport|Use: main|Type: string*|Default: unset|
16086 +--------------------------------------------------------------------+
16087
16088 This specifies the transport driver that is to be used when a mail command is
16089 used in a system filter.
16090
16091 +--------------------------------------------------------+
16092 |system_filter_user|Use: main|Type: string|Default: unset|
16093 +--------------------------------------------------------+
16094
16095 If this option is set to root, the system filter is run in the main Exim
16096 delivery process, as root. Otherwise, the system filter runs in a separate
16097 process, as the given user, defaulting to the Exim run-time user. Unless the
16098 string consists entirely of digits, it is looked up in the password data.
16099 Failure to find the named user causes a configuration error. The gid is either
16100 taken from the password data, or specified by system_filter_group. When the uid
16101 is specified numerically, system_filter_group is required to be set.
16102
16103 If the system filter generates any pipe, file, or reply deliveries, the uid
16104 under which the filter is run is used when transporting them, unless a
16105 transport option overrides.
16106
16107 +-------------------------------------------------+
16108 |tcp_nodelay|Use: main|Type: boolean|Default: true|
16109 +-------------------------------------------------+
16110
16111 If this option is set false, it stops the Exim daemon setting the TCP_NODELAY
16112 option on its listening sockets. Setting TCP_NODELAY turns off the "Nagle
16113 algorithm", which is a way of improving network performance in interactive
16114 (character-by-character) situations. Turning it off should improve Exim's
16115 performance a bit, so that is what happens by default. However, it appears that
16116 some broken clients cannot cope, and time out. Hence this option. It affects
16117 only those sockets that are set up for listening by the daemon. Sockets created
16118 by the smtp transport for delivering mail always set TCP_NODELAY.
16119
16120 +-----------------------------------------------------+
16121 |timeout_frozen_after|Use: main|Type: time|Default: 0s|
16122 +-----------------------------------------------------+
16123
16124 If timeout_frozen_after is set to a time greater than zero, a frozen message of
16125 any kind that has been in the queue for longer than the given time is
16126 automatically cancelled at the next queue run. If the frozen message is a
16127 bounce message, it is just discarded; otherwise, a bounce is sent to the
16128 sender, in a similar manner to cancellation by the -Mg command line option. If
16129 you want to timeout frozen bounce messages earlier than other kinds of frozen
16130 message, see ignore_bounce_errors_after.
16131
16132 Note: the default value of zero means no timeouts; with this setting, frozen
16133 messages remain in the queue forever (except for any frozen bounce messages
16134 that are released by ignore_bounce_errors_after).
16135
16136 +----------------------------------------------+
16137 |timezone|Use: main|Type: string|Default: unset|
16138 +----------------------------------------------+
16139
16140 The value of timezone is used to set the environment variable TZ while running
16141 Exim (if it is different on entry). This ensures that all timestamps created by
16142 Exim are in the required timezone. If you want all your timestamps to be in UTC
16143 (aka GMT) you should set
16144
16145 timezone = UTC
16146
16147 The default value is taken from TIMEZONE_DEFAULT in Local/Makefile, or, if that
16148 is not set, from the value of the TZ environment variable when Exim is built.
16149 If timezone is set to the empty string, either at build or run time, any
16150 existing TZ variable is removed from the environment when Exim runs. This is
16151 appropriate behaviour for obtaining wall-clock time on some, but unfortunately
16152 not all, operating systems.
16153
16154 +---------------------------------------------------------+
16155 |tls_advertise_hosts|Use: main|Type: host list*|Default: *|
16156 +---------------------------------------------------------+
16157
16158 When Exim is built with support for TLS encrypted connections, the availability
16159 of the STARTTLS command to set up an encrypted session is advertised in
16160 response to EHLO only to those client hosts that match this option. See chapter
16161 42 for details of Exim's support for TLS. Note that the default value requires
16162 that a certificate be supplied using the tls_certificate option. If TLS support
16163 for incoming connections is not required the tls_advertise_hosts option should
16164 be set empty.
16165
16166 +-----------------------------------------------------+
16167 |tls_certificate|Use: main|Type: string|Default: list*|
16168 +-----------------------------------------------------+
16169
16170 The value of this option is expanded, and must then be a list of absolute paths
16171 to files which contains the server's certificates. Commonly only one file is
16172 needed. The server's private key is also assumed to be in this file if
16173 tls_privatekey is unset. See chapter 42 for further details.
16174
16175 Note: The certificates defined by this option are used only when Exim is
16176 receiving incoming messages as a server. If you want to supply certificates for
16177 use when sending messages as a client, you must set the tls_certificate option
16178 in the relevant smtp transport.
16179
16180 Note: If you use filenames based on IP addresses, change the list separator in
16181 the usual way (6.21) >to avoid confusion under IPv6.
16182
16183 Note: Under versions of OpenSSL preceding 1.1.1, when a list of more than one
16184 file is used, the $tls_in_ourcert variable is unreliable.
16185
16186 Note: OCSP stapling is not usable under OpenSSL when a list of more than one
16187 file is used.
16188
16189 If the option contains $tls_out_sni and Exim is built against OpenSSL, then if
16190 the OpenSSL build supports TLS extensions and the TLS client sends the Server
16191 Name Indication extension, then this option and others documented in 42.10 will
16192 be re-expanded.
16193
16194 If this option is unset or empty a fresh self-signed certificate will be
16195 generated for every connection.
16196
16197 +----------------------------------------------+
16198 |tls_crl|Use: main|Type: string*|Default: unset|
16199 +----------------------------------------------+
16200
16201 This option specifies a certificate revocation list. The expanded value must be
16202 the name of a file that contains CRLs in PEM format.
16203
16204 Under OpenSSL the option can specify a directory with CRL files.
16205
16206 Note: Under OpenSSL the option must, if given, supply a CRL for each signing
16207 element of the certificate chain (i.e. all but the leaf). For the file variant
16208 this can be multiple PEM blocks in the one file.
16209
16210 See 42.10 for discussion of when this option might be re-expanded.
16211
16212 +-----------------------------------------------------+
16213 |tls_dh_max_bits|Use: main|Type: integer|Default: 2236|
16214 +-----------------------------------------------------+
16215
16216 The number of bits used for Diffie-Hellman key-exchange may be suggested by the
16217 chosen TLS library. That value might prove to be too high for interoperability.
16218 This option provides a maximum clamp on the value suggested, trading off
16219 security for interoperability.
16220
16221 The value must be at least 1024.
16222
16223 The value 2236 was chosen because, at time of adding the option, it was the
16224 hard-coded maximum value supported by the NSS cryptographic library, as used by
16225 Thunderbird, while GnuTLS was suggesting 2432 bits as normal.
16226
16227 If you prefer more security and are willing to break some clients, raise this
16228 number.
16229
16230 Note that the value passed to GnuTLS for *generating* a new prime may be a
16231 little less than this figure, because GnuTLS is inexact and may produce a
16232 larger prime than requested.
16233
16234 +--------------------------------------------------+
16235 |tls_dhparam|Use: main|Type: string*|Default: unset|
16236 +--------------------------------------------------+
16237
16238 The value of this option is expanded and indicates the source of DH parameters
16239 to be used by Exim.
16240
16241 Note: The Exim Maintainers strongly recommend using a filename with
16242 site-generated local DH parameters, which has been supported across all
16243 versions of Exim. The other specific constants available are a fallback so that
16244 even when "unconfigured", Exim can offer Perfect Forward Secrecy in older
16245 ciphersuites in TLS.
16246
16247 If tls_dhparam is a filename starting with a "/", then it names a file from
16248 which DH parameters should be loaded. If the file exists, it should hold a
16249 PEM-encoded PKCS#3 representation of the DH prime. If the file does not exist,
16250 for OpenSSL it is an error. For GnuTLS, Exim will attempt to create the file
16251 and fill it with a generated DH prime. For OpenSSL, if the DH bit-count from
16252 loading the file is greater than tls_dh_max_bits then it will be ignored, and
16253 treated as though the tls_dhparam were set to "none".
16254
16255 If this option expands to the string "none", then no DH parameters will be
16256 loaded by Exim.
16257
16258 If this option expands to the string "historic" and Exim is using GnuTLS, then
16259 Exim will attempt to load a file from inside the spool directory. If the file
16260 does not exist, Exim will attempt to create it. See section 42.3 for further
16261 details.
16262
16263 If Exim is using OpenSSL and this option is empty or unset, then Exim will load
16264 a default DH prime; the default is Exim-specific but lacks verifiable
16265 provenance.
16266
16267 In older versions of Exim the default was the 2048 bit prime described in
16268 section 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order
16269 Subgroup", which in IKE is assigned number 23.
16270
16271 Otherwise, the option must expand to the name used by Exim for any of a number
16272 of DH primes specified in RFC 2409, RFC 3526, RFC 5114, RFC 7919, or from other
16273 sources. As names, Exim uses a standard specified name, else "ike" followed by
16274 the number used by IKE, or "default" which corresponds to
16275 "exim.dev.20160529.3".
16276
16277 The available standard primes are: "ffdhe2048", "ffdhe3072", "ffdhe4096",
16278 "ffdhe6144", "ffdhe8192", "ike1", "ike2", "ike5", "ike14", "ike15", "ike16",
16279 "ike17", "ike18", "ike22", "ike23" and "ike24".
16280
16281 The available additional primes are: "exim.dev.20160529.1",
16282 "exim.dev.20160529.2" and "exim.dev.20160529.3".
16283
16284 Some of these will be too small to be accepted by clients. Some may be too
16285 large to be accepted by clients. The open cryptographic community has
16286 suspicions about the integrity of some of the later IKE values, which led into
16287 RFC7919 providing new fixed constants (the "ffdhe" identifiers).
16288
16289 At this point, all of the "ike" values should be considered obsolete; they're
16290 still in Exim to avoid breaking unusual configurations, but are candidates for
16291 removal the next time we have backwards-incompatible changes.
16292
16293 The TLS protocol does not negotiate an acceptable size for this; clients tend
16294 to hard-drop connections if what is offered by the server is unacceptable,
16295 whether too large or too small, and there's no provision for the client to tell
16296 the server what these constraints are. Thus, as a server operator, you need to
16297 make an educated guess as to what is most likely to work for your userbase.
16298
16299 Some known size constraints suggest that a bit-size in the range 2048 to 2236
16300 is most likely to maximise interoperability. The upper bound comes from
16301 applications using the Mozilla Network Security Services (NSS) library, which
16302 used to set its "DH_MAX_P_BITS" upper-bound to 2236. This affects many mail
16303 user agents (MUAs). The lower bound comes from Debian installs of Exim4 prior
16304 to the 4.80 release, as Debian used to patch Exim to raise the minimum
16305 acceptable bound from 1024 to 2048.
16306
16307 +---------------------------------------------------+
16308 |tls_eccurve|Use: main|Type: string*|Default: "auto"|
16309 +---------------------------------------------------+
16310
16311 This option selects a EC curve for use by Exim when used with OpenSSL. It has
16312 no effect when Exim is used with GnuTLS.
16313
16314 After expansion it must contain a valid EC curve parameter, such as
16315 "prime256v1", "secp384r1", or "P-512". Consult your OpenSSL manual for valid
16316 selections.
16317
16318 For OpenSSL versions before (and not including) 1.0.2, the string "auto"
16319 selects "prime256v1". For more recent OpenSSL versions "auto" tells the library
16320 to choose.
16321
16322 If the option expands to an empty string, no EC curves will be enabled.
16323
16324 +----------------------------------------------------+
16325 |tls_ocsp_file|Use: main|Type: string*|Default: unset|
16326 +----------------------------------------------------+
16327
16328 This option must if set expand to the absolute path to a file which contains a
16329 current status proof for the server's certificate, as obtained from the
16330 Certificate Authority.
16331
16332 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
16333
16334 For GnuTLS 3.5.6 or later the expanded value of this option can be a list of
16335 files, to match a list given for the tls_certificate option. The ordering of
16336 the two lists must match.
16337
16338 +---------------------------------------------------------------+
16339 |tls_on_connect_ports|Use: main|Type: string list|Default: unset|
16340 +---------------------------------------------------------------+
16341
16342 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
16343 operate the SSMTP (SMTPS) protocol, where a TLS session is immediately set up
16344 without waiting for the client to issue a STARTTLS command. For further
16345 details, see section 13.4.
16346
16347 +----------------------------------------------------+
16348 |tls_privatekey|Use: main|Type: string|Default: list*|
16349 +----------------------------------------------------+
16350
16351 The value of this option is expanded, and must then be a list of absolute paths
16352 to files which contains the server's private keys. If this option is unset, or
16353 if the expansion is forced to fail, or the result is an empty string, the
16354 private key is assumed to be in the same file as the server's certificates. See
16355 chapter 42 for further details.
16356
16357 See 42.10 for discussion of when this option might be re-expanded.
16358
16359 +---------------------------------------------------------+
16360 |tls_remember_esmtp|Use: main|Type: boolean|Default: false|
16361 +---------------------------------------------------------+
16362
16363 If this option is set true, Exim violates the RFCs by remembering that it is in
16364 "esmtp" state after successfully negotiating a TLS session. This provides
16365 support for broken clients that fail to send a new EHLO after starting a TLS
16366 session.
16367
16368 +----------------------------------------------------------+
16369 |tls_require_ciphers|Use: main|Type: string*|Default: unset|
16370 +----------------------------------------------------------+
16371
16372 This option controls which ciphers can be used for incoming TLS connections.
16373 The smtp transport has an option of the same name for controlling outgoing
16374 connections. This option is expanded for each connection, so can be varied for
16375 different clients if required. The value of this option must be a list of
16376 permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
16377 in somewhat different ways. If GnuTLS is being used, the client controls the
16378 preference order of the available ciphers. Details are given in sections 42.4
16379 and 42.5.
16380
16381 +--------------------------------------------------------------+
16382 |tls_try_verify_hosts|Use: main|Type: host list*|Default: unset|
16383 +--------------------------------------------------------------+
16384
16385 See tls_verify_hosts below.
16386
16387 +---------------------------------------------------------------+
16388 |tls_verify_certificates|Use: main|Type: string*|Default: system|
16389 +---------------------------------------------------------------+
16390
16391 The value of this option is expanded, and must then be either the word "system"
16392 or the absolute path to a file or directory containing permitted certificates
16393 for clients that match tls_verify_hosts or tls_try_verify_hosts.
16394
16395 The "system" value for the option will use a system default location compiled
16396 into the SSL library. This is not available for GnuTLS versions preceding
16397 3.0.20, and will be taken as empty; an explicit location must be specified.
16398
16399 The use of a directory for the option value is not available for GnuTLS
16400 versions preceding 3.3.6 and a single file must be used.
16401
16402 With OpenSSL the certificates specified explicitly either by file or directory
16403 are added to those given by the system default location.
16404
16405 These certificates should be for the certificate authorities trusted, rather
16406 than the public cert of individual clients. With both OpenSSL and GnuTLS, if
16407 the value is a file then the certificates are sent by Exim as a server to
16408 connecting clients, defining the list of accepted certificate authorities. Thus
16409 the values defined should be considered public data. To avoid this, use the
16410 explicit directory version.
16411
16412 See 42.10 for discussion of when this option might be re-expanded.
16413
16414 A forced expansion failure or setting to an empty string is equivalent to being
16415 unset.
16416
16417 +----------------------------------------------------------+
16418 |tls_verify_hosts|Use: main|Type: host list*|Default: unset|
16419 +----------------------------------------------------------+
16420
16421 This option, along with tls_try_verify_hosts, controls the checking of
16422 certificates from clients. The expected certificates are defined by
16423 tls_verify_certificates, which must be set. A configuration error occurs if
16424 either tls_verify_hosts or tls_try_verify_hosts is set and
16425 tls_verify_certificates is not set.
16426
16427 Any client that matches tls_verify_hosts is constrained by
16428 tls_verify_certificates. When the client initiates a TLS session, it must
16429 present one of the listed certificates. If it does not, the connection is
16430 aborted. Warning: Including a host in tls_verify_hosts does not require the
16431 host to use TLS. It can still send SMTP commands through unencrypted
16432 connections. Forcing a client to use TLS has to be done separately using an ACL
16433 to reject inappropriate commands when the connection is not encrypted.
16434
16435 A weaker form of checking is provided by tls_try_verify_hosts. If a client
16436 matches this option (but not tls_verify_hosts), Exim requests a certificate and
16437 checks it against tls_verify_certificates, but does not abort the connection if
16438 there is no certificate or if it does not match. This state can be detected in
16439 an ACL, which makes it possible to implement policies such as "accept for relay
16440 only if a verified certificate has been received, but accept for local delivery
16441 if encrypted, even without a verified certificate".
16442
16443 Client hosts that match neither of these lists are not asked to present
16444 certificates.
16445
16446 +----------------------------------------------------------+
16447 |trusted_groups|Use: main|Type: string list*|Default: unset|
16448 +----------------------------------------------------------+
16449
16450 This option is expanded just once, at the start of Exim's processing. If this
16451 option is set, any process that is running in one of the listed groups, or
16452 which has one of them as a supplementary group, is trusted. The groups can be
16453 specified numerically or by name. See section 5.2 for details of what trusted
16454 callers are permitted to do. If neither trusted_groups nor trusted_users is
16455 set, only root and the Exim user are trusted.
16456
16457 +---------------------------------------------------------+
16458 |trusted_users|Use: main|Type: string list*|Default: unset|
16459 +---------------------------------------------------------+
16460
16461 This option is expanded just once, at the start of Exim's processing. If this
16462 option is set, any process that is running as one of the listed users is
16463 trusted. The users can be specified numerically or by name. See section 5.2 for
16464 details of what trusted callers are permitted to do. If neither trusted_groups
16465 nor trusted_users is set, only root and the Exim user are trusted.
16466
16467 +----------------------------------------------------+
16468 |unknown_login|Use: main|Type: string*|Default: unset|
16469 +----------------------------------------------------+
16470
16471 This is a specialized feature for use in unusual configurations. By default, if
16472 the uid of the caller of Exim cannot be looked up using getpwuid(), Exim gives
16473 up. The unknown_login option can be used to set a login name to be used in this
16474 circumstance. It is expanded, so values like user$caller_uid can be set. When
16475 unknown_login is used, the value of unknown_username is used for the user's
16476 real name (gecos field), unless this has been set by the -F option.
16477
16478 +------------------------------------------------------+
16479 |unknown_username|Use: main|Type: string|Default: unset|
16480 +------------------------------------------------------+
16481
16482 See unknown_login.
16483
16484 +-----------------------------------------------------------------+
16485 |untrusted_set_sender|Use: main|Type: address list*|Default: unset|
16486 +-----------------------------------------------------------------+
16487
16488 When an untrusted user submits a message to Exim using the standard input, Exim
16489 normally creates an envelope sender address from the user's login and the
16490 default qualification domain. Data from the -f option (for setting envelope
16491 senders on non-SMTP messages) or the SMTP MAIL command (if -bs or -bS is used)
16492 is ignored.
16493
16494 However, untrusted users are permitted to set an empty envelope sender address,
16495 to declare that a message should never generate any bounces. For example:
16496
16497 exim -f '<>' user@domain.example
16498
16499 The untrusted_set_sender option allows you to permit untrusted users to set
16500 other envelope sender addresses in a controlled way. When it is set, untrusted
16501 users are allowed to set envelope sender addresses that match any of the
16502 patterns in the list. Like all address lists, the string is expanded. The
16503 identity of the user is in $sender_ident, so you can, for example, restrict
16504 users to setting senders that start with their login ids followed by a hyphen
16505 by a setting like this:
16506
16507 untrusted_set_sender = ^$sender_ident-
16508
16509 If you want to allow untrusted users to set envelope sender addresses without
16510 restriction, you can use
16511
16512 untrusted_set_sender = *
16513
16514 The untrusted_set_sender option applies to all forms of local input, but only
16515 to the setting of the envelope sender. It does not permit untrusted users to
16516 use the other options which trusted user can use to override message
16517 parameters. Furthermore, it does not stop Exim from removing an existing
16518 Sender: header in the message, or from adding a Sender: header if necessary.
16519 See local_sender_retain and local_from_check for ways of overriding these
16520 actions. The handling of the Sender: header is also described in section 47.16.
16521
16522 The log line for a message's arrival shows the envelope sender following "<=".
16523 For local messages, the user's login always follows, after "U=". In -bp
16524 displays, and in the Exim monitor, if an untrusted user sets an envelope sender
16525 address, the user's login is shown in parentheses after the sender address.
16526
16527 +-----------------------------------------------------------+
16528 |uucp_from_pattern|Use: main|Type: string|Default: see below|
16529 +-----------------------------------------------------------+
16530
16531 Some applications that pass messages to an MTA via a command line interface use
16532 an initial line starting with "From " to pass the envelope sender. In
16533 particular, this is used by UUCP software. Exim recognizes such a line by means
16534 of a regular expression that is set in uucp_from_pattern. When the pattern
16535 matches, the sender address is constructed by expanding the contents of
16536 uucp_from_sender, provided that the caller of Exim is a trusted user. The
16537 default pattern recognizes lines in the following two forms:
16538
16539 From ph10 Fri Jan 5 12:35 GMT 1996
16540 From ph10 Fri, 7 Jan 97 14:00:00 GMT
16541
16542 The pattern can be seen by running
16543
16544 exim -bP uucp_from_pattern
16545
16546 It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit
16547 year in the second case. The first word after "From " is matched in the regular
16548 expression by a parenthesized subpattern. The default value for
16549 uucp_from_sender is "$1", which therefore just uses this first word ("ph10" in
16550 the example above) as the message's sender. See also ignore_fromline_hosts.
16551
16552 +------------------------------------------------------+
16553 |uucp_from_sender|Use: main|Type: string*|Default: "$1"|
16554 +------------------------------------------------------+
16555
16556 See uucp_from_pattern above.
16557
16558 +-------------------------------------------------------+
16559 |warn_message_file|Use: main|Type: string|Default: unset|
16560 +-------------------------------------------------------+
16561
16562 This option defines a template file containing paragraphs of text to be used
16563 for constructing the warning message which is sent by Exim when a message has
16564 been in the queue for a specified amount of time, as specified by delay_warning
16565 . Details of the file's contents are given in chapter 49. See also
16566 bounce_message_file.
16567
16568 +-----------------------------------------------------+
16569 |write_rejectlog|Use: main|Type: boolean|Default: true|
16570 +-----------------------------------------------------+
16571
16572 If this option is set false, Exim no longer writes anything to the reject log.
16573 See chapter 52 for details of what Exim writes to its logs.
16574
16575
16576
16577 ===============================================================================
16578 15. GENERIC OPTIONS FOR ROUTERS
16579
16580 This chapter describes the generic options that apply to all routers. Those
16581 that are preconditions are marked with ** in the "use" field.
16582
16583 For a general description of how a router operates, see sections 3.10 and 3.12.
16584 The latter specifies the order in which the preconditions are tested. The order
16585 of expansion of the options that provide data for a transport is: errors_to,
16586 headers_add, headers_remove, transport.
16587
16588 +------------------------------------------------------+
16589 |address_data|Use: routers|Type: string*|Default: unset|
16590 +------------------------------------------------------+
16591
16592 The string is expanded just before the router is run, that is, after all the
16593 precondition tests have succeeded. If the expansion is forced to fail, the
16594 router declines, the value of address_data remains unchanged, and the more
16595 option controls what happens next. Other expansion failures cause delivery of
16596 the address to be deferred.
16597
16598 When the expansion succeeds, the value is retained with the address, and can be
16599 accessed using the variable $address_data in the current router, subsequent
16600 routers, and the eventual transport.
16601
16602 Warning: If the current or any subsequent router is a redirect router that runs
16603 a user's filter file, the contents of $address_data are accessible in the
16604 filter. This is not normally a problem, because such data is usually either not
16605 confidential or it "belongs" to the current user, but if you do put
16606 confidential data into $address_data you need to remember this point.
16607
16608 Even if the router declines or passes, the value of $address_data remains with
16609 the address, though it can be changed by another address_data setting on a
16610 subsequent router. If a router generates child addresses, the value of
16611 $address_data propagates to them. This also applies to the special kind of
16612 "child" that is generated by a router with the unseen option.
16613
16614 The idea of address_data is that you can use it to look up a lot of data for
16615 the address once, and then pick out parts of the data later. For example, you
16616 could use a single LDAP lookup to return a string of the form
16617
16618 uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
16619
16620 In the transport you could pick out the mailbox by a setting such as
16621
16622 file = ${extract{mailbox}{$address_data}}
16623
16624 This makes the configuration file less messy, and also reduces the number of
16625 lookups (though Exim does cache lookups).
16626
16627 The address_data facility is also useful as a means of passing information from
16628 one router to another, and from a router to a transport. In addition, if
16629 $address_data is set by a router when verifying a recipient address from an
16630 ACL, it remains available for use in the rest of the ACL statement. After
16631 verifying a sender, the value is transferred to $sender_address_data.
16632
16633 +-------------------------------------------------------+
16634 |address_test|Use: routers**|Type: boolean|Default: true|
16635 +-------------------------------------------------------+
16636
16637 If this option is set false, the router is skipped when routing is being tested
16638 by means of the -bt command line option. This can be a convenience when your
16639 first router sends messages to an external scanner, because it saves you having
16640 to set the "already scanned" indicator when testing real address routing.
16641
16642 +--------------------------------------------------------------+
16643 |cannot_route_message|Use: routers|Type: string*|Default: unset|
16644 +--------------------------------------------------------------+
16645
16646 This option specifies a text message that is used when an address cannot be
16647 routed because Exim has run out of routers. The default message is "Unrouteable
16648 address". This option is useful only on routers that have more set false, or on
16649 the very last router in a configuration, because the value that is used is
16650 taken from the last router that is considered. This includes a router that is
16651 skipped because its preconditions are not met, as well as a router that
16652 declines. For example, using the default configuration, you could put:
16653
16654 cannot_route_message = Remote domain not found in DNS
16655
16656 on the first router, which is a dnslookup router with more set false, and
16657
16658 cannot_route_message = Unknown local user
16659
16660 on the final router that checks for local users. If string expansion fails for
16661 this option, the default message is used. Unless the expansion failure was
16662 explicitly forced, a message about the failure is written to the main and panic
16663 logs, in addition to the normal message about the routing failure.
16664
16665 +------------------------------------------------------------+
16666 |caseful_local_part|Use: routers|Type: boolean|Default: false|
16667 +------------------------------------------------------------+
16668
16669 By default, routers handle the local parts of addresses in a case-insensitive
16670 manner, though the actual case is preserved for transmission with the message.
16671 If you want the case of letters to be significant in a router, you must set
16672 this option true. For individual router options that contain address or local
16673 part lists (for example, local_parts), case-sensitive matching can be turned on
16674 by "+caseful" as a list item. See section 10.20 for more details.
16675
16676 The value of the $local_part variable is forced to lower case while a router is
16677 running unless caseful_local_part is set. When a router assigns an address to a
16678 transport, the value of $local_part when the transport runs is the same as it
16679 was in the router. Similarly, when a router generates child addresses by
16680 aliasing or forwarding, the values of $original_local_part and
16681 $parent_local_part are those that were used by the redirecting router.
16682
16683 This option applies to the processing of an address by a router. When a
16684 recipient address is being processed in an ACL, there is a separate control
16685 modifier that can be used to specify case-sensitive processing within the ACL
16686 (see section 43.22).
16687
16688 +------------------------------------------------------------+
16689 |check_local_user|Use: routers**|Type: boolean|Default: false|
16690 +------------------------------------------------------------+
16691
16692 When this option is true, Exim checks that the local part of the recipient
16693 address (with affixes removed if relevant) is the name of an account on the
16694 local system. The check is done by calling the getpwnam() function rather than
16695 trying to read /etc/passwd directly. This means that other methods of holding
16696 password data (such as NIS) are supported. If the local part is a local user,
16697 $home is set from the password data, and can be tested in other preconditions
16698 that are evaluated after this one (the order of evaluation is given in section
16699 3.12). However, the value of $home can be overridden by router_home_directory.
16700 If the local part is not a local user, the router is skipped.
16701
16702 If you want to check that the local part is either the name of a local user or
16703 matches something else, you cannot combine check_local_user with a setting of
16704 local_parts, because that specifies the logical and of the two conditions.
16705 However, you can use a passwd lookup in a local_parts setting to achieve this.
16706 For example:
16707
16708 local_parts = passwd;$local_part : lsearch;/etc/other/users
16709
16710 Note, however, that the side effects of check_local_user (such as setting up a
16711 home directory) do not occur when a passwd lookup is used in a local_parts (or
16712 any other) precondition.
16713
16714 +-----------------------------------------------------+
16715 |condition|Use: routers**|Type: string*|Default: unset|
16716 +-----------------------------------------------------+
16717
16718 This option specifies a general precondition test that has to succeed for the
16719 router to be called. The condition option is the last precondition to be
16720 evaluated (see section 3.12). The string is expanded, and if the result is a
16721 forced failure, or an empty string, or one of the strings "0" or "no" or
16722 "false" (checked without regard to the case of the letters), the router is
16723 skipped, and the address is offered to the next one.
16724
16725 If the result is any other value, the router is run (as this is the last
16726 precondition to be evaluated, all the other preconditions must be true).
16727
16728 This option is unusual in that multiple condition options may be present. All
16729 condition options must succeed.
16730
16731 The condition option provides a means of applying custom conditions to the
16732 running of routers. Note that in the case of a simple conditional expansion,
16733 the default expansion values are exactly what is wanted. For example:
16734
16735 condition = ${if >{$message_age}{600}}
16736
16737 Because of the default behaviour of the string expansion, this is equivalent to
16738
16739 condition = ${if >{$message_age}{600}{true}{}}
16740
16741 A multiple condition example, which succeeds:
16742
16743 condition = ${if >{$message_age}{600}}
16744 condition = ${if !eq{${lc:$local_part}}{postmaster}}
16745 condition = foobar
16746
16747 If the expansion fails (other than forced failure) delivery is deferred. Some
16748 of the other precondition options are common special cases that could in fact
16749 be specified using condition.
16750
16751 Historical note: We have condition on ACLs and on Routers. Routers are far
16752 older, and use one set of semantics. ACLs are newer and when they were created,
16753 the ACL condition process was given far stricter parse semantics. The bool{}
16754 expansion condition uses the same rules as ACLs. The bool_lax{} expansion
16755 condition uses the same rules as Routers. More pointedly, the bool_lax{} was
16756 written to match the existing Router rules processing behavior.
16757
16758 This is best illustrated in an example:
16759
16760 # If used in an ACL condition will fail with a syntax error, but
16761 # in a router condition any extra characters are treated as a string
16762
16763 $ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
16764 true {yes} {no}}
16765
16766 $ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}'
16767 {yes} {no}}
16768
16769 In each example above, the if statement actually ends after "{google.com}}".
16770 Since no true or false braces were defined, the default if behavior is to
16771 return a boolean true or a null answer (which evaluates to false). The rest of
16772 the line is then treated as a string. So the first example resulted in the
16773 boolean answer "true" with the string " {yes} {no}}" appended to it. The second
16774 example resulted in the null output (indicating false) with the string " {yes}
16775 {no}}" appended to it.
16776
16777 In fact you can put excess forward braces in too. In the router condition,
16778 Exim's parser only looks for "{" symbols when they mean something, like after a
16779 "$" or when required as part of a conditional. But otherwise "{" and "}" are
16780 treated as ordinary string characters.
16781
16782 Thus, in a Router, the above expansion strings will both always evaluate true,
16783 as the result of expansion is a non-empty string which doesn't match an
16784 explicit false value. This can be tricky to debug. By contrast, in an ACL
16785 either of those strings will always result in an expansion error because the
16786 result doesn't look sufficiently boolean.
16787
16788 +-----------------------------------------------------+
16789 |debug_print|Use: routers|Type: string*|Default: unset|
16790 +-----------------------------------------------------+
16791
16792 If this option is set and debugging is enabled (see the -d command line option)
16793 or in address-testing mode (see the -bt command line option), the string is
16794 expanded and included in the debugging output. If expansion of the string
16795 fails, the error message is written to the debugging output, and Exim carries
16796 on processing. This option is provided to help with checking out the values of
16797 variables and so on when debugging router configurations. For example, if a
16798 condition option appears not to be working, debug_print can be used to output
16799 the variables it references. The output happens after checks for domains,
16800 local_parts, and check_local_user but before any other preconditions are
16801 tested. A newline is added to the text if it does not end with one. The
16802 variable $router_name contains the name of the router.
16803
16804 +---------------------------------------------------------+
16805 |disable_logging|Use: routers|Type: boolean|Default: false|
16806 +---------------------------------------------------------+
16807
16808 If this option is set true, nothing is logged for any routing errors or for any
16809 deliveries caused by this router. You should not set this option unless you
16810 really, really know what you are doing. See also the generic transport option
16811 of the same name.
16812
16813 +---------------------------------------------------------------------+
16814 |dnssec_request_domains|Use: routers|Type: domain list*|Default: unset|
16815 +---------------------------------------------------------------------+
16816
16817 DNS lookups for domains matching dnssec_request_domains will be done with the
16818 dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup
16819 sequence.
16820
16821 +---------------------------------------------------------------------+
16822 |dnssec_require_domains|Use: routers|Type: domain list*|Default: unset|
16823 +---------------------------------------------------------------------+
16824
16825 DNS lookups for domains matching dnssec_require_domains will be done with the
16826 dnssec request bit set. Any returns not having the Authenticated Data bit (AD
16827 bit) set will be ignored and logged as a host-lookup failure. This applies to
16828 all of the SRV, MX, AAAA, A lookup sequence.
16829
16830 +--------------------------------------------------------+
16831 |domains|Use: routers**|Type: domain list*|Default: unset|
16832 +--------------------------------------------------------+
16833
16834 If this option is set, the router is skipped unless the current domain matches
16835 the list. If the match is achieved by means of a file lookup, the data that the
16836 lookup returned for the domain is placed in $domain_data for use in string
16837 expansions of the driver's private options. See section 3.12 for a list of the
16838 order in which preconditions are evaluated.
16839
16840 +-----------------------------------------------+
16841 |driver|Use: routers|Type: string|Default: unset|
16842 +-----------------------------------------------+
16843
16844 This option must always be set. It specifies which of the available routers is
16845 to be used.
16846
16847 +-----------------------------------------------------+
16848 |dsn_lasthop|Use: routers|Type: boolean|Default: false|
16849 +-----------------------------------------------------+
16850
16851 If this option is set true, and extended DSN (RFC3461) processing is in effect,
16852 Exim will not pass on DSN requests to downstream DSN-aware hosts but will
16853 instead send a success DSN as if the next hop does not support DSN. Not
16854 effective on redirect routers.
16855
16856 +---------------------------------------------------+
16857 |errors_to|Use: routers|Type: string*|Default: unset|
16858 +---------------------------------------------------+
16859
16860 If a router successfully handles an address, it may assign the address to a
16861 transport for delivery or it may generate child addresses. In both cases, if
16862 there is a delivery problem during later processing, the resulting bounce
16863 message is sent to the address that results from expanding this string,
16864 provided that the address verifies successfully. The errors_to option is
16865 expanded before headers_add, headers_remove, and transport.
16866
16867 The errors_to setting associated with an address can be overridden if it
16868 subsequently passes through other routers that have their own errors_to
16869 settings, or if the message is delivered by a transport with a return_path
16870 setting.
16871
16872 If errors_to is unset, or the expansion is forced to fail, or the result of the
16873 expansion fails to verify, the errors address associated with the incoming
16874 address is used. At top level, this is the envelope sender. A non-forced
16875 expansion failure causes delivery to be deferred.
16876
16877 If an address for which errors_to has been set ends up being delivered over
16878 SMTP, the envelope sender for that delivery is the errors_to value, so that any
16879 bounces that are generated by other MTAs on the delivery route are also sent
16880 there. You can set errors_to to the empty string by either of these settings:
16881
16882 errors_to =
16883 errors_to = ""
16884
16885 An expansion item that yields an empty string has the same effect. If you do
16886 this, a locally detected delivery error for addresses processed by this router
16887 no longer gives rise to a bounce message; the error is discarded. If the
16888 address is delivered to a remote host, the return path is set to "<>", unless
16889 overridden by the return_path option on the transport.
16890
16891 If for some reason you want to discard local errors, but use a non-empty MAIL
16892 command for remote delivery, you can preserve the original return path in
16893 $address_data in the router, and reinstate it in the transport by setting
16894 return_path.
16895
16896 The most common use of errors_to is to direct mailing list bounces to the
16897 manager of the list, as described in section 50.2, or to implement VERP
16898 (Variable Envelope Return Paths) (see section 50.6).
16899
16900 +-----------------------------------------------+
16901 |expn|Use: routers**|Type: boolean|Default: true|
16902 +-----------------------------------------------+
16903
16904 If this option is turned off, the router is skipped when testing an address as
16905 a result of processing an SMTP EXPN command. You might, for example, want to
16906 turn it off on a router for users' .forward files, while leaving it on for the
16907 system alias file. See section 3.12 for a list of the order in which
16908 preconditions are evaluated.
16909
16910 The use of the SMTP EXPN command is controlled by an ACL (see chapter 43). When
16911 Exim is running an EXPN command, it is similar to testing an address with -bt.
16912 Compare VRFY, whose counterpart is -bv.
16913
16914 +-----------------------------------------------------+
16915 |fail_verify|Use: routers|Type: boolean|Default: false|
16916 +-----------------------------------------------------+
16917
16918 Setting this option has the effect of setting both fail_verify_sender and
16919 fail_verify_recipient to the same value.
16920
16921 +---------------------------------------------------------------+
16922 |fail_verify_recipient|Use: routers|Type: boolean|Default: false|
16923 +---------------------------------------------------------------+
16924
16925 If this option is true and an address is accepted by this router when verifying
16926 a recipient, verification fails.
16927
16928 +------------------------------------------------------------+
16929 |fail_verify_sender|Use: routers|Type: boolean|Default: false|
16930 +------------------------------------------------------------+
16931
16932 If this option is true and an address is accepted by this router when verifying
16933 a sender, verification fails.
16934
16935 +------------------------------------------------------------+
16936 |fallback_hosts|Use: routers|Type: string list|Default: unset|
16937 +------------------------------------------------------------+
16938
16939 String expansion is not applied to this option. The argument must be a
16940 colon-separated list of host names or IP addresses. The list separator can be
16941 changed (see section 6.21), and a port can be specified with each name or
16942 address. In fact, the format of each item is exactly the same as defined for
16943 the list of hosts in a manualroute router (see section 20.5).
16944
16945 If a router queues an address for a remote transport, this host list is
16946 associated with the address, and used instead of the transport's fallback host
16947 list. If hosts_randomize is set on the transport, the order of the list is
16948 randomized for each use. See the fallback_hosts option of the smtp transport
16949 for further details.
16950
16951 +---------------------------------------------------+
16952 |group|Use: routers|Type: string*|Default: see below|
16953 +---------------------------------------------------+
16954
16955 When a router queues an address for a transport, and the transport does not
16956 specify a group, the group given here is used when running the delivery
16957 process. The group may be specified numerically or by name. If expansion fails,
16958 the error is logged and delivery is deferred. The default is unset, unless
16959 check_local_user is set, when the default is taken from the password
16960 information. See also initgroups and user and the discussion in chapter 23.
16961
16962 +---------------------------------------------------+
16963 |headers_add|Use: routers|Type: list*|Default: unset|
16964 +---------------------------------------------------+
16965
16966 This option specifies a list of text headers, newline-separated (by default,
16967 changeable in the usual way 6.21), that is associated with any addresses that
16968 are accepted by the router. Each item is separately expanded, at routing time.
16969 However, this option has no effect when an address is just being verified. The
16970 way in which the text is used to add header lines at transport time is
16971 described in section 47.17. New header lines are not actually added until the
16972 message is in the process of being transported. This means that references to
16973 header lines in string expansions in the transport's configuration do not "see"
16974 the added header lines.
16975
16976 The headers_add option is expanded after errors_to, but before headers_remove
16977 and transport. If an item is empty, or if an item expansion is forced to fail,
16978 the item has no effect. Other expansion failures are treated as configuration
16979 errors.
16980
16981 Unlike most options, headers_add can be specified multiple times for a router;
16982 all listed headers are added.
16983
16984 Warning 1: The headers_add option cannot be used for a redirect router that has
16985 the one_time option set.
16986
16987 Warning 2: If the unseen option is set on the router, all header additions are
16988 deleted when the address is passed on to subsequent routers. For a redirect
16989 router, if a generated address is the same as the incoming address, this can
16990 lead to duplicate addresses with different header modifications. Exim does not
16991 do duplicate deliveries (except, in certain circumstances, to pipes -- see
16992 section 22.7), but it is undefined which of the duplicates is discarded, so
16993 this ambiguous situation should be avoided. The repeat_use option of the
16994 redirect router may be of help.
16995
16996 +------------------------------------------------------+
16997 |headers_remove|Use: routers|Type: list*|Default: unset|
16998 +------------------------------------------------------+
16999
17000 This option specifies a list of text headers, colon-separated (by default,
17001 changeable in the usual way 6.21), that is associated with any addresses that
17002 are accepted by the router. Each item is separately expanded, at routing time.
17003 However, this option has no effect when an address is just being verified. The
17004 way in which the text is used to remove header lines at transport time is
17005 described in section 47.17. Header lines are not actually removed until the
17006 message is in the process of being transported. This means that references to
17007 header lines in string expansions in the transport's configuration still "see"
17008 the original header lines.
17009
17010 The headers_remove option is expanded after errors_to and headers_add, but
17011 before transport. If an item expansion is forced to fail, the item has no
17012 effect. Other expansion failures are treated as configuration errors.
17013
17014 Unlike most options, headers_remove can be specified multiple times for a
17015 router; all listed headers are removed.
17016
17017 Warning 1: The headers_remove option cannot be used for a redirect router that
17018 has the one_time option set.
17019
17020 Warning 2: If the unseen option is set on the router, all header removal
17021 requests are deleted when the address is passed on to subsequent routers, and
17022 this can lead to problems with duplicates -- see the similar warning for
17023 headers_add above.
17024
17025 Warning 3: Because of the separate expansion of the list items, items that
17026 contain a list separator must have it doubled. To avoid this, change the list
17027 separator (6.21).
17028
17029 +----------------------------------------------------------------+
17030 |ignore_target_hosts|Use: routers|Type: host list*|Default: unset|
17031 +----------------------------------------------------------------+
17032
17033 Although this option is a host list, it should normally contain IP address
17034 entries rather than names. If any host that is looked up by the router has an
17035 IP address that matches an item in this list, Exim behaves as if that IP
17036 address did not exist. This option allows you to cope with rogue DNS entries
17037 like
17038
17039 remote.domain.example. A 127.0.0.1
17040
17041 by setting
17042
17043 ignore_target_hosts = 127.0.0.1
17044
17045 on the relevant router. If all the hosts found by a dnslookup router are
17046 discarded in this way, the router declines. In a conventional configuration, an
17047 attempt to mail to such a domain would normally provoke the "unrouteable
17048 domain" error, and an attempt to verify an address in the domain would fail.
17049 Similarly, if ignore_target_hosts is set on an ipliteral router, the router
17050 declines if presented with one of the listed addresses.
17051
17052 You can use this option to disable the use of IPv4 or IPv6 for mail delivery by
17053 means of the first or the second of the following settings, respectively:
17054
17055 ignore_target_hosts = 0.0.0.0/0
17056 ignore_target_hosts = <; 0::0/0
17057
17058 The pattern in the first line matches all IPv4 addresses, whereas the pattern
17059 in the second line matches all IPv6 addresses.
17060
17061 This option may also be useful for ignoring link-local and site-local IPv6
17062 addresses. Because, like all host lists, the value of ignore_target_hosts is
17063 expanded before use as a list, it is possible to make it dependent on the
17064 domain that is being routed.
17065
17066 During its expansion, $host_address is set to the IP address that is being
17067 checked.
17068
17069 +----------------------------------------------------+
17070 |initgroups|Use: routers|Type: boolean|Default: false|
17071 +----------------------------------------------------+
17072
17073 If the router queues an address for a transport, and this option is true, and
17074 the uid supplied by the router is not overridden by the transport, the
17075 initgroups() function is called when running the transport to ensure that any
17076 additional groups associated with the uid are set up. See also group and user
17077 and the discussion in chapter 23.
17078
17079 +-----------------------------------------------------------------+
17080 |local_part_prefix|Use: routers**|Type: string list|Default: unset|
17081 +-----------------------------------------------------------------+
17082
17083 If this option is set, the router is skipped unless the local part starts with
17084 one of the given strings, or local_part_prefix_optional is true. See section
17085 3.12 for a list of the order in which preconditions are evaluated.
17086
17087 The list is scanned from left to right, and the first prefix that matches is
17088 used. A limited form of wildcard is available; if the prefix begins with an
17089 asterisk, it matches the longest possible sequence of arbitrary characters at
17090 the start of the local part. An asterisk should therefore always be followed by
17091 some character that does not occur in normal local parts. Wildcarding can be
17092 used to set up multiple user mailboxes, as described in section 50.8.
17093
17094 During the testing of the local_parts option, and while the router is running,
17095 the prefix is removed from the local part, and is available in the expansion
17096 variable $local_part_prefix. When a message is being delivered, if the router
17097 accepts the address, this remains true during subsequent delivery by a
17098 transport. In particular, the local part that is transmitted in the RCPT
17099 command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default.
17100 This behaviour can be overridden by setting rcpt_include_affixes true on the
17101 relevant transport.
17102
17103 When an address is being verified, local_part_prefix affects only the behaviour
17104 of the router. If the callout feature of verification is in use, this means
17105 that the full address, including the prefix, will be used during the callout.
17106
17107 The prefix facility is commonly used to handle local parts of the form
17108 owner-something. Another common use is to support local parts of the form
17109 real-username to bypass a user's .forward file - helpful when trying to tell a
17110 user their forwarding is broken - by placing a router like this one immediately
17111 before the router that handles .forward files:
17112
17113 real_localuser:
17114 driver = accept
17115 local_part_prefix = real-
17116 check_local_user
17117 transport = local_delivery
17118
17119 For security, it would probably be a good idea to restrict the use of this
17120 router to locally-generated messages, using a condition such as this:
17121
17122 condition = ${if match {$sender_host_address}\
17123 {\N^(|127\.0\.0\.1)$\N}}
17124
17125 If both local_part_prefix and local_part_suffix are set for a router, both
17126 conditions must be met if not optional. Care must be taken if wildcards are
17127 used in both a prefix and a suffix on the same router. Different separator
17128 characters must be used to avoid ambiguity.
17129
17130 +--------------------------------------------------------------------+
17131 |local_part_prefix_optional|Use: routers|Type: boolean|Default: false|
17132 +--------------------------------------------------------------------+
17133
17134 See local_part_prefix above.
17135
17136 +-----------------------------------------------------------------+
17137 |local_part_suffix|Use: routers**|Type: string list|Default: unset|
17138 +-----------------------------------------------------------------+
17139
17140 This option operates in the same way as local_part_prefix, except that the
17141 local part must end (rather than start) with the given string, the
17142 local_part_suffix_optional option determines whether the suffix is mandatory,
17143 and the wildcard * character, if present, must be the last character of the
17144 suffix. This option facility is commonly used to handle local parts of the form
17145 something-request and multiple user mailboxes of the form username-foo.
17146
17147 +--------------------------------------------------------------------+
17148 |local_part_suffix_optional|Use: routers|Type: boolean|Default: false|
17149 +--------------------------------------------------------------------+
17150
17151 See local_part_suffix above.
17152
17153 +----------------------------------------------------------------+
17154 |local_parts|Use: routers**|Type: local part list*|Default: unset|
17155 +----------------------------------------------------------------+
17156
17157 The router is run only if the local part of the address matches the list. See
17158 section 3.12 for a list of the order in which preconditions are evaluated, and
17159 section 10.21 for a discussion of local part lists. Because the string is
17160 expanded, it is possible to make it depend on the domain, for example:
17161
17162 local_parts = dbm;/usr/local/specials/$domain
17163
17164 If the match is achieved by a lookup, the data that the lookup returned for the
17165 local part is placed in the variable $local_part_data for use in expansions of
17166 the router's private options. You might use this option, for example, if you
17167 have a large number of local virtual domains, and you want to send all
17168 postmaster mail to the same place without having to set up an alias in each
17169 virtual domain:
17170
17171 postmaster:
17172 driver = redirect
17173 local_parts = postmaster
17174 data = postmaster@real.domain.example
17175
17176 +----------------------------------------------------------+
17177 |log_as_local|Use: routers|Type: boolean|Default: see below|
17178 +----------------------------------------------------------+
17179
17180 Exim has two logging styles for delivery, the idea being to make local
17181 deliveries stand out more visibly from remote ones. In the "local" style, the
17182 recipient address is given just as the local part, without a domain. The use of
17183 this style is controlled by this option. It defaults to true for the accept
17184 router, and false for all the others. This option applies only when a router
17185 assigns an address to a transport. It has no effect on routers that redirect
17186 addresses.
17187
17188 +----------------------------------------------+
17189 |more|Use: routers|Type: boolean*|Default: true|
17190 +----------------------------------------------+
17191
17192 The result of string expansion for this option must be a valid boolean value,
17193 that is, one of the strings "yes", "no", "true", or "false". Any other result
17194 causes an error, and delivery is deferred. If the expansion is forced to fail,
17195 the default value for the option (true) is used. Other failures cause delivery
17196 to be deferred.
17197
17198 If this option is set false, and the router declines to handle the address, no
17199 further routers are tried, routing fails, and the address is bounced. However,
17200 if the router explicitly passes an address to the following router by means of
17201 the setting
17202
17203 self = pass
17204
17205 or otherwise, the setting of more is ignored. Also, the setting of more does
17206 not affect the behaviour if one of the precondition tests fails. In that case,
17207 the address is always passed to the next router.
17208
17209 Note that address_data is not considered to be a precondition. If its expansion
17210 is forced to fail, the router declines, and the value of more controls what
17211 happens next.
17212
17213 +---------------------------------------------------------+
17214 |pass_on_timeout|Use: routers|Type: boolean|Default: false|
17215 +---------------------------------------------------------+
17216
17217 If a router times out during a host lookup, it normally causes deferral of the
17218 address. If pass_on_timeout is set, the address is passed on to the next
17219 router, overriding no_more. This may be helpful for systems that are
17220 intermittently connected to the Internet, or those that want to pass to a smart
17221 host any messages that cannot immediately be delivered.
17222
17223 There are occasional other temporary errors that can occur while doing DNS
17224 lookups. They are treated in the same way as a timeout, and this option applies
17225 to all of them.
17226
17227 +----------------------------------------------------+
17228 |pass_router|Use: routers|Type: string|Default: unset|
17229 +----------------------------------------------------+
17230
17231 Routers that recognize the generic self option (dnslookup, ipliteral, and
17232 manualroute) are able to return "pass", forcing routing to continue, and
17233 overriding a false setting of more. When one of these routers returns "pass",
17234 the address is normally handed on to the next router in sequence. This can be
17235 changed by setting pass_router to the name of another router. However (unlike
17236 redirect_router) the named router must be below the current router, to avoid
17237 loops. Note that this option applies only to the special case of "pass". It
17238 does not apply when a router returns "decline" because it cannot handle an
17239 address.
17240
17241 +--------------------------------------------------------+
17242 |redirect_router|Use: routers|Type: string|Default: unset|
17243 +--------------------------------------------------------+
17244
17245 Sometimes an administrator knows that it is pointless to reprocess addresses
17246 generated from alias or forward files with the same router again. For example,
17247 if an alias file translates real names into login ids there is no point
17248 searching the alias file a second time, especially if it is a large file.
17249
17250 The redirect_router option can be set to the name of any router instance. It
17251 causes the routing of any generated addresses to start at the named router
17252 instead of at the first router. This option has no effect if the router in
17253 which it is set does not generate new addresses.
17254
17255 +--------------------------------------------------------------+
17256 |require_files|Use: routers**|Type: string list*|Default: unset|
17257 +--------------------------------------------------------------+
17258
17259 This option provides a general mechanism for predicating the running of a
17260 router on the existence or non-existence of certain files or directories.
17261 Before running a router, as one of its precondition tests, Exim works its way
17262 through the require_files list, expanding each item separately.
17263
17264 Because the list is split before expansion, any colons in expansion items must
17265 be doubled, or the facility for using a different list separator must be used (
17266 6.21). If any expansion is forced to fail, the item is ignored. Other expansion
17267 failures cause routing of the address to be deferred.
17268
17269 If any expanded string is empty, it is ignored. Otherwise, except as described
17270 below, each string must be a fully qualified file path, optionally preceded by
17271 "!". The paths are passed to the stat() function to test for the existence of
17272 the files or directories. The router is skipped if any paths not preceded by "!
17273 " do not exist, or if any paths preceded by "!" do exist.
17274
17275 If stat() cannot determine whether a file exists or not, delivery of the
17276 message is deferred. This can happen when NFS-mounted filesystems are
17277 unavailable.
17278
17279 This option is checked after the domains, local_parts, and senders options, so
17280 you cannot use it to check for the existence of a file in which to look up a
17281 domain, local part, or sender. (See section 3.12 for a full list of the order
17282 in which preconditions are evaluated.) However, as these options are all
17283 expanded, you can use the exists expansion condition to make such tests. The
17284 require_files option is intended for checking files that the router may be
17285 going to use internally, or which are needed by a transport (e.g., .procmailrc
17286 ).
17287
17288 During delivery, the stat() function is run as root, but there is a facility
17289 for some checking of the accessibility of a file by another user. This is not a
17290 proper permissions check, but just a "rough" check that operates as follows:
17291
17292 If an item in a require_files list does not contain any forward slash
17293 characters, it is taken to be the user (and optional group, separated by a
17294 comma) to be checked for subsequent files in the list. If no group is specified
17295 but the user is specified symbolically, the gid associated with the uid is
17296 used. For example:
17297
17298 require_files = mail:/some/file
17299 require_files = $local_part:$home/.procmailrc
17300
17301 If a user or group name in a require_files list does not exist, the
17302 require_files condition fails.
17303
17304 Exim performs the check by scanning along the components of the file path, and
17305 checking the access for the given uid and gid. It checks for "x" access on
17306 directories, and "r" access on the final file. Note that this means that file
17307 access control lists, if the operating system has them, are ignored.
17308
17309 Warning 1: When the router is being run to verify addresses for an incoming
17310 SMTP message, Exim is not running as root, but under its own uid. This may
17311 affect the result of a require_files check. In particular, stat() may yield the
17312 error EACCES ("Permission denied"). This means that the Exim user is not
17313 permitted to read one of the directories on the file's path.
17314
17315 Warning 2: Even when Exim is running as root while delivering a message, stat()
17316 can yield EACCES for a file in an NFS directory that is mounted without root
17317 access. In this case, if a check for access by a particular user is requested,
17318 Exim creates a subprocess that runs as that user, and tries the check again in
17319 that process.
17320
17321 The default action for handling an unresolved EACCES is to consider it to be
17322 caused by a configuration error, and routing is deferred because the existence
17323 or non-existence of the file cannot be determined. However, in some
17324 circumstances it may be desirable to treat this condition as if the file did
17325 not exist. If the filename (or the exclamation mark that precedes the filename
17326 for non-existence) is preceded by a plus sign, the EACCES error is treated as
17327 if the file did not exist. For example:
17328
17329 require_files = +/some/file
17330
17331 If the router is not an essential part of verification (for example, it handles
17332 users' .forward files), another solution is to set the verify option false so
17333 that the router is skipped when verifying.
17334
17335 +------------------------------------------------------------------+
17336 |retry_use_local_part|Use: routers|Type: boolean|Default: see below|
17337 +------------------------------------------------------------------+
17338
17339 When a delivery suffers a temporary routing failure, a retry record is created
17340 in Exim's hints database. For addresses whose routing depends only on the
17341 domain, the key for the retry record should not involve the local part, but for
17342 other addresses, both the domain and the local part should be included.
17343 Usually, remote routing is of the former kind, and local routing is of the
17344 latter kind.
17345
17346 This option controls whether the local part is used to form the key for retry
17347 hints for addresses that suffer temporary errors while being handled by this
17348 router. The default value is true for any router that has check_local_user set,
17349 and false otherwise. Note that this option does not apply to hints keys for
17350 transport delays; they are controlled by a generic transport option of the same
17351 name.
17352
17353 The setting of retry_use_local_part applies only to the router on which it
17354 appears. If the router generates child addresses, they are routed
17355 independently; this setting does not become attached to them.
17356
17357 +---------------------------------------------------------------+
17358 |router_home_directory|Use: routers|Type: string*|Default: unset|
17359 +---------------------------------------------------------------+
17360
17361 This option sets a home directory for use while the router is running. (Compare
17362 transport_home_directory, which sets a home directory for later transporting.)
17363 In particular, if used on a redirect router, this option sets a value for $home
17364 while a filter is running. The value is expanded; forced expansion failure
17365 causes the option to be ignored - other failures cause the router to defer.
17366
17367 Expansion of router_home_directory happens immediately after the
17368 check_local_user test (if configured), before any further expansions take
17369 place. (See section 3.12 for a list of the order in which preconditions are
17370 evaluated.) While the router is running, router_home_directory overrides the
17371 value of $home that came from check_local_user.
17372
17373 When a router accepts an address and assigns it to a local transport (including
17374 the cases when a redirect router generates a pipe, file, or autoreply
17375 delivery), the home directory setting for the transport is taken from the first
17376 of these values that is set:
17377
17378 * The home_directory option on the transport;
17379
17380 * The transport_home_directory option on the router;
17381
17382 * The password data if check_local_user is set on the router;
17383
17384 * The router_home_directory option on the router.
17385
17386 In other words, router_home_directory overrides the password data for the
17387 router, but not for the transport.
17388
17389 +----------------------------------------------+
17390 |self|Use: routers|Type: string|Default: freeze|
17391 +----------------------------------------------+
17392
17393 This option applies to those routers that use a recipient address to find a
17394 list of remote hosts. Currently, these are the dnslookup, ipliteral, and
17395 manualroute routers. Certain configurations of the queryprogram router can also
17396 specify a list of remote hosts. Usually such routers are configured to send the
17397 message to a remote host via an smtp transport. The self option specifies what
17398 happens when the first host on the list turns out to be the local host. The way
17399 in which Exim checks for the local host is described in section 13.8.
17400
17401 Normally this situation indicates either an error in Exim's configuration (for
17402 example, the router should be configured not to process this domain), or an
17403 error in the DNS (for example, the MX should not point to this host). For this
17404 reason, the default action is to log the incident, defer the address, and
17405 freeze the message. The following alternatives are provided for use in special
17406 cases:
17407
17408 defer
17409
17410 Delivery of the message is tried again later, but the message is not
17411 frozen.
17412
17413 reroute: <domain>
17414
17415 The domain is changed to the given domain, and the address is passed back
17416 to be reprocessed by the routers. No rewriting of headers takes place. This
17417 behaviour is essentially a redirection.
17418
17419 reroute: rewrite: <domain>
17420
17421 The domain is changed to the given domain, and the address is passed back
17422 to be reprocessed by the routers. Any headers that contain the original
17423 domain are rewritten.
17424
17425 pass
17426
17427 The router passes the address to the next router, or to the router named in
17428 the pass_router option if it is set. This overrides no_more. During
17429 subsequent routing and delivery, the variable $self_hostname contains the
17430 name of the local host that the router encountered. This can be used to
17431 distinguish between different cases for hosts with multiple names. The
17432 combination
17433
17434 self = pass
17435 no_more
17436
17437 ensures that only those addresses that routed to the local host are passed
17438 on. Without no_more, addresses that were declined for other reasons would
17439 also be passed to the next router.
17440
17441 fail
17442
17443 Delivery fails and an error report is generated.
17444
17445 send
17446
17447 The anomaly is ignored and the address is queued for the transport. This
17448 setting should be used with extreme caution. For an smtp transport, it
17449 makes sense only in cases where the program that is listening on the SMTP
17450 port is not this version of Exim. That is, it must be some other MTA, or
17451 Exim with a different configuration file that handles the domain in another
17452 way.
17453
17454 +---------------------------------------------------------+
17455 |senders|Use: routers**|Type: address list*|Default: unset|
17456 +---------------------------------------------------------+
17457
17458 If this option is set, the router is skipped unless the message's sender
17459 address matches something on the list. See section 3.12 for a list of the order
17460 in which preconditions are evaluated.
17461
17462 There are issues concerning verification when the running of routers is
17463 dependent on the sender. When Exim is verifying the address in an errors_to
17464 setting, it sets the sender to the null string. When using the -bt option to
17465 check a configuration file, it is necessary also to use the -f option to set an
17466 appropriate sender. For incoming mail, the sender is unset when verifying the
17467 sender, but is available when verifying any recipients. If the SMTP VRFY
17468 command is enabled, it must be used after MAIL if the sender address matters.
17469
17470 +--------------------------------------------------------------+
17471 |translate_ip_address|Use: routers|Type: string*|Default: unset|
17472 +--------------------------------------------------------------+
17473
17474 There exist some rare networking situations (for example, packet radio) where
17475 it is helpful to be able to translate IP addresses generated by normal routing
17476 mechanisms into other IP addresses, thus performing a kind of manual IP
17477 routing. This should be done only if the normal IP routing of the TCP/IP stack
17478 is inadequate or broken. Because this is an extremely uncommon requirement, the
17479 code to support this option is not included in the Exim binary unless
17480 SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in Local/Makefile.
17481
17482 The translate_ip_address string is expanded for every IP address generated by
17483 the router, with the generated address set in $host_address. If the expansion
17484 is forced to fail, no action is taken. For any other expansion error, delivery
17485 of the message is deferred. If the result of the expansion is an IP address,
17486 that replaces the original address; otherwise the result is assumed to be a
17487 host name - this is looked up using gethostbyname() (or getipnodebyname() when
17488 available) to produce one or more replacement IP addresses. For example, to
17489 subvert all IP addresses in some specific networks, this could be added to a
17490 router:
17491
17492 translate_ip_address = \
17493 ${lookup{${mask:$host_address/26}}lsearch{/some/file}\
17494 {$value}fail}}
17495
17496 The file would contain lines like
17497
17498 10.2.3.128/26 some.host
17499 10.8.4.34/26 10.44.8.15
17500
17501 You should not make use of this facility unless you really understand what you
17502 are doing.
17503
17504 +---------------------------------------------------+
17505 |transport|Use: routers|Type: string*|Default: unset|
17506 +---------------------------------------------------+
17507
17508 This option specifies the transport to be used when a router accepts an address
17509 and sets it up for delivery. A transport is never needed if a router is used
17510 only for verification. The value of the option is expanded at routing time,
17511 after the expansion of errors_to, headers_add, and headers_remove, and result
17512 must be the name of one of the configured transports. If it is not, delivery is
17513 deferred.
17514
17515 The transport option is not used by the redirect router, but it does have some
17516 private options that set up transports for pipe and file deliveries (see
17517 chapter 22).
17518
17519 +---------------------------------------------------------------------+
17520 |transport_current_directory|Use: routers|Type: string*|Default: unset|
17521 +---------------------------------------------------------------------+
17522
17523 This option associates a current directory with any address that is routed to a
17524 local transport. This can happen either because a transport is explicitly
17525 configured for the router, or because it generates a delivery to a file or a
17526 pipe. During the delivery process (that is, at transport time), this option
17527 string is expanded and is set as the current directory, unless overridden by a
17528 setting on the transport. If the expansion fails for any reason, including
17529 forced failure, an error is logged, and delivery is deferred. See chapter 23
17530 for details of the local delivery environment.
17531
17532 +----------------------------------------------------------------------+
17533 |transport_home_directory|Use: routers|Type: string*|Default: see below|
17534 +----------------------------------------------------------------------+
17535
17536 This option associates a home directory with any address that is routed to a
17537 local transport. This can happen either because a transport is explicitly
17538 configured for the router, or because it generates a delivery to a file or a
17539 pipe. During the delivery process (that is, at transport time), the option
17540 string is expanded and is set as the home directory, unless overridden by a
17541 setting of home_directory on the transport. If the expansion fails for any
17542 reason, including forced failure, an error is logged, and delivery is deferred.
17543
17544 If the transport does not specify a home directory, and
17545 transport_home_directory is not set for the router, the home directory for the
17546 transport is taken from the password data if check_local_user is set for the
17547 router. Otherwise it is taken from router_home_directory if that option is set;
17548 if not, no home directory is set for the transport.
17549
17550 See chapter 23 for further details of the local delivery environment.
17551
17552 +-------------------------------------------------+
17553 |unseen|Use: routers|Type: boolean*|Default: false|
17554 +-------------------------------------------------+
17555
17556 The result of string expansion for this option must be a valid boolean value,
17557 that is, one of the strings "yes", "no", "true", or "false". Any other result
17558 causes an error, and delivery is deferred. If the expansion is forced to fail,
17559 the default value for the option (false) is used. Other failures cause delivery
17560 to be deferred.
17561
17562 When this option is set true, routing does not cease if the router accepts the
17563 address. Instead, a copy of the incoming address is passed to the next router,
17564 overriding a false setting of more. There is little point in setting more false
17565 if unseen is always true, but it may be useful in cases when the value of
17566 unseen contains expansion items (and therefore, presumably, is sometimes true
17567 and sometimes false).
17568
17569 Setting the unseen option has a similar effect to the unseen command qualifier
17570 in filter files. It can be used to cause copies of messages to be delivered to
17571 some other destination, while also carrying out a normal delivery. In effect,
17572 the current address is made into a "parent" that has two children - one that is
17573 delivered as specified by this router, and a clone that goes on to be routed
17574 further. For this reason, unseen may not be combined with the one_time option
17575 in a redirect router.
17576
17577 Warning: Header lines added to the address (or specified for removal) by this
17578 router or by previous routers affect the "unseen" copy of the message only. The
17579 clone that continues to be processed by further routers starts with no added
17580 headers and none specified for removal. For a redirect router, if a generated
17581 address is the same as the incoming address, this can lead to duplicate
17582 addresses with different header modifications. Exim does not do duplicate
17583 deliveries (except, in certain circumstances, to pipes -- see section 22.7),
17584 but it is undefined which of the duplicates is discarded, so this ambiguous
17585 situation should be avoided. The repeat_use option of the redirect router may
17586 be of help.
17587
17588 Unlike the handling of header modifications, any data that was set by the
17589 address_data option in the current or previous routers is passed on to
17590 subsequent routers.
17591
17592 +--------------------------------------------------+
17593 |user|Use: routers|Type: string*|Default: see below|
17594 +--------------------------------------------------+
17595
17596 When a router queues an address for a transport, and the transport does not
17597 specify a user, the user given here is used when running the delivery process.
17598 The user may be specified numerically or by name. If expansion fails, the error
17599 is logged and delivery is deferred. This user is also used by the redirect
17600 router when running a filter file. The default is unset, except when
17601 check_local_user is set. In this case, the default is taken from the password
17602 information. If the user is specified as a name, and group is not set, the
17603 group associated with the user is used. See also initgroups and group and the
17604 discussion in chapter 23.
17605
17606 +-------------------------------------------------+
17607 |verify|Use: routers**|Type: boolean|Default: true|
17608 +-------------------------------------------------+
17609
17610 Setting this option has the effect of setting verify_sender and
17611 verify_recipient to the same value.
17612
17613 +-------------------------------------------------------+
17614 |verify_only|Use: routers**|Type: boolean|Default: false|
17615 +-------------------------------------------------------+
17616
17617 If this option is set, the router is used only when verifying an address,
17618 delivering in cutthrough mode or testing with the -bv option, not when actually
17619 doing a delivery, testing with the -bt option, or running the SMTP EXPN
17620 command. It can be further restricted to verifying only senders or recipients
17621 by means of verify_sender and verify_recipient.
17622
17623 Warning: When the router is being run to verify addresses for an incoming SMTP
17624 message, Exim is not running as root, but under its own uid. If the router
17625 accesses any files, you need to make sure that they are accessible to the Exim
17626 user or group.
17627
17628 +-----------------------------------------------------------+
17629 |verify_recipient|Use: routers**|Type: boolean|Default: true|
17630 +-----------------------------------------------------------+
17631
17632 If this option is false, the router is skipped when verifying recipient
17633 addresses, delivering in cutthrough mode or testing recipient verification
17634 using -bv. See section 3.12 for a list of the order in which preconditions are
17635 evaluated. See also the $verify_mode variable.
17636
17637 +--------------------------------------------------------+
17638 |verify_sender|Use: routers**|Type: boolean|Default: true|
17639 +--------------------------------------------------------+
17640
17641 If this option is false, the router is skipped when verifying sender addresses
17642 or testing sender verification using -bvs. See section 3.12 for a list of the
17643 order in which preconditions are evaluated. See also the $verify_mode variable.
17644
17645
17646
17647 ===============================================================================
17648 16. THE ACCEPT ROUTER
17649
17650 The accept router has no private options of its own. Unless it is being used
17651 purely for verification (see verify_only) a transport is required to be defined
17652 by the generic transport option. If the preconditions that are specified by
17653 generic options are met, the router accepts the address and queues it for the
17654 given transport. The most common use of this router is for setting up
17655 deliveries to local mailboxes. For example:
17656
17657 localusers:
17658 driver = accept
17659 domains = mydomain.example
17660 check_local_user
17661 transport = local_delivery
17662
17663 The domains condition in this example checks the domain of the address, and
17664 check_local_user checks that the local part is the login of a local user. When
17665 both preconditions are met, the accept router runs, and queues the address for
17666 the local_delivery transport.
17667
17668
17669
17670 ===============================================================================
17671 17. THE DNSLOOKUP ROUTER
17672
17673 The dnslookup router looks up the hosts that handle mail for the recipient's
17674 domain in the DNS. A transport must always be set for this router, unless
17675 verify_only is set.
17676
17677 If SRV support is configured (see check_srv below), Exim first searches for SRV
17678 records. If none are found, or if SRV support is not configured, MX records are
17679 looked up. If no MX records exist, address records are sought. However,
17680 mx_domains can be set to disable the direct use of address records.
17681
17682 MX records of equal priority are sorted by Exim into a random order. Exim then
17683 looks for address records for the host names obtained from MX or SRV records.
17684 When a host has more than one IP address, they are sorted into a random order,
17685 except that IPv6 addresses are sorted before IPv4 addresses. If all the IP
17686 addresses found are discarded by a setting of the ignore_target_hosts generic
17687 option, the router declines.
17688
17689 Unless they have the highest priority (lowest MX value), MX records that point
17690 to the local host, or to any host name that matches hosts_treat_as_local, are
17691 discarded, together with any other MX records of equal or lower priority.
17692
17693 If the host pointed to by the highest priority MX record, or looked up as an
17694 address record, is the local host, or matches hosts_treat_as_local, what
17695 happens is controlled by the generic self option.
17696
17697
17698 17.1 Problems with DNS lookups
17699 ------------------------------
17700
17701 There have been problems with DNS servers when SRV records are looked up. Some
17702 misbehaving servers return a DNS error or timeout when a non-existent SRV
17703 record is sought. Similar problems have in the past been reported for MX
17704 records. The global dns_again_means_nonexist option can help with this problem,
17705 but it is heavy-handed because it is a global option.
17706
17707 For this reason, there are two options, srv_fail_domains and mx_fail_domains,
17708 that control what happens when a DNS lookup in a dnslookup router results in a
17709 DNS failure or a "try again" response. If an attempt to look up an SRV or MX
17710 record causes one of these results, and the domain matches the relevant list,
17711 Exim behaves as if the DNS had responded "no such record". In the case of an
17712 SRV lookup, this means that the router proceeds to look for MX records; in the
17713 case of an MX lookup, it proceeds to look for A or AAAA records, unless the
17714 domain matches mx_domains, in which case routing fails.
17715
17716
17717 17.2 Declining addresses by dnslookup
17718 -------------------------------------
17719
17720 There are a few cases where a dnslookup router will decline to accept an
17721 address; if such a router is expected to handle "all remaining non-local
17722 domains", then it is important to set no_more.
17723
17724 The router will defer rather than decline if the domain is found in the
17725 fail_defer_domains router option.
17726
17727 Reasons for a dnslookup router to decline currently include:
17728
17729 * The domain does not exist in DNS
17730
17731 * The domain exists but the MX record's host part is just "."; this is a
17732 common convention (borrowed from SRV) used to indicate that there is no
17733 such service for this domain and to not fall back to trying A/AAAA records.
17734
17735 * Ditto, but for SRV records, when check_srv is set on this router.
17736
17737 * MX record points to a non-existent host.
17738
17739 * MX record points to an IP address and the main section option
17740 allow_mx_to_ip is not set.
17741
17742 * MX records exist and point to valid hosts, but all hosts resolve only to
17743 addresses blocked by the ignore_target_hosts generic option on this router.
17744
17745 * The domain is not syntactically valid (see also allow_utf8_domains and
17746 dns_check_names_pattern for handling one variant of this)
17747
17748 * check_secondary_mx is set on this router but the local host can not be
17749 found in the MX records (see below)
17750
17751
17752 17.3 Private options for dnslookup
17753 ----------------------------------
17754
17755 The private options for the dnslookup router are as follows:
17756
17757 +--------------------------------------------------------------+
17758 |check_secondary_mx|Use: dnslookup|Type: boolean|Default: false|
17759 +--------------------------------------------------------------+
17760
17761 If this option is set, the router declines unless the local host is found in
17762 (and removed from) the list of hosts obtained by MX lookup. This can be used to
17763 process domains for which the local host is a secondary mail exchanger
17764 differently to other domains. The way in which Exim decides whether a host is
17765 the local host is described in section 13.8.
17766
17767 +-----------------------------------------------------+
17768 |check_srv|Use: dnslookup|Type: string*|Default: unset|
17769 +-----------------------------------------------------+
17770
17771 The dnslookup router supports the use of SRV records (see RFC 2782) in addition
17772 to MX and address records. The support is disabled by default. To enable SRV
17773 support, set the check_srv option to the name of the service required. For
17774 example,
17775
17776 check_srv = smtp
17777
17778 looks for SRV records that refer to the normal smtp service. The option is
17779 expanded, so the service name can vary from message to message or address to
17780 address. This might be helpful if SRV records are being used for a submission
17781 service. If the expansion is forced to fail, the check_srv option is ignored,
17782 and the router proceeds to look for MX records in the normal way.
17783
17784 When the expansion succeeds, the router searches first for SRV records for the
17785 given service (it assumes TCP protocol). A single SRV record with a host name
17786 that consists of just a single dot indicates "no such service for this domain";
17787 if this is encountered, the router declines. If other kinds of SRV record are
17788 found, they are used to construct a host list for delivery according to the
17789 rules of RFC 2782. MX records are not sought in this case.
17790
17791 When no SRV records are found, MX records (and address records) are sought in
17792 the traditional way. In other words, SRV records take precedence over MX
17793 records, just as MX records take precedence over address records. Note that
17794 this behaviour is not sanctioned by RFC 2782, though a previous draft RFC
17795 defined it. It is apparently believed that MX records are sufficient for email
17796 and that SRV records should not be used for this purpose. However, SRV records
17797 have an additional "weight" feature which some people might find useful when
17798 trying to split an SMTP load between hosts of different power.
17799
17800 See section 17.1 above for a discussion of Exim's behaviour when there is a DNS
17801 lookup error.
17802
17803 +-------------------------------------------------------------------+
17804 |fail_defer_domains|Use: dnslookup|Type: domain list*|Default: unset|
17805 +-------------------------------------------------------------------+
17806
17807 DNS lookups for domains matching fail_defer_domains which find no matching
17808 record will cause the router to defer rather than the default behaviour of
17809 decline. This maybe be useful for queueing messages for a newly created domain
17810 while the DNS configuration is not ready. However, it will result in any
17811 message with mistyped domains also being queued.
17812
17813 +-------------------------------------------+
17814 |ipv4_only|Use: string*|Type: unset|Default:|
17815 +-------------------------------------------+
17816
17817 The string is expanded, and if the result is anything but a forced failure, or
17818 an empty string, or one of the strings ?0? or ?no? or ?false? (checked without
17819 regard to the case of the letters), only A records are used.
17820
17821 +---------------------------------------------+
17822 |ipv4_prefer|Use: string*|Type: unset|Default:|
17823 +---------------------------------------------+
17824
17825 The string is expanded, and if the result is anything but a forced failure, or
17826 an empty string, or one of the strings ?0? or ?no? or ?false? (checked without
17827 regard to the case of the letters), A records are sorted before AAAA records
17828 (inverting the default).
17829
17830 +-----------------------------------------------------------+
17831 |mx_domains|Use: dnslookup|Type: domain list*|Default: unset|
17832 +-----------------------------------------------------------+
17833
17834 A domain that matches mx_domains is required to have either an MX or an SRV
17835 record in order to be recognized. (The name of this option could be improved.)
17836 For example, if all the mail hosts in fict.example are known to have MX
17837 records, except for those in discworld.fict.example, you could use this
17838 setting:
17839
17840 mx_domains = ! *.discworld.fict.example : *.fict.example
17841
17842 This specifies that messages addressed to a domain that matches the list but
17843 has no MX record should be bounced immediately instead of being routed using
17844 the address record.
17845
17846 +----------------------------------------------------------------+
17847 |mx_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
17848 +----------------------------------------------------------------+
17849
17850 If the DNS lookup for MX records for one of the domains in this list causes a
17851 DNS lookup error, Exim behaves as if no MX records were found. See section 17.1
17852 for more discussion.
17853
17854 +---------------------------------------------------------+
17855 |qualify_single|Use: dnslookup|Type: boolean|Default: true|
17856 +---------------------------------------------------------+
17857
17858 When this option is true, the resolver option RES_DEFNAMES is set for DNS
17859 lookups. Typically, but not standardly, this causes the resolver to qualify
17860 single-component names with the default domain. For example, on a machine
17861 called dictionary.ref.example, the domain thesaurus would be changed to
17862 thesaurus.ref.example inside the resolver. For details of what your resolver
17863 actually does, consult your man pages for resolver and resolv.conf.
17864
17865 +----------------------------------------------------------+
17866 |rewrite_headers|Use: dnslookup|Type: boolean|Default: true|
17867 +----------------------------------------------------------+
17868
17869 If the domain name in the address that is being processed is not fully
17870 qualified, it may be expanded to its full form by a DNS lookup. For example, if
17871 an address is specified as dormouse@teaparty, the domain might be expanded to
17872 teaparty.wonderland.fict.example. Domain expansion can also occur as a result
17873 of setting the widen_domains option. If rewrite_headers is true, all
17874 occurrences of the abbreviated domain name in any Bcc:, Cc:, From:, Reply-to:,
17875 Sender:, and To: header lines of the message are rewritten with the full domain
17876 name.
17877
17878 This option should be turned off only when it is known that no message is ever
17879 going to be sent outside an environment where the abbreviation makes sense.
17880
17881 When an MX record is looked up in the DNS and matches a wildcard record, name
17882 servers normally return a record containing the name that has been looked up,
17883 making it impossible to detect whether a wildcard was present or not. However,
17884 some name servers have recently been seen to return the wildcard entry. If the
17885 name returned by a DNS lookup begins with an asterisk, it is not used for
17886 header rewriting.
17887
17888 +--------------------------------------------------------------------+
17889 |same_domain_copy_routing|Use: dnslookup|Type: boolean|Default: false|
17890 +--------------------------------------------------------------------+
17891
17892 Addresses with the same domain are normally routed by the dnslookup router to
17893 the same list of hosts. However, this cannot be presumed, because the router
17894 options and preconditions may refer to the local part of the address. By
17895 default, therefore, Exim routes each address in a message independently. DNS
17896 servers run caches, so repeated DNS lookups are not normally expensive, and in
17897 any case, personal messages rarely have more than a few recipients.
17898
17899 If you are running mailing lists with large numbers of subscribers at the same
17900 domain, and you are using a dnslookup router which is independent of the local
17901 part, you can set same_domain_copy_routing to bypass repeated DNS lookups for
17902 identical domains in one message. In this case, when dnslookup routes an
17903 address to a remote transport, any other unrouted addresses in the message that
17904 have the same domain are automatically given the same routing without
17905 processing them independently, provided the following conditions are met:
17906
17907 * No router that processed the address specified headers_add or
17908 headers_remove.
17909
17910 * The router did not change the address in any way, for example, by
17911 "widening" the domain.
17912
17913 +----------------------------------------------------------+
17914 |search_parents|Use: dnslookup|Type: boolean|Default: false|
17915 +----------------------------------------------------------+
17916
17917 When this option is true, the resolver option RES_DNSRCH is set for DNS
17918 lookups. This is different from the qualify_single option in that it applies to
17919 domains containing dots. Typically, but not standardly, it causes the resolver
17920 to search for the name in the current domain and in parent domains. For
17921 example, on a machine in the fict.example domain, if looking up
17922 teaparty.wonderland failed, the resolver would try
17923 teaparty.wonderland.fict.example. For details of what your resolver actually
17924 does, consult your man pages for resolver and resolv.conf.
17925
17926 Setting this option true can cause problems in domains that have a wildcard MX
17927 record, because any domain that does not have its own MX record matches the
17928 local wildcard.
17929
17930 +-----------------------------------------------------------------+
17931 |srv_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
17932 +-----------------------------------------------------------------+
17933
17934 If the DNS lookup for SRV records for one of the domains in this list causes a
17935 DNS lookup error, Exim behaves as if no SRV records were found. See section
17936 17.1 for more discussion.
17937
17938 +-------------------------------------------------------------+
17939 |widen_domains|Use: dnslookup|Type: string list|Default: unset|
17940 +-------------------------------------------------------------+
17941
17942 If a DNS lookup fails and this option is set, each of its strings in turn is
17943 added onto the end of the domain, and the lookup is tried again. For example,
17944 if
17945
17946 widen_domains = fict.example:ref.example
17947
17948 is set and a lookup of klingon.dictionary fails,
17949 klingon.dictionary.fict.example is looked up, and if this fails,
17950 klingon.dictionary.ref.example is tried. Note that the qualify_single and
17951 search_parents options can cause some widening to be undertaken inside the DNS
17952 resolver. widen_domains is not applied to sender addresses when verifying,
17953 unless rewrite_headers is false (not the default).
17954
17955
17956 17.4 Effect of qualify_single and search_parents
17957 ------------------------------------------------
17958
17959 When a domain from an envelope recipient is changed by the resolver as a result
17960 of the qualify_single or search_parents options, Exim rewrites the
17961 corresponding address in the message's header lines unless rewrite_headers is
17962 set false. Exim then re-routes the address, using the full domain.
17963
17964 These two options affect only the DNS lookup that takes place inside the router
17965 for the domain of the address that is being routed. They do not affect lookups
17966 such as that implied by
17967
17968 domains = @mx_any
17969
17970 that may happen while processing a router precondition before the router is
17971 entered. No widening ever takes place for these lookups.
17972
17973
17974
17975 ===============================================================================
17976 18. THE IPLITERAL ROUTER
17977
17978 This router has no private options. Unless it is being used purely for
17979 verification (see verify_only) a transport is required to be defined by the
17980 generic transport option. The router accepts the address if its domain part
17981 takes the form of an RFC 2822 domain literal. For example, the ipliteral router
17982 handles the address
17983
17984 root@[192.168.1.1]
17985
17986 by setting up delivery to the host with that IP address. IPv4 domain literals
17987 consist of an IPv4 address enclosed in square brackets. IPv6 domain literals
17988 are similar, but the address is preceded by "ipv6:". For example:
17989
17990 postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678]
17991
17992 Exim allows "ipv4:" before IPv4 addresses, for consistency, and on the grounds
17993 that sooner or later somebody will try it.
17994
17995 If the IP address matches something in ignore_target_hosts, the router
17996 declines. If an IP literal turns out to refer to the local host, the generic
17997 self option determines what happens.
17998
17999 The RFCs require support for domain literals; however, their use is
18000 controversial in today's Internet. If you want to use this router, you must
18001 also set the main configuration option allow_domain_literals. Otherwise, Exim
18002 will not recognize the domain literal syntax in addresses.
18003
18004
18005
18006 ===============================================================================
18007 19. THE IPLOOKUP ROUTER
18008
18009 The iplookup router was written to fulfil a specific requirement in Cambridge
18010 University (which in fact no longer exists). For this reason, it is not
18011 included in the binary of Exim by default. If you want to include it, you must
18012 set
18013
18014 ROUTER_IPLOOKUP=yes
18015
18016 in your Local/Makefile configuration file.
18017
18018 The iplookup router routes an address by sending it over a TCP or UDP
18019 connection to one or more specific hosts. The host can then return the same or
18020 a different address - in effect rewriting the recipient address in the
18021 message's envelope. The new address is then passed on to subsequent routers. If
18022 this process fails, the address can be passed on to other routers, or delivery
18023 can be deferred. Since iplookup is just a rewriting router, a transport must
18024 not be specified for it.
18025
18026 +-----------------------------------------------+
18027 |hosts|Use: iplookup|Type: string|Default: unset|
18028 +-----------------------------------------------+
18029
18030 This option must be supplied. Its value is a colon-separated list of host
18031 names. The hosts are looked up using gethostbyname() (or getipnodebyname() when
18032 available) and are tried in order until one responds to the query. If none
18033 respond, what happens is controlled by optional.
18034
18035 +---------------------------------------------------+
18036 |optional|Use: iplookup|Type: boolean|Default: false|
18037 +---------------------------------------------------+
18038
18039 If optional is true, if no response is obtained from any host, the address is
18040 passed to the next router, overriding no_more. If optional is false, delivery
18041 to the address is deferred.
18042
18043 +-------------------------------------------+
18044 |port|Use: iplookup|Type: integer|Default: 0|
18045 +-------------------------------------------+
18046
18047 This option must be supplied. It specifies the port number for the TCP or UDP
18048 call.
18049
18050 +------------------------------------------------+
18051 |protocol|Use: iplookup|Type: string|Default: udp|
18052 +------------------------------------------------+
18053
18054 This option can be set to "udp" or "tcp" to specify which of the two protocols
18055 is to be used.
18056
18057 +----------------------------------------------------+
18058 |query|Use: iplookup|Type: string*|Default: see below|
18059 +----------------------------------------------------+
18060
18061 This defines the content of the query that is sent to the remote hosts. The
18062 default value is:
18063
18064 $local_part@$domain $local_part@$domain
18065
18066 The repetition serves as a way of checking that a response is to the correct
18067 query in the default case (see response_pattern below).
18068
18069 +--------------------------------------------------+
18070 |reroute|Use: iplookup|Type: string*|Default: unset|
18071 +--------------------------------------------------+
18072
18073 If this option is not set, the rerouted address is precisely the byte string
18074 returned by the remote host, up to the first white space, if any. If set, the
18075 string is expanded to form the rerouted address. It can include parts matched
18076 in the response by response_pattern by means of numeric variables such as $1,
18077 $2, etc. The variable $0 refers to the entire input string, whether or not a
18078 pattern is in use. In all cases, the rerouted address must end up in the form
18079 local_part@domain.
18080
18081 +----------------------------------------------------------+
18082 |response_pattern|Use: iplookup|Type: string|Default: unset|
18083 +----------------------------------------------------------+
18084
18085 This option can be set to a regular expression that is applied to the string
18086 returned from the remote host. If the pattern does not match the response, the
18087 router declines. If response_pattern is not set, no checking of the response is
18088 done, unless the query was defaulted, in which case there is a check that the
18089 text returned after the first white space is the original address. This checks
18090 that the answer that has been received is in response to the correct question.
18091 For example, if the response is just a new domain, the following could be used:
18092
18093 response_pattern = ^([^@]+)$
18094 reroute = $local_part@$1
18095
18096 +--------------------------------------------+
18097 |timeout|Use: iplookup|Type: time|Default: 5s|
18098 +--------------------------------------------+
18099
18100 This specifies the amount of time to wait for a response from the remote
18101 machine. The same timeout is used for the connect() function for a TCP call. It
18102 does not apply to UDP.
18103
18104
18105
18106 ===============================================================================
18107 20. THE MANUALROUTE ROUTER
18108
18109 The manualroute router is so-called because it provides a way of manually
18110 routing an address according to its domain. It is mainly used when you want to
18111 route addresses to remote hosts according to your own rules, bypassing the
18112 normal DNS routing that looks up MX records. However, manualroute can also
18113 route to local transports, a facility that may be useful if you want to save
18114 messages for dial-in hosts in local files.
18115
18116 The manualroute router compares a list of domain patterns with the domain it is
18117 trying to route. If there is no match, the router declines. Each pattern has
18118 associated with it a list of hosts and some other optional data, which may
18119 include a transport. The combination of a pattern and its data is called a
18120 "routing rule". For patterns that do not have an associated transport, the
18121 generic transport option must specify a transport, unless the router is being
18122 used purely for verification (see verify_only).
18123
18124 In the case of verification, matching the domain pattern is sufficient for the
18125 router to accept the address. When actually routing an address for delivery, an
18126 address that matches a domain pattern is queued for the associated transport.
18127 If the transport is not a local one, a host list must be associated with the
18128 pattern; IP addresses are looked up for the hosts, and these are passed to the
18129 transport along with the mail address. For local transports, a host list is
18130 optional. If it is present, it is passed in $host as a single text string.
18131
18132 The list of routing rules can be provided as an inline string in route_list, or
18133 the data can be obtained by looking up the domain in a file or database by
18134 setting route_data. Only one of these settings may appear in any one instance
18135 of manualroute. The format of routing rules is described below, following the
18136 list of private options.
18137
18138
18139 20.1 Private options for manualroute
18140 ------------------------------------
18141
18142 The private options for the manualroute router are as follows:
18143
18144 +-------------------------------------------------------------+
18145 |host_all_ignored|Use: manualroute|Type: string|Default: defer|
18146 +-------------------------------------------------------------+
18147
18148 See host_find_failed.
18149
18150 +--------------------------------------------------------------+
18151 |host_find_failed|Use: manualroute|Type: string|Default: freeze|
18152 +--------------------------------------------------------------+
18153
18154 This option controls what happens when manualroute tries to find an IP address
18155 for a host, and the host does not exist. The option can be set to one of the
18156 following values:
18157
18158 decline
18159 defer
18160 fail
18161 freeze
18162 ignore
18163 pass
18164
18165 The default ("freeze") assumes that this state is a serious configuration
18166 error. The difference between "pass" and "decline" is that the former forces
18167 the address to be passed to the next router (or the router defined by
18168 pass_router), overriding no_more, whereas the latter passes the address to the
18169 next router only if more is true.
18170
18171 The value "ignore" causes Exim to completely ignore a host whose IP address
18172 cannot be found. If all the hosts in the list are ignored, the behaviour is
18173 controlled by the host_all_ignored option. This takes the same values as
18174 host_find_failed, except that it cannot be set to "ignore".
18175
18176 The host_find_failed option applies only to a definite "does not exist" state;
18177 if a host lookup gets a temporary error, delivery is deferred unless the
18178 generic pass_on_timeout option is set.
18179
18180 +-------------------------------------------------------------+
18181 |hosts_randomize|Use: manualroute|Type: boolean|Default: false|
18182 +-------------------------------------------------------------+
18183
18184 If this option is set, the order of the items in a host list in a routing rule
18185 is randomized each time the list is used, unless an option in the routing rule
18186 overrides (see below). Randomizing the order of a host list can be used to do
18187 crude load sharing. However, if more than one mail address is routed by the
18188 same router to the same host list, the host lists are considered to be the same
18189 (even though they may be randomized into different orders) for the purpose of
18190 deciding whether to batch the deliveries into a single SMTP transaction.
18191
18192 When hosts_randomize is true, a host list may be split into groups whose order
18193 is separately randomized. This makes it possible to set up MX-like behaviour.
18194 The boundaries between groups are indicated by an item that is just "+" in the
18195 host list. For example:
18196
18197 route_list = * host1:host2:host3:+:host4:host5
18198
18199 The order of the first three hosts and the order of the last two hosts is
18200 randomized for each use, but the first three always end up before the last two.
18201 If hosts_randomize is not set, a "+" item in the list is ignored. If a
18202 randomized host list is passed to an smtp transport that also has
18203 hosts_randomize set, the list is not re-randomized.
18204
18205 +--------------------------------------------------------+
18206 |route_data|Use: manualroute|Type: string*|Default: unset|
18207 +--------------------------------------------------------+
18208
18209 If this option is set, it must expand to yield the data part of a routing rule.
18210 Typically, the expansion string includes a lookup based on the domain. For
18211 example:
18212
18213 route_data = ${lookup{$domain}dbm{/etc/routes}}
18214
18215 If the expansion is forced to fail, or the result is an empty string, the
18216 router declines. Other kinds of expansion failure cause delivery to be
18217 deferred.
18218
18219 +------------------------------------------------------------+
18220 |route_list|Use: manualroute|Type: string list|Default: unset|
18221 +------------------------------------------------------------+
18222
18223 This string is a list of routing rules, in the form defined below. Note that,
18224 unlike most string lists, the items are separated by semicolons. This is so
18225 that they may contain colon-separated host lists.
18226
18227 +----------------------------------------------------------------------+
18228 |same_domain_copy_routing|Use: manualroute|Type: boolean|Default: false|
18229 +----------------------------------------------------------------------+
18230
18231 Addresses with the same domain are normally routed by the manualroute router to
18232 the same list of hosts. However, this cannot be presumed, because the router
18233 options and preconditions may refer to the local part of the address. By
18234 default, therefore, Exim routes each address in a message independently. DNS
18235 servers run caches, so repeated DNS lookups are not normally expensive, and in
18236 any case, personal messages rarely have more than a few recipients.
18237
18238 If you are running mailing lists with large numbers of subscribers at the same
18239 domain, and you are using a manualroute router which is independent of the
18240 local part, you can set same_domain_copy_routing to bypass repeated DNS lookups
18241 for identical domains in one message. In this case, when manualroute routes an
18242 address to a remote transport, any other unrouted addresses in the message that
18243 have the same domain are automatically given the same routing without
18244 processing them independently. However, this is only done if headers_add and
18245 headers_remove are unset.
18246
18247
18248 20.2 Routing rules in route_list
18249 --------------------------------
18250
18251 The value of route_list is a string consisting of a sequence of routing rules,
18252 separated by semicolons. If a semicolon is needed in a rule, it can be entered
18253 as two semicolons. Alternatively, the list separator can be changed as
18254 described (for colon-separated lists) in section 6.20. Empty rules are ignored.
18255 The format of each rule is
18256
18257 <domain pattern> <list of hosts> <options>
18258
18259 The following example contains two rules, each with a simple domain pattern and
18260 no options:
18261
18262 route_list = \
18263 dict.ref.example mail-1.ref.example:mail-2.ref.example ; \
18264 thes.ref.example mail-3.ref.example:mail-4.ref.example
18265
18266 The three parts of a rule are separated by white space. The pattern and the
18267 list of hosts can be enclosed in quotes if necessary, and if they are, the
18268 usual quoting rules apply. Each rule in a route_list must start with a single
18269 domain pattern, which is the only mandatory item in the rule. The pattern is in
18270 the same format as one item in a domain list (see section 10.8), except that it
18271 may not be the name of an interpolated file. That is, it may be wildcarded, or
18272 a regular expression, or a file or database lookup (with semicolons doubled,
18273 because of the use of semicolon as a separator in a route_list).
18274
18275 The rules in route_list are searched in order until one of the patterns matches
18276 the domain that is being routed. The list of hosts and then options are then
18277 used as described below. If there is no match, the router declines. When
18278 route_list is set, route_data must not be set.
18279
18280
18281 20.3 Routing rules in route_data
18282 --------------------------------
18283
18284 The use of route_list is convenient when there are only a small number of
18285 routing rules. For larger numbers, it is easier to use a file or database to
18286 hold the routing information, and use the route_data option instead. The value
18287 of route_data is a list of hosts, followed by (optional) options. Most
18288 commonly, route_data is set as a string that contains an expansion lookup. For
18289 example, suppose we place two routing rules in a file like this:
18290
18291 dict.ref.example: mail-1.ref.example:mail-2.ref.example
18292 thes.ref.example: mail-3.ref.example:mail-4.ref.example
18293
18294 This data can be accessed by setting
18295
18296 route_data = ${lookup{$domain}lsearch{/the/file/name}}
18297
18298 Failure of the lookup results in an empty string, causing the router to
18299 decline. However, you do not have to use a lookup in route_data. The only
18300 requirement is that the result of expanding the string is a list of hosts,
18301 possibly followed by options, separated by white space. The list of hosts must
18302 be enclosed in quotes if it contains white space.
18303
18304
18305 20.4 Format of the list of hosts
18306 --------------------------------
18307
18308 A list of hosts, whether obtained via route_data or route_list, is always
18309 separately expanded before use. If the expansion fails, the router declines.
18310 The result of the expansion must be a colon-separated list of names and/or IP
18311 addresses, optionally also including ports. If the list is written with spaces,
18312 it must be protected with quotes. The format of each item in the list is
18313 described in the next section. The list separator can be changed as described
18314 in section 6.21.
18315
18316 If the list of hosts was obtained from a route_list item, the following
18317 variables are set during its expansion:
18318
18319 * If the domain was matched against a regular expression, the numeric
18320 variables $1, $2, etc. may be set. For example:
18321
18322 route_list = ^domain(\d+) host-$1.text.example
18323
18324 * $0 is always set to the entire domain.
18325
18326 * $1 is also set when partial matching is done in a file lookup.
18327
18328 * If the pattern that matched the domain was a lookup item, the data that was
18329 looked up is available in the expansion variable $value. For example:
18330
18331 route_list = lsearch;;/some/file.routes $value
18332
18333 Note the doubling of the semicolon in the pattern that is necessary because
18334 semicolon is the default route list separator.
18335
18336
18337 20.5 Format of one host item
18338 ----------------------------
18339
18340 Each item in the list of hosts is either a host name or an IP address,
18341 optionally with an attached port number. When no port is given, an IP address
18342 is not enclosed in brackets. When a port is specified, it overrides the port
18343 specification on the transport. The port is separated from the name or address
18344 by a colon. This leads to some complications:
18345
18346 * Because colon is the default separator for the list of hosts, either the
18347 colon that specifies a port must be doubled, or the list separator must be
18348 changed. The following two examples have the same effect:
18349
18350 route_list = * "host1.tld::1225 : host2.tld::1226"
18351 route_list = * "<+ host1.tld:1225 + host2.tld:1226"
18352
18353 * When IPv6 addresses are involved, it gets worse, because they contain
18354 colons of their own. To make this case easier, it is permitted to enclose
18355 an IP address (either v4 or v6) in square brackets if a port number
18356 follows. For example:
18357
18358 route_list = * "</ [10.1.1.1]:1225 / [::1]:1226"
18359
18360
18361 20.6 How the list of hosts is used
18362 ----------------------------------
18363
18364 When an address is routed to an smtp transport by manualroute, each of the
18365 hosts is tried, in the order specified, when carrying out the SMTP delivery.
18366 However, the order can be changed by setting the hosts_randomize option, either
18367 on the router (see section 20.1 above), or on the transport.
18368
18369 Hosts may be listed by name or by IP address. An unadorned name in the list of
18370 hosts is interpreted as a host name. A name that is followed by "/MX" is
18371 interpreted as an indirection to a sublist of hosts obtained by looking up MX
18372 records in the DNS. For example:
18373
18374 route_list = * x.y.z:p.q.r/MX:e.f.g
18375
18376 If this feature is used with a port specifier, the port must come last. For
18377 example:
18378
18379 route_list = * dom1.tld/mx::1225
18380
18381 If the hosts_randomize option is set, the order of the items in the list is
18382 randomized before any lookups are done. Exim then scans the list; for any name
18383 that is not followed by "/MX" it looks up an IP address. If this turns out to
18384 be an interface on the local host and the item is not the first in the list,
18385 Exim discards it and any subsequent items. If it is the first item, what
18386 happens is controlled by the self option of the router.
18387
18388 A name on the list that is followed by "/MX" is replaced with the list of hosts
18389 obtained by looking up MX records for the name. This is always a DNS lookup;
18390 the bydns and byname options (see section 20.7 below) are not relevant here.
18391 The order of these hosts is determined by the preference values in the MX
18392 records, according to the usual rules. Because randomizing happens before the
18393 MX lookup, it does not affect the order that is defined by MX preferences.
18394
18395 If the local host is present in the sublist obtained from MX records, but is
18396 not the most preferred host in that list, it and any equally or less preferred
18397 hosts are removed before the sublist is inserted into the main list.
18398
18399 If the local host is the most preferred host in the MX list, what happens
18400 depends on where in the original list of hosts the "/MX" item appears. If it is
18401 not the first item (that is, there are previous hosts in the main list), Exim
18402 discards this name and any subsequent items in the main list.
18403
18404 If the MX item is first in the list of hosts, and the local host is the most
18405 preferred host, what happens is controlled by the self option of the router.
18406
18407 DNS failures when lookup up the MX records are treated in the same way as DNS
18408 failures when looking up IP addresses: pass_on_timeout and host_find_failed are
18409 used when relevant.
18410
18411 The generic ignore_target_hosts option applies to all hosts in the list,
18412 whether obtained from an MX lookup or not.
18413
18414
18415 20.7 How the options are used
18416 -----------------------------
18417
18418 The options are a sequence of words, space-separated. One of the words can be
18419 the name of a transport; this overrides the transport option on the router for
18420 this particular routing rule only. The other words (if present) control
18421 randomization of the list of hosts on a per-rule basis, and how the IP
18422 addresses of the hosts are to be found when routing to a remote transport.
18423 These options are as follows:
18424
18425 * randomize: randomize the order of the hosts in this list, overriding the
18426 setting of hosts_randomize for this routing rule only.
18427
18428 * no_randomize: do not randomize the order of the hosts in this list,
18429 overriding the setting of hosts_randomize for this routing rule only.
18430
18431 * byname: use getipnodebyname() (gethostbyname() on older systems) to find IP
18432 addresses. This function may ultimately cause a DNS lookup, but it may also
18433 look in /etc/hosts or other sources of information.
18434
18435 * bydns: look up address records for the hosts directly in the DNS; fail if
18436 no address records are found. If there is a temporary DNS error (such as a
18437 timeout), delivery is deferred.
18438
18439 * ipv4_only: in direct DNS lookups, look up only A records.
18440
18441 * ipv4_prefer: in direct DNS lookups, sort A records before AAAA records.
18442
18443 For example:
18444
18445 route_list = domain1 host1:host2:host3 randomize bydns;\
18446 domain2 host4:host5
18447
18448 If neither byname nor bydns is given, Exim behaves as follows: First, a DNS
18449 lookup is done. If this yields anything other than HOST_NOT_FOUND, that result
18450 is used. Otherwise, Exim goes on to try a call to getipnodebyname() or
18451 gethostbyname(), and the result of the lookup is the result of that call.
18452
18453 Warning: It has been discovered that on some systems, if a DNS lookup called
18454 via getipnodebyname() times out, HOST_NOT_FOUND is returned instead of
18455 TRY_AGAIN. That is why the default action is to try a DNS lookup first. Only if
18456 that gives a definite "no such host" is the local function called.
18457
18458 Compatibility: From Exim 4.85 until fixed for 4.90, there was an inadvertent
18459 constraint that a transport name as an option had to be the last option
18460 specified.
18461
18462 If no IP address for a host can be found, what happens is controlled by the
18463 host_find_failed option.
18464
18465 When an address is routed to a local transport, IP addresses are not looked up.
18466 The host list is passed to the transport in the $host variable.
18467
18468
18469 20.8 Manualroute examples
18470 -------------------------
18471
18472 In some of the examples that follow, the presence of the remote_smtp transport,
18473 as defined in the default configuration file, is assumed:
18474
18475 * The manualroute router can be used to forward all external mail to a smart
18476 host. If you have set up, in the main part of the configuration, a named
18477 domain list that contains your local domains, for example:
18478
18479 domainlist local_domains = my.domain.example
18480
18481 You can arrange for all other domains to be routed to a smart host by
18482 making your first router something like this:
18483
18484 smart_route:
18485 driver = manualroute
18486 domains = !+local_domains
18487 transport = remote_smtp
18488 route_list = * smarthost.ref.example
18489
18490 This causes all non-local addresses to be sent to the single host
18491 smarthost.ref.example. If a colon-separated list of smart hosts is given,
18492 they are tried in order (but you can use hosts_randomize to vary the order
18493 each time). Another way of configuring the same thing is this:
18494
18495 smart_route:
18496 driver = manualroute
18497 transport = remote_smtp
18498 route_list = !+local_domains smarthost.ref.example
18499
18500 There is no difference in behaviour between these two routers as they
18501 stand. However, they behave differently if no_more is added to them. In the
18502 first example, the router is skipped if the domain does not match the
18503 domains precondition; the following router is always tried. If the router
18504 runs, it always matches the domain and so can never decline. Therefore,
18505 no_more would have no effect. In the second case, the router is never
18506 skipped; it always runs. However, if it doesn't match the domain, it
18507 declines. In this case no_more would prevent subsequent routers from
18508 running.
18509
18510 * A mail hub is a host which receives mail for a number of domains via MX
18511 records in the DNS and delivers it via its own private routing mechanism.
18512 Often the final destinations are behind a firewall, with the mail hub being
18513 the one machine that can connect to machines both inside and outside the
18514 firewall. The manualroute router is usually used on a mail hub to route
18515 incoming messages to the correct hosts. For a small number of domains, the
18516 routing can be inline, using the route_list option, but for a larger number
18517 a file or database lookup is easier to manage.
18518
18519 If the domain names are in fact the names of the machines to which the mail
18520 is to be sent by the mail hub, the configuration can be quite simple. For
18521 example:
18522
18523 hub_route:
18524 driver = manualroute
18525 transport = remote_smtp
18526 route_list = *.rhodes.tvs.example $domain
18527
18528 This configuration routes domains that match "*.rhodes.tvs.example" to
18529 hosts whose names are the same as the mail domains. A similar approach can
18530 be taken if the host name can be obtained from the domain name by a string
18531 manipulation that the expansion facilities can handle. Otherwise, a lookup
18532 based on the domain can be used to find the host:
18533
18534 through_firewall:
18535 driver = manualroute
18536 transport = remote_smtp
18537 route_data = ${lookup {$domain} cdb {/internal/host/routes}}
18538
18539 The result of the lookup must be the name or IP address of the host (or
18540 hosts) to which the address is to be routed. If the lookup fails, the route
18541 data is empty, causing the router to decline. The address then passes to
18542 the next router.
18543
18544 * You can use manualroute to deliver messages to pipes or files in batched
18545 SMTP format for onward transportation by some other means. This is one way
18546 of storing mail for a dial-up host when it is not connected. The route list
18547 entry can be as simple as a single domain name in a configuration like
18548 this:
18549
18550 save_in_file:
18551 driver = manualroute
18552 transport = batchsmtp_appendfile
18553 route_list = saved.domain.example
18554
18555 though often a pattern is used to pick up more than one domain. If there
18556 are several domains or groups of domains with different transport
18557 requirements, different transports can be listed in the routing
18558 information:
18559
18560 save_in_file:
18561 driver = manualroute
18562 route_list = \
18563 *.saved.domain1.example $domain batch_appendfile; \
18564 *.saved.domain2.example \
18565 ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \
18566 batch_pipe
18567
18568 The first of these just passes the domain in the $host variable, which
18569 doesn't achieve much (since it is also in $domain), but the second does a
18570 file lookup to find a value to pass, causing the router to decline to
18571 handle the address if the lookup fails.
18572
18573 * Routing mail directly to UUCP software is a specific case of the use of
18574 manualroute in a gateway to another mail environment. This is an example of
18575 one way it can be done:
18576
18577 # Transport
18578 uucp:
18579 driver = pipe
18580 user = nobody
18581 command = /usr/local/bin/uux -r - \
18582 ${substr_-5:$host}!rmail ${local_part}
18583 return_fail_output = true
18584
18585 # Router
18586 uucphost:
18587 transport = uucp
18588 driver = manualroute
18589 route_data = \
18590 ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}}
18591
18592 The file /usr/local/exim/uucphosts contains entries like
18593
18594 darksite.ethereal.example: darksite.UUCP
18595
18596 It can be set up more simply without adding and removing ".UUCP" but this
18597 way makes clear the distinction between the domain name
18598 darksite.ethereal.example and the UUCP host name darksite.
18599
18600
18601
18602 ===============================================================================
18603 21. THE QUERYPROGRAM ROUTER
18604
18605 The queryprogram router routes an address by running an external command and
18606 acting on its output. This is an expensive way to route, and is intended mainly
18607 for use in lightly-loaded systems, or for performing experiments. However, if
18608 it is possible to use the precondition options (domains, local_parts, etc) to
18609 skip this router for most addresses, it could sensibly be used in special
18610 cases, even on a busy host. There are the following private options:
18611
18612 +------------------------------------------------------+
18613 |command|Use: queryprogram|Type: string*|Default: unset|
18614 +------------------------------------------------------+
18615
18616 This option must be set. It specifies the command that is to be run. The
18617 command is split up into a command name and arguments, and then each is
18618 expanded separately (exactly as for a pipe transport, described in chapter 29).
18619
18620 +-----------------------------------------------------------+
18621 |command_group|Use: queryprogram|Type: string|Default: unset|
18622 +-----------------------------------------------------------+
18623
18624 This option specifies a gid to be set when running the command while routing an
18625 address for deliver. It must be set if command_user specifies a numerical uid.
18626 If it begins with a digit, it is interpreted as the numerical value of the gid.
18627 Otherwise it is looked up using getgrnam().
18628
18629 +----------------------------------------------------------+
18630 |command_user|Use: queryprogram|Type: string|Default: unset|
18631 +----------------------------------------------------------+
18632
18633 This option must be set. It specifies the uid which is set when running the
18634 command while routing an address for delivery. If the value begins with a
18635 digit, it is interpreted as the numerical value of the uid. Otherwise, it is
18636 looked up using getpwnam() to obtain a value for the uid and, if command_group
18637 is not set, a value for the gid also.
18638
18639 Warning: Changing uid and gid is possible only when Exim is running as root,
18640 which it does during a normal delivery in a conventional configuration.
18641 However, when an address is being verified during message reception, Exim is
18642 usually running as the Exim user, not as root. If the queryprogram router is
18643 called from a non-root process, Exim cannot change uid or gid before running
18644 the command. In this circumstance the command runs under the current uid and
18645 gid.
18646
18647 +-----------------------------------------------------------+
18648 |current_directory|Use: queryprogram|Type: string|Default: /|
18649 +-----------------------------------------------------------+
18650
18651 This option specifies an absolute path which is made the current directory
18652 before running the command.
18653
18654 +------------------------------------------------+
18655 |timeout|Use: queryprogram|Type: time|Default: 1h|
18656 +------------------------------------------------+
18657
18658 If the command does not complete within the timeout period, its process group
18659 is killed and the message is frozen. A value of zero time specifies no timeout.
18660
18661 The standard output of the command is connected to a pipe, which is read when
18662 the command terminates. It should consist of a single line of output,
18663 containing up to five fields, separated by white space. The maximum length of
18664 the line is 1023 characters. Longer lines are silently truncated. The first
18665 field is one of the following words (case-insensitive):
18666
18667 * Accept: routing succeeded; the remaining fields specify what to do (see
18668 below).
18669
18670 * Decline: the router declines; pass the address to the next router, unless
18671 no_more is set.
18672
18673 * Fail: routing failed; do not pass the address to any more routers. Any
18674 subsequent text on the line is an error message. If the router is run as
18675 part of address verification during an incoming SMTP message, the message
18676 is included in the SMTP response.
18677
18678 * Defer: routing could not be completed at this time; try again later. Any
18679 subsequent text on the line is an error message which is logged. It is not
18680 included in any SMTP response.
18681
18682 * Freeze: the same as defer, except that the message is frozen.
18683
18684 * Pass: pass the address to the next router (or the router specified by
18685 pass_router), overriding no_more.
18686
18687 * Redirect: the message is redirected. The remainder of the line is a list of
18688 new addresses, which are routed independently, starting with the first
18689 router, or the router specified by redirect_router, if set.
18690
18691 When the first word is accept, the remainder of the line consists of a number
18692 of keyed data values, as follows (split into two lines here, to fit on the
18693 page):
18694
18695 ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts>
18696 LOOKUP=byname|bydns DATA=<text>
18697
18698 The data items can be given in any order, and all are optional. If no transport
18699 is included, the transport specified by the generic transport option is used.
18700 The list of hosts and the lookup type are needed only if the transport is an
18701 smtp transport that does not itself supply a list of hosts.
18702
18703 The format of the list of hosts is the same as for the manualroute router. As
18704 well as host names and IP addresses with optional port numbers, as described in
18705 section 20.5, it may contain names followed by "/MX" to specify sublists of
18706 hosts that are obtained by looking up MX records (see section 20.6).
18707
18708 If the lookup type is not specified, Exim behaves as follows when trying to
18709 find an IP address for each host: First, a DNS lookup is done. If this yields
18710 anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim goes
18711 on to try a call to getipnodebyname() or gethostbyname(), and the result of the
18712 lookup is the result of that call.
18713
18714 If the DATA field is set, its value is placed in the $address_data variable.
18715 For example, this return line
18716
18717 accept hosts=x1.y.example:x2.y.example data="rule1"
18718
18719 routes the address to the default transport, passing a list of two hosts. When
18720 the transport runs, the string "rule1" is in $address_data.
18721
18722
18723
18724 ===============================================================================
18725 22. THE REDIRECT ROUTER
18726
18727 The redirect router handles several kinds of address redirection. Its most
18728 common uses are for resolving local part aliases from a central alias file
18729 (usually called /etc/aliases) and for handling users' personal .forward files,
18730 but it has many other potential uses. The incoming address can be redirected in
18731 several different ways:
18732
18733 * It can be replaced by one or more new addresses which are themselves routed
18734 independently.
18735
18736 * It can be routed to be delivered to a given file or directory.
18737
18738 * It can be routed to be delivered to a specified pipe command.
18739
18740 * It can cause an automatic reply to be generated.
18741
18742 * It can be forced to fail, optionally with a custom error message.
18743
18744 * It can be temporarily deferred, optionally with a custom message.
18745
18746 * It can be discarded.
18747
18748 The generic transport option must not be set for redirect routers. However,
18749 there are some private options which define transports for delivery to files
18750 and pipes, and for generating autoreplies. See the file_transport,
18751 pipe_transport and reply_transport descriptions below.
18752
18753 If success DSNs have been requested redirection triggers one and the DSN
18754 options are not passed any further.
18755
18756
18757 22.1 Redirection data
18758 ---------------------
18759
18760 The router operates by interpreting a text string which it obtains either by
18761 expanding the contents of the data option, or by reading the entire contents of
18762 a file whose name is given in the file option. These two options are mutually
18763 exclusive. The first is commonly used for handling system aliases, in a
18764 configuration like this:
18765
18766 system_aliases:
18767 driver = redirect
18768 data = ${lookup{$local_part}lsearch{/etc/aliases}}
18769
18770 If the lookup fails, the expanded string in this example is empty. When the
18771 expansion of data results in an empty string, the router declines. A forced
18772 expansion failure also causes the router to decline; other expansion failures
18773 cause delivery to be deferred.
18774
18775 A configuration using file is commonly used for handling users' .forward files,
18776 like this:
18777
18778 userforward:
18779 driver = redirect
18780 check_local_user
18781 file = $home/.forward
18782 no_verify
18783
18784 If the file does not exist, or causes no action to be taken (for example, it is
18785 empty or consists only of comments), the router declines. Warning: This is not
18786 the case when the file contains syntactically valid items that happen to yield
18787 empty addresses, for example, items containing only RFC 2822 address comments.
18788
18789
18790 22.2 Forward files and address verification
18791 -------------------------------------------
18792
18793 It is usual to set no_verify on redirect routers which handle users' .forward
18794 files, as in the example above. There are two reasons for this:
18795
18796 * When Exim is receiving an incoming SMTP message from a remote host, it is
18797 running under the Exim uid, not as root. Exim is unable to change uid to
18798 read the file as the user, and it may not be able to read it as the Exim
18799 user. So in practice the router may not be able to operate.
18800
18801 * However, even when the router can operate, the existence of a .forward file
18802 is unimportant when verifying an address. What should be checked is whether
18803 the local part is a valid user name or not. Cutting out the redirection
18804 processing saves some resources.
18805
18806
18807 22.3 Interpreting redirection data
18808 ----------------------------------
18809
18810 The contents of the data string, whether obtained from data or file, can be
18811 interpreted in two different ways:
18812
18813 * If the allow_filter option is set true, and the data begins with the text "
18814 #Exim filter" or "#Sieve filter", it is interpreted as a list of filtering
18815 instructions in the form of an Exim or Sieve filter file, respectively.
18816 Details of the syntax and semantics of filter files are described in a
18817 separate document entitled Exim's interfaces to mail filtering; this
18818 document is intended for use by end users.
18819
18820 * Otherwise, the data must be a comma-separated list of redirection items, as
18821 described in the next section.
18822
18823 When a message is redirected to a file (a "mail folder"), the filename given in
18824 a non-filter redirection list must always be an absolute path. A filter may
18825 generate a relative path - how this is handled depends on the transport's
18826 configuration. See section 26.1 for a discussion of this issue for the
18827 appendfile transport.
18828
18829
18830 22.4 Items in a non-filter redirection list
18831 -------------------------------------------
18832
18833 When the redirection data is not an Exim or Sieve filter, for example, if it
18834 comes from a conventional alias or forward file, it consists of a list of
18835 addresses, filenames, pipe commands, or certain special items (see section 22.6
18836 below). The special items can be individually enabled or disabled by means of
18837 options whose names begin with allow_ or forbid_, depending on their default
18838 values. The items in the list are separated by commas or newlines. If a comma
18839 is required in an item, the entire item must be enclosed in double quotes.
18840
18841 Lines starting with a # character are comments, and are ignored, and # may also
18842 appear following a comma, in which case everything between the # and the next
18843 newline character is ignored.
18844
18845 If an item is entirely enclosed in double quotes, these are removed. Otherwise
18846 double quotes are retained because some forms of mail address require their use
18847 (but never to enclose the entire address). In the following description, "item"
18848 refers to what remains after any surrounding double quotes have been removed.
18849
18850 Warning: If you use an Exim expansion to construct a redirection address, and
18851 the expansion contains a reference to $local_part, you should make use of the
18852 quote_local_part expansion operator, in case the local part contains special
18853 characters. For example, to redirect all mail for the domain obsolete.example,
18854 retaining the existing local part, you could use this setting:
18855
18856 data = ${quote_local_part:$local_part}@newdomain.example
18857
18858
18859 22.5 Redirecting to a local mailbox
18860 -----------------------------------
18861
18862 A redirection item may safely be the same as the address currently under
18863 consideration. This does not cause a routing loop, because a router is
18864 automatically skipped if any ancestor of the address that is being processed is
18865 the same as the current address and was processed by the current router. Such
18866 an address is therefore passed to the following routers, so it is handled as if
18867 there were no redirection. When making this loop-avoidance test, the complete
18868 local part, including any prefix or suffix, is used.
18869
18870 Specifying the same local part without a domain is a common usage in personal
18871 filter files when the user wants to have messages delivered to the local
18872 mailbox and also forwarded elsewhere. For example, the user whose login is cleo
18873 might have a .forward file containing this:
18874
18875 cleo, cleopatra@egypt.example
18876
18877 For compatibility with other MTAs, such unqualified local parts may be preceded
18878 by "\", but this is not a requirement for loop prevention. However, it does
18879 make a difference if more than one domain is being handled synonymously.
18880
18881 If an item begins with "\" and the rest of the item parses as a valid RFC 2822
18882 address that does not include a domain, the item is qualified using the domain
18883 of the incoming address. In the absence of a leading "\", unqualified addresses
18884 are qualified using the value in qualify_recipient, but you can force the
18885 incoming domain to be used by setting qualify_preserve_domain.
18886
18887 Care must be taken if there are alias names for local users. Consider an MTA
18888 handling a single local domain where the system alias file contains:
18889
18890 Sam.Reman: spqr
18891
18892 Now suppose that Sam (whose login id is spqr) wants to save copies of messages
18893 in the local mailbox, and also forward copies elsewhere. He creates this
18894 forward file:
18895
18896 Sam.Reman, spqr@reme.elsewhere.example
18897
18898 With these settings, an incoming message addressed to Sam.Reman fails. The
18899 redirect router for system aliases does not process Sam.Reman the second time
18900 round, because it has previously routed it, and the following routers
18901 presumably cannot handle the alias. The forward file should really contain
18902
18903 spqr, spqr@reme.elsewhere.example
18904
18905 but because this is such a common error, the check_ancestor option (see below)
18906 exists to provide a way to get round it. This is normally set on a redirect
18907 router that is handling users' .forward files.
18908
18909
18910 22.6 Special items in redirection lists
18911 ---------------------------------------
18912
18913 In addition to addresses, the following types of item may appear in redirection
18914 lists (that is, in non-filter redirection data):
18915
18916 * An item is treated as a pipe command if it begins with "|" and does not
18917 parse as a valid RFC 2822 address that includes a domain. A transport for
18918 running the command must be specified by the pipe_transport option.
18919 Normally, either the router or the transport specifies a user and a group
18920 under which to run the delivery. The default is to use the Exim user and
18921 group.
18922
18923 Single or double quotes can be used for enclosing the individual arguments
18924 of the pipe command; no interpretation of escapes is done for single
18925 quotes. If the command contains a comma character, it is necessary to put
18926 the whole item in double quotes, for example:
18927
18928 "|/some/command ready,steady,go"
18929
18930 since items in redirection lists are terminated by commas. Do not, however,
18931 quote just the command. An item such as
18932
18933 |"/some/command ready,steady,go"
18934
18935 is interpreted as a pipe with a rather strange command name, and no
18936 arguments.
18937
18938 Note that the above example assumes that the text comes from a lookup
18939 source of some sort, so that the quotes are part of the data. If composing
18940 a redirect router with a data option directly specifying this command, the
18941 quotes will be used by the configuration parser to define the extent of one
18942 string, but will not be passed down into the redirect router itself. There
18943 are two main approaches to get around this: escape quotes to be part of the
18944 data itself, or avoid using this mechanism and instead create a custom
18945 transport with the command option set and reference that transport from an
18946 accept router.
18947
18948 * An item is interpreted as a path name if it begins with "/" and does not
18949 parse as a valid RFC 2822 address that includes a domain. For example,
18950
18951 /home/world/minbari
18952
18953 is treated as a filename, but
18954
18955 /s=molari/o=babylon/@x400gate.way
18956
18957 is treated as an address. For a filename, a transport must be specified
18958 using the file_transport option. However, if the generated path name ends
18959 with a forward slash character, it is interpreted as a directory name
18960 rather than a filename, and directory_transport is used instead.
18961
18962 Normally, either the router or the transport specifies a user and a group
18963 under which to run the delivery. The default is to use the Exim user and
18964 group.
18965
18966 However, if a redirection item is the path /dev/null, delivery to it is
18967 bypassed at a high level, and the log entry shows "**bypassed**" instead of
18968 a transport name. In this case the user and group are not used.
18969
18970 * If an item is of the form
18971
18972 :include:<path name>
18973
18974 a list of further items is taken from the given file and included at that
18975 point. Note: Such a file can not be a filter file; it is just an
18976 out-of-line addition to the list. The items in the included list are
18977 separated by commas or newlines and are not subject to expansion. If this
18978 is the first item in an alias list in an lsearch file, a colon must be used
18979 to terminate the alias name. This example is incorrect:
18980
18981 list1 :include:/opt/lists/list1
18982
18983 It must be given as
18984
18985 list1: :include:/opt/lists/list1
18986
18987 * Sometimes you want to throw away mail to a particular local part. Making
18988 the data option expand to an empty string does not work, because that
18989 causes the router to decline. Instead, the alias item
18990
18991 :blackhole:
18992
18993 can be used. It does what its name implies. No delivery is done, and no
18994 error message is generated. This has the same effect as specifying /dev/
18995 null as a destination, but it can be independently disabled.
18996
18997 Warning: If :blackhole: appears anywhere in a redirection list, no delivery
18998 is done for the original local part, even if other redirection items are
18999 present. If you are generating a multi-item list (for example, by reading a
19000 database) and need the ability to provide a no-op item, you must use /dev/
19001 null.
19002
19003 * An attempt to deliver a particular address can be deferred or forced to
19004 fail by redirection items of the form
19005
19006 :defer:
19007 :fail:
19008
19009 respectively. When a redirection list contains such an item, it applies to
19010 the entire redirection; any other items in the list are ignored. Any text
19011 following :fail: or :defer: is placed in the error text associated with the
19012 failure. For example, an alias file might contain:
19013
19014 X.Employee: :fail: Gone away, no forwarding address
19015
19016 In the case of an address that is being verified from an ACL or as the
19017 subject of a VRFY command, the text is included in the SMTP error response
19018 by default. The text is not included in the response to an EXPN command. In
19019 non-SMTP cases the text is included in the error message that Exim
19020 generates.
19021
19022 By default, Exim sends a 451 SMTP code for a :defer:, and 550 for :fail:.
19023 However, if the message starts with three digits followed by a space,
19024 optionally followed by an extended code of the form n.n.n, also followed by
19025 a space, and the very first digit is the same as the default error code,
19026 the code from the message is used instead. If the very first digit is
19027 incorrect, a panic error is logged, and the default code is used. You can
19028 suppress the use of the supplied code in a redirect router by setting the
19029 forbid_smtp_code option true. In this case, any SMTP code is quietly
19030 ignored.
19031
19032 In an ACL, an explicitly provided message overrides the default, but the
19033 default message is available in the variable $acl_verify_message and can
19034 therefore be included in a custom message if this is desired.
19035
19036 Normally the error text is the rest of the redirection list - a comma does
19037 not terminate it - but a newline does act as a terminator. Newlines are not
19038 normally present in alias expansions. In lsearch lookups they are removed
19039 as part of the continuation process, but they may exist in other kinds of
19040 lookup and in :include: files.
19041
19042 During routing for message delivery (as opposed to verification), a
19043 redirection containing :fail: causes an immediate failure of the incoming
19044 address, whereas :defer: causes the message to remain in the queue so that
19045 a subsequent delivery attempt can happen at a later time. If an address is
19046 deferred for too long, it will ultimately fail, because the normal retry
19047 rules still apply.
19048
19049 * Sometimes it is useful to use a single-key search type with a default (see
19050 chapter 9) to look up aliases. However, there may be a need for exceptions
19051 to the default. These can be handled by aliasing them to :unknown:. This
19052 differs from :fail: in that it causes the redirect router to decline,
19053 whereas :fail: forces routing to fail. A lookup which results in an empty
19054 redirection list has the same effect.
19055
19056
19057 22.7 Duplicate addresses
19058 ------------------------
19059
19060 Exim removes duplicate addresses from the list to which it is delivering, so as
19061 to deliver just one copy to each address. This does not apply to deliveries
19062 routed to pipes by different immediate parent addresses, but an indirect
19063 aliasing scheme of the type
19064
19065 pipe: |/some/command $local_part
19066 localpart1: pipe
19067 localpart2: pipe
19068
19069 does not work with a message that is addressed to both local parts, because
19070 when the second is aliased to the intermediate local part "pipe" it gets
19071 discarded as being the same as a previously handled address. However, a scheme
19072 such as
19073
19074 localpart1: |/some/command $local_part
19075 localpart2: |/some/command $local_part
19076
19077 does result in two different pipe deliveries, because the immediate parents of
19078 the pipes are distinct.
19079
19080
19081 22.8 Repeated redirection expansion
19082 -----------------------------------
19083
19084 When a message cannot be delivered to all of its recipients immediately,
19085 leading to two or more delivery attempts, redirection expansion is carried out
19086 afresh each time for those addresses whose children were not all previously
19087 delivered. If redirection is being used as a mailing list, this can lead to new
19088 members of the list receiving copies of old messages. The one_time option can
19089 be used to avoid this.
19090
19091
19092 22.9 Errors in redirection lists
19093 --------------------------------
19094
19095 If skip_syntax_errors is set, a malformed address that causes a parsing error
19096 is skipped, and an entry is written to the main log. This may be useful for
19097 mailing lists that are automatically managed. Otherwise, if an error is
19098 detected while generating the list of new addresses, the original address is
19099 deferred. See also syntax_errors_to.
19100
19101
19102 22.10 Private options for the redirect router
19103 ---------------------------------------------
19104
19105 The private options for the redirect router are as follows:
19106
19107 +------------------------------------------------------+
19108 |allow_defer|Use: redirect|Type: boolean|Default: false|
19109 +------------------------------------------------------+
19110
19111 Setting this option allows the use of :defer: in non-filter redirection data,
19112 or the defer command in an Exim filter file.
19113
19114 +-----------------------------------------------------+
19115 |allow_fail|Use: redirect|Type: boolean|Default: false|
19116 +-----------------------------------------------------+
19117
19118 If this option is true, the :fail: item can be used in a redirection list, and
19119 the fail command may be used in an Exim filter file.
19120
19121 +-------------------------------------------------------+
19122 |allow_filter|Use: redirect|Type: boolean|Default: false|
19123 +-------------------------------------------------------+
19124
19125 Setting this option allows Exim to interpret redirection data that starts with
19126 "#Exim filter" or "#Sieve filter" as a set of filtering instructions. There are
19127 some features of Exim filter files that some administrators may wish to lock
19128 out; see the forbid_filter_xxx options below.
19129
19130 It is also possible to lock out Exim filters or Sieve filters while allowing
19131 the other type; see forbid_exim_filter and forbid_sieve_filter.
19132
19133 The filter is run using the uid and gid set by the generic user and group
19134 options. These take their defaults from the password data if check_local_user
19135 is set, so in the normal case of users' personal filter files, the filter is
19136 run as the relevant user. When allow_filter is set true, Exim insists that
19137 either check_local_user or user is set.
19138
19139 +-------------------------------------------------------+
19140 |allow_freeze|Use: redirect|Type: boolean|Default: false|
19141 +-------------------------------------------------------+
19142
19143 Setting this option allows the use of the freeze command in an Exim filter.
19144 This command is more normally encountered in system filters, and is disabled by
19145 default for redirection filters because it isn't something you usually want to
19146 let ordinary users do.
19147
19148 +---------------------------------------------------------+
19149 |check_ancestor|Use: redirect|Type: boolean|Default: false|
19150 +---------------------------------------------------------+
19151
19152 This option is concerned with handling generated addresses that are the same as
19153 some address in the list of redirection ancestors of the current address.
19154 Although it is turned off by default in the code, it is set in the default
19155 configuration file for handling users' .forward files. It is recommended for
19156 this use of the redirect router.
19157
19158 When check_ancestor is set, if a generated address (including the domain) is
19159 the same as any ancestor of the current address, it is replaced by a copy of
19160 the current address. This helps in the case where local part A is aliased to B,
19161 and B has a .forward file pointing back to A. For example, within a single
19162 domain, the local part "Joe.Bloggs" is aliased to "jb" and jb/.forward
19163 contains:
19164
19165 \Joe.Bloggs, <other item(s)>
19166
19167 Without the check_ancestor setting, either local part ("jb" or "joe.bloggs")
19168 gets processed once by each router and so ends up as it was originally. If "jb"
19169 is the real mailbox name, mail to "jb" gets delivered (having been turned into
19170 "joe.bloggs" by the .forward file and back to "jb" by the alias), but mail to
19171 "joe.bloggs" fails. Setting check_ancestor on the redirect router that handles
19172 the .forward file prevents it from turning "jb" back into "joe.bloggs" when
19173 that was the original address. See also the repeat_use option below.
19174
19175 +----------------------------------------------------------+
19176 |check_group|Use: redirect|Type: boolean|Default: see below|
19177 +----------------------------------------------------------+
19178
19179 When the file option is used, the group owner of the file is checked only when
19180 this option is set. The permitted groups are those listed in the owngroups
19181 option, together with the user's default group if check_local_user is set. If
19182 the file has the wrong group, routing is deferred. The default setting for this
19183 option is true if check_local_user is set and the modemask option permits the
19184 group write bit, or if the owngroups option is set. Otherwise it is false, and
19185 no group check occurs.
19186
19187 +----------------------------------------------------------+
19188 |check_owner|Use: redirect|Type: boolean|Default: see below|
19189 +----------------------------------------------------------+
19190
19191 When the file option is used, the owner of the file is checked only when this
19192 option is set. If check_local_user is set, the local user is permitted;
19193 otherwise the owner must be one of those listed in the owners option. The
19194 default value for this option is true if check_local_user or owners is set.
19195 Otherwise the default is false, and no owner check occurs.
19196
19197 +-----------------------------------------------+
19198 |data|Use: redirect|Type: string*|Default: unset|
19199 +-----------------------------------------------+
19200
19201 This option is mutually exclusive with file. One or other of them must be set,
19202 but not both. The contents of data are expanded, and then used as the list of
19203 forwarding items, or as a set of filtering instructions. If the expansion is
19204 forced to fail, or the result is an empty string or a string that has no effect
19205 (consists entirely of comments), the router declines.
19206
19207 When filtering instructions are used, the string must begin with "#Exim
19208 filter", and all comments in the string, including this initial one, must be
19209 terminated with newline characters. For example:
19210
19211 data = #Exim filter\n\
19212 if $h_to: contains Exim then save $home/mail/exim endif
19213
19214 If you are reading the data from a database where newlines cannot be included,
19215 you can use the ${sg} expansion item to turn the escape string of your choice
19216 into a newline.
19217
19218 +--------------------------------------------------------------+
19219 |directory_transport|Use: redirect|Type: string*|Default: unset|
19220 +--------------------------------------------------------------+
19221
19222 A redirect router sets up a direct delivery to a directory when a path name
19223 ending with a slash is specified as a new "address". The transport used is
19224 specified by this option, which, after expansion, must be the name of a
19225 configured transport. This should normally be an appendfile transport.
19226
19227 +-----------------------------------------------+
19228 |file|Use: redirect|Type: string*|Default: unset|
19229 +-----------------------------------------------+
19230
19231 This option specifies the name of a file that contains the redirection data. It
19232 is mutually exclusive with the data option. The string is expanded before use;
19233 if the expansion is forced to fail, the router declines. Other expansion
19234 failures cause delivery to be deferred. The result of a successful expansion
19235 must be an absolute path. The entire file is read and used as the redirection
19236 data. If the data is an empty string or a string that has no effect (consists
19237 entirely of comments), the router declines.
19238
19239 If the attempt to open the file fails with a "does not exist" error, Exim runs
19240 a check on the containing directory, unless ignore_enotdir is true (see below).
19241 If the directory does not appear to exist, delivery is deferred. This can
19242 happen when users' .forward files are in NFS-mounted directories, and there is
19243 a mount problem. If the containing directory does exist, but the file does not,
19244 the router declines.
19245
19246 +---------------------------------------------------------+
19247 |file_transport|Use: redirect|Type: string*|Default: unset|
19248 +---------------------------------------------------------+
19249
19250 A redirect router sets up a direct delivery to a file when a path name not
19251 ending in a slash is specified as a new "address". The transport used is
19252 specified by this option, which, after expansion, must be the name of a
19253 configured transport. This should normally be an appendfile transport. When it
19254 is running, the filename is in $address_file.
19255
19256 +-------------------------------------------------------------+
19257 |filter_prepend_home|Use: redirect|Type: boolean|Default: true|
19258 +-------------------------------------------------------------+
19259
19260 When this option is true, if a save command in an Exim filter specifies a
19261 relative path, and $home is defined, it is automatically prepended to the
19262 relative path. If this option is set false, this action does not happen. The
19263 relative path is then passed to the transport unmodified.
19264
19265 +-----------------------------------------------------------+
19266 |forbid_blackhole|Use: redirect|Type: boolean|Default: false|
19267 +-----------------------------------------------------------+
19268
19269 If this option is true, the :blackhole: item may not appear in a redirection
19270 list.
19271
19272 +-------------------------------------------------------------+
19273 |forbid_exim_filter|Use: redirect|Type: boolean|Default: false|
19274 +-------------------------------------------------------------+
19275
19276 If this option is set true, only Sieve filters are permitted when allow_filter
19277 is true.
19278
19279 +------------------------------------------------------+
19280 |forbid_file|Use: redirect|Type: boolean|Default: false|
19281 +------------------------------------------------------+
19282
19283 If this option is true, this router may not generate a new address that
19284 specifies delivery to a local file or directory, either from a filter or from a
19285 conventional forward file. This option is forced to be true if one_time is set.
19286 It applies to Sieve filters as well as to Exim filters, but if true, it locks
19287 out the Sieve's "keep" facility.
19288
19289 +---------------------------------------------------------------+
19290 |forbid_filter_dlfunc|Use: redirect|Type: boolean|Default: false|
19291 +---------------------------------------------------------------+
19292
19293 If this option is true, string expansions in Exim filters are not allowed to
19294 make use of the dlfunc expansion facility to run dynamically loaded functions.
19295
19296 +-------------------------------------------------------------------+
19297 |forbid_filter_existstest|Use: redirect|Type: boolean|Default: false|
19298 +-------------------------------------------------------------------+
19299
19300 If this option is true, string expansions in Exim filters are not allowed to
19301 make use of the exists condition or the stat expansion item.
19302
19303 +-----------------------------------------------------------------+
19304 |forbid_filter_logwrite|Use: redirect|Type: boolean|Default: false|
19305 +-----------------------------------------------------------------+
19306
19307 If this option is true, use of the logging facility in Exim filters is not
19308 permitted. Logging is in any case available only if the filter is being run
19309 under some unprivileged uid (which is normally the case for ordinary users'
19310 .forward files).
19311
19312 +---------------------------------------------------------------+
19313 |forbid_filter_lookup|Use: redirect|Type: boolean|Default: false|
19314 +---------------------------------------------------------------+
19315
19316 If this option is true, string expansions in Exim filter files are not allowed
19317 to make use of lookup items.
19318
19319 +-------------------------------------------------------------+
19320 |forbid_filter_perl|Use: redirect|Type: boolean|Default: false|
19321 +-------------------------------------------------------------+
19322
19323 This option has an effect only if Exim is built with embedded Perl support. If
19324 it is true, string expansions in Exim filter files are not allowed to make use
19325 of the embedded Perl support.
19326
19327 +-----------------------------------------------------------------+
19328 |forbid_filter_readfile|Use: redirect|Type: boolean|Default: false|
19329 +-----------------------------------------------------------------+
19330
19331 If this option is true, string expansions in Exim filter files are not allowed
19332 to make use of readfile items.
19333
19334 +-------------------------------------------------------------------+
19335 |forbid_filter_readsocket|Use: redirect|Type: boolean|Default: false|
19336 +-------------------------------------------------------------------+
19337
19338 If this option is true, string expansions in Exim filter files are not allowed
19339 to make use of readsocket items.
19340
19341 +--------------------------------------------------------------+
19342 |forbid_filter_reply|Use: redirect|Type: boolean|Default: false|
19343 +--------------------------------------------------------------+
19344
19345 If this option is true, this router may not generate an automatic reply
19346 message. Automatic replies can be generated only from Exim or Sieve filter
19347 files, not from traditional forward files. This option is forced to be true if
19348 one_time is set.
19349
19350 +------------------------------------------------------------+
19351 |forbid_filter_run|Use: redirect|Type: boolean|Default: false|
19352 +------------------------------------------------------------+
19353
19354 If this option is true, string expansions in Exim filter files are not allowed
19355 to make use of run items.
19356
19357 +---------------------------------------------------------+
19358 |forbid_include|Use: redirect|Type: boolean|Default: false|
19359 +---------------------------------------------------------+
19360
19361 If this option is true, items of the form
19362
19363 :include:<path name>
19364
19365 are not permitted in non-filter redirection lists.
19366
19367 +------------------------------------------------------+
19368 |forbid_pipe|Use: redirect|Type: boolean|Default: false|
19369 +------------------------------------------------------+
19370
19371 If this option is true, this router may not generate a new address which
19372 specifies delivery to a pipe, either from an Exim filter or from a conventional
19373 forward file. This option is forced to be true if one_time is set.
19374
19375 +--------------------------------------------------------------+
19376 |forbid_sieve_filter|Use: redirect|Type: boolean|Default: false|
19377 +--------------------------------------------------------------+
19378
19379 If this option is set true, only Exim filters are permitted when allow_filter
19380 is true.
19381
19382 +-----------------------------------------------------------+
19383 |forbid_smtp_code|Use: redirect|Type: boolean|Default: false|
19384 +-----------------------------------------------------------+
19385
19386 If this option is set true, any SMTP error codes that are present at the start
19387 of messages specified for ":defer:" or ":fail:" are quietly ignored, and the
19388 default codes (451 and 550, respectively) are always used.
19389
19390 +---------------------------------------------------------------+
19391 |hide_child_in_errmsg|Use: redirect|Type: boolean|Default: false|
19392 +---------------------------------------------------------------+
19393
19394 If this option is true, it prevents Exim from quoting a child address if it
19395 generates a bounce or delay message for it. Instead it says "an address
19396 generated from <the top level address>". Of course, this applies only to
19397 bounces generated locally. If a message is forwarded to another host, its
19398 bounce may well quote the generated address.
19399
19400 +--------------------------------------------------------+
19401 |ignore_eacces|Use: redirect|Type: boolean|Default: false|
19402 +--------------------------------------------------------+
19403
19404 If this option is set and an attempt to open a redirection file yields the
19405 EACCES error (permission denied), the redirect router behaves as if the file
19406 did not exist.
19407
19408 +---------------------------------------------------------+
19409 |ignore_enotdir|Use: redirect|Type: boolean|Default: false|
19410 +---------------------------------------------------------+
19411
19412 If this option is set and an attempt to open a redirection file yields the
19413 ENOTDIR error (something on the path is not a directory), the redirect router
19414 behaves as if the file did not exist.
19415
19416 Setting ignore_enotdir has another effect as well: When a redirect router that
19417 has the file option set discovers that the file does not exist (the ENOENT
19418 error), it tries to stat() the parent directory, as a check against unmounted
19419 NFS directories. If the parent can not be statted, delivery is deferred.
19420 However, it seems wrong to do this check when ignore_enotdir is set, because
19421 that option tells Exim to ignore "something on the path is not a directory"
19422 (the ENOTDIR error). This is a confusing area, because it seems that some
19423 operating systems give ENOENT where others give ENOTDIR.
19424
19425 +-----------------------------------------------------------+
19426 |include_directory|Use: redirect|Type: string|Default: unset|
19427 +-----------------------------------------------------------+
19428
19429 If this option is set, the path names of any :include: items in a redirection
19430 list must start with this directory.
19431
19432 +-------------------------------------------------------+
19433 |modemask|Use: redirect|Type: octal integer|Default: 022|
19434 +-------------------------------------------------------+
19435
19436 This specifies mode bits which must not be set for a file specified by the file
19437 option. If any of the forbidden bits are set, delivery is deferred.
19438
19439 +---------------------------------------------------+
19440 |one_time|Use: redirect|Type: boolean|Default: false|
19441 +---------------------------------------------------+
19442
19443 Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
19444 files each time it tries to deliver a message causes a problem when one or more
19445 of the generated addresses fails be delivered at the first attempt. The problem
19446 is not one of duplicate delivery - Exim is clever enough to handle that - but
19447 of what happens when the redirection list changes during the time that the
19448 message is on Exim's queue. This is particularly true in the case of mailing
19449 lists, where new subscribers might receive copies of messages that were posted
19450 before they subscribed.
19451
19452 If one_time is set and any addresses generated by the router fail to deliver at
19453 the first attempt, the failing addresses are added to the message as "top
19454 level" addresses, and the parent address that generated them is marked
19455 "delivered". Thus, redirection does not happen again at the next delivery
19456 attempt.
19457
19458 Warning 1: Any header line addition or removal that is specified by this router
19459 would be lost if delivery did not succeed at the first attempt. For this
19460 reason, the headers_add and headers_remove generic options are not permitted
19461 when one_time is set.
19462
19463 Warning 2: To ensure that the router generates only addresses (as opposed to
19464 pipe or file deliveries or auto-replies) forbid_file, forbid_pipe, and
19465 forbid_filter_reply are forced to be true when one_time is set.
19466
19467 Warning 3: The unseen generic router option may not be set with one_time.
19468
19469 The original top-level address is remembered with each of the generated
19470 addresses, and is output in any log messages. However, any intermediate parent
19471 addresses are not recorded. This makes a difference to the log only if
19472 all_parents log selector is set. It is expected that one_time will typically be
19473 used for mailing lists, where there is normally just one level of expansion.
19474
19475 +-----------------------------------------------------+
19476 |owners|Use: redirect|Type: string list|Default: unset|
19477 +-----------------------------------------------------+
19478
19479 This specifies a list of permitted owners for the file specified by file. This
19480 list is in addition to the local user when check_local_user is set. See
19481 check_owner above.
19482
19483 +--------------------------------------------------------+
19484 |owngroups|Use: redirect|Type: string list|Default: unset|
19485 +--------------------------------------------------------+
19486
19487 This specifies a list of permitted groups for the file specified by file. The
19488 list is in addition to the local user's primary group when check_local_user is
19489 set. See check_group above.
19490
19491 +---------------------------------------------------------+
19492 |pipe_transport|Use: redirect|Type: string*|Default: unset|
19493 +---------------------------------------------------------+
19494
19495 A redirect router sets up a direct delivery to a pipe when a string starting
19496 with a vertical bar character is specified as a new "address". The transport
19497 used is specified by this option, which, after expansion, must be the name of a
19498 configured transport. This should normally be a pipe transport. When the
19499 transport is run, the pipe command is in $address_pipe.
19500
19501 +---------------------------------------------------------+
19502 |qualify_domain|Use: redirect|Type: string*|Default: unset|
19503 +---------------------------------------------------------+
19504
19505 If this option is set, and an unqualified address (one without a domain) is
19506 generated, and that address would normally be qualified by the global setting
19507 in qualify_recipient, it is instead qualified with the domain specified by
19508 expanding this string. If the expansion fails, the router declines. If you want
19509 to revert to the default, you can have the expansion generate
19510 $qualify_recipient.
19511
19512 This option applies to all unqualified addresses generated by Exim filters, but
19513 for traditional .forward files, it applies only to addresses that are not
19514 preceded by a backslash. Sieve filters cannot generate unqualified addresses.
19515
19516 +------------------------------------------------------------------+
19517 |qualify_preserve_domain|Use: redirect|Type: boolean|Default: false|
19518 +------------------------------------------------------------------+
19519
19520 If this option is set, the router's local qualify_domain option must not be set
19521 (a configuration error occurs if it is). If an unqualified address (one without
19522 a domain) is generated, it is qualified with the domain of the parent address
19523 (the immediately preceding ancestor) instead of the global qualify_recipient
19524 value. In the case of a traditional .forward file, this applies whether or not
19525 the address is preceded by a backslash.
19526
19527 +----------------------------------------------------+
19528 |repeat_use|Use: redirect|Type: boolean|Default: true|
19529 +----------------------------------------------------+
19530
19531 If this option is set false, the router is skipped for a child address that has
19532 any ancestor that was routed by this router. This test happens before any of
19533 the other preconditions are tested. Exim's default anti-looping rules skip only
19534 when the ancestor is the same as the current address. See also check_ancestor
19535 above and the generic redirect_router option.
19536
19537 +----------------------------------------------------------+
19538 |reply_transport|Use: redirect|Type: string*|Default: unset|
19539 +----------------------------------------------------------+
19540
19541 A redirect router sets up an automatic reply when a mail or vacation command is
19542 used in a filter file. The transport used is specified by this option, which,
19543 after expansion, must be the name of a configured transport. This should
19544 normally be an autoreply transport. Other transports are unlikely to do
19545 anything sensible or useful.
19546
19547 +-------------------------------------------------+
19548 |rewrite|Use: redirect|Type: boolean|Default: true|
19549 +-------------------------------------------------+
19550
19551 If this option is set false, addresses generated by the router are not subject
19552 to address rewriting. Otherwise, they are treated like new addresses and are
19553 rewritten according to the global rewriting rules.
19554
19555 +-----------------------------------------------------------+
19556 |sieve_subaddress|Use: redirect|Type: string*|Default: unset|
19557 +-----------------------------------------------------------+
19558
19559 The value of this option is passed to a Sieve filter to specify the :subaddress
19560 part of an address.
19561
19562 +------------------------------------------------------------+
19563 |sieve_useraddress|Use: redirect|Type: string*|Default: unset|
19564 +------------------------------------------------------------+
19565
19566 The value of this option is passed to a Sieve filter to specify the :user part
19567 of an address. However, if it is unset, the entire original local part
19568 (including any prefix or suffix) is used for :user.
19569
19570 +-------------------------------------------------------------------+
19571 |sieve_vacation_directory|Use: redirect|Type: string*|Default: unset|
19572 +-------------------------------------------------------------------+
19573
19574 To enable the "vacation" extension for Sieve filters, you must set
19575 sieve_vacation_directory to the directory where vacation databases are held (do
19576 not put anything else in that directory), and ensure that the reply_transport
19577 option refers to an autoreply transport. Each user needs their own directory;
19578 Exim will create it if necessary.
19579
19580 +-------------------------------------------------------------+
19581 |skip_syntax_errors|Use: redirect|Type: boolean|Default: false|
19582 +-------------------------------------------------------------+
19583
19584 If skip_syntax_errors is set, syntactically malformed addresses in non-filter
19585 redirection data are skipped, and each failing address is logged. If
19586 syntax_errors_to is set, a message is sent to the address it defines, giving
19587 details of the failures. If syntax_errors_text is set, its contents are
19588 expanded and placed at the head of the error message generated by
19589 syntax_errors_to. Usually it is appropriate to set syntax_errors_to to be the
19590 same address as the generic errors_to option. The skip_syntax_errors option is
19591 often used when handling mailing lists.
19592
19593 If all the addresses in a redirection list are skipped because of syntax
19594 errors, the router declines to handle the original address, and it is passed to
19595 the following routers.
19596
19597 If skip_syntax_errors is set when an Exim filter is interpreted, any syntax
19598 error in the filter causes filtering to be abandoned without any action being
19599 taken. The incident is logged, and the router declines to handle the address,
19600 so it is passed to the following routers.
19601
19602 Syntax errors in a Sieve filter file cause the "keep" action to occur. This
19603 action is specified by RFC 3028. The values of skip_syntax_errors,
19604 syntax_errors_to, and syntax_errors_text are not used.
19605
19606 skip_syntax_errors can be used to specify that errors in users' forward lists
19607 or filter files should not prevent delivery. The syntax_errors_to option, used
19608 with an address that does not get redirected, can be used to notify users of
19609 these errors, by means of a router like this:
19610
19611 userforward:
19612 driver = redirect
19613 allow_filter
19614 check_local_user
19615 file = $home/.forward
19616 file_transport = address_file
19617 pipe_transport = address_pipe
19618 reply_transport = address_reply
19619 no_verify
19620 skip_syntax_errors
19621 syntax_errors_to = real-$local_part@$domain
19622 syntax_errors_text = \
19623 This is an automatically generated message. An error has\n\
19624 been found in your .forward file. Details of the error are\n\
19625 reported below. While this error persists, you will receive\n\
19626 a copy of this message for every message that is addressed\n\
19627 to you. If your .forward file is a filter file, or if it is\n\
19628 a non-filter file containing no valid forwarding addresses,\n\
19629 a copy of each incoming message will be put in your normal\n\
19630 mailbox. If a non-filter file contains at least one valid\n\
19631 forwarding address, forwarding to the valid addresses will\n\
19632 happen, and those will be the only deliveries that occur.
19633
19634 You also need a router to ensure that local addresses that are prefixed by
19635 "real-" are recognized, but not forwarded or filtered. For example, you could
19636 put this immediately before the userforward router:
19637
19638 real_localuser:
19639 driver = accept
19640 check_local_user
19641 local_part_prefix = real-
19642 transport = local_delivery
19643
19644 For security, it would probably be a good idea to restrict the use of this
19645 router to locally-generated messages, using a condition such as this:
19646
19647 condition = ${if match {$sender_host_address}\
19648 {\N^(|127\.0\.0\.1)$\N}}
19649
19650 +-------------------------------------------------------------+
19651 |syntax_errors_text|Use: redirect|Type: string*|Default: unset|
19652 +-------------------------------------------------------------+
19653
19654 See skip_syntax_errors above.
19655
19656 +----------------------------------------------------------+
19657 |syntax_errors_to|Use: redirect|Type: string|Default: unset|
19658 +----------------------------------------------------------+
19659
19660 See skip_syntax_errors above.
19661
19662
19663
19664 ===============================================================================
19665 23. ENVIRONMENT FOR RUNNING LOCAL TRANSPORTS
19666
19667 Local transports handle deliveries to files and pipes. (The autoreply transport
19668 can be thought of as similar to a pipe.) Exim always runs transports in
19669 subprocesses, under specified uids and gids. Typical deliveries to local
19670 mailboxes run under the uid and gid of the local user.
19671
19672 Exim also sets a specific current directory while running the transport; for
19673 some transports a home directory setting is also relevant. The pipe transport
19674 is the only one that sets up environment variables; see section 29.4 for
19675 details.
19676
19677 The values used for the uid, gid, and the directories may come from several
19678 different places. In many cases, the router that handles the address associates
19679 settings with that address as a result of its check_local_user, group, or user
19680 options. However, values may also be given in the transport's own
19681 configuration, and these override anything that comes from the router.
19682
19683
19684 23.1 Concurrent deliveries
19685 --------------------------
19686
19687 If two different messages for the same local recipient arrive more or less
19688 simultaneously, the two delivery processes are likely to run concurrently. When
19689 the appendfile transport is used to write to a file, Exim applies locking rules
19690 to stop concurrent processes from writing to the same file at the same time.
19691
19692 However, when you use a pipe transport, it is up to you to arrange any locking
19693 that is needed. Here is a silly example:
19694
19695 my_transport:
19696 driver = pipe
19697 command = /bin/sh -c 'cat >>/some/file'
19698
19699 This is supposed to write the message at the end of the file. However, if two
19700 messages arrive at the same time, the file will be scrambled. You can use the
19701 exim_lock utility program (see section 53.15) to lock a file using the same
19702 algorithm that Exim itself uses.
19703
19704
19705 23.2 Uids and gids
19706 ------------------
19707
19708 All transports have the options group and user. If group is set, it overrides
19709 any group that the router set in the address, even if user is not set for the
19710 transport. This makes it possible, for example, to run local mail delivery
19711 under the uid of the recipient (set by the router), but in a special group (set
19712 by the transport). For example:
19713
19714 # Routers ...
19715 # User/group are set by check_local_user in this router
19716 local_users:
19717 driver = accept
19718 check_local_user
19719 transport = group_delivery
19720
19721 # Transports ...
19722 # This transport overrides the group
19723 group_delivery:
19724 driver = appendfile
19725 file = /var/spool/mail/$local_part
19726 group = mail
19727
19728 If user is set for a transport, its value overrides what is set in the address
19729 by the router. If user is non-numeric and group is not set, the gid associated
19730 with the user is used. If user is numeric, group must be set.
19731
19732 When the uid is taken from the transport's configuration, the initgroups()
19733 function is called for the groups associated with that uid if the initgroups
19734 option is set for the transport. When the uid is not specified by the
19735 transport, but is associated with the address by a router, the option for
19736 calling initgroups() is taken from the router configuration.
19737
19738 The pipe transport contains the special option pipe_as_creator. If this is set
19739 and user is not set, the uid of the process that called Exim to receive the
19740 message is used, and if group is not set, the corresponding original gid is
19741 also used.
19742
19743 This is the detailed preference order for obtaining a gid; the first of the
19744 following that is set is used:
19745
19746 * A group setting of the transport;
19747
19748 * A group setting of the router;
19749
19750 * A gid associated with a user setting of the router, either as a result of
19751 check_local_user or an explicit non-numeric user setting;
19752
19753 * The group associated with a non-numeric user setting of the transport;
19754
19755 * In a pipe transport, the creator's gid if deliver_as_creator is set and the
19756 uid is the creator's uid;
19757
19758 * The Exim gid if the Exim uid is being used as a default.
19759
19760 If, for example, the user is specified numerically on the router and there are
19761 no group settings, no gid is available. In this situation, an error occurs.
19762 This is different for the uid, for which there always is an ultimate default.
19763 The first of the following that is set is used:
19764
19765 * A user setting of the transport;
19766
19767 * In a pipe transport, the creator's uid if deliver_as_creator is set;
19768
19769 * A user setting of the router;
19770
19771 * A check_local_user setting of the router;
19772
19773 * The Exim uid.
19774
19775 Of course, an error will still occur if the uid that is chosen is on the
19776 never_users list.
19777
19778
19779 23.3 Current and home directories
19780 ---------------------------------
19781
19782 Routers may set current and home directories for local transports by means of
19783 the transport_current_directory and transport_home_directory options. However,
19784 if the transport's current_directory or home_directory options are set, they
19785 override the router's values. In detail, the home directory for a local
19786 transport is taken from the first of these values that is set:
19787
19788 * The home_directory option on the transport;
19789
19790 * The transport_home_directory option on the router;
19791
19792 * The password data if check_local_user is set on the router;
19793
19794 * The router_home_directory option on the router.
19795
19796 The current directory is taken from the first of these values that is set:
19797
19798 * The current_directory option on the transport;
19799
19800 * The transport_current_directory option on the router.
19801
19802 If neither the router nor the transport sets a current directory, Exim uses the
19803 value of the home directory, if it is set. Otherwise it sets the current
19804 directory to / before running a local transport.
19805
19806
19807 23.4 Expansion variables derived from the address
19808 -------------------------------------------------
19809
19810 Normally a local delivery is handling a single address, and in that case the
19811 variables such as $domain and $local_part are set during local deliveries.
19812 However, in some circumstances more than one address may be handled at once
19813 (for example, while writing batch SMTP for onward transmission by some other
19814 means). In this case, the variables associated with the local part are never
19815 set, $domain is set only if all the addresses have the same domain, and
19816 $original_domain is never set.
19817
19818
19819
19820 ===============================================================================
19821 24. GENERIC OPTIONS FOR TRANSPORTS
19822
19823 The following generic options apply to all transports:
19824
19825 +------------------------------------------------------+
19826 |body_only|Use: transports|Type: boolean|Default: false|
19827 +------------------------------------------------------+
19828
19829 If this option is set, the message's headers are not transported. It is
19830 mutually exclusive with headers_only. If it is used with the appendfile or pipe
19831 transports, the settings of message_prefix and message_suffix should be
19832 checked, because this option does not automatically suppress them.
19833
19834 +--------------------------------------------------------------+
19835 |current_directory|Use: transports|Type: string*|Default: unset|
19836 +--------------------------------------------------------------+
19837
19838 This specifies the current directory that is to be set while running the
19839 transport, overriding any value that may have been set by the router. If the
19840 expansion fails for any reason, including forced failure, an error is logged,
19841 and delivery is deferred.
19842
19843 +------------------------------------------------------------+
19844 |disable_logging|Use: transports|Type: boolean|Default: false|
19845 +------------------------------------------------------------+
19846
19847 If this option is set true, nothing is logged for any deliveries by the
19848 transport or for any transport errors. You should not set this option unless
19849 you really, really know what you are doing.
19850
19851 +--------------------------------------------------------+
19852 |debug_print|Use: transports|Type: string*|Default: unset|
19853 +--------------------------------------------------------+
19854
19855 If this option is set and debugging is enabled (see the -d command line
19856 option), the string is expanded and included in the debugging output when the
19857 transport is run. If expansion of the string fails, the error message is
19858 written to the debugging output, and Exim carries on processing. This facility
19859 is provided to help with checking out the values of variables and so on when
19860 debugging driver configurations. For example, if a headers_add option is not
19861 working properly, debug_print could be used to output the variables it
19862 references. A newline is added to the text if it does not end with one. The
19863 variables $transport_name and $router_name contain the name of the transport
19864 and the router that called it.
19865
19866 +--------------------------------------------------------------+
19867 |delivery_date_add|Use: transports|Type: boolean|Default: false|
19868 +--------------------------------------------------------------+
19869
19870 If this option is true, a Delivery-date: header is added to the message. This
19871 gives the actual time the delivery was made. As this is not a standard header,
19872 Exim has a configuration option (delivery_date_remove) which requests its
19873 removal from incoming messages, so that delivered messages can safely be resent
19874 to other recipients.
19875
19876 +--------------------------------------------------+
19877 |driver|Use: transports|Type: string|Default: unset|
19878 +--------------------------------------------------+
19879
19880 This specifies which of the available transport drivers is to be used. There is
19881 no default, and this option must be set for every transport.
19882
19883 +------------------------------------------------------------+
19884 |envelope_to_add|Use: transports|Type: boolean|Default: false|
19885 +------------------------------------------------------------+
19886
19887 If this option is true, an Envelope-to: header is added to the message. This
19888 gives the original address(es) in the incoming envelope that caused this
19889 delivery to happen. More than one address may be present if the transport is
19890 configured to handle several addresses at once, or if more than one original
19891 address was redirected to the same final address. As this is not a standard
19892 header, Exim has a configuration option (envelope_to_remove) which requests its
19893 removal from incoming messages, so that delivered messages can safely be resent
19894 to other recipients.
19895
19896 +---------------------------------------------------------+
19897 |event_action|Use: transports|Type: string*|Default: unset|
19898 +---------------------------------------------------------+
19899
19900 This option declares a string to be expanded for Exim's events mechanism. For
19901 details see chapter 60.
19902
19903 +-------------------------------------------------------+
19904 |group|Use: transports|Type: string*|Default: Exim group|
19905 +-------------------------------------------------------+
19906
19907 This option specifies a gid for running the transport process, overriding any
19908 value that the router supplies, and also overriding any value associated with
19909 user (see below).
19910
19911 +------------------------------------------------------+
19912 |headers_add|Use: transports|Type: list*|Default: unset|
19913 +------------------------------------------------------+
19914
19915 This option specifies a list of text headers, newline-separated (by default,
19916 changeable in the usual way 6.21), which are (separately) expanded and added to
19917 the header portion of a message as it is transported, as described in section
19918 47.17. Additional header lines can also be specified by routers. If the result
19919 of the expansion is an empty string, or if the expansion is forced to fail, no
19920 action is taken. Other expansion failures are treated as errors and cause the
19921 delivery to be deferred.
19922
19923 Unlike most options, headers_add can be specified multiple times for a
19924 transport; all listed headers are added.
19925
19926 +---------------------------------------------------------+
19927 |headers_only|Use: transports|Type: boolean|Default: false|
19928 +---------------------------------------------------------+
19929
19930 If this option is set, the message's body is not transported. It is mutually
19931 exclusive with body_only. If it is used with the appendfile or pipe transports,
19932 the settings of message_prefix and message_suffix should be checked, since this
19933 option does not automatically suppress them.
19934
19935 +---------------------------------------------------------+
19936 |headers_remove|Use: transports|Type: list*|Default: unset|
19937 +---------------------------------------------------------+
19938
19939 This option specifies a list of header names, colon-separated (by default,
19940 changeable in the usual way 6.21); these headers are omitted from the message
19941 as it is transported, as described in section 47.17. Header removal can also be
19942 specified by routers. Each list item is separately expanded. If the result of
19943 the expansion is an empty string, or if the expansion is forced to fail, no
19944 action is taken. Other expansion failures are treated as errors and cause the
19945 delivery to be deferred.
19946
19947 Unlike most options, headers_remove can be specified multiple times for a
19948 transport; all listed headers are removed.
19949
19950 Warning: Because of the separate expansion of the list items, items that
19951 contain a list separator must have it doubled. To avoid this, change the list
19952 separator (6.21).
19953
19954 +-----------------------------------------------------------+
19955 |headers_rewrite|Use: transports|Type: string|Default: unset|
19956 +-----------------------------------------------------------+
19957
19958 This option allows addresses in header lines to be rewritten at transport time,
19959 that is, as the message is being copied to its destination. The contents of the
19960 option are a colon-separated list of rewriting rules. Each rule is in exactly
19961 the same form as one of the general rewriting rules that are applied when a
19962 message is received. These are described in chapter 31. For example,
19963
19964 headers_rewrite = a@b c@d f : \
19965 x@y w@z
19966
19967 changes a@b into c@d in From: header lines, and x@y into w@z in all
19968 address-bearing header lines. The rules are applied to the header lines just
19969 before they are written out at transport time, so they affect only those copies
19970 of the message that pass through the transport. However, only the message's
19971 original header lines, and any that were added by a system filter, are
19972 rewritten. If a router or transport adds header lines, they are not affected by
19973 this option. These rewriting rules are not applied to the envelope. You can
19974 change the return path using return_path, but you cannot change envelope
19975 recipients at this time.
19976
19977 +-----------------------------------------------------------+
19978 |home_directory|Use: transports|Type: string*|Default: unset|
19979 +-----------------------------------------------------------+
19980
19981 This option specifies a home directory setting for a local transport,
19982 overriding any value that may be set by the router. The home directory is
19983 placed in $home while expanding the transport's private options. It is also
19984 used as the current directory if no current directory is set by the
19985 current_directory option on the transport or the transport_current_directory
19986 option on the router. If the expansion fails for any reason, including forced
19987 failure, an error is logged, and delivery is deferred.
19988
19989 +-------------------------------------------------------+
19990 |initgroups|Use: transports|Type: boolean|Default: false|
19991 +-------------------------------------------------------+
19992
19993 If this option is true and the uid for the delivery process is provided by the
19994 transport, the initgroups() function is called when running the transport to
19995 ensure that any additional groups associated with the uid are set up.
19996
19997 +----------------------------------------------------------+
19998 |max_parallel|Use: transports|Type: integer*|Default: unset|
19999 +----------------------------------------------------------+
20000
20001 If this option is set and expands to an integer greater than zero it limits the
20002 number of concurrent runs of the transport. The control does not apply to
20003 shadow transports.
20004
20005 Exim implements this control by means of a hints database in which a record is
20006 incremented whenever a transport process is being created. The record is
20007 decremented and possibly removed when the process terminates. Obviously there
20008 is scope for records to get left lying around if there is a system or program
20009 crash. To guard against this, Exim ignores any records that are more than six
20010 hours old.
20011
20012 If you use this option, you should also arrange to delete the relevant hints
20013 database whenever your system reboots. The names of the files start with misc
20014 and they are kept in the spool/db directory. There may be one or two files,
20015 depending on the type of DBM in use. The same files are used for ETRN and smtp
20016 transport serialization.
20017
20018 +-----------------------------------------------------------+
20019 |message_size_limit|Use: transports|Type: string*|Default: 0|
20020 +-----------------------------------------------------------+
20021
20022 This option controls the size of messages passed through the transport. It is
20023 expanded before use; the result of the expansion must be a sequence of decimal
20024 digits, optionally followed by K or M. If the expansion fails for any reason,
20025 including forced failure, or if the result is not of the required form,
20026 delivery is deferred. If the value is greater than zero and the size of a
20027 message exceeds this limit, the address is failed. If there is any chance that
20028 the resulting bounce message could be routed to the same transport, you should
20029 ensure that return_size_limit is less than the transport's message_size_limit,
20030 as otherwise the bounce message will fail to get delivered.
20031
20032 +-----------------------------------------------------------------+
20033 |rcpt_include_affixes|Use: transports|Type: boolean|Default: false|
20034 +-----------------------------------------------------------------+
20035
20036 When this option is false (the default), and an address that has had any
20037 affixes (prefixes or suffixes) removed from the local part is delivered by any
20038 form of SMTP or LMTP, the affixes are not included. For example, if a router
20039 that contains
20040
20041 local_part_prefix = *-
20042
20043 routes the address abc-xyz@some.domain to an SMTP transport, the envelope is
20044 delivered with
20045
20046 RCPT TO:<xyz@some.domain>
20047
20048 This is also the case when an ACL-time callout is being used to verify a
20049 recipient address. However, if rcpt_include_affixes is set true, the whole
20050 local part is included in the RCPT command. This option applies to BSMTP
20051 deliveries by the appendfile and pipe transports as well as to the lmtp and
20052 smtp transports.
20053
20054 +---------------------------------------------------------------------+
20055 |retry_use_local_part|Use: transports|Type: boolean|Default: see below|
20056 +---------------------------------------------------------------------+
20057
20058 When a delivery suffers a temporary failure, a retry record is created in
20059 Exim's hints database. For remote deliveries, the key for the retry record is
20060 based on the name and/or IP address of the failing remote host. For local
20061 deliveries, the key is normally the entire address, including both the local
20062 part and the domain. This is suitable for most common cases of local delivery
20063 temporary failure - for example, exceeding a mailbox quota should delay only
20064 deliveries to that mailbox, not to the whole domain.
20065
20066 However, in some special cases you may want to treat a temporary local delivery
20067 as a failure associated with the domain, and not with a particular local part.
20068 (For example, if you are storing all mail for some domain in files.) You can do
20069 this by setting retry_use_local_part false.
20070
20071 For all the local transports, its default value is true. For remote transports,
20072 the default value is false for tidiness, but changing the value has no effect
20073 on a remote transport in the current implementation.
20074
20075 +--------------------------------------------------------+
20076 |return_path|Use: transports|Type: string*|Default: unset|
20077 +--------------------------------------------------------+
20078
20079 If this option is set, the string is expanded at transport time and replaces
20080 the existing return path (envelope sender) value in the copy of the message
20081 that is being delivered. An empty return path is permitted. This feature is
20082 designed for remote deliveries, where the value of this option is used in the
20083 SMTP MAIL command. If you set return_path for a local transport, the only
20084 effect is to change the address that is placed in the Return-path: header line,
20085 if one is added to the message (see the next option).
20086
20087 Note: A changed return path is not logged unless you add
20088 return_path_on_delivery to the log selector.
20089
20090 The expansion can refer to the existing value via $return_path. This is either
20091 the message's envelope sender, or an address set by the errors_to option on a
20092 router. If the expansion is forced to fail, no replacement occurs; if it fails
20093 for another reason, delivery is deferred. This option can be used to support
20094 VERP (Variable Envelope Return Paths) - see section 50.6.
20095
20096 Note: If a delivery error is detected locally, including the case when a remote
20097 server rejects a message at SMTP time, the bounce message is not sent to the
20098 value of this option. It is sent to the previously set errors address. This
20099 defaults to the incoming sender address, but can be changed by setting
20100 errors_to in a router.
20101
20102 +------------------------------------------------------------+
20103 |return_path_add|Use: transports|Type: boolean|Default: false|
20104 +------------------------------------------------------------+
20105
20106 If this option is true, a Return-path: header is added to the message. Although
20107 the return path is normally available in the prefix line of BSD mailboxes, this
20108 is commonly not displayed by MUAs, and so the user does not have easy access to
20109 it.
20110
20111 RFC 2821 states that the Return-path: header is added to a message "when the
20112 delivery SMTP server makes the final delivery". This implies that this header
20113 should not be present in incoming messages. Exim has a configuration option,
20114 return_path_remove, which requests removal of this header from incoming
20115 messages, so that delivered messages can safely be resent to other recipients.
20116
20117 +-------------------------------------------------------------+
20118 |shadow_condition|Use: transports|Type: string*|Default: unset|
20119 +-------------------------------------------------------------+
20120
20121 See shadow_transport below.
20122
20123 +------------------------------------------------------------+
20124 |shadow_transport|Use: transports|Type: string|Default: unset|
20125 +------------------------------------------------------------+
20126
20127 A local transport may set the shadow_transport option to the name of another
20128 local transport. Shadow remote transports are not supported.
20129
20130 Whenever a delivery to the main transport succeeds, and either shadow_condition
20131 is unset, or its expansion does not result in the empty string or one of the
20132 strings "0" or "no" or "false", the message is also passed to the shadow
20133 transport, with the same delivery address or addresses. If expansion fails, no
20134 action is taken except that non-forced expansion failures cause a log line to
20135 be written.
20136
20137 The result of the shadow transport is discarded and does not affect the
20138 subsequent processing of the message. Only a single level of shadowing is
20139 provided; the shadow_transport option is ignored on any transport when it is
20140 running as a shadow. Options concerned with output from pipes are also ignored.
20141 The log line for the successful delivery has an item added on the end, of the
20142 form
20143
20144 ST=<shadow transport name>
20145
20146 If the shadow transport did not succeed, the error message is put in
20147 parentheses afterwards. Shadow transports can be used for a number of different
20148 purposes, including keeping more detailed log information than Exim normally
20149 provides, and implementing automatic acknowledgment policies based on message
20150 headers that some sites insist on.
20151
20152 +-------------------------------------------------------------+
20153 |transport_filter|Use: transports|Type: string*|Default: unset|
20154 +-------------------------------------------------------------+
20155
20156 This option sets up a filtering (in the Unix shell sense) process for messages
20157 at transport time. It should not be confused with mail filtering as set up by
20158 individual users or via a system filter. If unset, or expanding to an empty
20159 string, no filtering is done.
20160
20161 When the message is about to be written out, the command specified by
20162 transport_filter is started up in a separate, parallel process, and the entire
20163 message, including the header lines, is passed to it on its standard input
20164 (this in fact is done from a third process, to avoid deadlock). The command
20165 must be specified as an absolute path.
20166
20167 The lines of the message that are written to the transport filter are
20168 terminated by newline ("\n"). The message is passed to the filter before any
20169 SMTP-specific processing, such as turning "\n" into "\r\n" and escaping lines
20170 beginning with a dot, and also before any processing implied by the settings of
20171 check_string and escape_string in the appendfile or pipe transports.
20172
20173 The standard error for the filter process is set to the same destination as its
20174 standard output; this is read and written to the message's ultimate
20175 destination. The process that writes the message to the filter, the filter
20176 itself, and the original process that reads the result and delivers it are all
20177 run in parallel, like a shell pipeline.
20178
20179 The filter can perform any transformations it likes, but of course should take
20180 care not to break RFC 2822 syntax. Exim does not check the result, except to
20181 test for a final newline when SMTP is in use. All messages transmitted over
20182 SMTP must end with a newline, so Exim supplies one if it is missing.
20183
20184 A transport filter can be used to provide content-scanning on a per-user basis
20185 at delivery time if the only required effect of the scan is to modify the
20186 message. For example, a content scan could insert a new header line containing
20187 a spam score. This could be interpreted by a filter in the user's MUA. It is
20188 not possible to discard a message at this stage.
20189
20190 A problem might arise if the filter increases the size of a message that is
20191 being sent down an SMTP connection. If the receiving SMTP server has indicated
20192 support for the SIZE parameter, Exim will have sent the size of the message at
20193 the start of the SMTP session. If what is actually sent is substantially more,
20194 the server might reject the message. This can be worked round by setting the
20195 size_addition option on the smtp transport, either to allow for additions to
20196 the message, or to disable the use of SIZE altogether.
20197
20198 The value of the transport_filter option is the command string for starting the
20199 filter, which is run directly from Exim, not under a shell. The string is
20200 parsed by Exim in the same way as a command string for the pipe transport: Exim
20201 breaks it up into arguments and then expands each argument separately (see
20202 section 29.3). Any kind of expansion failure causes delivery to be deferred.
20203 The special argument $pipe_addresses is replaced by a number of arguments, one
20204 for each address that applies to this delivery. (This isn't an ideal name for
20205 this feature here, but as it was already implemented for the pipe transport, it
20206 seemed sensible not to change it.)
20207
20208 The expansion variables $host and $host_address are available when the
20209 transport is a remote one. They contain the name and IP address of the host to
20210 which the message is being sent. For example:
20211
20212 transport_filter = /some/directory/transport-filter.pl \
20213 $host $host_address $sender_address $pipe_addresses
20214
20215 Two problems arise if you want to use more complicated expansion items to
20216 generate transport filter commands, both of which due to the fact that the
20217 command is split up before expansion.
20218
20219 * If an expansion item contains white space, you must quote it, so that it is
20220 all part of the same command item. If the entire option setting is one such
20221 expansion item, you have to take care what kind of quoting you use. For
20222 example:
20223
20224 transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
20225
20226 This runs the command /bin/cmd1 if the host name is a.b.c, and /bin/cmd2
20227 otherwise. If double quotes had been used, they would have been stripped by
20228 Exim when it read the option's value. When the value is used, if the single
20229 quotes were missing, the line would be split into two items, "/bin/cmd${if"
20230 and "eq{$host}{a.b.c}{1}{2}", and an error would occur when Exim tried to
20231 expand the first one.
20232
20233 * Except for the special case of $pipe_addresses that is mentioned above, an
20234 expansion cannot generate multiple arguments, or a command name followed by
20235 arguments. Consider this example:
20236
20237 transport_filter = ${lookup{$host}lsearch{/a/file}\
20238 {$value}{/bin/cat}}
20239
20240 The result of the lookup is interpreted as the name of the command, even if
20241 it contains white space. The simplest way round this is to use a shell:
20242
20243 transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\
20244 {$value}{/bin/cat}}
20245
20246 The filter process is run under the same uid and gid as the normal delivery.
20247 For remote deliveries this is the Exim uid/gid by default. The command should
20248 normally yield a zero return code. Transport filters are not supposed to fail.
20249 A non-zero code is taken to mean that the transport filter encountered some
20250 serious problem. Delivery of the message is deferred; the message remains on
20251 the queue and is tried again later. It is not possible to cause a message to be
20252 bounced from a transport filter.
20253
20254 If a transport filter is set on an autoreply transport, the original message is
20255 passed through the filter as it is being copied into the newly generated
20256 message, which happens if the return_message option is set.
20257
20258 +---------------------------------------------------------------+
20259 |transport_filter_timeout|Use: transports|Type: time|Default: 5m|
20260 +---------------------------------------------------------------+
20261
20262 When Exim is reading the output of a transport filter, it applies a timeout
20263 that can be set by this option. Exceeding the timeout is normally treated as a
20264 temporary delivery failure. However, if a transport filter is used with a pipe
20265 transport, a timeout in the transport filter is treated in the same way as a
20266 timeout in the pipe command itself. By default, a timeout is a hard error, but
20267 if the pipe transport's timeout_defer option is set true, it becomes a
20268 temporary error.
20269
20270 +-----------------------------------------------------+
20271 |user|Use: transports|Type: string*|Default: Exim user|
20272 +-----------------------------------------------------+
20273
20274 This option specifies the user under whose uid the delivery process is to be
20275 run, overriding any uid that may have been set by the router. If the user is
20276 given as a name, the uid is looked up from the password data, and the
20277 associated group is taken as the value of the gid to be used if the group
20278 option is not set.
20279
20280 For deliveries that use local transports, a user and group are normally
20281 specified explicitly or implicitly (for example, as a result of
20282 check_local_user) by the router or transport.
20283
20284 For remote transports, you should leave this option unset unless you really are
20285 sure you know what you are doing. When a remote transport is running, it needs
20286 to be able to access Exim's hints databases, because each host may have its own
20287 retry data.
20288
20289
20290
20291 ===============================================================================
20292 25. ADDRESS BATCHING IN LOCAL TRANSPORTS
20293
20294 The only remote transport (smtp) is normally configured to handle more than one
20295 address at a time, so that when several addresses are routed to the same remote
20296 host, just one copy of the message is sent. Local transports, however, normally
20297 handle one address at a time. That is, a separate instance of the transport is
20298 run for each address that is routed to the transport. A separate copy of the
20299 message is delivered each time.
20300
20301 In special cases, it may be desirable to handle several addresses at once in a
20302 local transport, for example:
20303
20304 * In an appendfile transport, when storing messages in files for later
20305 delivery by some other means, a single copy of the message with multiple
20306 recipients saves space.
20307
20308 * In an lmtp transport, when delivering over "local SMTP" to some process, a
20309 single copy saves time, and is the normal way LMTP is expected to work.
20310
20311 * In a pipe transport, when passing the message to a scanner program or to
20312 some other delivery mechanism such as UUCP, multiple recipients may be
20313 acceptable.
20314
20315 These three local transports all have the same options for controlling multiple
20316 ("batched") deliveries, namely batch_max and batch_id. To save repeating the
20317 information for each transport, these options are described here.
20318
20319 The batch_max option specifies the maximum number of addresses that can be
20320 delivered together in a single run of the transport. Its default value is one
20321 (no batching). When more than one address is routed to a transport that has a
20322 batch_max value greater than one, the addresses are delivered in a batch (that
20323 is, in a single run of the transport with multiple recipients), subject to
20324 certain conditions:
20325
20326 * If any of the transport's options contain a reference to $local_part, no
20327 batching is possible.
20328
20329 * If any of the transport's options contain a reference to $domain, only
20330 addresses with the same domain are batched.
20331
20332 * If batch_id is set, it is expanded for each address, and only those
20333 addresses with the same expanded value are batched. This allows you to
20334 specify customized batching conditions. Failure of the expansion for any
20335 reason, including forced failure, disables batching, but it does not stop
20336 the delivery from taking place.
20337
20338 * Batched addresses must also have the same errors address (where to send
20339 delivery errors), the same header additions and removals, the same user and
20340 group for the transport, and if a host list is present, the first host must
20341 be the same.
20342
20343 In the case of the appendfile and pipe transports, batching applies both when
20344 the file or pipe command is specified in the transport, and when it is
20345 specified by a redirect router, but all the batched addresses must of course be
20346 routed to the same file or pipe command. These two transports have an option
20347 called use_bsmtp, which causes them to deliver the message in "batched SMTP"
20348 format, with the envelope represented as SMTP commands. The check_string and
20349 escape_string options are forced to the values
20350
20351 check_string = "."
20352 escape_string = ".."
20353
20354 when batched SMTP is in use. A full description of the batch SMTP mechanism is
20355 given in section 48.10. The lmtp transport does not have a use_bsmtp option,
20356 because it always delivers using the SMTP protocol.
20357
20358 If the generic envelope_to_add option is set for a batching transport, the
20359 Envelope-to: header that is added to the message contains all the addresses
20360 that are being processed together. If you are using a batching appendfile
20361 transport without use_bsmtp, the only way to preserve the recipient addresses
20362 is to set the envelope_to_add option.
20363
20364 If you are using a pipe transport without BSMTP, and setting the transport's
20365 command option, you can include $pipe_addresses as part of the command. This is
20366 not a true variable; it is a bit of magic that causes each of the recipient
20367 addresses to be inserted into the command as a separate argument. This provides
20368 a way of accessing all the addresses that are being delivered in the batch.
20369 Note: This is not possible for pipe commands that are specified by a redirect
20370 router.
20371
20372
20373
20374 ===============================================================================
20375 26. THE APPENDFILE TRANSPORT
20376
20377 The appendfile transport delivers a message by appending it to an existing
20378 file, or by creating an entirely new file in a specified directory. Single
20379 files to which messages are appended can be in the traditional Unix mailbox
20380 format, or optionally in the MBX format supported by the Pine MUA and
20381 University of Washington IMAP daemon, inter alia. When each message is being
20382 delivered as a separate file, "maildir" format can optionally be used to give
20383 added protection against failures that happen part-way through the delivery. A
20384 third form of separate-file delivery known as "mailstore" is also supported.
20385 For all file formats, Exim attempts to create as many levels of directory as
20386 necessary, provided that create_directory is set.
20387
20388 The code for the optional formats is not included in the Exim binary by
20389 default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or
20390 SUPPORT_MAILSTORE in Local/Makefile to have the appropriate code included.
20391
20392 Exim recognizes system quota errors, and generates an appropriate message. Exim
20393 also supports its own quota control within the transport, for use when the
20394 system facility is unavailable or cannot be used for some reason.
20395
20396 If there is an error while appending to a file (for example, quota exceeded or
20397 partition filled), Exim attempts to reset the file's length and last
20398 modification time back to what they were before. If there is an error while
20399 creating an entirely new file, the new file is removed.
20400
20401 Before appending to a file, a number of security checks are made, and the file
20402 is locked. A detailed description is given below, after the list of private
20403 options.
20404
20405 The appendfile transport is most commonly used for local deliveries to users'
20406 mailboxes. However, it can also be used as a pseudo-remote transport for
20407 putting messages into files for remote delivery by some means other than Exim.
20408 "Batch SMTP" format is often used in this case (see the use_bsmtp option).
20409
20410
20411 26.1 The file and directory options
20412 -----------------------------------
20413
20414 The file option specifies a single file, to which the message is appended; the
20415 directory option specifies a directory, in which a new file containing the
20416 message is created. Only one of these two options can be set, and for normal
20417 deliveries to mailboxes, one of them must be set.
20418
20419 However, appendfile is also used for delivering messages to files or
20420 directories whose names (or parts of names) are obtained from alias,
20421 forwarding, or filtering operations (for example, a save command in a user's
20422 Exim filter). When such a transport is running, $local_part contains the local
20423 part that was aliased or forwarded, and $address_file contains the name (or
20424 partial name) of the file or directory generated by the redirection operation.
20425 There are two cases:
20426
20427 * If neither file nor directory is set, the redirection operation must
20428 specify an absolute path (one that begins with "/"). This is the most
20429 common case when users with local accounts use filtering to sort mail into
20430 different folders. See for example, the address_file transport in the
20431 default configuration. If the path ends with a slash, it is assumed to be
20432 the name of a directory. A delivery to a directory can also be forced by
20433 setting maildir_format or mailstore_format.
20434
20435 * If file or directory is set for a delivery from a redirection, it is used
20436 to determine the file or directory name for the delivery. Normally, the
20437 contents of $address_file are used in some way in the string expansion.
20438
20439 As an example of the second case, consider an environment where users do not
20440 have home directories. They may be permitted to use Exim filter commands of the
20441 form:
20442
20443 save folder23
20444
20445 or Sieve filter commands of the form:
20446
20447 require "fileinto";
20448 fileinto "folder23";
20449
20450 In this situation, the expansion of file or directory in the transport must
20451 transform the relative path into an appropriate absolute filename. In the case
20452 of Sieve filters, the name inbox must be handled. It is the name that is used
20453 as a result of a "keep" action in the filter. This example shows one way of
20454 handling this requirement:
20455
20456 file = ${if eq{$address_file}{inbox} \
20457 {/var/mail/$local_part} \
20458 {${if eq{${substr_0_1:$address_file}}{/} \
20459 {$address_file} \
20460 {$home/mail/$address_file} \
20461 }} \
20462 }
20463
20464 With this setting of file, inbox refers to the standard mailbox location,
20465 absolute paths are used without change, and other folders are in the mail
20466 directory within the home directory.
20467
20468 Note 1: While processing an Exim filter, a relative path such as folder23 is
20469 turned into an absolute path if a home directory is known to the router. In
20470 particular, this is the case if check_local_user is set. If you want to prevent
20471 this happening at routing time, you can set router_home_directory empty. This
20472 forces the router to pass the relative path to the transport.
20473
20474 Note 2: An absolute path in $address_file is not treated specially; the file or
20475 directory option is still used if it is set.
20476
20477
20478 26.2 Private options for appendfile
20479 -----------------------------------
20480
20481 +-------------------------------------------------------+
20482 |allow_fifo|Use: appendfile|Type: boolean|Default: false|
20483 +-------------------------------------------------------+
20484
20485 Setting this option permits delivery to named pipes (FIFOs) as well as to
20486 regular files. If no process is reading the named pipe at delivery time, the
20487 delivery is deferred.
20488
20489 +----------------------------------------------------------+
20490 |allow_symlink|Use: appendfile|Type: boolean|Default: false|
20491 +----------------------------------------------------------+
20492
20493 By default, appendfile will not deliver if the path name for the file is that
20494 of a symbolic link. Setting this option relaxes that constraint, but there are
20495 security issues involved in the use of symbolic links. Be sure you know what
20496 you are doing if you set this. Details of exactly what this option affects are
20497 included in the discussion which follows this list of options.
20498
20499 +-----------------------------------------------------+
20500 |batch_id|Use: appendfile|Type: string*|Default: unset|
20501 +-----------------------------------------------------+
20502
20503 See the description of local delivery batching in chapter 25. However, batching
20504 is automatically disabled for appendfile deliveries that happen as a result of
20505 forwarding or aliasing or other redirection directly to a file.
20506
20507 +--------------------------------------------------+
20508 |batch_max|Use: appendfile|Type: integer|Default: 1|
20509 +--------------------------------------------------+
20510
20511 See the description of local delivery batching in chapter 25.
20512
20513 +--------------------------------------------------------+
20514 |check_group|Use: appendfile|Type: boolean|Default: false|
20515 +--------------------------------------------------------+
20516
20517 When this option is set, the group owner of the file defined by the file option
20518 is checked to see that it is the same as the group under which the delivery
20519 process is running. The default setting is false because the default file mode
20520 is 0600, which means that the group is irrelevant.
20521
20522 +-------------------------------------------------------+
20523 |check_owner|Use: appendfile|Type: boolean|Default: true|
20524 +-------------------------------------------------------+
20525
20526 When this option is set, the owner of the file defined by the file option is
20527 checked to ensure that it is the same as the user under which the delivery
20528 process is running.
20529
20530 +------------------------------------------------------------+
20531 |check_string|Use: appendfile|Type: string|Default: see below|
20532 +------------------------------------------------------------+
20533
20534 As appendfile writes the message, the start of each line is tested for matching
20535 check_string, and if it does, the initial matching characters are replaced by
20536 the contents of escape_string. The value of check_string is a literal string,
20537 not a regular expression, and the case of any letters it contains is
20538 significant.
20539
20540 If use_bsmtp is set the values of check_string and escape_string are forced to
20541 "." and ".." respectively, and any settings in the configuration are ignored.
20542 Otherwise, they default to "From " and ">From " when the file option is set,
20543 and unset when any of the directory, maildir, or mailstore options are set.
20544
20545 The default settings, along with message_prefix and message_suffix, are
20546 suitable for traditional "BSD" mailboxes, where a line beginning with "From "
20547 indicates the start of a new message. All four options need changing if another
20548 format is used. For example, to deliver to mailboxes in MMDF format:
20549
20550 check_string = "\1\1\1\1\n"
20551 escape_string = "\1\1\1\1 \n"
20552 message_prefix = "\1\1\1\1\n"
20553 message_suffix = "\1\1\1\1\n"
20554
20555 +------------------------------------------------------------+
20556 |create_directory|Use: appendfile|Type: boolean|Default: true|
20557 +------------------------------------------------------------+
20558
20559 When this option is true, Exim attempts to create any missing superior
20560 directories for the file that it is about to write. A created directory's mode
20561 is given by the directory_mode option.
20562
20563 The group ownership of a newly created directory is highly dependent on the
20564 operating system (and possibly the file system) that is being used. For
20565 example, in Solaris, if the parent directory has the setgid bit set, its group
20566 is propagated to the child; if not, the currently set group is used. However,
20567 in FreeBSD, the parent's group is always used.
20568
20569 +----------------------------------------------------------+
20570 |create_file|Use: appendfile|Type: string|Default: anywhere|
20571 +----------------------------------------------------------+
20572
20573 This option constrains the location of files and directories that are created
20574 by this transport. It applies to files defined by the file option and
20575 directories defined by the directory option. In the case of maildir delivery,
20576 it applies to the top level directory, not the maildir directories beneath.
20577
20578 The option must be set to one of the words "anywhere", "inhome", or
20579 "belowhome". In the second and third cases, a home directory must have been set
20580 for the transport. This option is not useful when an explicit filename is given
20581 for normal mailbox deliveries. It is intended for the case when filenames are
20582 generated from users' .forward files. These are usually handled by an
20583 appendfile transport called address_file. See also file_must_exist.
20584
20585 +------------------------------------------------------+
20586 |directory|Use: appendfile|Type: string*|Default: unset|
20587 +------------------------------------------------------+
20588
20589 This option is mutually exclusive with the file option, but one of file or
20590 directory must be set, unless the delivery is the direct result of a
20591 redirection (see section 26.1).
20592
20593 When directory is set, the string is expanded, and the message is delivered
20594 into a new file or files in or below the given directory, instead of being
20595 appended to a single mailbox file. A number of different formats are provided
20596 (see maildir_format and mailstore_format), and see section 26.4 for further
20597 details of this form of delivery.
20598
20599 +---------------------------------------------------------------+
20600 |directory_file|Use: appendfile|Type: string*|Default: see below|
20601 +---------------------------------------------------------------+
20602
20603 When directory is set, but neither maildir_format nor mailstore_format is set,
20604 appendfile delivers each message into a file whose name is obtained by
20605 expanding this string. The default value is:
20606
20607 q${base62:$tod_epoch}-$inode
20608
20609 This generates a unique name from the current time, in base 62 form, and the
20610 inode of the file. The variable $inode is available only when expanding this
20611 option.
20612
20613 +----------------------------------------------------------------+
20614 |directory_mode|Use: appendfile|Type: octal integer|Default: 0700|
20615 +----------------------------------------------------------------+
20616
20617 If appendfile creates any directories as a result of the create_directory
20618 option, their mode is specified by this option.
20619
20620 +-------------------------------------------------------------------+
20621 |escape_string|Use: appendfile|Type: string|Default: see description|
20622 +-------------------------------------------------------------------+
20623
20624 See check_string above.
20625
20626 +-------------------------------------------------+
20627 |file|Use: appendfile|Type: string*|Default: unset|
20628 +-------------------------------------------------+
20629
20630 This option is mutually exclusive with the directory option, but one of file or
20631 directory must be set, unless the delivery is the direct result of a
20632 redirection (see section 26.1). The file option specifies a single file, to
20633 which the message is appended. One or more of use_fcntl_lock, use_flock_lock,
20634 or use_lockfile must be set with file.
20635
20636 If you are using more than one host to deliver over NFS into the same
20637 mailboxes, you should always use lock files.
20638
20639 The string value is expanded for each delivery, and must yield an absolute
20640 path. The most common settings of this option are variations on one of these
20641 examples:
20642
20643 file = /var/spool/mail/$local_part
20644 file = /home/$local_part/inbox
20645 file = $home/inbox
20646
20647 In the first example, all deliveries are done into the same directory. If Exim
20648 is configured to use lock files (see use_lockfile below) it must be able to
20649 create a file in the directory, so the "sticky" bit must be turned on for
20650 deliveries to be possible, or alternatively the group option can be used to run
20651 the delivery under a group id which has write access to the directory.
20652
20653 +-------------------------------------------------------+
20654 |file_format|Use: appendfile|Type: string|Default: unset|
20655 +-------------------------------------------------------+
20656
20657 This option requests the transport to check the format of an existing file
20658 before adding to it. The check consists of matching a specific string at the
20659 start of the file. The value of the option consists of an even number of
20660 colon-separated strings. The first of each pair is the test string, and the
20661 second is the name of a transport. If the transport associated with a matched
20662 string is not the current transport, control is passed over to the other
20663 transport. For example, suppose the standard local_delivery transport has this
20664 added to it:
20665
20666 file_format = "From : local_delivery :\
20667 \1\1\1\1\n : local_mmdf_delivery"
20668
20669 Mailboxes that begin with "From" are still handled by this transport, but if a
20670 mailbox begins with four binary ones followed by a newline, control is passed
20671 to a transport called local_mmdf_delivery, which presumably is configured to do
20672 the delivery in MMDF format. If a mailbox does not exist or is empty, it is
20673 assumed to match the current transport. If the start of a mailbox doesn't match
20674 any string, or if the transport named for a given string is not defined,
20675 delivery is deferred.
20676
20677 +------------------------------------------------------------+
20678 |file_must_exist|Use: appendfile|Type: boolean|Default: false|
20679 +------------------------------------------------------------+
20680
20681 If this option is true, the file specified by the file option must exist. A
20682 temporary error occurs if it does not, causing delivery to be deferred. If this
20683 option is false, the file is created if it does not exist.
20684
20685 +---------------------------------------------------------+
20686 |lock_fcntl_timeout|Use: appendfile|Type: time|Default: 0s|
20687 +---------------------------------------------------------+
20688
20689 By default, the appendfile transport uses non-blocking calls to fcntl() when
20690 locking an open mailbox file. If the call fails, the delivery process sleeps
20691 for lock_interval and tries again, up to lock_retries times. Non-blocking calls
20692 are used so that the file is not kept open during the wait for the lock; the
20693 reason for this is to make it as safe as possible for deliveries over NFS in
20694 the case when processes might be accessing an NFS mailbox without using a lock
20695 file. This should not be done, but misunderstandings and hence
20696 misconfigurations are not unknown.
20697
20698 On a busy system, however, the performance of a non-blocking lock approach is
20699 not as good as using a blocking lock with a timeout. In this case, the waiting
20700 is done inside the system call, and Exim's delivery process acquires the lock
20701 and can proceed as soon as the previous lock holder releases it.
20702
20703 If lock_fcntl_timeout is set to a non-zero time, blocking locks, with that
20704 timeout, are used. There may still be some retrying: the maximum number of
20705 retries is
20706
20707 (lock_retries * lock_interval) / lock_fcntl_timeout
20708
20709 rounded up to the next whole number. In other words, the total time during
20710 which appendfile is trying to get a lock is roughly the same, unless
20711 lock_fcntl_timeout is set very large.
20712
20713 You should consider setting this option if you are getting a lot of delayed
20714 local deliveries because of errors of the form
20715
20716 failed to lock mailbox /some/file (fcntl)
20717
20718 +---------------------------------------------------------+
20719 |lock_flock_timeout|Use: appendfile|Type: time|Default: 0s|
20720 +---------------------------------------------------------+
20721
20722 This timeout applies to file locking when using flock() (see use_flock); the
20723 timeout operates in a similar manner to lock_fcntl_timeout.
20724
20725 +----------------------------------------------------+
20726 |lock_interval|Use: appendfile|Type: time|Default: 3s|
20727 +----------------------------------------------------+
20728
20729 This specifies the time to wait between attempts to lock the file. See below
20730 for details of locking.
20731
20732 +------------------------------------------------------+
20733 |lock_retries|Use: appendfile|Type: integer|Default: 10|
20734 +------------------------------------------------------+
20735
20736 This specifies the maximum number of attempts to lock the file. A value of zero
20737 is treated as 1. See below for details of locking.
20738
20739 +---------------------------------------------------------------+
20740 |lockfile_mode|Use: appendfile|Type: octal integer|Default: 0600|
20741 +---------------------------------------------------------------+
20742
20743 This specifies the mode of the created lock file, when a lock file is being
20744 used (see use_lockfile and use_mbx_lock).
20745
20746 +--------------------------------------------------------+
20747 |lockfile_timeout|Use: appendfile|Type: time|Default: 30m|
20748 +--------------------------------------------------------+
20749
20750 When a lock file is being used (see use_lockfile), if a lock file already
20751 exists and is older than this value, it is assumed to have been left behind by
20752 accident, and Exim attempts to remove it.
20753
20754 +--------------------------------------------------------------+
20755 |mailbox_filecount|Use: appendfile|Type: string*|Default: unset|
20756 +--------------------------------------------------------------+
20757
20758 If this option is set, it is expanded, and the result is taken as the current
20759 number of files in the mailbox. It must be a decimal number, optionally
20760 followed by K or M. This provides a way of obtaining this information from an
20761 external source that maintains the data.
20762
20763 +---------------------------------------------------------+
20764 |mailbox_size|Use: appendfile|Type: string*|Default: unset|
20765 +---------------------------------------------------------+
20766
20767 If this option is set, it is expanded, and the result is taken as the current
20768 size the mailbox. It must be a decimal number, optionally followed by K or M.
20769 This provides a way of obtaining this information from an external source that
20770 maintains the data. This is likely to be helpful for maildir deliveries where
20771 it is computationally expensive to compute the size of a mailbox.
20772
20773 +-----------------------------------------------------------+
20774 |maildir_format|Use: appendfile|Type: boolean|Default: false|
20775 +-----------------------------------------------------------+
20776
20777 If this option is set with the directory option, the delivery is into a new
20778 file, in the "maildir" format that is used by other mail software. When the
20779 transport is activated directly from a redirect router (for example, the
20780 address_file transport in the default configuration), setting maildir_format
20781 causes the path received from the router to be treated as a directory, whether
20782 or not it ends with "/". This option is available only if SUPPORT_MAILDIR is
20783 present in Local/Makefile. See section 26.5 below for further details.
20784
20785 +-----------------------------------------------------------------------------+
20786 |maildir_quota_directory_regex|Use: appendfile|Type: string|Default: See below|
20787 +-----------------------------------------------------------------------------+
20788
20789 This option is relevant only when maildir_use_size_file is set. It defines a
20790 regular expression for specifying directories, relative to the quota directory
20791 (see quota_directory), that should be included in the quota calculation. The
20792 default value is:
20793
20794 maildir_quota_directory_regex = ^(?:cur|new|\..*)$
20795
20796 This includes the cur and new directories, and any maildir++ folders
20797 (directories whose names begin with a dot). If you want to exclude the Trash
20798 folder from the count (as some sites do), you need to change this setting to
20799
20800 maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
20801
20802 This uses a negative lookahead in the regular expression to exclude the
20803 directory whose name is .Trash. When a directory is excluded from quota
20804 calculations, quota processing is bypassed for any messages that are delivered
20805 directly into that directory.
20806
20807 +---------------------------------------------------------+
20808 |maildir_retries|Use: appendfile|Type: integer|Default: 10|
20809 +---------------------------------------------------------+
20810
20811 This option specifies the number of times to retry when writing a file in
20812 "maildir" format. See section 26.5 below.
20813
20814 +--------------------------------------------------------+
20815 |maildir_tag|Use: appendfile|Type: string*|Default: unset|
20816 +--------------------------------------------------------+
20817
20818 This option applies only to deliveries in maildir format, and is described in
20819 section 26.5 below.
20820
20821 +-------------------------------------------------------------------+
20822 |maildir_use_size_file|Use: appendfile*|Type: boolean|Default: false|
20823 +-------------------------------------------------------------------+
20824
20825 The result of string expansion for this option must be a valid boolean value.
20826 If it is true, it enables support for maildirsize files. Exim creates a
20827 maildirsize file in a maildir if one does not exist, taking the quota from the
20828 quota option of the transport. If quota is unset, the value is zero. See
20829 maildir_quota_directory_regex above and section 26.5 below for further details.
20830
20831 +----------------------------------------------------------------------+
20832 |maildirfolder_create_regex|Use: appendfile|Type: string|Default: unset|
20833 +----------------------------------------------------------------------+
20834
20835 The value of this option is a regular expression. If it is unset, it has no
20836 effect. Otherwise, before a maildir delivery takes place, the pattern is
20837 matched against the name of the maildir directory, that is, the directory
20838 containing the new and tmp subdirectories that will be used for the delivery.
20839 If there is a match, Exim checks for the existence of a file called
20840 maildirfolder in the directory, and creates it if it does not exist. See
20841 section 26.5 for more details.
20842
20843 +-------------------------------------------------------------+
20844 |mailstore_format|Use: appendfile|Type: boolean|Default: false|
20845 +-------------------------------------------------------------+
20846
20847 If this option is set with the directory option, the delivery is into two new
20848 files in "mailstore" format. The option is available only if SUPPORT_MAILSTORE
20849 is present in Local/Makefile. See section 26.4 below for further details.
20850
20851 +-------------------------------------------------------------+
20852 |mailstore_prefix|Use: appendfile|Type: string*|Default: unset|
20853 +-------------------------------------------------------------+
20854
20855 This option applies only to deliveries in mailstore format, and is described in
20856 section 26.4 below.
20857
20858 +-------------------------------------------------------------+
20859 |mailstore_suffix|Use: appendfile|Type: string*|Default: unset|
20860 +-------------------------------------------------------------+
20861
20862 This option applies only to deliveries in mailstore format, and is described in
20863 section 26.4 below.
20864
20865 +-------------------------------------------------------+
20866 |mbx_format|Use: appendfile|Type: boolean|Default: false|
20867 +-------------------------------------------------------+
20868
20869 This option is available only if Exim has been compiled with SUPPORT_MBX set in
20870 Local/Makefile. If mbx_format is set with the file option, the message is
20871 appended to the mailbox file in MBX format instead of traditional Unix format.
20872 This format is supported by Pine4 and its associated IMAP and POP daemons, by
20873 means of the c-client library that they all use.
20874
20875 Note: The message_prefix and message_suffix options are not automatically
20876 changed by the use of mbx_format. They should normally be set empty when using
20877 MBX format, so this option almost always appears in this combination:
20878
20879 mbx_format = true
20880 message_prefix =
20881 message_suffix =
20882
20883 If none of the locking options are mentioned in the configuration, use_mbx_lock
20884 is assumed and the other locking options default to false. It is possible to
20885 specify the other kinds of locking with mbx_format, but use_fcntl_lock and
20886 use_mbx_lock are mutually exclusive. MBX locking interworks with c-client,
20887 providing for shared access to the mailbox. It should not be used if any
20888 program that does not use this form of locking is going to access the mailbox,
20889 nor should it be used if the mailbox file is NFS mounted, because it works only
20890 when the mailbox is accessed from a single host.
20891
20892 If you set use_fcntl_lock with an MBX-format mailbox, you cannot use the
20893 standard version of c-client, because as long as it has a mailbox open (this
20894 means for the whole of a Pine or IMAP session), Exim will not be able to append
20895 messages to it.
20896
20897 +---------------------------------------------------------------+
20898 |message_prefix|Use: appendfile|Type: string*|Default: see below|
20899 +---------------------------------------------------------------+
20900
20901 The string specified here is expanded and output at the start of every message.
20902 The default is unset unless file is specified and use_bsmtp is not set, in
20903 which case it is:
20904
20905 message_prefix = "From ${if def:return_path{$return_path}\
20906 {MAILER-DAEMON}} $tod_bsdinbox\n"
20907
20908 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
20909 n" in message_prefix.
20910
20911 +---------------------------------------------------------------+
20912 |message_suffix|Use: appendfile|Type: string*|Default: see below|
20913 +---------------------------------------------------------------+
20914
20915 The string specified here is expanded and output at the end of every message.
20916 The default is unset unless file is specified and use_bsmtp is not set, in
20917 which case it is a single newline character. The suffix can be suppressed by
20918 setting
20919
20920 message_suffix =
20921
20922 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
20923 n" in message_suffix.
20924
20925 +------------------------------------------------------+
20926 |mode|Use: appendfile|Type: octal integer|Default: 0600|
20927 +------------------------------------------------------+
20928
20929 If the output file is created, it is given this mode. If it already exists and
20930 has wider permissions, they are reduced to this mode. If it has narrower
20931 permissions, an error occurs unless mode_fail_narrower is false. However, if
20932 the delivery is the result of a save command in a filter file specifying a
20933 particular mode, the mode of the output file is always forced to take that
20934 value, and this option is ignored.
20935
20936 +--------------------------------------------------------------+
20937 |mode_fail_narrower|Use: appendfile|Type: boolean|Default: true|
20938 +--------------------------------------------------------------+
20939
20940 This option applies in the case when an existing mailbox file has a narrower
20941 mode than that specified by the mode option. If mode_fail_narrower is true, the
20942 delivery is deferred ("mailbox has the wrong mode"); otherwise Exim continues
20943 with the delivery attempt, using the existing mode of the file.
20944
20945 +----------------------------------------------------------+
20946 |notify_comsat|Use: appendfile|Type: boolean|Default: false|
20947 +----------------------------------------------------------+
20948
20949 If this option is true, the comsat daemon is notified after every successful
20950 delivery to a user mailbox. This is the daemon that notifies logged on users
20951 about incoming mail.
20952
20953 +--------------------------------------------------+
20954 |quota|Use: appendfile|Type: string*|Default: unset|
20955 +--------------------------------------------------+
20956
20957 This option imposes a limit on the size of the file to which Exim is appending,
20958 or to the total space used in the directory tree when the directory option is
20959 set. In the latter case, computation of the space used is expensive, because
20960 all the files in the directory (and any sub-directories) have to be
20961 individually inspected and their sizes summed. (See quota_size_regex and
20962 maildir_use_size_file for ways to avoid this in environments where users have
20963 no shell access to their mailboxes).
20964
20965 As there is no interlock against two simultaneous deliveries into a multi-file
20966 mailbox, it is possible for the quota to be overrun in this case. For
20967 single-file mailboxes, of course, an interlock is a necessity.
20968
20969 A file's size is taken as its used value. Because of blocking effects, this may
20970 be a lot less than the actual amount of disk space allocated to the file. If
20971 the sizes of a number of files are being added up, the rounding effect can
20972 become quite noticeable, especially on systems that have large block sizes.
20973 Nevertheless, it seems best to stick to the used figure, because this is the
20974 obvious value which users understand most easily.
20975
20976 The value of the option is expanded, and must then be a numerical value
20977 (decimal point allowed), optionally followed by one of the letters K, M, or G,
20978 for kilobytes, megabytes, or gigabytes, optionally followed by a slash and
20979 further option modifiers. If Exim is running on a system with large file
20980 support (Linux and FreeBSD have this), mailboxes larger than 2G can be handled.
20981
20982 The option modifier no_check can be used to force delivery even if the over
20983 quota condition is met. The quota gets updated as usual.
20984
20985 Note: A value of zero is interpreted as "no quota".
20986
20987 The expansion happens while Exim is running as root, before it changes uid for
20988 the delivery. This means that files that are inaccessible to the end user can
20989 be used to hold quota values that are looked up in the expansion. When delivery
20990 fails because this quota is exceeded, the handling of the error is as for
20991 system quota failures.
20992
20993 By default, Exim's quota checking mimics system quotas, and restricts the
20994 mailbox to the specified maximum size, though the value is not accurate to the
20995 last byte, owing to separator lines and additional headers that may get added
20996 during message delivery. When a mailbox is nearly full, large messages may get
20997 refused even though small ones are accepted, because the size of the current
20998 message is added to the quota when the check is made. This behaviour can be
20999 changed by setting quota_is_inclusive false. When this is done, the check for
21000 exceeding the quota does not include the current message. Thus, deliveries
21001 continue until the quota has been exceeded; thereafter, no further messages are
21002 delivered. See also quota_warn_threshold.
21003
21004 +------------------------------------------------------------+
21005 |quota_directory|Use: appendfile|Type: string*|Default: unset|
21006 +------------------------------------------------------------+
21007
21008 This option defines the directory to check for quota purposes when delivering
21009 into individual files. The default is the delivery directory, or, if a file
21010 called maildirfolder exists in a maildir directory, the parent of the delivery
21011 directory.
21012
21013 +--------------------------------------------------------+
21014 |quota_filecount|Use: appendfile|Type: string*|Default: 0|
21015 +--------------------------------------------------------+
21016
21017 This option applies when the directory option is set. It limits the total
21018 number of files in the directory (compare the inode limit in system quotas). It
21019 can only be used if quota is also set. The value is expanded; an expansion
21020 failure causes delivery to be deferred. A value of zero is interpreted as "no
21021 quota".
21022
21023 The option modifier no_check can be used to force delivery even if the over
21024 quota condition is met. The quota gets updated as usual.
21025
21026 +--------------------------------------------------------------+
21027 |quota_is_inclusive|Use: appendfile|Type: boolean|Default: true|
21028 +--------------------------------------------------------------+
21029
21030 See quota above.
21031
21032 +------------------------------------------------------------+
21033 |quota_size_regex|Use: appendfile|Type: string|Default: unset|
21034 +------------------------------------------------------------+
21035
21036 This option applies when one of the delivery modes that writes a separate file
21037 for each message is being used. When Exim wants to find the size of one of
21038 these files in order to test the quota, it first checks quota_size_regex. If
21039 this is set to a regular expression that matches the filename, and it captures
21040 one string, that string is interpreted as a representation of the file's size.
21041 The value of quota_size_regex is not expanded.
21042
21043 This feature is useful only when users have no shell access to their mailboxes
21044 - otherwise they could defeat the quota simply by renaming the files. This
21045 facility can be used with maildir deliveries, by setting maildir_tag to add the
21046 file length to the filename. For example:
21047
21048 maildir_tag = ,S=$message_size
21049 quota_size_regex = ,S=(\d+)
21050
21051 An alternative to $message_size is $message_linecount, which contains the
21052 number of lines in the message.
21053
21054 The regular expression should not assume that the length is at the end of the
21055 filename (even though maildir_tag puts it there) because maildir MUAs sometimes
21056 add other information onto the ends of message filenames.
21057
21058 Section 26.7 contains further information.
21059
21060 +-------------------------------------------------------------------+
21061 |quota_warn_message|Use: appendfile|Type: string*|Default: see below|
21062 +-------------------------------------------------------------------+
21063
21064 See below for the use of this option. If it is not set when
21065 quota_warn_threshold is set, it defaults to
21066
21067 quota_warn_message = "\
21068 To: $local_part@$domain\n\
21069 Subject: Your mailbox\n\n\
21070 This message is automatically created \
21071 by mail delivery software.\n\n\
21072 The size of your mailbox has exceeded \
21073 a warning threshold that is\n\
21074 set by the system administrator.\n"
21075
21076 +-------------------------------------------------------------+
21077 |quota_warn_threshold|Use: appendfile|Type: string*|Default: 0|
21078 +-------------------------------------------------------------+
21079
21080 This option is expanded in the same way as quota (see above). If the resulting
21081 value is greater than zero, and delivery of the message causes the size of the
21082 file or total space in the directory tree to cross the given threshold, a
21083 warning message is sent. If quota is also set, the threshold may be specified
21084 as a percentage of it by following the value with a percent sign. For example:
21085
21086 quota = 10M
21087 quota_warn_threshold = 75%
21088
21089 If quota is not set, a setting of quota_warn_threshold that ends with a percent
21090 sign is ignored.
21091
21092 The warning message itself is specified by the quota_warn_message option, and
21093 it must start with a To: header line containing the recipient(s) of the warning
21094 message. These do not necessarily have to include the recipient(s) of the
21095 original message. A Subject: line should also normally be supplied. You can
21096 include any other header lines that you want. If you do not include a From:
21097 line, the default is:
21098
21099 From: Mail Delivery System <mailer-daemon@$qualify_domain_sender>
21100
21101 If you supply a Reply-To: line, it overrides the global errors_reply_to option.
21102
21103 The quota option does not have to be set in order to use this option; they are
21104 independent of one another except when the threshold is specified as a
21105 percentage.
21106
21107 +------------------------------------------------------+
21108 |use_bsmtp|Use: appendfile|Type: boolean|Default: false|
21109 +------------------------------------------------------+
21110
21111 If this option is set true, appendfile writes messages in "batch SMTP" format,
21112 with the envelope sender and recipient(s) included as SMTP commands. If you
21113 want to include a leading HELO command with such messages, you can do so by
21114 setting the message_prefix option. See section 48.10 for details of batch SMTP.
21115
21116 +-----------------------------------------------------+
21117 |use_crlf|Use: appendfile|Type: boolean|Default: false|
21118 +-----------------------------------------------------+
21119
21120 This option causes lines to be terminated with the two-character CRLF sequence
21121 (carriage return, linefeed) instead of just a linefeed character. In the case
21122 of batched SMTP, the byte sequence written to the file is then an exact image
21123 of what would be sent down a real SMTP connection.
21124
21125 Note: The contents of the message_prefix and message_suffix options (which are
21126 used to supply the traditional "From " and blank line separators in
21127 Berkeley-style mailboxes) are written verbatim, so must contain their own
21128 carriage return characters if these are needed. In cases where these options
21129 have non-empty defaults, the values end with a single linefeed, so they must be
21130 changed to end with "\r\n" if use_crlf is set.
21131
21132 +---------------------------------------------------------------+
21133 |use_fcntl_lock|Use: appendfile|Type: boolean|Default: see below|
21134 +---------------------------------------------------------------+
21135
21136 This option controls the use of the fcntl() function to lock a file for
21137 exclusive use when a message is being appended. It is set by default unless
21138 use_flock_lock is set. Otherwise, it should be turned off only if you know that
21139 all your MUAs use lock file locking. When both use_fcntl_lock and
21140 use_flock_lock are unset, use_lockfile must be set.
21141
21142 +-----------------------------------------------------------+
21143 |use_flock_lock|Use: appendfile|Type: boolean|Default: false|
21144 +-----------------------------------------------------------+
21145
21146 This option is provided to support the use of flock() for file locking, for the
21147 few situations where it is needed. Most modern operating systems support fcntl
21148 () and lockf() locking, and these two functions interwork with each other. Exim
21149 uses fcntl() locking by default.
21150
21151 This option is required only if you are using an operating system where flock()
21152 is used by programs that access mailboxes (typically MUAs), and where flock()
21153 does not correctly interwork with fcntl(). You can use both fcntl() and flock()
21154 locking simultaneously if you want.
21155
21156 Not all operating systems provide flock(). Some versions of Solaris do not have
21157 it (and some, I think, provide a not quite right version built on top of lockf
21158 ()). If the OS does not have flock(), Exim will be built without the ability to
21159 use it, and any attempt to do so will cause a configuration error.
21160
21161 Warning: flock() locks do not work on NFS files (unless flock() is just being
21162 mapped onto fcntl() by the OS).
21163
21164 +-------------------------------------------------------------+
21165 |use_lockfile|Use: appendfile|Type: boolean|Default: see below|
21166 +-------------------------------------------------------------+
21167
21168 If this option is turned off, Exim does not attempt to create a lock file when
21169 appending to a mailbox file. In this situation, the only locking is by fcntl().
21170 You should only turn use_lockfile off if you are absolutely sure that every MUA
21171 that is ever going to look at your users' mailboxes uses fcntl() rather than a
21172 lock file, and even then only when you are not delivering over NFS from more
21173 than one host.
21174
21175 In order to append to an NFS file safely from more than one host, it is
21176 necessary to take out a lock before opening the file, and the lock file
21177 achieves this. Otherwise, even with fcntl() locking, there is a risk of file
21178 corruption.
21179
21180 The use_lockfile option is set by default unless use_mbx_lock is set. It is not
21181 possible to turn both use_lockfile and use_fcntl_lock off, except when
21182 mbx_format is set.
21183
21184 +-------------------------------------------------------------+
21185 |use_mbx_lock|Use: appendfile|Type: boolean|Default: see below|
21186 +-------------------------------------------------------------+
21187
21188 This option is available only if Exim has been compiled with SUPPORT_MBX set in
21189 Local/Makefile. Setting the option specifies that special MBX locking rules be
21190 used. It is set by default if mbx_format is set and none of the locking options
21191 are mentioned in the configuration. The locking rules are the same as are used
21192 by the c-client library that underlies Pine and the IMAP4 and POP daemons that
21193 come with it (see the discussion below). The rules allow for shared access to
21194 the mailbox. However, this kind of locking does not work when the mailbox is
21195 NFS mounted.
21196
21197 You can set use_mbx_lock with either (or both) of use_fcntl_lock and
21198 use_flock_lock to control what kind of locking is used in implementing the MBX
21199 locking rules. The default is to use fcntl() if use_mbx_lock is set without
21200 use_fcntl_lock or use_flock_lock.
21201
21202
21203 26.3 Operational details for appending
21204 --------------------------------------
21205
21206 Before appending to a file, the following preparations are made:
21207
21208 * If the name of the file is /dev/null, no action is taken, and a success
21209 return is given.
21210
21211 * If any directories on the file's path are missing, Exim creates them if the
21212 create_directory option is set. A created directory's mode is given by the
21213 directory_mode option.
21214
21215 * If file_format is set, the format of an existing file is checked. If this
21216 indicates that a different transport should be used, control is passed to
21217 that transport.
21218
21219 * If use_lockfile is set, a lock file is built in a way that will work
21220 reliably over NFS, as follows:
21221
21222 1. Create a "hitching post" file whose name is that of the lock file with
21223 the current time, primary host name, and process id added, by opening
21224 for writing as a new file. If this fails with an access error, delivery
21225 is deferred.
21226
21227 2. Close the hitching post file, and hard link it to the lock filename.
21228
21229 3. If the call to link() succeeds, creation of the lock file has
21230 succeeded. Unlink the hitching post name.
21231
21232 4. Otherwise, use stat() to get information about the hitching post file,
21233 and then unlink hitching post name. If the number of links is exactly
21234 two, creation of the lock file succeeded but something (for example, an
21235 NFS server crash and restart) caused this fact not to be communicated
21236 to the link() call.
21237
21238 5. If creation of the lock file failed, wait for lock_interval and try
21239 again, up to lock_retries times. However, since any program that writes
21240 to a mailbox should complete its task very quickly, it is reasonable to
21241 time out old lock files that are normally the result of user agent and
21242 system crashes. If an existing lock file is older than lockfile_timeout
21243 Exim attempts to unlink it before trying again.
21244
21245 * A call is made to lstat() to discover whether the main file exists, and if
21246 so, what its characteristics are. If lstat() fails for any reason other
21247 than non-existence, delivery is deferred.
21248
21249 * If the file does exist and is a symbolic link, delivery is deferred, unless
21250 the allow_symlink option is set, in which case the ownership of the link is
21251 checked, and then stat() is called to find out about the real file, which
21252 is then subjected to the checks below. The check on the top-level link
21253 ownership prevents one user creating a link for another's mailbox in a
21254 sticky directory, though allowing symbolic links in this case is definitely
21255 not a good idea. If there is a chain of symbolic links, the intermediate
21256 ones are not checked.
21257
21258 * If the file already exists but is not a regular file, or if the file's
21259 owner and group (if the group is being checked - see check_group above) are
21260 different from the user and group under which the delivery is running,
21261 delivery is deferred.
21262
21263 * If the file's permissions are more generous than specified, they are
21264 reduced. If they are insufficient, delivery is deferred, unless
21265 mode_fail_narrower is set false, in which case the delivery is tried using
21266 the existing permissions.
21267
21268 * The file's inode number is saved, and the file is then opened for
21269 appending. If this fails because the file has vanished, appendfile behaves
21270 as if it hadn't existed (see below). For any other failures, delivery is
21271 deferred.
21272
21273 * If the file is opened successfully, check that the inode number hasn't
21274 changed, that it is still a regular file, and that the owner and
21275 permissions have not changed. If anything is wrong, defer delivery and
21276 freeze the message.
21277
21278 * If the file did not exist originally, defer delivery if the file_must_exist
21279 option is set. Otherwise, check that the file is being created in a
21280 permitted directory if the create_file option is set (deferring on
21281 failure), and then open for writing as a new file, with the O_EXCL and
21282 O_CREAT options, except when dealing with a symbolic link (the
21283 allow_symlink option must be set). In this case, which can happen if the
21284 link points to a non-existent file, the file is opened for writing using
21285 O_CREAT but not O_EXCL, because that prevents link following.
21286
21287 * If opening fails because the file exists, obey the tests given above for
21288 existing files. However, to avoid looping in a situation where the file is
21289 being continuously created and destroyed, the exists/not-exists loop is
21290 broken after 10 repetitions, and the message is then frozen.
21291
21292 * If opening fails with any other error, defer delivery.
21293
21294 * Once the file is open, unless both use_fcntl_lock and use_flock_lock are
21295 false, it is locked using fcntl() or flock() or both. If use_mbx_lock is
21296 false, an exclusive lock is requested in each case. However, if
21297 use_mbx_lock is true, Exim takes out a shared lock on the open file, and an
21298 exclusive lock on the file whose name is
21299
21300 /tmp/.<device-number>.<inode-number>
21301
21302 using the device and inode numbers of the open mailbox file, in accordance
21303 with the MBX locking rules. This file is created with a mode that is
21304 specified by the lockfile_mode option.
21305
21306 If Exim fails to lock the file, there are two possible courses of action,
21307 depending on the value of the locking timeout. This is obtained from
21308 lock_fcntl_timeout or lock_flock_timeout, as appropriate.
21309
21310 If the timeout value is zero, the file is closed, Exim waits for
21311 lock_interval, and then goes back and re-opens the file as above and tries
21312 to lock it again. This happens up to lock_retries times, after which the
21313 delivery is deferred.
21314
21315 If the timeout has a value greater than zero, blocking calls to fcntl() or
21316 flock() are used (with the given timeout), so there has already been some
21317 waiting involved by the time locking fails. Nevertheless, Exim does not
21318 give up immediately. It retries up to
21319
21320 (lock_retries * lock_interval) / <timeout>
21321
21322 times (rounded up).
21323
21324 At the end of delivery, Exim closes the file (which releases the fcntl() and/or
21325 flock() locks) and then deletes the lock file if one was created.
21326
21327
21328 26.4 Operational details for delivery to a new file
21329 ---------------------------------------------------
21330
21331 When the directory option is set instead of file, each message is delivered
21332 into a newly-created file or set of files. When appendfile is activated
21333 directly from a redirect router, neither file nor directory is normally set,
21334 because the path for delivery is supplied by the router. (See for example, the
21335 address_file transport in the default configuration.) In this case, delivery is
21336 to a new file if either the path name ends in "/", or the maildir_format or
21337 mailstore_format option is set.
21338
21339 No locking is required while writing the message to a new file, so the various
21340 locking options of the transport are ignored. The "From" line that by default
21341 separates messages in a single file is not normally needed, nor is the escaping
21342 of message lines that start with "From", and there is no need to ensure a
21343 newline at the end of each message. Consequently, the default values for
21344 check_string, message_prefix, and message_suffix are all unset when any of
21345 directory, maildir_format, or mailstore_format is set.
21346
21347 If Exim is required to check a quota setting, it adds up the sizes of all the
21348 files in the delivery directory by default. However, you can specify a
21349 different directory by setting quota_directory. Also, for maildir deliveries
21350 (see below) the maildirfolder convention is honoured.
21351
21352 There are three different ways in which delivery to individual files can be
21353 done, controlled by the settings of the maildir_format and mailstore_format
21354 options. Note that code to support maildir or mailstore formats is not included
21355 in the binary unless SUPPORT_MAILDIR or SUPPORT_MAILSTORE, respectively, is set
21356 in Local/Makefile.
21357
21358 In all three cases an attempt is made to create the directory and any necessary
21359 sub-directories if they do not exist, provided that the create_directory option
21360 is set (the default). The location of a created directory can be constrained by
21361 setting create_file. A created directory's mode is given by the directory_mode
21362 option. If creation fails, or if the create_directory option is not set when
21363 creation is required, delivery is deferred.
21364
21365
21366 26.5 Maildir delivery
21367 ---------------------
21368
21369 If the maildir_format option is true, Exim delivers each message by writing it
21370 to a file whose name is tmp/<stime>.H<mtime>P<pid>.<host> in the directory that
21371 is defined by the directory option (the "delivery directory"). If the delivery
21372 is successful, the file is renamed into the new subdirectory.
21373
21374 In the filename, <stime> is the current time of day in seconds, and <mtime> is
21375 the microsecond fraction of the time. After a maildir delivery, Exim checks
21376 that the time-of-day clock has moved on by at least one microsecond before
21377 terminating the delivery process. This guarantees uniqueness for the filename.
21378 However, as a precaution, Exim calls stat() for the file before opening it. If
21379 any response other than ENOENT (does not exist) is given, Exim waits 2 seconds
21380 and tries again, up to maildir_retries times.
21381
21382 Before Exim carries out a maildir delivery, it ensures that subdirectories
21383 called new, cur, and tmp exist in the delivery directory. If they do not exist,
21384 Exim tries to create them and any superior directories in their path, subject
21385 to the create_directory and create_file options. If the
21386 maildirfolder_create_regex option is set, and the regular expression it
21387 contains matches the delivery directory, Exim also ensures that a file called
21388 maildirfolder exists in the delivery directory. If a missing directory or
21389 maildirfolder file cannot be created, delivery is deferred.
21390
21391 These features make it possible to use Exim to create all the necessary files
21392 and directories in a maildir mailbox, including subdirectories for maildir++
21393 folders. Consider this example:
21394
21395 maildir_format = true
21396 directory = /var/mail/$local_part\
21397 ${if eq{$local_part_suffix}{}{}\
21398 {/.${substr_1:$local_part_suffix}}}
21399 maildirfolder_create_regex = /\.[^/]+$
21400
21401 If $local_part_suffix is empty (there was no suffix for the local part),
21402 delivery is into a toplevel maildir with a name like /var/mail/pimbo (for the
21403 user called pimbo). The pattern in maildirfolder_create_regex does not match
21404 this name, so Exim will not look for or create the file /var/mail/pimbo/
21405 maildirfolder, though it will create /var/mail/pimbo/{cur,new,tmp} if
21406 necessary.
21407
21408 However, if $local_part_suffix contains "-eximusers" (for example), delivery is
21409 into the maildir++ folder /var/mail/pimbo/.eximusers, which does match
21410 maildirfolder_create_regex. In this case, Exim will create /var/mail/pimbo
21411 /.eximusers/maildirfolder as well as the three maildir directories /var/mail/
21412 pimbo/.eximusers/{cur,new,tmp}.
21413
21414 Warning: Take care when setting maildirfolder_create_regex that it does not
21415 inadvertently match the toplevel maildir directory, because a maildirfolder
21416 file at top level would completely break quota calculations.
21417
21418 If Exim is required to check a quota setting before a maildir delivery, and
21419 quota_directory is not set, it looks for a file called maildirfolder in the
21420 maildir directory (alongside new, cur, tmp). If this exists, Exim assumes the
21421 directory is a maildir++ folder directory, which is one level down from the
21422 user's top level mailbox directory. This causes it to start at the parent
21423 directory instead of the current directory when calculating the amount of space
21424 used.
21425
21426 One problem with delivering into a multi-file mailbox is that it is
21427 computationally expensive to compute the size of the mailbox for quota
21428 checking. Various approaches have been taken to reduce the amount of work
21429 needed. The next two sections describe two of them. A third alternative is to
21430 use some external process for maintaining the size data, and use the expansion
21431 of the mailbox_size option as a way of importing it into Exim.
21432
21433
21434 26.6 Using tags to record message sizes
21435 ---------------------------------------
21436
21437 If maildir_tag is set, the string is expanded for each delivery. When the
21438 maildir file is renamed into the new sub-directory, the tag is added to its
21439 name. However, if adding the tag takes the length of the name to the point
21440 where the test stat() call fails with ENAMETOOLONG, the tag is dropped and the
21441 maildir file is created with no tag.
21442
21443 Tags can be used to encode the size of files in their names; see
21444 quota_size_regex above for an example. The expansion of maildir_tag happens
21445 after the message has been written. The value of the $message_size variable is
21446 set to the number of bytes actually written. If the expansion is forced to
21447 fail, the tag is ignored, but a non-forced failure causes delivery to be
21448 deferred. The expanded tag may contain any printing characters except "/".
21449 Non-printing characters in the string are ignored; if the resulting string is
21450 empty, it is ignored. If it starts with an alphanumeric character, a leading
21451 colon is inserted; this default has not proven to be the path that popular
21452 maildir implementations have chosen (but changing it in Exim would break
21453 backwards compatibility).
21454
21455 For one common implementation, you might set:
21456
21457 maildir_tag = ,S=${message_size}
21458
21459 but you should check the documentation of the other software to be sure.
21460
21461 It is advisable to also set quota_size_regex when setting maildir_tag as this
21462 allows Exim to extract the size from your tag, instead of having to stat() each
21463 message file.
21464
21465
21466 26.7 Using a maildirsize file
21467 -----------------------------
21468
21469 If maildir_use_size_file is true, Exim implements the maildir++ rules for
21470 storing quota and message size information in a file called maildirsize within
21471 the toplevel maildir directory. If this file does not exist, Exim creates it,
21472 setting the quota from the quota option of the transport. If the maildir
21473 directory itself does not exist, it is created before any attempt to write a
21474 maildirsize file.
21475
21476 The maildirsize file is used to hold information about the sizes of messages in
21477 the maildir, thus speeding up quota calculations. The quota value in the file
21478 is just a cache; if the quota is changed in the transport, the new value
21479 overrides the cached value when the next message is delivered. The cache is
21480 maintained for the benefit of other programs that access the maildir and need
21481 to know the quota.
21482
21483 If the quota option in the transport is unset or zero, the maildirsize file is
21484 maintained (with a zero quota setting), but no quota is imposed.
21485
21486 A regular expression is available for controlling which directories in the
21487 maildir participate in quota calculations when a maildirsizefile is in use. See
21488 the description of the maildir_quota_directory_regex option above for details.
21489
21490
21491 26.8 Mailstore delivery
21492 -----------------------
21493
21494 If the mailstore_format option is true, each message is written as two files in
21495 the given directory. A unique base name is constructed from the message id and
21496 the current delivery process, and the files that are written use this base name
21497 plus the suffixes .env and .msg. The .env file contains the message's envelope,
21498 and the .msg file contains the message itself. The base name is placed in the
21499 variable $mailstore_basename.
21500
21501 During delivery, the envelope is first written to a file with the suffix .tmp.
21502 The .msg file is then written, and when it is complete, the .tmp file is
21503 renamed as the .env file. Programs that access messages in mailstore format
21504 should wait for the presence of both a .msg and a .env file before accessing
21505 either of them. An alternative approach is to wait for the absence of a .tmp
21506 file.
21507
21508 The envelope file starts with any text defined by the mailstore_prefix option,
21509 expanded and terminated by a newline if there isn't one. Then follows the
21510 sender address on one line, then all the recipient addresses, one per line.
21511 There can be more than one recipient only if the batch_max option is set
21512 greater than one. Finally, mailstore_suffix is expanded and the result appended
21513 to the file, followed by a newline if it does not end with one.
21514
21515 If expansion of mailstore_prefix or mailstore_suffix ends with a forced
21516 failure, it is ignored. Other expansion errors are treated as serious
21517 configuration errors, and delivery is deferred. The variable
21518 $mailstore_basename is available for use during these expansions.
21519
21520
21521 26.9 Non-special new file delivery
21522 ----------------------------------
21523
21524 If neither maildir_format nor mailstore_format is set, a single new file is
21525 created directly in the named directory. For example, when delivering messages
21526 into files in batched SMTP format for later delivery to some host (see section
21527 48.10), a setting such as
21528
21529 directory = /var/bsmtp/$host
21530
21531 might be used. A message is written to a file with a temporary name, which is
21532 then renamed when the delivery is complete. The final name is obtained by
21533 expanding the contents of the directory_file option.
21534
21535
21536
21537 ===============================================================================
21538 27. THE AUTOREPLY TRANSPORT
21539
21540 The autoreply transport is not a true transport in that it does not cause the
21541 message to be transmitted. Instead, it generates a new mail message as an
21542 automatic reply to the incoming message. References: and Auto-Submitted: header
21543 lines are included. These are constructed according to the rules in RFCs 2822
21544 and 3834, respectively.
21545
21546 If the router that passes the message to this transport does not have the
21547 unseen option set, the original message (for the current recipient) is not
21548 delivered anywhere. However, when the unseen option is set on the router that
21549 passes the message to this transport, routing of the address continues, so
21550 another router can set up a normal message delivery.
21551
21552 The autoreply transport is usually run as the result of mail filtering, a
21553 "vacation" message being the standard example. However, it can also be run
21554 directly from a router like any other transport. To reduce the possibility of
21555 message cascades, messages created by the autoreply transport always have empty
21556 envelope sender addresses, like bounce messages.
21557
21558 The parameters of the message to be sent can be specified in the configuration
21559 by options described below. However, these are used only when the address
21560 passed to the transport does not contain its own reply information. When the
21561 transport is run as a consequence of a mail or vacation command in a filter
21562 file, the parameters of the message are supplied by the filter, and passed with
21563 the address. The transport's options that define the message are then ignored
21564 (so they are not usually set in this case). The message is specified entirely
21565 by the filter or by the transport; it is never built from a mixture of options.
21566 However, the file_optional, mode, and return_message options apply in all
21567 cases.
21568
21569 Autoreply is implemented as a local transport. When used as a result of a
21570 command in a user's filter file, autoreply normally runs under the uid and gid
21571 of the user, and with appropriate current and home directories (see chapter 23
21572 ).
21573
21574 There is a subtle difference between routing a message to a pipe transport that
21575 generates some text to be returned to the sender, and routing it to an
21576 autoreply transport. This difference is noticeable only if more than one
21577 address from the same message is so handled. In the case of a pipe, the
21578 separate outputs from the different addresses are gathered up and returned to
21579 the sender in a single message, whereas if autoreply is used, a separate
21580 message is generated for each address that is passed to it.
21581
21582 Non-printing characters are not permitted in the header lines generated for the
21583 message that autoreply creates, with the exception of newlines that are
21584 immediately followed by white space. If any non-printing characters are found,
21585 the transport defers. Whether characters with the top bit set count as printing
21586 characters or not is controlled by the print_topbitchars global option.
21587
21588 If any of the generic options for manipulating headers (for example,
21589 headers_add) are set on an autoreply transport, they apply to the copy of the
21590 original message that is included in the generated message when return_message
21591 is set. They do not apply to the generated message itself.
21592
21593 If the autoreply transport receives return code 2 from Exim when it submits the
21594 message, indicating that there were no recipients, it does not treat this as an
21595 error. This means that autoreplies sent to $sender_address when this is empty
21596 (because the incoming message is a bounce message) do not cause problems. They
21597 are just discarded.
21598
21599
21600 27.1 Private options for autoreply
21601 ----------------------------------
21602
21603 +-----------------------------------------------+
21604 |bcc|Use: autoreply|Type: string*|Default: unset|
21605 +-----------------------------------------------+
21606
21607 This specifies the addresses that are to receive "blind carbon copies" of the
21608 message when the message is specified by the transport.
21609
21610 +----------------------------------------------+
21611 |cc|Use: autoreply|Type: string*|Default: unset|
21612 +----------------------------------------------+
21613
21614 This specifies recipients of the message and the contents of the Cc: header
21615 when the message is specified by the transport.
21616
21617 +------------------------------------------------+
21618 |file|Use: autoreply|Type: string*|Default: unset|
21619 +------------------------------------------------+
21620
21621 The contents of the file are sent as the body of the message when the message
21622 is specified by the transport. If both file and text are set, the text string
21623 comes first.
21624
21625 +-------------------------------------------------------+
21626 |file_expand|Use: autoreply|Type: boolean|Default: false|
21627 +-------------------------------------------------------+
21628
21629 If this is set, the contents of the file named by the file option are subjected
21630 to string expansion as they are added to the message.
21631
21632 +---------------------------------------------------------+
21633 |file_optional|Use: autoreply|Type: boolean|Default: false|
21634 +---------------------------------------------------------+
21635
21636 If this option is true, no error is generated if the file named by the file
21637 option or passed with the address does not exist or cannot be read.
21638
21639 +------------------------------------------------+
21640 |from|Use: autoreply|Type: string*|Default: unset|
21641 +------------------------------------------------+
21642
21643 This specifies the contents of the From: header when the message is specified
21644 by the transport.
21645
21646 +---------------------------------------------------+
21647 |headers|Use: autoreply|Type: string*|Default: unset|
21648 +---------------------------------------------------+
21649
21650 This specifies additional RFC 2822 headers that are to be added to the message
21651 when the message is specified by the transport. Several can be given by using "
21652 \n" to separate them. There is no check on the format.
21653
21654 +-----------------------------------------------+
21655 |log|Use: autoreply|Type: string*|Default: unset|
21656 +-----------------------------------------------+
21657
21658 This option names a file in which a record of every message sent is logged when
21659 the message is specified by the transport.
21660
21661 +-----------------------------------------------------+
21662 |mode|Use: autoreply|Type: octal integer|Default: 0600|
21663 +-----------------------------------------------------+
21664
21665 If either the log file or the "once" file has to be created, this mode is used.
21666
21667 +------------------------------------------------------------+
21668 |never_mail|Use: autoreply|Type: address list*|Default: unset|
21669 +------------------------------------------------------------+
21670
21671 If any run of the transport creates a message with a recipient that matches any
21672 item in the list, that recipient is quietly discarded. If all recipients are
21673 discarded, no message is created. This applies both when the recipients are
21674 generated by a filter and when they are specified in the transport.
21675
21676 +------------------------------------------------+
21677 |once|Use: autoreply|Type: string*|Default: unset|
21678 +------------------------------------------------+
21679
21680 This option names a file or DBM database in which a record of each To:
21681 recipient is kept when the message is specified by the transport. Note: This
21682 does not apply to Cc: or Bcc: recipients.
21683
21684 If once is unset, or is set to an empty string, the message is always sent. By
21685 default, if once is set to a non-empty filename, the message is not sent if a
21686 potential recipient is already listed in the database. However, if the
21687 once_repeat option specifies a time greater than zero, the message is sent if
21688 that much time has elapsed since a message was last sent to this recipient. A
21689 setting of zero time for once_repeat (the default) prevents a message from
21690 being sent a second time - in this case, zero means infinity.
21691
21692 If once_file_size is zero, a DBM database is used to remember recipients, and
21693 it is allowed to grow as large as necessary. If once_file_size is set greater
21694 than zero, it changes the way Exim implements the once option. Instead of using
21695 a DBM file to record every recipient it sends to, it uses a regular file, whose
21696 size will never get larger than the given value.
21697
21698 In the file, Exim keeps a linear list of recipient addresses and the times at
21699 which they were sent messages. If the file is full when a new address needs to
21700 be added, the oldest address is dropped. If once_repeat is not set, this means
21701 that a given recipient may receive multiple messages, but at unpredictable
21702 intervals that depend on the rate of turnover of addresses in the file. If
21703 once_repeat is set, it specifies a maximum time between repeats.
21704
21705 +------------------------------------------------------+
21706 |once_file_size|Use: autoreply|Type: integer|Default: 0|
21707 +------------------------------------------------------+
21708
21709 See once above.
21710
21711 +--------------------------------------------------+
21712 |once_repeat|Use: autoreply|Type: time*|Default: 0s|
21713 +--------------------------------------------------+
21714
21715 See once above. After expansion, the value of this option must be a valid time
21716 value.
21717
21718 +----------------------------------------------------+
21719 |reply_to|Use: autoreply|Type: string*|Default: unset|
21720 +----------------------------------------------------+
21721
21722 This specifies the contents of the Reply-To: header when the message is
21723 specified by the transport.
21724
21725 +----------------------------------------------------------+
21726 |return_message|Use: autoreply|Type: boolean|Default: false|
21727 +----------------------------------------------------------+
21728
21729 If this is set, a copy of the original message is returned with the new
21730 message, subject to the maximum size set in the return_size_limit global
21731 configuration option.
21732
21733 +---------------------------------------------------+
21734 |subject|Use: autoreply|Type: string*|Default: unset|
21735 +---------------------------------------------------+
21736
21737 This specifies the contents of the Subject: header when the message is
21738 specified by the transport. It is tempting to quote the original subject in
21739 automatic responses. For example:
21740
21741 subject = Re: $h_subject:
21742
21743 There is a danger in doing this, however. It may allow a third party to
21744 subscribe your users to an opt-in mailing list, provided that the list accepts
21745 bounce messages as subscription confirmations. Well-managed lists require a
21746 non-bounce message to confirm a subscription, so the danger is relatively
21747 small.
21748
21749 +------------------------------------------------+
21750 |text|Use: autoreply|Type: string*|Default: unset|
21751 +------------------------------------------------+
21752
21753 This specifies a single string to be used as the body of the message when the
21754 message is specified by the transport. If both text and file are set, the text
21755 comes first.
21756
21757 +----------------------------------------------+
21758 |to|Use: autoreply|Type: string*|Default: unset|
21759 +----------------------------------------------+
21760
21761 This specifies recipients of the message and the contents of the To: header
21762 when the message is specified by the transport.
21763
21764
21765
21766 ===============================================================================
21767 28. THE LMTP TRANSPORT
21768
21769 The lmtp transport runs the LMTP protocol (RFC 2033) over a pipe to a specified
21770 command or by interacting with a Unix domain socket. This transport is
21771 something of a cross between the pipe and smtp transports. Exim also has
21772 support for using LMTP over TCP/IP; this is implemented as an option for the
21773 smtp transport. Because LMTP is expected to be of minority interest, the
21774 default build-time configure in src/EDITME has it commented out. You need to
21775 ensure that
21776
21777 TRANSPORT_LMTP=yes
21778
21779 is present in your Local/Makefile in order to have the lmtp transport included
21780 in the Exim binary. The private options of the lmtp transport are as follows:
21781
21782 +-----------------------------------------------+
21783 |batch_id|Use: lmtp|Type: string*|Default: unset|
21784 +-----------------------------------------------+
21785
21786 See the description of local delivery batching in chapter 25.
21787
21788 +--------------------------------------------+
21789 |batch_max|Use: lmtp|Type: integer|Default: 1|
21790 +--------------------------------------------+
21791
21792 This limits the number of addresses that can be handled in a single delivery.
21793 Most LMTP servers can handle several addresses at once, so it is normally a
21794 good idea to increase this value. See the description of local delivery
21795 batching in chapter 25.
21796
21797 +----------------------------------------------+
21798 |command|Use: lmtp|Type: string*|Default: unset|
21799 +----------------------------------------------+
21800
21801 This option must be set if socket is not set. The string is a command which is
21802 run in a separate process. It is split up into a command name and list of
21803 arguments, each of which is separately expanded (so expansion cannot change the
21804 number of arguments). The command is run directly, not via a shell. The message
21805 is passed to the new process using the standard input and output to operate the
21806 LMTP protocol.
21807
21808 +---------------------------------------------------+
21809 |ignore_quota|Use: lmtp|Type: boolean|Default: false|
21810 +---------------------------------------------------+
21811
21812 If this option is set true, the string "IGNOREQUOTA" is added to RCPT commands,
21813 provided that the LMTP server has advertised support for IGNOREQUOTA in its
21814 response to the LHLO command.
21815
21816 +---------------------------------------------+
21817 |socket|Use: lmtp|Type: string*|Default: unset|
21818 +---------------------------------------------+
21819
21820 This option must be set if command is not set. The result of expansion must be
21821 the name of a Unix domain socket. The transport connects to the socket and
21822 delivers the message to it using the LMTP protocol.
21823
21824 +----------------------------------------+
21825 |timeout|Use: lmtp|Type: time|Default: 5m|
21826 +----------------------------------------+
21827
21828 The transport is aborted if the created process or Unix domain socket does not
21829 respond to LMTP commands or message input within this timeout. Delivery is
21830 deferred, and will be tried again later. Here is an example of a typical LMTP
21831 transport:
21832
21833 lmtp:
21834 driver = lmtp
21835 command = /some/local/lmtp/delivery/program
21836 batch_max = 20
21837 user = exim
21838
21839 This delivers up to 20 addresses at a time, in a mixture of domains if
21840 necessary, running as the user exim.
21841
21842
21843
21844 ===============================================================================
21845 29. THE PIPE TRANSPORT
21846
21847 The pipe transport is used to deliver messages via a pipe to a command running
21848 in another process. One example is the use of pipe as a pseudo-remote transport
21849 for passing messages to some other delivery mechanism (such as UUCP). Another
21850 is the use by individual users to automatically process their incoming
21851 messages. The pipe transport can be used in one of the following ways:
21852
21853 * A router routes one address to a transport in the normal way, and the
21854 transport is configured as a pipe transport. In this case, $local_part
21855 contains the local part of the address (as usual), and the command that is
21856 run is specified by the command option on the transport.
21857
21858 * If the batch_max option is set greater than 1 (the default is 1), the
21859 transport can handle more than one address in a single run. In this case,
21860 when more than one address is routed to the transport, $local_part is not
21861 set (because it is not unique). However, the pseudo-variable
21862 $pipe_addresses (described in section 29.3 below) contains all the
21863 addresses that are routed to the transport.
21864
21865 * A router redirects an address directly to a pipe command (for example, from
21866 an alias or forward file). In this case, $address_pipe contains the text of
21867 the pipe command, and the command option on the transport is ignored unless
21868 force_command is set. If only one address is being transported (batch_max
21869 is not greater than one, or only one address was redirected to this pipe
21870 command), $local_part contains the local part that was redirected.
21871
21872 The pipe transport is a non-interactive delivery method. Exim can also deliver
21873 messages over pipes using the LMTP interactive protocol. This is implemented by
21874 the lmtp transport.
21875
21876 In the case when pipe is run as a consequence of an entry in a local user's
21877 .forward file, the command runs under the uid and gid of that user. In other
21878 cases, the uid and gid have to be specified explicitly, either on the transport
21879 or on the router that handles the address. Current and "home" directories are
21880 also controllable. See chapter 23 for details of the local delivery environment
21881 and chapter 25 for a discussion of local delivery batching.
21882
21883
21884 29.1 Concurrent delivery
21885 ------------------------
21886
21887 If two messages arrive at almost the same time, and both are routed to a pipe
21888 delivery, the two pipe transports may be run concurrently. You must ensure that
21889 any pipe commands you set up are robust against this happening. If the commands
21890 write to a file, the exim_lock utility might be of use. Alternatively the
21891 max_parallel option could be used with a value of "1" to enforce serialization.
21892
21893
21894 29.2 Returned status and data
21895 -----------------------------
21896
21897 If the command exits with a non-zero return code, the delivery is deemed to
21898 have failed, unless either the ignore_status option is set (in which case the
21899 return code is treated as zero), or the return code is one of those listed in
21900 the temp_errors option, which are interpreted as meaning "try again later". In
21901 this case, delivery is deferred. Details of a permanent failure are logged, but
21902 are not included in the bounce message, which merely contains "local delivery
21903 failed".
21904
21905 If the command exits on a signal and the freeze_signal option is set then the
21906 message will be frozen in the queue. If that option is not set, a bounce will
21907 be sent as normal.
21908
21909 If the return code is greater than 128 and the command being run is a shell
21910 script, it normally means that the script was terminated by a signal whose
21911 value is the return code minus 128. The freeze_signal option does not apply in
21912 this case.
21913
21914 If Exim is unable to run the command (that is, if execve() fails), the return
21915 code is set to 127. This is the value that a shell returns if it is asked to
21916 run a non-existent command. The wording for the log line suggests that a
21917 non-existent command may be the problem.
21918
21919 The return_output option can affect the result of a pipe delivery. If it is set
21920 and the command produces any output on its standard output or standard error
21921 streams, the command is considered to have failed, even if it gave a zero
21922 return code or if ignore_status is set. The output from the command is included
21923 as part of the bounce message. The return_fail_output option is similar, except
21924 that output is returned only when the command exits with a failure return code,
21925 that is, a value other than zero or a code that matches temp_errors.
21926
21927
21928 29.3 How the command is run
21929 ---------------------------
21930
21931 The command line is (by default) broken down into a command name and arguments
21932 by the pipe transport itself. The allow_commands and restrict_to_path options
21933 can be used to restrict the commands that may be run.
21934
21935 Unquoted arguments are delimited by white space. If an argument appears in
21936 double quotes, backslash is interpreted as an escape character in the usual
21937 way. If an argument appears in single quotes, no escaping is done.
21938
21939 String expansion is applied to the command line except when it comes from a
21940 traditional .forward file (commands from a filter file are expanded). The
21941 expansion is applied to each argument in turn rather than to the whole line.
21942 For this reason, any string expansion item that contains white space must be
21943 quoted so as to be contained within a single argument. A setting such as
21944
21945 command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}}
21946
21947 will not work, because the expansion item gets split between several arguments.
21948 You have to write
21949
21950 command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}"
21951
21952 to ensure that it is all in one argument. The expansion is done in this way,
21953 argument by argument, so that the number of arguments cannot be changed as a
21954 result of expansion, and quotes or backslashes in inserted variables do not
21955 interact with external quoting. However, this leads to problems if you want to
21956 generate multiple arguments (or the command name plus arguments) from a single
21957 expansion. In this situation, the simplest solution is to use a shell. For
21958 example:
21959
21960 command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}}
21961
21962 Special handling takes place when an argument consists of precisely the text
21963 "$pipe_addresses" (no quotes). This is not a general expansion variable; the
21964 only place this string is recognized is when it appears as an argument for a
21965 pipe or transport filter command. It causes each address that is being handled
21966 to be inserted in the argument list at that point as a separate argument. This
21967 avoids any problems with spaces or shell metacharacters, and is of use when a
21968 pipe transport is handling groups of addresses in a batch.
21969
21970 If force_command is enabled on the transport, Special handling takes place for
21971 an argument that consists of precisely the text "$address_pipe". It is handled
21972 similarly to $pipe_addresses above. It is expanded and each argument is
21973 inserted in the argument list at that point as a separate argument. The
21974 "$address_pipe" item does not need to be the only item in the argument; in
21975 fact, if it were then force_command should behave as a no-op. Rather, it should
21976 be used to adjust the command run while preserving the argument vector
21977 separation.
21978
21979 After splitting up into arguments and expansion, the resulting command is run
21980 in a subprocess directly from the transport, not under a shell. The message
21981 that is being delivered is supplied on the standard input, and the standard
21982 output and standard error are both connected to a single pipe that is read by
21983 Exim. The max_output option controls how much output the command may produce,
21984 and the return_output and return_fail_output options control what is done with
21985 it.
21986
21987 Not running the command under a shell (by default) lessens the security risks
21988 in cases when a command from a user's filter file is built out of data that was
21989 taken from an incoming message. If a shell is required, it can of course be
21990 explicitly specified as the command to be run. However, there are circumstances
21991 where existing commands (for example, in .forward files) expect to be run under
21992 a shell and cannot easily be modified. To allow for these cases, there is an
21993 option called use_shell, which changes the way the pipe transport works.
21994 Instead of breaking up the command line as just described, it expands it as a
21995 single string and passes the result to /bin/sh. The restrict_to_path option and
21996 the $pipe_addresses facility cannot be used with use_shell, and the whole
21997 mechanism is inherently less secure.
21998
21999
22000 29.4 Environment variables
22001 --------------------------
22002
22003 The environment variables listed below are set up when the command is invoked.
22004 This list is a compromise for maximum compatibility with other MTAs. Note that
22005 the environment option can be used to add additional variables to this
22006 environment. The environment for the pipe transport is not subject to the
22007 add_environment and keep_environment main config options.
22008
22009 DOMAIN the domain of the address
22010 HOME the home directory, if set
22011 HOST the host name when called from a router (see below)
22012 LOCAL_PART see below
22013 LOCAL_PART_PREFIX see below
22014 LOCAL_PART_SUFFIX see below
22015 LOGNAME see below
22016 MESSAGE_ID Exim's local ID for the message
22017 PATH as specified by the path option below
22018 QUALIFY_DOMAIN the sender qualification domain
22019 RECIPIENT the complete recipient address
22020 SENDER the sender of the message (empty if a bounce)
22021 SHELL /bin/sh
22022 TZ the value of the timezone option, if set
22023 USER see below
22024
22025 When a pipe transport is called directly from (for example) an accept router,
22026 LOCAL_PART is set to the local part of the address. When it is called as a
22027 result of a forward or alias expansion, LOCAL_PART is set to the local part of
22028 the address that was expanded. In both cases, any affixes are removed from the
22029 local part, and made available in LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX,
22030 respectively. LOGNAME and USER are set to the same value as LOCAL_PART for
22031 compatibility with other MTAs.
22032
22033 HOST is set only when a pipe transport is called from a router that associates
22034 hosts with an address, typically when using pipe as a pseudo-remote transport.
22035 HOST is set to the first host name specified by the router.
22036
22037 If the transport's generic home_directory option is set, its value is used for
22038 the HOME environment variable. Otherwise, a home directory may be set by the
22039 router's transport_home_directory option, which defaults to the user's home
22040 directory if check_local_user is set.
22041
22042
22043 29.5 Private options for pipe
22044 -----------------------------
22045
22046 +----------------------------------------------------------+
22047 |allow_commands|Use: pipe|Type: string list*|Default: unset|
22048 +----------------------------------------------------------+
22049
22050 The string is expanded, and is then interpreted as a colon-separated list of
22051 permitted commands. If restrict_to_path is not set, the only commands permitted
22052 are those in the allow_commands list. They need not be absolute paths; the path
22053 option is still used for relative paths. If restrict_to_path is set with
22054 allow_commands, the command must either be in the allow_commands list, or a
22055 name without any slashes that is found on the path. In other words, if neither
22056 allow_commands nor restrict_to_path is set, there is no restriction on the
22057 command, but otherwise only commands that are permitted by one or the other are
22058 allowed. For example, if
22059
22060 allow_commands = /usr/bin/vacation
22061
22062 and restrict_to_path is not set, the only permitted command is /usr/bin/
22063 vacation. The allow_commands option may not be set if use_shell is set.
22064
22065 +-----------------------------------------------+
22066 |batch_id|Use: pipe|Type: string*|Default: unset|
22067 +-----------------------------------------------+
22068
22069 See the description of local delivery batching in chapter 25.
22070
22071 +--------------------------------------------+
22072 |batch_max|Use: pipe|Type: integer|Default: 1|
22073 +--------------------------------------------+
22074
22075 This limits the number of addresses that can be handled in a single delivery.
22076 See the description of local delivery batching in chapter 25.
22077
22078 +--------------------------------------------------+
22079 |check_string|Use: pipe|Type: string|Default: unset|
22080 +--------------------------------------------------+
22081
22082 As pipe writes the message, the start of each line is tested for matching
22083 check_string, and if it does, the initial matching characters are replaced by
22084 the contents of escape_string, provided both are set. The value of check_string
22085 is a literal string, not a regular expression, and the case of any letters it
22086 contains is significant. When use_bsmtp is set, the contents of check_string
22087 and escape_string are forced to values that implement the SMTP escaping
22088 protocol. Any settings made in the configuration file are ignored.
22089
22090 +----------------------------------------------+
22091 |command|Use: pipe|Type: string*|Default: unset|
22092 +----------------------------------------------+
22093
22094 This option need not be set when pipe is being used to deliver to pipes
22095 obtained directly from address redirections. In other cases, the option must be
22096 set, to provide a command to be run. It need not yield an absolute path (see
22097 the path option below). The command is split up into separate arguments by
22098 Exim, and each argument is separately expanded, as described in section 29.3
22099 above.
22100
22101 +--------------------------------------------------+
22102 |environment|Use: pipe|Type: string*|Default: unset|
22103 +--------------------------------------------------+
22104
22105 This option is used to add additional variables to the environment in which the
22106 command runs (see section 29.4 for the default list). Its value is a string
22107 which is expanded, and then interpreted as a colon-separated list of
22108 environment settings of the form <name>=<value>.
22109
22110 +---------------------------------------------------+
22111 |escape_string|Use: pipe|Type: string|Default: unset|
22112 +---------------------------------------------------+
22113
22114 See check_string above.
22115
22116 +-------------------------------------------------------+
22117 |freeze_exec_fail|Use: pipe|Type: boolean|Default: false|
22118 +-------------------------------------------------------+
22119
22120 Failure to exec the command in a pipe transport is by default treated like any
22121 other failure while running the command. However, if freeze_exec_fail is set,
22122 failure to exec is treated specially, and causes the message to be frozen,
22123 whatever the setting of ignore_status.
22124
22125 +----------------------------------------------------+
22126 |freeze_signal|Use: pipe|Type: boolean|Default: false|
22127 +----------------------------------------------------+
22128
22129 Normally if the process run by a command in a pipe transport exits on a signal,
22130 a bounce message is sent. If freeze_signal is set, the message will be frozen
22131 in Exim's queue instead.
22132
22133 +----------------------------------------------------+
22134 |force_command|Use: pipe|Type: boolean|Default: false|
22135 +----------------------------------------------------+
22136
22137 Normally when a router redirects an address directly to a pipe command the
22138 command option on the transport is ignored. If force_command is set, the
22139 command option will used. This is especially useful for forcing a wrapper or
22140 additional argument to be added to the command. For example:
22141
22142 command = /usr/bin/remote_exec myhost -- $address_pipe
22143 force_command
22144
22145 Note that $address_pipe is handled specially in command when force_command is
22146 set, expanding out to the original argument vector as separate items, similarly
22147 to a Unix shell ""$@"" construct.
22148
22149 +----------------------------------------------------+
22150 |ignore_status|Use: pipe|Type: boolean|Default: false|
22151 +----------------------------------------------------+
22152
22153 If this option is true, the status returned by the subprocess that is set up to
22154 run the command is ignored, and Exim behaves as if zero had been returned.
22155 Otherwise, a non-zero status or termination by signal causes an error return
22156 from the transport unless the status value is one of those listed in
22157 temp_errors; these cause the delivery to be deferred and tried again later.
22158
22159 Note: This option does not apply to timeouts, which do not return a status. See
22160 the timeout_defer option for how timeouts are handled.
22161
22162 +-------------------------------------------------------+
22163 |log_defer_output|Use: pipe|Type: boolean|Default: false|
22164 +-------------------------------------------------------+
22165
22166 If this option is set, and the status returned by the command is one of the
22167 codes listed in temp_errors (that is, delivery was deferred), and any output
22168 was produced on stdout or stderr, the first line of it is written to the main
22169 log.
22170
22171 +------------------------------------------------------+
22172 |log_fail_output|Use: pipe|Type: boolean|Default: false|
22173 +------------------------------------------------------+
22174
22175 If this option is set, and the command returns any output on stdout or stderr,
22176 and also ends with a return code that is neither zero nor one of the return
22177 codes listed in temp_errors (that is, the delivery failed), the first line of
22178 output is written to the main log. This option and log_output are mutually
22179 exclusive. Only one of them may be set.
22180
22181 +-------------------------------------------------+
22182 |log_output|Use: pipe|Type: boolean|Default: false|
22183 +-------------------------------------------------+
22184
22185 If this option is set and the command returns any output on stdout or stderr,
22186 the first line of output is written to the main log, whatever the return code.
22187 This option and log_fail_output are mutually exclusive. Only one of them may be
22188 set.
22189
22190 +-----------------------------------------------+
22191 |max_output|Use: pipe|Type: integer|Default: 20K|
22192 +-----------------------------------------------+
22193
22194 This specifies the maximum amount of output that the command may produce on its
22195 standard output and standard error file combined. If the limit is exceeded, the
22196 process running the command is killed. This is intended as a safety measure to
22197 catch runaway processes. The limit is applied independently of the settings of
22198 the options that control what is done with such output (for example,
22199 return_output). Because of buffering effects, the amount of output may exceed
22200 the limit by a small amount before Exim notices.
22201
22202 +---------------------------------------------------------+
22203 |message_prefix|Use: pipe|Type: string*|Default: see below|
22204 +---------------------------------------------------------+
22205
22206 The string specified here is expanded and output at the start of every message.
22207 The default is unset if use_bsmtp is set. Otherwise it is
22208
22209 message_prefix = \
22210 From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
22211 ${tod_bsdinbox}\n
22212
22213 This is required by the commonly used /usr/bin/vacation program. However, it
22214 must not be present if delivery is to the Cyrus IMAP server, or to the tmail
22215 local delivery agent. The prefix can be suppressed by setting
22216
22217 message_prefix =
22218
22219 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
22220 n" in message_prefix.
22221
22222 +---------------------------------------------------------+
22223 |message_suffix|Use: pipe|Type: string*|Default: see below|
22224 +---------------------------------------------------------+
22225
22226 The string specified here is expanded and output at the end of every message.
22227 The default is unset if use_bsmtp is set. Otherwise it is a single newline. The
22228 suffix can be suppressed by setting
22229
22230 message_suffix =
22231
22232 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
22233 n" in message_suffix.
22234
22235 +---------------------------------------------------+
22236 |path|Use: pipe|Type: string*|Default: /bin:/usr/bin|
22237 +---------------------------------------------------+
22238
22239 This option is expanded and specifies the string that is set up in the PATH
22240 environment variable of the subprocess. If the command option does not yield an
22241 absolute path name, the command is sought in the PATH directories, in the usual
22242 way. Warning: This does not apply to a command specified as a transport filter.
22243
22244 +------------------------------------------------------+
22245 |permit_coredump|Use: pipe|Type: boolean|Default: false|
22246 +------------------------------------------------------+
22247
22248 Normally Exim inhibits core-dumps during delivery. If you have a need to get a
22249 core-dump of a pipe command, enable this command. This enables core-dumps
22250 during delivery and affects both the Exim binary and the pipe command run. It
22251 is recommended that this option remain off unless and until you have a need for
22252 it and that this only be enabled when needed, as the risk of excessive resource
22253 consumption can be quite high. Note also that Exim is typically installed as a
22254 setuid binary and most operating systems will inhibit coredumps of these by
22255 default, so further OS-specific action may be required.
22256
22257 +------------------------------------------------------+
22258 |pipe_as_creator|Use: pipe|Type: boolean|Default: false|
22259 +------------------------------------------------------+
22260
22261 If the generic user option is not set and this option is true, the delivery
22262 process is run under the uid that was in force when Exim was originally called
22263 to accept the message. If the group id is not otherwise set (via the generic
22264 group option), the gid that was in force when Exim was originally called to
22265 accept the message is used.
22266
22267 +-------------------------------------------------------+
22268 |restrict_to_path|Use: pipe|Type: boolean|Default: false|
22269 +-------------------------------------------------------+
22270
22271 When this option is set, any command name not listed in allow_commands must
22272 contain no slashes. The command is searched for only in the directories listed
22273 in the path option. This option is intended for use in the case when a pipe
22274 command has been generated from a user's .forward file. This is usually handled
22275 by a pipe transport called address_pipe.
22276
22277 +---------------------------------------------------------+
22278 |return_fail_output|Use: pipe|Type: boolean|Default: false|
22279 +---------------------------------------------------------+
22280
22281 If this option is true, and the command produced any output and ended with a
22282 return code other than zero or one of the codes listed in temp_errors (that is,
22283 the delivery failed), the output is returned in the bounce message. However, if
22284 the message has a null sender (that is, it is itself a bounce message), output
22285 from the command is discarded. This option and return_output are mutually
22286 exclusive. Only one of them may be set.
22287
22288 +----------------------------------------------------+
22289 |return_output|Use: pipe|Type: boolean|Default: false|
22290 +----------------------------------------------------+
22291
22292 If this option is true, and the command produced any output, the delivery is
22293 deemed to have failed whatever the return code from the command, and the output
22294 is returned in the bounce message. Otherwise, the output is just discarded.
22295 However, if the message has a null sender (that is, it is a bounce message),
22296 output from the command is always discarded, whatever the setting of this
22297 option. This option and return_fail_output are mutually exclusive. Only one of
22298 them may be set.
22299
22300 +----------------------------------------------------------+
22301 |temp_errors|Use: pipe|Type: string list|Default: see below|
22302 +----------------------------------------------------------+
22303
22304 This option contains either a colon-separated list of numbers, or a single
22305 asterisk. If ignore_status is false and return_output is not set, and the
22306 command exits with a non-zero return code, the failure is treated as temporary
22307 and the delivery is deferred if the return code matches one of the numbers, or
22308 if the setting is a single asterisk. Otherwise, non-zero return codes are
22309 treated as permanent errors. The default setting contains the codes defined by
22310 EX_TEMPFAIL and EX_CANTCREAT in sysexits.h. If Exim is compiled on a system
22311 that does not define these macros, it assumes values of 75 and 73,
22312 respectively.
22313
22314 +----------------------------------------+
22315 |timeout|Use: pipe|Type: time|Default: 1h|
22316 +----------------------------------------+
22317
22318 If the command fails to complete within this time, it is killed. This normally
22319 causes the delivery to fail (but see timeout_defer). A zero time interval
22320 specifies no timeout. In order to ensure that any subprocesses created by the
22321 command are also killed, Exim makes the initial process a process group leader,
22322 and kills the whole process group on a timeout. However, this can be defeated
22323 if one of the processes starts a new process group.
22324
22325 +----------------------------------------------------+
22326 |timeout_defer|Use: pipe|Type: boolean|Default: false|
22327 +----------------------------------------------------+
22328
22329 A timeout in a pipe transport, either in the command that the transport runs,
22330 or in a transport filter that is associated with it, is by default treated as a
22331 hard error, and the delivery fails. However, if timeout_defer is set true, both
22332 kinds of timeout become temporary errors, causing the delivery to be deferred.
22333
22334 +------------------------------------------------+
22335 |umask|Use: pipe|Type: octal integer|Default: 022|
22336 +------------------------------------------------+
22337
22338 This specifies the umask setting for the subprocess that runs the command.
22339
22340 +------------------------------------------------+
22341 |use_bsmtp|Use: pipe|Type: boolean|Default: false|
22342 +------------------------------------------------+
22343
22344 If this option is set true, the pipe transport writes messages in "batch SMTP"
22345 format, with the envelope sender and recipient(s) included as SMTP commands. If
22346 you want to include a leading HELO command with such messages, you can do so by
22347 setting the message_prefix option. See section 48.10 for details of batch SMTP.
22348
22349 +---------------------------------------------------------+
22350 |use_classresources|Use: pipe|Type: boolean|Default: false|
22351 +---------------------------------------------------------+
22352
22353 This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/
22354 OS. If it is set true, the setclassresources() function is used to set resource
22355 limits when a pipe transport is run to perform a delivery. The limits for the
22356 uid under which the pipe is to run are obtained from the login class database.
22357
22358 +-----------------------------------------------+
22359 |use_crlf|Use: pipe|Type: boolean|Default: false|
22360 +-----------------------------------------------+
22361
22362 This option causes lines to be terminated with the two-character CRLF sequence
22363 (carriage return, linefeed) instead of just a linefeed character. In the case
22364 of batched SMTP, the byte sequence written to the pipe is then an exact image
22365 of what would be sent down a real SMTP connection.
22366
22367 The contents of the message_prefix and message_suffix options are written
22368 verbatim, so must contain their own carriage return characters if these are
22369 needed. When use_bsmtp is not set, the default values for both message_prefix
22370 and message_suffix end with a single linefeed, so their values must be changed
22371 to end with "\r\n" if use_crlf is set.
22372
22373 +------------------------------------------------+
22374 |use_shell|Use: pipe|Type: boolean|Default: false|
22375 +------------------------------------------------+
22376
22377 If this option is set, it causes the command to be passed to /bin/sh instead of
22378 being run directly from the transport, as described in section 29.3. This is
22379 less secure, but is needed in some situations where the command is expected to
22380 be run under a shell and cannot easily be modified. The allow_commands and
22381 restrict_to_path options, and the "$pipe_addresses" facility are incompatible
22382 with use_shell. The command is expanded as a single string, and handed to /bin/
22383 sh as data for its -c option.
22384
22385
22386 29.6 Using an external local delivery agent
22387 -------------------------------------------
22388
22389 The pipe transport can be used to pass all messages that require local delivery
22390 to a separate local delivery agent such as procmail. When doing this, care must
22391 be taken to ensure that the pipe is run under an appropriate uid and gid. In
22392 some configurations one wants this to be a uid that is trusted by the delivery
22393 agent to supply the correct sender of the message. It may be necessary to
22394 recompile or reconfigure the delivery agent so that it trusts an appropriate
22395 user. The following is an example transport and router configuration for
22396 procmail:
22397
22398 # transport
22399 procmail_pipe:
22400 driver = pipe
22401 command = /usr/local/bin/procmail -d $local_part
22402 return_path_add
22403 delivery_date_add
22404 envelope_to_add
22405 check_string = "From "
22406 escape_string = ">From "
22407 umask = 077
22408 user = $local_part
22409 group = mail
22410
22411 # router
22412 procmail:
22413 driver = accept
22414 check_local_user
22415 transport = procmail_pipe
22416
22417 In this example, the pipe is run as the local user, but with the group set to
22418 mail. An alternative is to run the pipe as a specific user such as mail or exim
22419 , but in this case you must arrange for procmail to trust that user to supply a
22420 correct sender address. If you do not specify either a group or a user option,
22421 the pipe command is run as the local user. The home directory is the user's
22422 home directory by default.
22423
22424 Note: The command that the pipe transport runs does not begin with
22425
22426 IFS=" "
22427
22428 as shown in some procmail documentation, because Exim does not by default use a
22429 shell to run pipe commands.
22430
22431 The next example shows a transport and a router for a system where local
22432 deliveries are handled by the Cyrus IMAP server.
22433
22434 # transport
22435 local_delivery_cyrus:
22436 driver = pipe
22437 command = /usr/cyrus/bin/deliver \
22438 -m ${substr_1:$local_part_suffix} -- $local_part
22439 user = cyrus
22440 group = mail
22441 return_output
22442 log_output
22443 message_prefix =
22444 message_suffix =
22445
22446 # router
22447 local_user_cyrus:
22448 driver = accept
22449 check_local_user
22450 local_part_suffix = .*
22451 transport = local_delivery_cyrus
22452
22453 Note the unsetting of message_prefix and message_suffix, and the use of
22454 return_output to cause any text written by Cyrus to be returned to the sender.
22455
22456
22457
22458 ===============================================================================
22459 30. THE SMTP TRANSPORT
22460
22461 The smtp transport delivers messages over TCP/IP connections using the SMTP or
22462 LMTP protocol. The list of hosts to try can either be taken from the address
22463 that is being processed (having been set up by the router), or specified
22464 explicitly for the transport. Timeout and retry processing (see chapter 32) is
22465 applied to each IP address independently.
22466
22467
22468 30.1 Multiple messages on a single connection
22469 ---------------------------------------------
22470
22471 The sending of multiple messages over a single TCP/IP connection can arise in
22472 two ways:
22473
22474 * If a message contains more than max_rcpt (see below) addresses that are
22475 routed to the same host, more than one copy of the message has to be sent
22476 to that host. In this situation, multiple copies may be sent in a single
22477 run of the smtp transport over a single TCP/IP connection. (What Exim
22478 actually does when it has too many addresses to send in one message also
22479 depends on the value of the global remote_max_parallel option. Details are
22480 given in section 48.1.)
22481
22482 * When a message has been successfully delivered over a TCP/IP connection,
22483 Exim looks in its hints database to see if there are any other messages
22484 awaiting a connection to the same host. If there are, a new delivery
22485 process is started for one of them, and the current TCP/IP connection is
22486 passed on to it. The new process may in turn send multiple copies and
22487 possibly create yet another process.
22488
22489 For each copy sent over the same TCP/IP connection, a sequence counter is
22490 incremented, and if it ever gets to the value of connection_max_messages, no
22491 further messages are sent over that connection.
22492
22493
22494 30.2 Use of the $host and $host_address variables
22495 -------------------------------------------------
22496
22497 At the start of a run of the smtp transport, the values of $host and
22498 $host_address are the name and IP address of the first host on the host list
22499 passed by the router. However, when the transport is about to connect to a
22500 specific host, and while it is connected to that host, $host and $host_address
22501 are set to the values for that host. These are the values that are in force
22502 when the helo_data, hosts_try_auth, interface, serialize_hosts, and the various
22503 TLS options are expanded.
22504
22505
22506 30.3 Use of $tls_cipher and $tls_peerdn
22507 ---------------------------------------
22508
22509 At the start of a run of the smtp transport, the values of $tls_bits,
22510 $tls_cipher, $tls_peerdn and $tls_sni are the values that were set when the
22511 message was received. These are the values that are used for options that are
22512 expanded before any SMTP connections are made. Just before each connection is
22513 made, these four variables are emptied. If TLS is subsequently started, they
22514 are set to the appropriate values for the outgoing connection, and these are
22515 the values that are in force when any authenticators are run and when the
22516 authenticated_sender option is expanded.
22517
22518 These variables are deprecated in favour of $tls_in_cipher et. al. and will be
22519 removed in a future release.
22520
22521
22522 30.4 Private options for smtp
22523 -----------------------------
22524
22525 The private options of the smtp transport are as follows:
22526
22527 +------------------------------------------------------------------+
22528 |address_retry_include_sender|Use: smtp|Type: boolean|Default: true|
22529 +------------------------------------------------------------------+
22530
22531 When an address is delayed because of a 4xx response to a RCPT command, it is
22532 the combination of sender and recipient that is delayed in subsequent queue
22533 runs until the retry time is reached. You can delay the recipient without
22534 reference to the sender (which is what earlier versions of Exim did), by
22535 setting address_retry_include_sender false. However, this can lead to problems
22536 with servers that regularly issue 4xx responses to RCPT commands.
22537
22538 +------------------------------------------------------+
22539 |allow_localhost|Use: smtp|Type: boolean|Default: false|
22540 +------------------------------------------------------+
22541
22542 When a host specified in hosts or fallback_hosts (see below) turns out to be
22543 the local host, or is listed in hosts_treat_as_local, delivery is deferred by
22544 default. However, if allow_localhost is set, Exim goes on to do the delivery
22545 anyway. This should be used only in special cases when the configuration
22546 ensures that no looping will result (for example, a differently configured Exim
22547 is listening on the port to which the message is sent).
22548
22549 +-----------------------------------------------------------+
22550 |authenticated_sender|Use: smtp|Type: string*|Default: unset|
22551 +-----------------------------------------------------------+
22552
22553 When Exim has authenticated as a client, or if authenticated_sender_force is
22554 true, this option sets a value for the AUTH= item on outgoing MAIL commands,
22555 overriding any existing authenticated sender value. If the string expansion is
22556 forced to fail, the option is ignored. Other expansion failures cause delivery
22557 to be deferred. If the result of expansion is an empty string, that is also
22558 ignored.
22559
22560 The expansion happens after the outgoing connection has been made and TLS
22561 started, if required. This means that the $host, $host_address, $tls_out_cipher
22562 , and $tls_out_peerdn variables are set according to the particular connection.
22563
22564 If the SMTP session is not authenticated, the expansion of authenticated_sender
22565 still happens (and can cause the delivery to be deferred if it fails), but no
22566 AUTH= item is added to MAIL commands unless authenticated_sender_force is true.
22567
22568 This option allows you to use the smtp transport in LMTP mode to deliver mail
22569 to Cyrus IMAP and provide the proper local part as the "authenticated sender",
22570 via a setting such as:
22571
22572 authenticated_sender = $local_part
22573
22574 This removes the need for IMAP subfolders to be assigned special ACLs to allow
22575 direct delivery to those subfolders.
22576
22577 Because of expected uses such as that just described for Cyrus (when no domain
22578 is involved), there is no checking on the syntax of the provided value.
22579
22580 +-----------------------------------------------------------------+
22581 |authenticated_sender_force|Use: smtp|Type: boolean|Default: false|
22582 +-----------------------------------------------------------------+
22583
22584 If this option is set true, the authenticated_sender option's value is used for
22585 the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as
22586 a client.
22587
22588 +------------------------------------------------+
22589 |command_timeout|Use: smtp|Type: time|Default: 5m|
22590 +------------------------------------------------+
22591
22592 This sets a timeout for receiving a response to an SMTP command that has been
22593 sent out. It is also used when waiting for the initial banner line from the
22594 remote host. Its value must not be zero.
22595
22596 +------------------------------------------------+
22597 |connect_timeout|Use: smtp|Type: time|Default: 5m|
22598 +------------------------------------------------+
22599
22600 This sets a timeout for the connect() function, which sets up a TCP/IP call to
22601 a remote host. A setting of zero allows the system timeout (typically several
22602 minutes) to act. To have any effect, the value of this option must be less than
22603 the system timeout. However, it has been observed that on some systems there is
22604 no system timeout, which is why the default value for this option is 5 minutes,
22605 a value recommended by RFC 1123.
22606
22607 +------------------------------------------------------------+
22608 |connection_max_messages|Use: smtp|Type: integer|Default: 500|
22609 +------------------------------------------------------------+
22610
22611 This controls the maximum number of separate message deliveries that are sent
22612 over a single TCP/IP connection. If the value is zero, there is no limit. For
22613 testing purposes, this value can be overridden by the -oB command line option.
22614
22615 +---------------------------------------------------------------+
22616 |dane_require_tls_ciphers|Use: smtp|Type: string*|Default: unset|
22617 +---------------------------------------------------------------+
22618
22619 This option may be used to override tls_require_ciphers for connections where
22620 DANE has been determined to be in effect. If not set, then tls_require_ciphers
22621 will be used. Normal SMTP delivery is not able to make strong demands of TLS
22622 cipher configuration, because delivery will fall back to plaintext. Once DANE
22623 has been determined to be in effect, there is no plaintext fallback and making
22624 the TLS cipherlist configuration stronger will increase security, rather than
22625 counter-intuitively decreasing it. If the option expands to be empty or is
22626 forced to fail, then it will be treated as unset and tls_require_ciphers will
22627 be used instead.
22628
22629 +---------------------------------------------+
22630 |data_timeout|Use: smtp|Type: time|Default: 5m|
22631 +---------------------------------------------+
22632
22633 This sets a timeout for the transmission of each block in the data portion of
22634 the message. As a result, the overall timeout for a message depends on the size
22635 of the message. Its value must not be zero. See also final_timeout.
22636
22637 +-------------------------------------------------+
22638 |dkim_canon|Use: smtp|Type: string*|Default: unset|
22639 +-------------------------------------------------+
22640
22641 +-------------------------------------------------+
22642 |dkim_domain|Use: smtp|Type: string|Default: list*|
22643 +-------------------------------------------------+
22644
22645 +-------------------------------------------------+
22646 |dkim_hash|Use: smtp|Type: string*|Default: sha256|
22647 +-------------------------------------------------+
22648
22649 +----------------------------------------------------+
22650 |dkim_identity|Use: smtp|Type: string*|Default: unset|
22651 +----------------------------------------------------+
22652
22653 +-------------------------------------------------------+
22654 |dkim_private_key|Use: smtp|Type: string*|Default: unset|
22655 +-------------------------------------------------------+
22656
22657 +----------------------------------------------------+
22658 |dkim_selector|Use: smtp|Type: string*|Default: unset|
22659 +----------------------------------------------------+
22660
22661 +--------------------------------------------------+
22662 |dkim_strict|Use: smtp|Type: string*|Default: unset|
22663 +--------------------------------------------------+
22664
22665 +----------------------------------------------------------+
22666 |dkim_sign_headers|Use: smtp|Type: string*|Default: per RFC|
22667 +----------------------------------------------------------+
22668
22669 +------------------------------------------------------+
22670 |dkim_timestamps|Use: smtp|Type: string*|Default: unset|
22671 +------------------------------------------------------+
22672
22673 DKIM signing options. For details see section 57.2.
22674
22675 +--------------------------------------------------------+
22676 |delay_after_cutoff|Use: smtp|Type: boolean|Default: true|
22677 +--------------------------------------------------------+
22678
22679 This option controls what happens when all remote IP addresses for a given
22680 domain have been inaccessible for so long that they have passed their retry
22681 cutoff times.
22682
22683 In the default state, if the next retry time has not been reached for any of
22684 them, the address is bounced without trying any deliveries. In other words,
22685 Exim delays retrying an IP address after the final cutoff time until a new
22686 retry time is reached, and can therefore bounce an address without ever trying
22687 a delivery, when machines have been down for a long time. Some people are
22688 unhappy at this prospect, so...
22689
22690 If delay_after_cutoff is set false, Exim behaves differently. If all IP
22691 addresses are past their final cutoff time, Exim tries to deliver to those IP
22692 addresses that have not been tried since the message arrived. If there are
22693 none, of if they all fail, the address is bounced. In other words, it does not
22694 delay when a new message arrives, but immediately tries those expired IP
22695 addresses that haven't been tried since the message arrived. If there is a
22696 continuous stream of messages for the dead hosts, unsetting delay_after_cutoff
22697 means that there will be many more attempts to deliver to them.
22698
22699 +--------------------------------------------------------+
22700 |dns_qualify_single|Use: smtp|Type: boolean|Default: true|
22701 +--------------------------------------------------------+
22702
22703 If the hosts or fallback_hosts option is being used, and the gethostbyname
22704 option is false, the RES_DEFNAMES resolver option is set. See the
22705 qualify_single option in chapter 17 for more details.
22706
22707 +---------------------------------------------------------+
22708 |dns_search_parents|Use: smtp|Type: boolean|Default: false|
22709 +---------------------------------------------------------+
22710
22711 If the hosts or fallback_hosts option is being used, and the gethostbyname
22712 option is false, the RES_DNSRCH resolver option is set. See the search_parents
22713 option in chapter 17 for more details.
22714
22715 +------------------------------------------------------------------+
22716 |dnssec_request_domains|Use: smtp|Type: domain list*|Default: unset|
22717 +------------------------------------------------------------------+
22718
22719 DNS lookups for domains matching dnssec_request_domains will be done with the
22720 dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup
22721 sequence.
22722
22723 +------------------------------------------------------------------+
22724 |dnssec_require_domains|Use: smtp|Type: domain list*|Default: unset|
22725 +------------------------------------------------------------------+
22726
22727 DNS lookups for domains matching dnssec_require_domains will be done with the
22728 dnssec request bit set. Any returns not having the Authenticated Data bit (AD
22729 bit) set will be ignored and logged as a host-lookup failure. This applies to
22730 all of the SRV, MX, AAAA, A lookup sequence.
22731
22732 +-------------------------------------------+
22733 |dscp|Use: smtp|Type: string*|Default: unset|
22734 +-------------------------------------------+
22735
22736 This option causes the DSCP value associated with a socket to be set to one of
22737 a number of fixed strings or to numeric value. The -bI:dscp option may be used
22738 to ask Exim which names it knows of. Common values include "throughput",
22739 "mincost", and on newer systems "ef", "af41", etc. Numeric values may be in the
22740 range 0 to 0x3F.
22741
22742 The outbound packets from Exim will be marked with this value in the header
22743 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee
22744 that these values will have any effect, not be stripped by networking
22745 equipment, or do much of anything without cooperation with your Network
22746 Engineer and those of all network operators between the source and destination.
22747
22748 +---------------------------------------------------------+
22749 |fallback_hosts|Use: smtp|Type: string list|Default: unset|
22750 +---------------------------------------------------------+
22751
22752 String expansion is not applied to this option. The argument must be a
22753 colon-separated list of host names or IP addresses, optionally also including
22754 port numbers, though the separator can be changed, as described in section 6.20
22755 . Each individual item in the list is the same as an item in a route_list
22756 setting for the manualroute router, as described in section 20.5.
22757
22758 Fallback hosts can also be specified on routers, which associate them with the
22759 addresses they process. As for the hosts option without hosts_override,
22760 fallback_hosts specified on the transport is used only if the address does not
22761 have its own associated fallback host list. Unlike hosts, a setting of
22762 fallback_hosts on an address is not overridden by hosts_override. However,
22763 hosts_randomize does apply to fallback host lists.
22764
22765 If Exim is unable to deliver to any of the hosts for a particular address, and
22766 the errors are not permanent rejections, the address is put on a separate
22767 transport queue with its host list replaced by the fallback hosts, unless the
22768 address was routed via MX records and the current host was in the original MX
22769 list. In that situation, the fallback host list is not used.
22770
22771 Once normal deliveries are complete, the fallback queue is delivered by
22772 re-running the same transports with the new host lists. If several failing
22773 addresses have the same fallback hosts (and max_rcpt permits it), a single copy
22774 of the message is sent.
22775
22776 The resolution of the host names on the fallback list is controlled by the
22777 gethostbyname option, as for the hosts option. Fallback hosts apply both to
22778 cases when the host list comes with the address and when it is taken from hosts
22779 . This option provides a "use a smart host only if delivery fails" facility.
22780
22781 +-----------------------------------------------+
22782 |final_timeout|Use: smtp|Type: time|Default: 10m|
22783 +-----------------------------------------------+
22784
22785 This is the timeout that applies while waiting for the response to the final
22786 line containing just "." that terminates a message. Its value must not be zero.
22787
22788 +----------------------------------------------------+
22789 |gethostbyname|Use: smtp|Type: boolean|Default: false|
22790 +----------------------------------------------------+
22791
22792 If this option is true when the hosts and/or fallback_hosts options are being
22793 used, names are looked up using gethostbyname() (or getipnodebyname() when
22794 available) instead of using the DNS. Of course, that function may in fact use
22795 the DNS, but it may also consult other sources of information such as /etc/
22796 hosts.
22797
22798 +---------------------------------------------------------+
22799 |gnutls_compat_mode|Use: smtp|Type: boolean|Default: unset|
22800 +---------------------------------------------------------+
22801
22802 This option controls whether GnuTLS is used in compatibility mode in an Exim
22803 server. This reduces security slightly, but improves interworking with older
22804 implementations of TLS.
22805
22806 +----------------------------------------------------+
22807 |helo_data|Use: smtp|Type: string*|Default: see below|
22808 +----------------------------------------------------+
22809
22810 The value of this option is expanded after a connection to a another host has
22811 been set up. The result is used as the argument for the EHLO, HELO, or LHLO
22812 command that starts the outgoing SMTP or LMTP session. The default value of the
22813 option is:
22814
22815 $primary_hostname
22816
22817 During the expansion, the variables $host and $host_address are set to the
22818 identity of the remote host, and the variables $sending_ip_address and
22819 $sending_port are set to the local IP address and port number that are being
22820 used. These variables can be used to generate different values for different
22821 servers or different local IP addresses. For example, if you want the string
22822 that is used for helo_data to be obtained by a DNS lookup of the outgoing
22823 interface address, you could use this:
22824
22825 helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
22826 {$primary_hostname}}
22827
22828 The use of helo_data applies both to sending messages and when doing callouts.
22829
22830 +-------------------------------------------------+
22831 |hosts|Use: smtp|Type: string list*|Default: unset|
22832 +-------------------------------------------------+
22833
22834 Hosts are associated with an address by a router such as dnslookup, which finds
22835 the hosts by looking up the address domain in the DNS, or by manualroute, which
22836 has lists of hosts in its configuration. However, email addresses can be passed
22837 to the smtp transport by any router, and not all of them can provide an
22838 associated list of hosts.
22839
22840 The hosts option specifies a list of hosts to be used if the address being
22841 processed does not have any hosts associated with it. The hosts specified by
22842 hosts are also used, whether or not the address has its own hosts, if
22843 hosts_override is set.
22844
22845 The string is first expanded, before being interpreted as a colon-separated
22846 list of host names or IP addresses, possibly including port numbers. The
22847 separator may be changed to something other than colon, as described in section
22848 6.20. Each individual item in the list is the same as an item in a route_list
22849 setting for the manualroute router, as described in section 20.5. However, note
22850 that the "/MX" facility of the manualroute router is not available here.
22851
22852 If the expansion fails, delivery is deferred. Unless the failure was caused by
22853 the inability to complete a lookup, the error is logged to the panic log as
22854 well as the main log. Host names are looked up either by searching directly for
22855 address records in the DNS or by calling gethostbyname() (or getipnodebyname()
22856 when available), depending on the setting of the gethostbyname option. When
22857 Exim is compiled with IPv6 support, if a host that is looked up in the DNS has
22858 both IPv4 and IPv6 addresses, both types of address are used.
22859
22860 During delivery, the hosts are tried in order, subject to their retry status,
22861 unless hosts_randomize is set.
22862
22863 +-----------------------------------------------------------+
22864 |hosts_avoid_esmtp|Use: smtp|Type: host list*|Default: unset|
22865 +-----------------------------------------------------------+
22866
22867 This option is for use with broken hosts that announce ESMTP facilities (for
22868 example, PIPELINING) and then fail to implement them properly. When a host
22869 matches hosts_avoid_esmtp, Exim sends HELO rather than EHLO at the start of the
22870 SMTP session. This means that it cannot use any of the ESMTP facilities such as
22871 AUTH, PIPELINING, SIZE, and STARTTLS.
22872
22873 +----------------------------------------------------------------+
22874 |hosts_avoid_pipelining|Use: smtp|Type: host list*|Default: unset|
22875 +----------------------------------------------------------------+
22876
22877 Exim will not use the SMTP PIPELINING extension when delivering to any host
22878 that matches this list, even if the server host advertises PIPELINING support.
22879
22880 +---------------------------------------------------------+
22881 |hosts_avoid_tls|Use: smtp|Type: host list*|Default: unset|
22882 +---------------------------------------------------------+
22883
22884 Exim will not try to start a TLS session when delivering to any host that
22885 matches this list. See chapter 42 for details of TLS.
22886
22887 +----------------------------------------------------------------+
22888 |hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: unset|
22889 +----------------------------------------------------------------+
22890
22891 Exim will not try to start a TLS session for a verify callout, or when
22892 delivering in cutthrough mode, to any host that matches this list.
22893
22894 +------------------------------------------------+
22895 |hosts_max_try|Use: smtp|Type: integer|Default: 5|
22896 +------------------------------------------------+
22897
22898 This option limits the number of IP addresses that are tried for any one
22899 delivery in cases where there are temporary delivery errors. Section 30.5
22900 describes in detail how the value of this option is used.
22901
22902 +-----------------------------------------------------------+
22903 |hosts_max_try_hardlimit|Use: smtp|Type: integer|Default: 50|
22904 +-----------------------------------------------------------+
22905
22906 This is an additional check on the maximum number of IP addresses that Exim
22907 tries for any one delivery. Section 30.5 describes its use and why it exists.
22908
22909 +----------------------------------------------------------+
22910 |hosts_nopass_tls|Use: smtp|Type: host list*|Default: unset|
22911 +----------------------------------------------------------+
22912
22913 For any host that matches this list, a connection on which a TLS session has
22914 been started will not be passed to a new delivery process for sending another
22915 message on the same connection. See section 42.11 for an explanation of when
22916 this might be needed.
22917
22918 +-------------------------------------------------------+
22919 |hosts_noproxy_tls|Use: smtp|Type: host list*|Default: *|
22920 +-------------------------------------------------------+
22921
22922 For any host that matches this list, a TLS session which has been started will
22923 not be passed to a new delivery process for sending another message on the same
22924 session.
22925
22926 The traditional implementation closes down TLS and re-starts it in the new
22927 process, on the same open TCP connection, for each successive message sent. If
22928 permitted by this option a pipe to to the new process is set up instead, and
22929 the original process maintains the TLS connection and proxies the SMTP
22930 connection from and to the new process and any subsequents. The new process has
22931 no access to TLS information, so cannot include it in logging.
22932
22933 +-----------------------------------------------------+
22934 |hosts_override|Use: smtp|Type: boolean|Default: false|
22935 +-----------------------------------------------------+
22936
22937 If this option is set and the hosts option is also set, any hosts that are
22938 attached to the address are ignored, and instead the hosts specified by the
22939 hosts option are always used. This option does not apply to fallback_hosts.
22940
22941 +------------------------------------------------------+
22942 |hosts_randomize|Use: smtp|Type: boolean|Default: false|
22943 +------------------------------------------------------+
22944
22945 If this option is set, and either the list of hosts is taken from the hosts or
22946 the fallback_hosts option, or the hosts supplied by the router were not
22947 obtained from MX records (this includes fallback hosts from the router), and
22948 were not randomized by the router, the order of trying the hosts is randomized
22949 each time the transport runs. Randomizing the order of a host list can be used
22950 to do crude load sharing.
22951
22952 When hosts_randomize is true, a host list may be split into groups whose order
22953 is separately randomized. This makes it possible to set up MX-like behaviour.
22954 The boundaries between groups are indicated by an item that is just "+" in the
22955 host list. For example:
22956
22957 hosts = host1:host2:host3:+:host4:host5
22958
22959 The order of the first three hosts and the order of the last two hosts is
22960 randomized for each use, but the first three always end up before the last two.
22961 If hosts_randomize is not set, a "+" item in the list is ignored.
22962
22963 +------------------------------------------------------------+
22964 |hosts_require_auth|Use: smtp|Type: host list*|Default: unset|
22965 +------------------------------------------------------------+
22966
22967 This option provides a list of servers for which authentication must succeed
22968 before Exim will try to transfer a message. If authentication fails for servers
22969 which are not in this list, Exim tries to send unauthenticated. If
22970 authentication fails for one of these servers, delivery is deferred. This
22971 temporary error is detectable in the retry rules, so it can be turned into a
22972 hard failure if required. See also hosts_try_auth, and chapter 33 for details
22973 of authentication.
22974
22975 +--------------------------------------------------------+
22976 |hosts_request_ocsp|Use: smtp|Type: host list*|Default: *|
22977 +--------------------------------------------------------+
22978
22979 Exim will request a Certificate Status on a TLS session for any host that
22980 matches this list. tls_verify_certificates should also be set for the
22981 transport.
22982
22983 +------------------------------------------------------------+
22984 |hosts_require_dane|Use: smtp|Type: host list*|Default: unset|
22985 +------------------------------------------------------------+
22986
22987 If built with DANE support, Exim will require that a DNSSEC-validated TLSA
22988 record is present for any host matching the list, and that a DANE-verified TLS
22989 connection is made. There will be no fallback to in-clear communication. See
22990 section 42.15.
22991
22992 +------------------------------------------------------------+
22993 |hosts_require_ocsp|Use: smtp|Type: host list*|Default: unset|
22994 +------------------------------------------------------------+
22995
22996 Exim will request, and check for a valid Certificate Status being given, on a
22997 TLS session for any host that matches this list. tls_verify_certificates should
22998 also be set for the transport.
22999
23000 +-----------------------------------------------------------+
23001 |hosts_require_tls|Use: smtp|Type: host list*|Default: unset|
23002 +-----------------------------------------------------------+
23003
23004 Exim will insist on using a TLS session when delivering to any host that
23005 matches this list. See chapter 42 for details of TLS. Note: This option affects
23006 outgoing mail only. To insist on TLS for incoming messages, use an appropriate
23007 ACL.
23008
23009 +--------------------------------------------------------+
23010 |hosts_try_auth|Use: smtp|Type: host list*|Default: unset|
23011 +--------------------------------------------------------+
23012
23013 This option provides a list of servers to which, provided they announce
23014 authentication support, Exim will attempt to authenticate as a client when it
23015 connects. If authentication fails, Exim will try to transfer the message
23016 unauthenticated. See also hosts_require_auth, and chapter 33 for details of
23017 authentication.
23018
23019 +--------------------------------------------------------+
23020 |hosts_try_chunking|Use: smtp|Type: host list*|Default: *|
23021 +--------------------------------------------------------+
23022
23023 This option provides a list of servers to which, provided they announce
23024 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA. BDAT
23025 will not be used in conjunction with a transport filter.
23026
23027 +--------------------------------------------------------+
23028 |hosts_try_dane|Use: smtp|Type: host list*|Default: unset|
23029 +--------------------------------------------------------+
23030
23031 If built with DANE support, Exim will lookup a TLSA record for any host
23032 matching the list. If found and verified by DNSSEC, a DANE-verified TLS
23033 connection is made to that host; there will be no fallback to in-clear
23034 communication. See section 42.15.
23035
23036 +------------------------------------------------------------+
23037 |hosts_try_fastopen|Use: smtp|Type: host list*|Default: unset|
23038 +------------------------------------------------------------+
23039
23040 This option provides a list of servers to which, provided the facility is
23041 supported by this system, Exim will attempt to perform a TCP Fast Open. No data
23042 is sent on the SYN segment but, if the remote server also supports the
23043 facility, it can send its SMTP banner immediately after the SYN,ACK segment.
23044 This can save up to one round-trip time.
23045
23046 The facility is only active for previously-contacted servers, as the initiator
23047 must present a cookie in the SYN segment.
23048
23049 On (at least some) current Linux distributions the facility must be enabled in
23050 the kernel by the sysadmin before the support is usable. There is no option for
23051 control of the server side; if the system supports it it is always enabled.
23052 Note that lengthy operations in the connect ACL, such as DNSBL lookups, will
23053 still delay the emission of the SMTP banner.
23054
23055 +----------------------------------------------------+
23056 |hosts_try_prdr|Use: smtp|Type: host list*|Default: *|
23057 +----------------------------------------------------+
23058
23059 This option provides a list of servers to which, provided they announce PRDR
23060 support, Exim will attempt to negotiate PRDR for multi-recipient messages. The
23061 option can usually be left as default.
23062
23063 +-----------------------------------------------------+
23064 |interface|Use: smtp|Type: string list*|Default: unset|
23065 +-----------------------------------------------------+
23066
23067 This option specifies which interface to bind to when making an outgoing SMTP
23068 call. The value is an IP address, not an interface name such as "eth0". Do not
23069 confuse this with the interface address that was used when a message was
23070 received, which is in $received_ip_address, formerly known as
23071 $interface_address. The name was changed to minimize confusion with the
23072 outgoing interface address. There is no variable that contains an outgoing
23073 interface address because, unless it is set by this option, its value is
23074 unknown.
23075
23076 During the expansion of the interface option the variables $host and
23077 $host_address refer to the host to which a connection is about to be made
23078 during the expansion of the string. Forced expansion failure, or an empty
23079 string result causes the option to be ignored. Otherwise, after expansion, the
23080 string must be a list of IP addresses, colon-separated by default, but the
23081 separator can be changed in the usual way (6.21). For example:
23082
23083 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
23084
23085 The first interface of the correct type (IPv4 or IPv6) is used for the outgoing
23086 connection. If none of them are the correct type, the option is ignored. If
23087 interface is not set, or is ignored, the system's IP functions choose which
23088 interface to use if the host has more than one.
23089
23090 +-----------------------------------------------+
23091 |keepalive|Use: smtp|Type: boolean|Default: true|
23092 +-----------------------------------------------+
23093
23094 This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket
23095 connections. When set, it causes the kernel to probe idle connections
23096 periodically, by sending packets with "old" sequence numbers. The other end of
23097 the connection should send a acknowledgment if the connection is still okay or
23098 a reset if the connection has been aborted. The reason for doing this is that
23099 it has the beneficial effect of freeing up certain types of connection that can
23100 get stuck when the remote host is disconnected without tidying up the TCP/IP
23101 call properly. The keepalive mechanism takes several hours to detect
23102 unreachable hosts.
23103
23104 +--------------------------------------------------------+
23105 |lmtp_ignore_quota|Use: smtp|Type: boolean|Default: false|
23106 +--------------------------------------------------------+
23107
23108 If this option is set true when the protocol option is set to "lmtp", the
23109 string "IGNOREQUOTA" is added to RCPT commands, provided that the LMTP server
23110 has advertised support for IGNOREQUOTA in its response to the LHLO command.
23111
23112 +---------------------------------------------+
23113 |max_rcpt|Use: smtp|Type: integer|Default: 100|
23114 +---------------------------------------------+
23115
23116 This option limits the number of RCPT commands that are sent in a single SMTP
23117 message transaction. Each set of addresses is treated independently, and so can
23118 cause parallel connections to the same host if remote_max_parallel permits
23119 this.
23120
23121 +---------------------------------------------------+
23122 |multi_domain|Use: smtp|Type: boolean*|Default: true|
23123 +---------------------------------------------------+
23124
23125 When this option is set, the smtp transport can handle a number of addresses
23126 containing a mixture of different domains provided they all resolve to the same
23127 list of hosts. Turning the option off restricts the transport to handling only
23128 one domain at a time. This is useful if you want to use $domain in an expansion
23129 for the transport, because it is set only when there is a single domain
23130 involved in a remote delivery.
23131
23132 It is expanded per-address and can depend on any of $address_data, $domain_data
23133 , $local_part_data, $host, $host_address and $host_port.
23134
23135 +-----------------------------------------------+
23136 |port|Use: smtp|Type: string*|Default: see below|
23137 +-----------------------------------------------+
23138
23139 This option specifies the TCP/IP port on the server to which Exim connects.
23140 Note: Do not confuse this with the port that was used when a message was
23141 received, which is in $received_port, formerly known as $interface_port. The
23142 name was changed to minimize confusion with the outgoing port. There is no
23143 variable that contains an outgoing port.
23144
23145 If the value of this option begins with a digit it is taken as a port number;
23146 otherwise it is looked up using getservbyname(). The default value is normally
23147 "smtp", but if protocol is set to "lmtp" the default is "lmtp" and if protocol
23148 is set to "smtps" the default is "smtps". If the expansion fails, or if a port
23149 number cannot be found, delivery is deferred.
23150
23151 Note that at least one Linux distribution has been seen failing to put "smtps"
23152 in its "/etc/services" file, resulting is such deferrals.
23153
23154 +---------------------------------------------+
23155 |protocol|Use: smtp|Type: string|Default: smtp|
23156 +---------------------------------------------+
23157
23158 If this option is set to "lmtp" instead of "smtp", the default value for the
23159 port option changes to "lmtp", and the transport operates the LMTP protocol
23160 (RFC 2033) instead of SMTP. This protocol is sometimes used for local
23161 deliveries into closed message stores. Exim also has support for running LMTP
23162 over a pipe to a local process - see chapter 28.
23163
23164 If this option is set to "smtps", the default value for the port option changes
23165 to "smtps", and the transport initiates TLS immediately after connecting, as an
23166 outbound SSL-on-connect, instead of using STARTTLS to upgrade.
23167
23168 The Internet standards bodies used to strongly discourage use of this mode, but
23169 as of RFC 8314 it is perferred over STARTTLS for message submission (as
23170 distinct from MTA-MTA communication).
23171
23172 +---------------------------------------------------------------+
23173 |retry_include_ip_address|Use: smtp|Type: boolean*|Default: true|
23174 +---------------------------------------------------------------+
23175
23176 Exim normally includes both the host name and the IP address in the key it
23177 constructs for indexing retry data after a temporary delivery failure. This
23178 means that when one of several IP addresses for a host is failing, it gets
23179 tried periodically (controlled by the retry rules), but use of the other IP
23180 addresses is not affected.
23181
23182 However, in some dialup environments hosts are assigned a different IP address
23183 each time they connect. In this situation the use of the IP address as part of
23184 the retry key leads to undesirable behaviour. Setting this option false causes
23185 Exim to use only the host name. Since it is expanded it can be made to depend
23186 on the host or domain.
23187
23188 +---------------------------------------------------------+
23189 |serialize_hosts|Use: smtp|Type: host list*|Default: unset|
23190 +---------------------------------------------------------+
23191
23192 Because Exim operates in a distributed manner, if several messages for the same
23193 host arrive at around the same time, more than one simultaneous connection to
23194 the remote host can occur. This is not usually a problem except when there is a
23195 slow link between the hosts. In that situation it may be helpful to restrict
23196 Exim to one connection at a time. This can be done by setting serialize_hosts
23197 to match the relevant hosts.
23198
23199 Exim implements serialization by means of a hints database in which a record is
23200 written whenever a process connects to one of the restricted hosts. The record
23201 is deleted when the connection is completed. Obviously there is scope for
23202 records to get left lying around if there is a system or program crash. To
23203 guard against this, Exim ignores any records that are more than six hours old.
23204
23205 If you set up this kind of serialization, you should also arrange to delete the
23206 relevant hints database whenever your system reboots. The names of the files
23207 start with misc and they are kept in the spool/db directory. There may be one
23208 or two files, depending on the type of DBM in use. The same files are used for
23209 ETRN serialization.
23210
23211 See also the max_parallel generic transport option.
23212
23213 +---------------------------------------------------+
23214 |size_addition|Use: smtp|Type: integer|Default: 1024|
23215 +---------------------------------------------------+
23216
23217 If a remote SMTP server indicates that it supports the SIZE option of the MAIL
23218 command, Exim uses this to pass over the message size at the start of an SMTP
23219 transaction. It adds the value of size_addition to the value it sends, to allow
23220 for headers and other text that may be added during delivery by configuration
23221 options or in a transport filter. It may be necessary to increase this if a lot
23222 of text is added to messages.
23223
23224 Alternatively, if the value of size_addition is set negative, it disables the
23225 use of the SIZE option altogether.
23226
23227 +--------------------------------------------------+
23228 |socks_proxy|Use: smtp|Type: string*|Default: unset|
23229 +--------------------------------------------------+
23230
23231 This option enables use of SOCKS proxies for connections made by the transport.
23232 For details see section 58.2.
23233
23234 +------------------------------------------------------+
23235 |tls_certificate|Use: smtp|Type: string*|Default: unset|
23236 +------------------------------------------------------+
23237
23238 The value of this option must be the absolute path to a file which contains the
23239 client's certificate, for possible use when sending a message over an encrypted
23240 connection. The values of $host and $host_address are set to the name and
23241 address of the server during the expansion. See chapter 42 for details of TLS.
23242
23243 Note: This option must be set if you want Exim to be able to use a TLS
23244 certificate when sending messages as a client. The global option of the same
23245 name specifies the certificate for Exim as a server; it is not automatically
23246 assumed that the same certificate should be used when Exim is operating as a
23247 client.
23248
23249 +----------------------------------------------+
23250 |tls_crl|Use: smtp|Type: string*|Default: unset|
23251 +----------------------------------------------+
23252
23253 This option specifies a certificate revocation list. The expanded value must be
23254 the name of a file that contains a CRL in PEM format.
23255
23256 +-----------------------------------------------------+
23257 |tls_dh_min_bits|Use: smtp|Type: integer|Default: 1024|
23258 +-----------------------------------------------------+
23259
23260 When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman key
23261 agreement is negotiated, the server will provide a large prime number for use.
23262 This option establishes the minimum acceptable size of that number. If the
23263 parameter offered by the server is too small, then the TLS handshake will fail.
23264
23265 Only supported when using GnuTLS.
23266
23267 +-----------------------------------------------------+
23268 |tls_privatekey|Use: smtp|Type: string*|Default: unset|
23269 +-----------------------------------------------------+
23270
23271 The value of this option must be the absolute path to a file which contains the
23272 client's private key. This is used when sending a message over an encrypted
23273 connection using a client certificate. The values of $host and $host_address
23274 are set to the name and address of the server during the expansion. If this
23275 option is unset, or the expansion is forced to fail, or the result is an empty
23276 string, the private key is assumed to be in the same file as the certificate.
23277 See chapter 42 for details of TLS.
23278
23279 +----------------------------------------------------------+
23280 |tls_require_ciphers|Use: smtp|Type: string*|Default: unset|
23281 +----------------------------------------------------------+
23282
23283 The value of this option must be a list of permitted cipher suites, for use
23284 when setting up an outgoing encrypted connection. (There is a global option of
23285 the same name for controlling incoming connections.) The values of $host and
23286 $host_address are set to the name and address of the server during the
23287 expansion. See chapter 42 for details of TLS; note that this option is used in
23288 different ways by OpenSSL and GnuTLS (see sections 42.4 and 42.5). For GnuTLS,
23289 the order of the ciphers is a preference order.
23290
23291 +----------------------------------------------+
23292 |tls_sni|Use: smtp|Type: string*|Default: unset|
23293 +----------------------------------------------+
23294
23295 If this option is set then it sets the $tls_out_sni variable and causes any TLS
23296 session to pass this value as the Server Name Indication extension to the
23297 remote side, which can be used by the remote side to select an appropriate
23298 certificate and private key for the session.
23299
23300 See 42.10 for more information.
23301
23302 Note that for OpenSSL, this feature requires a build of OpenSSL that supports
23303 TLS extensions.
23304
23305 +-----------------------------------------------------------+
23306 |tls_tempfail_tryclear|Use: smtp|Type: boolean|Default: true|
23307 +-----------------------------------------------------------+
23308
23309 When the server host is not in hosts_require_tls, and there is a problem in
23310 setting up a TLS session, this option determines whether or not Exim should try
23311 to deliver the message unencrypted. If it is set false, delivery to the current
23312 host is deferred; if there are other hosts, they are tried. If this option is
23313 set true, Exim attempts to deliver unencrypted after a 4xx response to
23314 STARTTLS. Also, if STARTTLS is accepted, but the subsequent TLS negotiation
23315 fails, Exim closes the current connection (because it is in an unknown state),
23316 opens a new one to the same host, and then tries the delivery in clear.
23317
23318 +----------------------------------------------------------+
23319 |tls_try_verify_hosts|Use: smtp|Type: host list*|Default: *|
23320 +----------------------------------------------------------+
23321
23322 This option gives a list of hosts for which, on encrypted connections,
23323 certificate verification will be tried but need not succeed. The
23324 tls_verify_certificates option must also be set. Note that unless the host is
23325 in this list TLS connections will be denied to hosts using self-signed
23326 certificates when tls_verify_certificates is matched. The
23327 $tls_out_certificate_verified variable is set when certificate verification
23328 succeeds.
23329
23330 +---------------------------------------------------------------+
23331 |tls_verify_cert_hostnames|Use: smtp|Type: host list*|Default: *|
23332 +---------------------------------------------------------------+
23333
23334 This option give a list of hosts for which, while verifying the server
23335 certificate, checks will be included on the host name (note that this will
23336 generally be the result of a DNS MX lookup) versus Subject and
23337 Subject-Alternate-Name fields. Wildcard names are permitted limited to being
23338 the initial component of a 3-or-more component FQDN.
23339
23340 There is no equivalent checking on client certificates.
23341
23342 +---------------------------------------------------------------+
23343 |tls_verify_certificates|Use: smtp|Type: string*|Default: system|
23344 +---------------------------------------------------------------+
23345
23346 The value of this option must be either the word "system" or the absolute path
23347 to a file or directory containing permitted certificates for servers, for use
23348 when setting up an encrypted connection.
23349
23350 The "system" value for the option will use a location compiled into the SSL
23351 library. This is not available for GnuTLS versions preceding 3.0.20; a value of
23352 "system" is taken as empty and an explicit location must be specified.
23353
23354 The use of a directory for the option value is not available for GnuTLS
23355 versions preceding 3.3.6 and a single file must be used.
23356
23357 With OpenSSL the certificates specified explicitly either by file or directory
23358 are added to those given by the system default location.
23359
23360 The values of $host and $host_address are set to the name and address of the
23361 server during the expansion of this option. See chapter 42 for details of TLS.
23362
23363 For back-compatibility, if neither tls_verify_hosts nor tls_try_verify_hosts
23364 are set (a single-colon empty list counts as being set) and certificate
23365 verification fails the TLS connection is closed.
23366
23367 +----------------------------------------------------------+
23368 |tls_verify_hosts|Use: smtp|Type: host list*|Default: unset|
23369 +----------------------------------------------------------+
23370
23371 This option gives a list of hosts for which, on encrypted connections,
23372 certificate verification must succeed. The tls_verify_certificates option must
23373 also be set. If both this option and tls_try_verify_hosts are unset operation
23374 is as if this option selected all hosts.
23375
23376 +---------------------------------------------------------+
23377 |utf8_downconvert|Use: smtp|Type: integer!!|Default: unset|
23378 +---------------------------------------------------------+
23379
23380 If built with internationalization support, this option controls conversion of
23381 UTF-8 in message addresses to a-label form. For details see section 59.1.
23382
23383
23384 30.5 How the limits for the number of hosts to try are used
23385 -----------------------------------------------------------
23386
23387 There are two options that are concerned with the number of hosts that are
23388 tried when an SMTP delivery takes place. They are hosts_max_try and
23389 hosts_max_try_hardlimit.
23390
23391 The hosts_max_try option limits the number of hosts that are tried for a single
23392 delivery. However, despite the term "host" in its name, the option actually
23393 applies to each IP address independently. In other words, a multihomed host is
23394 treated as several independent hosts, just as it is for retrying.
23395
23396 Many of the larger ISPs have multiple MX records which often point to
23397 multihomed hosts. As a result, a list of a dozen or more IP addresses may be
23398 created as a result of routing one of these domains.
23399
23400 Trying every single IP address on such a long list does not seem sensible; if
23401 several at the top of the list fail, it is reasonable to assume there is some
23402 problem that is likely to affect all of them. Roughly speaking, the value of
23403 hosts_max_try is the maximum number that are tried before deferring the
23404 delivery. However, the logic cannot be quite that simple.
23405
23406 Firstly, IP addresses that are skipped because their retry times have not
23407 arrived do not count, and in addition, addresses that are past their retry
23408 limits are also not counted, even when they are tried. This means that when
23409 some IP addresses are past their retry limits, more than the value of
23410 hosts_max_retry may be tried. The reason for this behaviour is to ensure that
23411 all IP addresses are considered before timing out an email address (but see
23412 below for an exception).
23413
23414 Secondly, when the hosts_max_try limit is reached, Exim looks down the host
23415 list to see if there is a subsequent host with a different (higher valued) MX.
23416 If there is, that host is considered next, and the current IP address is used
23417 but not counted. This behaviour helps in the case of a domain with a retry rule
23418 that hardly ever delays any hosts, as is now explained:
23419
23420 Consider the case of a long list of hosts with one MX value, and a few with a
23421 higher MX value. If hosts_max_try is small (the default is 5) only a few hosts
23422 at the top of the list are tried at first. With the default retry rule, which
23423 specifies increasing retry times, the higher MX hosts are eventually tried when
23424 those at the top of the list are skipped because they have not reached their
23425 retry times.
23426
23427 However, it is common practice to put a fixed short retry time on domains for
23428 large ISPs, on the grounds that their servers are rarely down for very long.
23429 Unfortunately, these are exactly the domains that tend to resolve to long lists
23430 of hosts. The short retry time means that the lowest MX hosts are tried every
23431 time. The attempts may be in a different order because of random sorting, but
23432 without the special MX check, the higher MX hosts would never be tried until
23433 all the lower MX hosts had timed out (which might be several days), because
23434 there are always some lower MX hosts that have reached their retry times. With
23435 the special check, Exim considers at least one IP address from each MX value at
23436 every delivery attempt, even if the hosts_max_try limit has already been
23437 reached.
23438
23439 The above logic means that hosts_max_try is not a hard limit, and in
23440 particular, Exim normally eventually tries all the IP addresses before timing
23441 out an email address. When hosts_max_try was implemented, this seemed a
23442 reasonable thing to do. Recently, however, some lunatic DNS configurations have
23443 been set up with hundreds of IP addresses for some domains. It can take a very
23444 long time indeed for an address to time out in these cases.
23445
23446 The hosts_max_try_hardlimit option was added to help with this problem. Exim
23447 never tries more than this number of IP addresses; if it hits this limit and
23448 they are all timed out, the email address is bounced, even though not all
23449 possible IP addresses have been tried.
23450
23451
23452
23453 ===============================================================================
23454 31. ADDRESS REWRITING
23455
23456 There are some circumstances in which Exim automatically rewrites domains in
23457 addresses. The two most common are when an address is given without a domain
23458 (referred to as an "unqualified address") or when an address contains an
23459 abbreviated domain that is expanded by DNS lookup.
23460
23461 Unqualified envelope addresses are accepted only for locally submitted
23462 messages, or for messages that are received from hosts matching
23463 sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.
23464 Unqualified addresses in header lines are qualified if they are in locally
23465 submitted messages, or messages from hosts that are permitted to send
23466 unqualified envelope addresses. Otherwise, unqualified addresses in header
23467 lines are neither qualified nor rewritten.
23468
23469 One situation in which Exim does not automatically rewrite a domain is when it
23470 is the name of a CNAME record in the DNS. The older RFCs suggest that such a
23471 domain should be rewritten using the "canonical" name, and some MTAs do this.
23472 The new RFCs do not contain this suggestion.
23473
23474
23475 31.1 Explicitly configured address rewriting
23476 --------------------------------------------
23477
23478 This chapter describes the rewriting rules that can be used in the main rewrite
23479 section of the configuration file, and also in the generic headers_rewrite
23480 option that can be set on any transport.
23481
23482 Some people believe that configured address rewriting is a Mortal Sin. Others
23483 believe that life is not possible without it. Exim provides the facility; you
23484 do not have to use it.
23485
23486 The main rewriting rules that appear in the "rewrite" section of the
23487 configuration file are applied to addresses in incoming messages, both envelope
23488 addresses and addresses in header lines. Each rule specifies the types of
23489 address to which it applies.
23490
23491 Whether or not addresses in header lines are rewritten depends on the origin of
23492 the headers and the type of rewriting. Global rewriting, that is, rewriting
23493 rules from the rewrite section of the configuration file, is applied only to
23494 those headers that were received with the message. Header lines that are added
23495 by ACLs or by a system filter or by individual routers or transports (which are
23496 specific to individual recipient addresses) are not rewritten by the global
23497 rules.
23498
23499 Rewriting at transport time, by means of the headers_rewrite option, applies
23500 all headers except those added by routers and transports. That is, as well as
23501 the headers that were received with the message, it also applies to headers
23502 that were added by an ACL or a system filter.
23503
23504 In general, rewriting addresses from your own system or domain has some
23505 legitimacy. Rewriting other addresses should be done only with great care and
23506 in special circumstances. The author of Exim believes that rewriting should be
23507 used sparingly, and mainly for "regularizing" addresses in your own domains.
23508 Although it can sometimes be used as a routing tool, this is very strongly
23509 discouraged.
23510
23511 There are two commonly encountered circumstances where rewriting is used, as
23512 illustrated by these examples:
23513
23514 * The company whose domain is hitch.fict.example has a number of hosts that
23515 exchange mail with each other behind a firewall, but there is only a single
23516 gateway to the outer world. The gateway rewrites *.hitch.fict.example as
23517 hitch.fict.example when sending mail off-site.
23518
23519 * A host rewrites the local parts of its own users so that, for example,
23520 fp42@hitch.fict.example becomes Ford.Prefect@hitch.fict.example.
23521
23522
23523 31.2 When does rewriting happen?
23524 --------------------------------
23525
23526 Configured address rewriting can take place at several different stages of a
23527 message's processing.
23528
23529 At the start of an ACL for MAIL, the sender address may have been rewritten by
23530 a special SMTP-time rewrite rule (see section 31.9), but no ordinary rewrite
23531 rules have yet been applied. If, however, the sender address is verified in the
23532 ACL, it is rewritten before verification, and remains rewritten thereafter. The
23533 subsequent value of $sender_address is the rewritten address. This also applies
23534 if sender verification happens in a RCPT ACL. Otherwise, when the sender
23535 address is not verified, it is rewritten as soon as a message's header lines
23536 have been received.
23537
23538 Similarly, at the start of an ACL for RCPT, the current recipient's address may
23539 have been rewritten by a special SMTP-time rewrite rule, but no ordinary
23540 rewrite rules have yet been applied to it. However, the behaviour is different
23541 from the sender address when a recipient is verified. The address is rewritten
23542 for the verification, but the rewriting is not remembered at this stage. The
23543 value of $local_part and $domain after verification are always the same as they
23544 were before (that is, they contain the unrewritten - except for SMTP-time
23545 rewriting - address).
23546
23547 As soon as a message's header lines have been received, all the envelope
23548 recipient addresses are permanently rewritten, and rewriting is also applied to
23549 the addresses in the header lines (if configured). This happens before adding
23550 any header lines that were specified in MAIL or RCPT ACLs, and before the DATA
23551 ACL and local_scan() functions are run.
23552
23553 When an address is being routed, either for delivery or for verification,
23554 rewriting is applied immediately to child addresses that are generated by
23555 redirection, unless no_rewrite is set on the router.
23556
23557 At transport time, additional rewriting of addresses in header lines can be
23558 specified by setting the generic headers_rewrite option on a transport. This
23559 option contains rules that are identical in form to those in the rewrite
23560 section of the configuration file. They are applied to the original message
23561 header lines and any that were added by ACLs or a system filter. They are not
23562 applied to header lines that are added by routers or the transport.
23563
23564 The outgoing envelope sender can be rewritten by means of the return_path
23565 transport option. However, it is not possible to rewrite envelope recipients at
23566 transport time.
23567
23568
23569 31.3 Testing the rewriting rules that apply on input
23570 ----------------------------------------------------
23571
23572 Exim's input rewriting configuration appears in a part of the runtime
23573 configuration file headed by "begin rewrite". It can be tested by the -brw
23574 command line option. This takes an address (which can be a full RFC 2822
23575 address) as its argument. The output is a list of how the address would be
23576 transformed by the rewriting rules for each of the different places it might
23577 appear in an incoming message, that is, for each different header and for the
23578 envelope sender and recipient fields. For example,
23579
23580 exim -brw ph10@exim.workshop.example
23581
23582 might produce the output
23583
23584 sender: Philip.Hazel@exim.workshop.example
23585 from: Philip.Hazel@exim.workshop.example
23586 to: ph10@exim.workshop.example
23587 cc: ph10@exim.workshop.example
23588 bcc: ph10@exim.workshop.example
23589 reply-to: Philip.Hazel@exim.workshop.example
23590 env-from: Philip.Hazel@exim.workshop.example
23591 env-to: ph10@exim.workshop.example
23592
23593 which shows that rewriting has been set up for that address when used in any of
23594 the source fields, but not when it appears as a recipient address. At the
23595 present time, there is no equivalent way of testing rewriting rules that are
23596 set for a particular transport.
23597
23598
23599 31.4 Rewriting rules
23600 --------------------
23601
23602 The rewrite section of the configuration file consists of lines of rewriting
23603 rules in the form
23604
23605 <source pattern> <replacement> <flags>
23606
23607 Rewriting rules that are specified for the headers_rewrite generic transport
23608 option are given as a colon-separated list. Each item in the list takes the
23609 same form as a line in the main rewriting configuration (except that any colons
23610 must be doubled, of course).
23611
23612 The formats of source patterns and replacement strings are described below.
23613 Each is terminated by white space, unless enclosed in double quotes, in which
23614 case normal quoting conventions apply inside the quotes. The flags are single
23615 characters which may appear in any order. Spaces and tabs between them are
23616 ignored.
23617
23618 For each address that could potentially be rewritten, the rules are scanned in
23619 order, and replacements for the address from earlier rules can themselves be
23620 replaced by later rules (but see the "q" and "R" flags).
23621
23622 The order in which addresses are rewritten is undefined, may change between
23623 releases, and must not be relied on, with one exception: when a message is
23624 received, the envelope sender is always rewritten first, before any header
23625 lines are rewritten. For example, the replacement string for a rewrite of an
23626 address in To: must not assume that the message's address in From: has (or has
23627 not) already been rewritten. However, a rewrite of From: may assume that the
23628 envelope sender has already been rewritten.
23629
23630 The variables $local_part and $domain can be used in the replacement string to
23631 refer to the address that is being rewritten. Note that lookup-driven rewriting
23632 can be done by a rule of the form
23633
23634 *@* ${lookup ...
23635
23636 where the lookup key uses $1 and $2 or $local_part and $domain to refer to the
23637 address that is being rewritten.
23638
23639
23640 31.5 Rewriting patterns
23641 -----------------------
23642
23643 The source pattern in a rewriting rule is any item which may appear in an
23644 address list (see section 10.19). It is in fact processed as a single-item
23645 address list, which means that it is expanded before being tested against the
23646 address. As always, if you use a regular expression as a pattern, you must take
23647 care to escape dollar and backslash characters, or use the "\N" facility to
23648 suppress string expansion within the regular expression.
23649
23650 Domains in patterns should be given in lower case. Local parts in patterns are
23651 case-sensitive. If you want to do case-insensitive matching of local parts, you
23652 can use a regular expression that starts with "^(?i)".
23653
23654 After matching, the numerical variables $1, $2, etc. may be set, depending on
23655 the type of match which occurred. These can be used in the replacement string
23656 to insert portions of the incoming address. $0 always refers to the complete
23657 incoming address. When a regular expression is used, the numerical variables
23658 are set from its capturing subexpressions. For other types of pattern they are
23659 set as follows:
23660
23661 * If a local part or domain starts with an asterisk, the numerical variables
23662 refer to the character strings matched by asterisks, with $1 associated
23663 with the first asterisk, and $2 with the second, if present. For example,
23664 if the pattern
23665
23666 *queen@*.fict.example
23667
23668 is matched against the address hearts-queen@wonderland.fict.example then
23669
23670 $0 = hearts-queen@wonderland.fict.example
23671 $1 = hearts-
23672 $2 = wonderland
23673
23674 Note that if the local part does not start with an asterisk, but the domain
23675 does, it is $1 that contains the wild part of the domain.
23676
23677 * If the domain part of the pattern is a partial lookup, the wild and fixed
23678 parts of the domain are placed in the next available numerical variables.
23679 Suppose, for example, that the address foo@bar.baz.example is processed by
23680 a rewriting rule of the form
23681
23682 *@partial-dbm;/some/dbm/file <replacement string>
23683
23684 and the key in the file that matches the domain is "*.baz.example". Then
23685
23686 $1 = foo
23687 $2 = bar
23688 $3 = baz.example
23689
23690 If the address foo@baz.example is looked up, this matches the same wildcard
23691 file entry, and in this case $2 is set to the empty string, but $3 is still
23692 set to baz.example. If a non-wild key is matched in a partial lookup, $2 is
23693 again set to the empty string and $3 is set to the whole domain. For
23694 non-partial domain lookups, no numerical variables are set.
23695
23696
23697 31.6 Rewriting replacements
23698 ---------------------------
23699
23700 If the replacement string for a rule is a single asterisk, addresses that match
23701 the pattern and the flags are not rewritten, and no subsequent rewriting rules
23702 are scanned. For example,
23703
23704 hatta@lookingglass.fict.example * f
23705
23706 specifies that hatta@lookingglass.fict.example is never to be rewritten in
23707 From: headers.
23708
23709 If the replacement string is not a single asterisk, it is expanded, and must
23710 yield a fully qualified address. Within the expansion, the variables
23711 $local_part and $domain refer to the address that is being rewritten. Any
23712 letters they contain retain their original case - they are not lower cased. The
23713 numerical variables are set up according to the type of pattern that matched
23714 the address, as described above. If the expansion is forced to fail by the
23715 presence of "fail" in a conditional or lookup item, rewriting by the current
23716 rule is abandoned, but subsequent rules may take effect. Any other expansion
23717 failure causes the entire rewriting operation to be abandoned, and an entry
23718 written to the panic log.
23719
23720
23721 31.7 Rewriting flags
23722 --------------------
23723
23724 There are three different kinds of flag that may appear on rewriting rules:
23725
23726 * Flags that specify which headers and envelope addresses to rewrite: E, F,
23727 T, b, c, f, h, r, s, t.
23728
23729 * A flag that specifies rewriting at SMTP time: S.
23730
23731 * Flags that control the rewriting process: Q, q, R, w.
23732
23733 For rules that are part of the headers_rewrite generic transport option, E, F,
23734 T, and S are not permitted.
23735
23736
23737 31.8 Flags specifying which headers and envelope addresses to rewrite
23738 ---------------------------------------------------------------------
23739
23740 If none of the following flag letters, nor the "S" flag (see section 31.9) are
23741 present, a main rewriting rule applies to all headers and to both the sender
23742 and recipient fields of the envelope, whereas a transport-time rewriting rule
23743 just applies to all headers. Otherwise, the rewriting rule is skipped unless
23744 the relevant addresses are being processed.
23745
23746 E rewrite all envelope fields
23747 F rewrite the envelope From field
23748 T rewrite the envelope To field
23749 b rewrite the Bcc: header
23750 c rewrite the Cc: header
23751 f rewrite the From: header
23752 h rewrite all headers
23753 r rewrite the Reply-To: header
23754 s rewrite the Sender: header
23755 t rewrite the To: header
23756
23757 "All headers" means all of the headers listed above that can be selected
23758 individually, plus their Resent- versions. It does not include other headers
23759 such as Subject: etc.
23760
23761 You should be particularly careful about rewriting Sender: headers, and
23762 restrict this to special known cases in your own domains.
23763
23764
23765 31.9 The SMTP-time rewriting flag
23766 ---------------------------------
23767
23768 The rewrite flag "S" specifies a rewrite of incoming envelope addresses at SMTP
23769 time, as soon as an address is received in a MAIL or RCPT command, and before
23770 any other processing; even before syntax checking. The pattern is required to
23771 be a regular expression, and it is matched against the whole of the data for
23772 the command, including any surrounding angle brackets.
23773
23774 This form of rewrite rule allows for the handling of addresses that are not
23775 compliant with RFCs 2821 and 2822 (for example, "bang paths" in batched SMTP
23776 input). Because the input is not required to be a syntactically valid address,
23777 the variables $local_part and $domain are not available during the expansion of
23778 the replacement string. The result of rewriting replaces the original address
23779 in the MAIL or RCPT command.
23780
23781
23782 31.10 Flags controlling the rewriting process
23783 ---------------------------------------------
23784
23785 There are four flags which control the way the rewriting process works. These
23786 take effect only when a rule is invoked, that is, when the address is of the
23787 correct type (matches the flags) and matches the pattern:
23788
23789 * If the "Q" flag is set on a rule, the rewritten address is permitted to be
23790 an unqualified local part. It is qualified with qualify_recipient. In the
23791 absence of "Q" the rewritten address must always include a domain.
23792
23793 * If the "q" flag is set on a rule, no further rewriting rules are
23794 considered, even if no rewriting actually takes place because of a "fail"
23795 in the expansion. The "q" flag is not effective if the address is of the
23796 wrong type (does not match the flags) or does not match the pattern.
23797
23798 * The "R" flag causes a successful rewriting rule to be re-applied to the new
23799 address, up to ten times. It can be combined with the "q" flag, to stop
23800 rewriting once it fails to match (after at least one successful rewrite).
23801
23802 * When an address in a header is rewritten, the rewriting normally applies
23803 only to the working part of the address, with any comments and RFC 2822
23804 "phrase" left unchanged. For example, rewriting might change
23805
23806 From: Ford Prefect <fp42@restaurant.hitch.fict.example>
23807
23808 into
23809
23810 From: Ford Prefect <prefectf@hitch.fict.example>
23811
23812 Sometimes there is a need to replace the whole address item, and this can
23813 be done by adding the flag letter "w" to a rule. If this is set on a rule
23814 that causes an address in a header line to be rewritten, the entire address
23815 is replaced, not just the working part. The replacement must be a complete
23816 RFC 2822 address, including the angle brackets if necessary. If text
23817 outside angle brackets contains a character whose value is greater than 126
23818 or less than 32 (except for tab), the text is encoded according to RFC
23819 2047. The character set is taken from headers_charset, which gets its
23820 default at build time.
23821
23822 When the "w" flag is set on a rule that causes an envelope address to be
23823 rewritten, all but the working part of the replacement address is
23824 discarded.
23825
23826
23827 31.11 Rewriting examples
23828 ------------------------
23829
23830 Here is an example of the two common rewriting paradigms:
23831
23832 *@*.hitch.fict.example $1@hitch.fict.example
23833 *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\
23834 {$value}fail}@hitch.fict.example bctfrF
23835
23836 Note the use of "fail" in the lookup expansion in the second rule, forcing the
23837 string expansion to fail if the lookup does not succeed. In this context it has
23838 the effect of leaving the original address unchanged, but Exim goes on to
23839 consider subsequent rewriting rules, if any, because the "q" flag is not
23840 present in that rule. An alternative to "fail" would be to supply $1
23841 explicitly, which would cause the rewritten address to be the same as before,
23842 at the cost of a small bit of processing. Not supplying either of these is an
23843 error, since the rewritten address would then contain no local part.
23844
23845 The first example above replaces the domain with a superior, more general
23846 domain. This may not be desirable for certain local parts. If the rule
23847
23848 root@*.hitch.fict.example *
23849
23850 were inserted before the first rule, rewriting would be suppressed for the
23851 local part root at any domain ending in hitch.fict.example.
23852
23853 Rewriting can be made conditional on a number of tests, by making use of ${if
23854 in the expansion item. For example, to apply a rewriting rule only to messages
23855 that originate outside the local host:
23856
23857 *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\
23858 {$1@hitch.fict.example}fail}"
23859
23860 The replacement string is quoted in this example because it contains white
23861 space.
23862
23863 Exim does not handle addresses in the form of "bang paths". If it sees such an
23864 address it treats it as an unqualified local part which it qualifies with the
23865 local qualification domain (if the source of the message is local or if the
23866 remote host is permitted to send unqualified addresses). Rewriting can
23867 sometimes be used to handle simple bang paths with a fixed number of
23868 components. For example, the rule
23869
23870 \N^([^!]+)!(.*)@your.domain.example$\N $2@$1
23871
23872 rewrites a two-component bang path host.name!user as the domain address
23873 user@host.name. However, there is a security implication in using this as a
23874 global rewriting rule for envelope addresses. It can provide a backdoor method
23875 for using your system as a relay, because the incoming addresses appear to be
23876 local. If the bang path addresses are received via SMTP, it is safer to use the
23877 "S" flag to rewrite them as they are received, so that relay checking can be
23878 done on the rewritten addresses.
23879
23880
23881
23882 ===============================================================================
23883 32. RETRY CONFIGURATION
23884
23885 The "retry" section of the runtime configuration file contains a list of retry
23886 rules that control how often Exim tries to deliver messages that cannot be
23887 delivered at the first attempt. If there are no retry rules (the section is
23888 empty or not present), there are no retries. In this situation, temporary
23889 errors are treated as permanent. The default configuration contains a single,
23890 general-purpose retry rule (see section 7.6). The -brt command line option can
23891 be used to test which retry rule will be used for a given address, domain and
23892 error.
23893
23894 The most common cause of retries is temporary failure to deliver to a remote
23895 host because the host is down, or inaccessible because of a network problem.
23896 Exim's retry processing in this case is applied on a per-host (strictly, per IP
23897 address) basis, not on a per-message basis. Thus, if one message has recently
23898 been delayed, delivery of a new message to the same host is not immediately
23899 tried, but waits for the host's retry time to arrive. If the retry_defer log
23900 selector is set, the message "retry time not reached" is written to the main
23901 log whenever a delivery is skipped for this reason. Section 48.2 contains more
23902 details of the handling of errors during remote deliveries.
23903
23904 Retry processing applies to routing as well as to delivering, except as covered
23905 in the next paragraph. The retry rules do not distinguish between these
23906 actions. It is not possible, for example, to specify different behaviour for
23907 failures to route the domain snark.fict.example and failures to deliver to the
23908 host snark.fict.example. I didn't think anyone would ever need this added
23909 complication, so did not implement it. However, although they share the same
23910 retry rule, the actual retry times for routing and transporting a given domain
23911 are maintained independently.
23912
23913 When a delivery is not part of a queue run (typically an immediate delivery on
23914 receipt of a message), the routers are always run, and local deliveries are
23915 always attempted, even if retry times are set for them. This makes for better
23916 behaviour if one particular message is causing problems (for example, causing
23917 quota overflow, or provoking an error in a filter file). If such a delivery
23918 suffers a temporary failure, the retry data is updated as normal, and
23919 subsequent delivery attempts from queue runs occur only when the retry time for
23920 the local address is reached.
23921
23922
23923 32.1 Changing retry rules
23924 -------------------------
23925
23926 If you change the retry rules in your configuration, you should consider
23927 whether or not to delete the retry data that is stored in Exim's spool area in
23928 files with names like db/retry. Deleting any of Exim's hints files is always
23929 safe; that is why they are called "hints".
23930
23931 The hints retry data contains suggested retry times based on the previous
23932 rules. In the case of a long-running problem with a remote host, it might
23933 record the fact that the host has timed out. If your new rules increase the
23934 timeout time for such a host, you should definitely remove the old retry data
23935 and let Exim recreate it, based on the new rules. Otherwise Exim might bounce
23936 messages that it should now be retaining.
23937
23938
23939 32.2 Format of retry rules
23940 --------------------------
23941
23942 Each retry rule occupies one line and consists of three or four parts,
23943 separated by white space: a pattern, an error name, an optional list of sender
23944 addresses, and a list of retry parameters. The pattern and sender lists must be
23945 enclosed in double quotes if they contain white space. The rules are searched
23946 in order until one is found where the pattern, error name, and sender list (if
23947 present) match the failing host or address, the error that occurred, and the
23948 message's sender, respectively.
23949
23950 The pattern is any single item that may appear in an address list (see section
23951 10.19). It is in fact processed as a one-item address list, which means that it
23952 is expanded before being tested against the address that has been delayed. A
23953 negated address list item is permitted. Address list processing treats a plain
23954 domain name as if it were preceded by "*@", which makes it possible for many
23955 retry rules to start with just a domain. For example,
23956
23957 lookingglass.fict.example * F,24h,30m;
23958
23959 provides a rule for any address in the lookingglass.fict.example domain,
23960 whereas
23961
23962 alice@lookingglass.fict.example * F,24h,30m;
23963
23964 applies only to temporary failures involving the local part alice. In practice,
23965 almost all rules start with a domain name pattern without a local part.
23966
23967 Warning: If you use a regular expression in a retry rule pattern, it must match
23968 a complete address, not just a domain, because that is how regular expressions
23969 work in address lists.
23970
23971 ^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2 Wrong
23972 ^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2 Right
23973
23974
23975 32.3 Choosing which retry rule to use for address errors
23976 --------------------------------------------------------
23977
23978 When Exim is looking for a retry rule after a routing attempt has failed (for
23979 example, after a DNS timeout), each line in the retry configuration is tested
23980 against the complete address only if retry_use_local_part is set for the
23981 router. Otherwise, only the domain is used, except when matching against a
23982 regular expression, when the local part of the address is replaced with "*". A
23983 domain on its own can match a domain pattern, or a pattern that starts with
23984 "*@". By default, retry_use_local_part is true for routers where
23985 check_local_user is true, and false for other routers.
23986
23987 Similarly, when Exim is looking for a retry rule after a local delivery has
23988 failed (for example, after a mailbox full error), each line in the retry
23989 configuration is tested against the complete address only if
23990 retry_use_local_part is set for the transport (it defaults true for all local
23991 transports).
23992
23993 However, when Exim is looking for a retry rule after a remote delivery attempt
23994 suffers an address error (a 4xx SMTP response for a recipient address), the
23995 whole address is always used as the key when searching the retry rules. The
23996 rule that is found is used to create a retry time for the combination of the
23997 failing address and the message's sender. It is the combination of sender and
23998 recipient that is delayed in subsequent queue runs until its retry time is
23999 reached. You can delay the recipient without regard to the sender by setting
24000 address_retry_include_sender false in the smtp transport but this can lead to
24001 problems with servers that regularly issue 4xx responses to RCPT commands.
24002
24003
24004 32.4 Choosing which retry rule to use for host and message errors
24005 -----------------------------------------------------------------
24006
24007 For a temporary error that is not related to an individual address (for
24008 example, a connection timeout), each line in the retry configuration is checked
24009 twice. First, the name of the remote host is used as a domain name (preceded by
24010 "*@" when matching a regular expression). If this does not match the line, the
24011 domain from the email address is tried in a similar fashion. For example,
24012 suppose the MX records for a.b.c.example are
24013
24014 a.b.c.example MX 5 x.y.z.example
24015 MX 6 p.q.r.example
24016 MX 7 m.n.o.example
24017
24018 and the retry rules are
24019
24020 p.q.r.example * F,24h,30m;
24021 a.b.c.example * F,4d,45m;
24022
24023 and a delivery to the host x.y.z.example suffers a connection failure. The
24024 first rule matches neither the host nor the domain, so Exim looks at the second
24025 rule. This does not match the host, but it does match the domain, so it is used
24026 to calculate the retry time for the host x.y.z.example. Meanwhile, Exim tries
24027 to deliver to p.q.r.example. If this also suffers a host error, the first retry
24028 rule is used, because it matches the host.
24029
24030 In other words, temporary failures to deliver to host p.q.r.example use the
24031 first rule to determine retry times, but for all the other hosts for the domain
24032 a.b.c.example, the second rule is used. The second rule is also used if routing
24033 to a.b.c.example suffers a temporary failure.
24034
24035 Note: The host name is used when matching the patterns, not its IP address.
24036 However, if a message is routed directly to an IP address without the use of a
24037 host name, for example, if a manualroute router contains a setting such as:
24038
24039 route_list = *.a.example 192.168.34.23
24040
24041 then the "host name" that is used when searching for a retry rule is the
24042 textual form of the IP address.
24043
24044
24045 32.5 Retry rules for specific errors
24046 ------------------------------------
24047
24048 The second field in a retry rule is the name of a particular error, or an
24049 asterisk, which matches any error. The errors that can be tested for are:
24050
24051 auth_failed
24052
24053 Authentication failed when trying to send to a host in the
24054 hosts_require_auth list in an smtp transport.
24055
24056 data_4xx
24057
24058 A 4xx error was received for an outgoing DATA command, either immediately
24059 after the command, or after sending the message's data.
24060
24061 mail_4xx
24062
24063 A 4xx error was received for an outgoing MAIL command.
24064
24065 rcpt_4xx
24066
24067 A 4xx error was received for an outgoing RCPT command.
24068
24069 For the three 4xx errors, either the first or both of the x's can be given as
24070 specific digits, for example: "mail_45x" or "rcpt_436". For example, to
24071 recognize 452 errors given to RCPT commands for addresses in a certain domain,
24072 and have retries every ten minutes with a one-hour timeout, you could set up a
24073 retry rule of this form:
24074
24075 the.domain.name rcpt_452 F,1h,10m
24076
24077 These errors apply to both outgoing SMTP (the smtp transport) and outgoing LMTP
24078 (either the lmtp transport, or the smtp transport in LMTP mode).
24079
24080 lost_connection
24081
24082 A server unexpectedly closed the SMTP connection. There may, of course,
24083 legitimate reasons for this (host died, network died), but if it repeats a
24084 lot for the same host, it indicates something odd.
24085
24086 lookup
24087
24088 A DNS lookup for a host failed. Note that a dnslookup router will need to
24089 have matched its fail_defer_domains option for this retry type to be
24090 usable. Also note that a manualroute router will probably need its
24091 host_find_failed option set to defer.
24092
24093 refused_MX
24094
24095 A connection to a host obtained from an MX record was refused.
24096
24097 refused_A
24098
24099 A connection to a host not obtained from an MX record was refused.
24100
24101 refused
24102
24103 A connection was refused.
24104
24105 timeout_connect_MX
24106
24107 A connection attempt to a host obtained from an MX record timed out.
24108
24109 timeout_connect_A
24110
24111 A connection attempt to a host not obtained from an MX record timed out.
24112
24113 timeout_connect
24114
24115 A connection attempt timed out.
24116
24117 timeout_MX
24118
24119 There was a timeout while connecting or during an SMTP session with a host
24120 obtained from an MX record.
24121
24122 timeout_A
24123
24124 There was a timeout while connecting or during an SMTP session with a host
24125 not obtained from an MX record.
24126
24127 timeout
24128
24129 There was a timeout while connecting or during an SMTP session.
24130
24131 tls_required
24132
24133 The server was required to use TLS (it matched hosts_require_tls in the
24134 smtp transport), but either did not offer TLS, or it responded with 4xx to
24135 STARTTLS, or there was a problem setting up the TLS connection.
24136
24137 quota
24138
24139 A mailbox quota was exceeded in a local delivery by the appendfile
24140 transport.
24141
24142 quota_<time>
24143
24144 A mailbox quota was exceeded in a local delivery by the appendfile
24145 transport, and the mailbox has not been accessed for <time>. For example,
24146 quota_4d applies to a quota error when the mailbox has not been accessed
24147 for four days.
24148
24149 The idea of quota_<time> is to make it possible to have shorter timeouts when
24150 the mailbox is full and is not being read by its owner. Ideally, it should be
24151 based on the last time that the user accessed the mailbox. However, it is not
24152 always possible to determine this. Exim uses the following heuristic rules:
24153
24154 * If the mailbox is a single file, the time of last access (the "atime") is
24155 used. As no new messages are being delivered (because the mailbox is over
24156 quota), Exim does not access the file, so this is the time of last user
24157 access.
24158
24159 * For a maildir delivery, the time of last modification of the new
24160 subdirectory is used. As the mailbox is over quota, no new files are
24161 created in the new subdirectory, because no new messages are being
24162 delivered. Any change to the new subdirectory is therefore assumed to be
24163 the result of an MUA moving a new message to the cur directory when it is
24164 first read. The time that is used is therefore the last time that the user
24165 read a new message.
24166
24167 * For other kinds of multi-file mailbox, the time of last access cannot be
24168 obtained, so a retry rule that uses this type of error field is never
24169 matched.
24170
24171 The quota errors apply both to system-enforced quotas and to Exim's own quota
24172 mechanism in the appendfile transport. The quota error also applies when a
24173 local delivery is deferred because a partition is full (the ENOSPC error).
24174
24175
24176 32.6 Retry rules for specified senders
24177 --------------------------------------
24178
24179 You can specify retry rules that apply only when the failing message has a
24180 specific sender. In particular, this can be used to define retry rules that
24181 apply only to bounce messages. The third item in a retry rule can be of this
24182 form:
24183
24184 senders=<address list>
24185
24186 The retry timings themselves are then the fourth item. For example:
24187
24188 * rcpt_4xx senders=: F,1h,30m
24189
24190 matches recipient 4xx errors for bounce messages sent to any address at any
24191 host. If the address list contains white space, it must be enclosed in quotes.
24192 For example:
24193
24194 a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5
24195
24196 Warning: This facility can be unhelpful if it is used for host errors (which do
24197 not depend on the recipient). The reason is that the sender is used only to
24198 match the retry rule. Once the rule has been found for a host error, its
24199 contents are used to set a retry time for the host, and this will apply to all
24200 messages, not just those with specific senders.
24201
24202 When testing retry rules using -brt, you can supply a sender using the -f
24203 command line option, like this:
24204
24205 exim -f "" -brt user@dom.ain
24206
24207 If you do not set -f with -brt, a retry rule that contains a senders list is
24208 never matched.
24209
24210
24211 32.7 Retry parameters
24212 ---------------------
24213
24214 The third (or fourth, if a senders list is present) field in a retry rule is a
24215 sequence of retry parameter sets, separated by semicolons. Each set consists of
24216
24217 <letter>,<cutoff time>,<arguments>
24218
24219 The letter identifies the algorithm for computing a new retry time; the cutoff
24220 time is the time beyond which this algorithm no longer applies, and the
24221 arguments vary the algorithm's action. The cutoff time is measured from the
24222 time that the first failure for the domain (combined with the local part if
24223 relevant) was detected, not from the time the message was received.
24224
24225 The available algorithms are:
24226
24227 * F: retry at fixed intervals. There is a single time parameter specifying
24228 the interval.
24229
24230 * G: retry at geometrically increasing intervals. The first argument
24231 specifies a starting value for the interval, and the second a multiplier,
24232 which is used to increase the size of the interval at each retry.
24233
24234 * H: retry at randomized intervals. The arguments are as for G. For each
24235 retry, the previous interval is multiplied by the factor in order to get a
24236 maximum for the next interval. The minimum interval is the first argument
24237 of the parameter, and an actual interval is chosen randomly between them.
24238 Such a rule has been found to be helpful in cluster configurations when all
24239 the members of the cluster restart at once, and may therefore synchronize
24240 their queue processing times.
24241
24242 When computing the next retry time, the algorithm definitions are scanned in
24243 order until one whose cutoff time has not yet passed is reached. This is then
24244 used to compute a new retry time that is later than the current time. In the
24245 case of fixed interval retries, this simply means adding the interval to the
24246 current time. For geometrically increasing intervals, retry intervals are
24247 computed from the rule's parameters until one that is greater than the previous
24248 interval is found. The main configuration variable retry_interval_max limits
24249 the maximum interval between retries. It cannot be set greater than "24h",
24250 which is its default value.
24251
24252 A single remote domain may have a number of hosts associated with it, and each
24253 host may have more than one IP address. Retry algorithms are selected on the
24254 basis of the domain name, but are applied to each IP address independently. If,
24255 for example, a host has two IP addresses and one is unusable, Exim will
24256 generate retry times for it and will not try to use it until its next retry
24257 time comes. Thus the good IP address is likely to be tried first most of the
24258 time.
24259
24260 Retry times are hints rather than promises. Exim does not make any attempt to
24261 run deliveries exactly at the computed times. Instead, a queue runner process
24262 starts delivery processes for delayed messages periodically, and these attempt
24263 new deliveries only for those addresses that have passed their next retry time.
24264 If a new message arrives for a deferred address, an immediate delivery attempt
24265 occurs only if the address has passed its retry time. In the absence of new
24266 messages, the minimum time between retries is the interval between queue runner
24267 processes. There is not much point in setting retry times of five minutes if
24268 your queue runners happen only once an hour, unless there are a significant
24269 number of incoming messages (which might be the case on a system that is
24270 sending everything to a smart host, for example).
24271
24272 The data in the retry hints database can be inspected by using the exim_dumpdb
24273 or exim_fixdb utility programs (see chapter 53). The latter utility can also be
24274 used to change the data. The exinext utility script can be used to find out
24275 what the next retry times are for the hosts associated with a particular mail
24276 domain, and also for local deliveries that have been deferred.
24277
24278
24279 32.8 Retry rule examples
24280 ------------------------
24281
24282 Here are some example retry rules:
24283
24284 alice@wonderland.fict.example quota_5d F,7d,3h
24285 wonderland.fict.example quota_5d
24286 wonderland.fict.example * F,1h,15m; G,2d,1h,2;
24287 lookingglass.fict.example * F,24h,30m;
24288 * refused_A F,2h,20m;
24289 * * F,2h,15m; G,16h,1h,1.5; F,5d,8h
24290
24291 The first rule sets up special handling for mail to
24292 alice@wonderland.fict.example when there is an over-quota error and the mailbox
24293 has not been read for at least 5 days. Retries continue every three hours for 7
24294 days. The second rule handles over-quota errors for all other local parts at
24295 wonderland.fict.example; the absence of a local part has the same effect as
24296 supplying "*@". As no retry algorithms are supplied, messages that fail are
24297 bounced immediately if the mailbox has not been read for at least 5 days.
24298
24299 The third rule handles all other errors at wonderland.fict.example; retries
24300 happen every 15 minutes for an hour, then with geometrically increasing
24301 intervals until two days have passed since a delivery first failed. After the
24302 first hour there is a delay of one hour, then two hours, then four hours, and
24303 so on (this is a rather extreme example).
24304
24305 The fourth rule controls retries for the domain lookingglass.fict.example. They
24306 happen every 30 minutes for 24 hours only. The remaining two rules handle all
24307 other domains, with special action for connection refusal from hosts that were
24308 not obtained from an MX record.
24309
24310 The final rule in a retry configuration should always have asterisks in the
24311 first two fields so as to provide a general catch-all for any addresses that do
24312 not have their own special handling. This example tries every 15 minutes for 2
24313 hours, then with intervals starting at one hour and increasing by a factor of
24314 1.5 up to 16 hours, then every 8 hours up to 5 days.
24315
24316
24317 32.9 Timeout of retry data
24318 --------------------------
24319
24320 Exim timestamps the data that it writes to its retry hints database. When it
24321 consults the data during a delivery it ignores any that is older than the value
24322 set in retry_data_expire (default 7 days). If, for example, a host hasn't been
24323 tried for 7 days, Exim will try to deliver to it immediately a message arrives,
24324 and if that fails, it will calculate a retry time as if it were failing for the
24325 first time.
24326
24327 This improves the behaviour for messages routed to rarely-used hosts such as MX
24328 backups. If such a host was down at one time, and happens to be down again when
24329 Exim tries a month later, using the old retry data would imply that it had been
24330 down all the time, which is not a justified assumption.
24331
24332 If a host really is permanently dead, this behaviour causes a burst of retries
24333 every now and again, but only if messages routed to it are rare. If there is a
24334 message at least once every 7 days the retry data never expires.
24335
24336
24337 32.10 Long-term failures
24338 ------------------------
24339
24340 Special processing happens when an email address has been failing for so long
24341 that the cutoff time for the last algorithm is reached. For example, using the
24342 default retry rule:
24343
24344 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
24345
24346 the cutoff time is four days. Reaching the retry cutoff is independent of how
24347 long any specific message has been failing; it is the length of continuous
24348 failure for the recipient address that counts.
24349
24350 When the cutoff time is reached for a local delivery, or for all the IP
24351 addresses associated with a remote delivery, a subsequent delivery failure
24352 causes Exim to give up on the address, and a bounce message is generated. In
24353 order to cater for new messages that use the failing address, a next retry time
24354 is still computed from the final algorithm, and is used as follows:
24355
24356 For local deliveries, one delivery attempt is always made for any subsequent
24357 messages. If this delivery fails, the address fails immediately. The
24358 post-cutoff retry time is not used.
24359
24360 If the delivery is remote, there are two possibilities, controlled by the
24361 delay_after_cutoff option of the smtp transport. The option is true by default.
24362 Until the post-cutoff retry time for one of the IP addresses, as set by the
24363 retry_data_expire option, is reached, the failing email address is bounced
24364 immediately, without a delivery attempt taking place. After that time, one new
24365 delivery attempt is made to those IP addresses that are past their retry times,
24366 and if that still fails, the address is bounced and new retry times are
24367 computed.
24368
24369 In other words, when all the hosts for a given email address have been failing
24370 for a long time, Exim bounces rather then defers until one of the hosts' retry
24371 times is reached. Then it tries once, and bounces if that attempt fails. This
24372 behaviour ensures that few resources are wasted in repeatedly trying to deliver
24373 to a broken destination, but if the host does recover, Exim will eventually
24374 notice.
24375
24376 If delay_after_cutoff is set false, Exim behaves differently. If all IP
24377 addresses are past their final cutoff time, Exim tries to deliver to those IP
24378 addresses that have not been tried since the message arrived. If there are no
24379 suitable IP addresses, or if they all fail, the address is bounced. In other
24380 words, it does not delay when a new message arrives, but tries the expired
24381 addresses immediately, unless they have been tried since the message arrived.
24382 If there is a continuous stream of messages for the failing domains, setting
24383 delay_after_cutoff false means that there will be many more attempts to deliver
24384 to permanently failing IP addresses than when delay_after_cutoff is true.
24385
24386
24387 32.11 Deliveries that work intermittently
24388 -----------------------------------------
24389
24390 Some additional logic is needed to cope with cases where a host is
24391 intermittently available, or when a message has some attribute that prevents
24392 its delivery when others to the same address get through. In this situation,
24393 because some messages are successfully delivered, the "retry clock" for the
24394 host or address keeps getting reset by the successful deliveries, and so
24395 failing messages remain in the queue for ever because the cutoff time is never
24396 reached.
24397
24398 Two exceptional actions are applied to prevent this happening. The first
24399 applies to errors that are related to a message rather than a remote host.
24400 Section 48.2 has a discussion of the different kinds of error; examples of
24401 message-related errors are 4xx responses to MAIL or DATA commands, and quota
24402 failures. For this type of error, if a message's arrival time is earlier than
24403 the "first failed" time for the error, the earlier time is used when scanning
24404 the retry rules to decide when to try next and when to time out the address.
24405
24406 The exceptional second action applies in all cases. If a message has been on
24407 the queue for longer than the cutoff time of any applicable retry rule for a
24408 given address, a delivery is attempted for that address, even if it is not yet
24409 time, and if this delivery fails, the address is timed out. A new retry time is
24410 not computed in this case, so that other messages for the same address are
24411 considered immediately.
24412
24413
24414
24415 ===============================================================================
24416 33. SMTP AUTHENTICATION
24417
24418 The "authenticators" section of Exim's runtime configuration is concerned with
24419 SMTP authentication. This facility is an extension to the SMTP protocol,
24420 described in RFC 2554, which allows a client SMTP host to authenticate itself
24421 to a server. This is a common way for a server to recognize clients that are
24422 permitted to use it as a relay. SMTP authentication is not of relevance to the
24423 transfer of mail between servers that have no managerial connection with each
24424 other.
24425
24426 Very briefly, the way SMTP authentication works is as follows:
24427
24428 * The server advertises a number of authentication mechanisms in response to
24429 the client's EHLO command.
24430
24431 * The client issues an AUTH command, naming a specific mechanism. The command
24432 may, optionally, contain some authentication data.
24433
24434 * The server may issue one or more challenges, to which the client must send
24435 appropriate responses. In simple authentication mechanisms, the challenges
24436 are just prompts for user names and passwords. The server does not have to
24437 issue any challenges - in some mechanisms the relevant data may all be
24438 transmitted with the AUTH command.
24439
24440 * The server either accepts or denies authentication.
24441
24442 * If authentication succeeds, the client may optionally make use of the AUTH
24443 option on the MAIL command to pass an authenticated sender in subsequent
24444 mail transactions. Authentication lasts for the remainder of the SMTP
24445 connection.
24446
24447 * If authentication fails, the client may give up, or it may try a different
24448 authentication mechanism, or it may try transferring mail over the
24449 unauthenticated connection.
24450
24451 If you are setting up a client, and want to know which authentication
24452 mechanisms the server supports, you can use Telnet to connect to port 25 (the
24453 SMTP port) on the server, and issue an EHLO command. The response to this
24454 includes the list of supported mechanisms. For example:
24455
24456 $ telnet server.example 25
24457 Trying 192.168.34.25...
24458 Connected to server.example.
24459 Escape character is '^]'.
24460 220 server.example ESMTP Exim 4.20 ...
24461 ehlo client.example
24462 250-server.example Hello client.example [10.8.4.5]
24463 250-SIZE 52428800
24464 250-PIPELINING
24465 250-AUTH PLAIN
24466 250 HELP
24467
24468 The second-last line of this example output shows that the server supports
24469 authentication using the PLAIN mechanism. In Exim, the different authentication
24470 mechanisms are configured by specifying authenticator drivers. Like the routers
24471 and transports, which authenticators are included in the binary is controlled
24472 by build-time definitions. The following are currently available, included by
24473 setting
24474
24475 AUTH_CRAM_MD5=yes
24476 AUTH_CYRUS_SASL=yes
24477 AUTH_DOVECOT=yes
24478 AUTH_GSASL=yes
24479 AUTH_HEIMDAL_GSSAPI=yes
24480 AUTH_PLAINTEXT=yes
24481 AUTH_SPA=yes
24482 AUTH_TLS=yes
24483
24484 in Local/Makefile, respectively. The first of these supports the CRAM-MD5
24485 authentication mechanism (RFC 2195), and the second provides an interface to
24486 the Cyrus SASL authentication library. The third is an interface to Dovecot's
24487 authentication system, delegating the work via a socket interface. The fourth
24488 provides an interface to the GNU SASL authentication library, which provides
24489 mechanisms but typically not data sources. The fifth provides direct access to
24490 Heimdal GSSAPI, geared for Kerberos, but supporting setting a server keytab.
24491 The sixth can be configured to support the PLAIN authentication mechanism (RFC
24492 2595) or the LOGIN mechanism, which is not formally documented, but used by
24493 several MUAs. The seventh authenticator supports Microsoft's Secure Password
24494 Authentication mechanism. The eighth is an Exim authenticator but not an SMTP
24495 one; instead it can use information from a TLS negotiation.
24496
24497 The authenticators are configured using the same syntax as other drivers (see
24498 section 6.23). If no authenticators are required, no authentication section
24499 need be present in the configuration file. Each authenticator can in principle
24500 have both server and client functions. When Exim is receiving SMTP mail, it is
24501 acting as a server; when it is sending out messages over SMTP, it is acting as
24502 a client. Authenticator configuration options are provided for use in both
24503 these circumstances.
24504
24505 To make it clear which options apply to which situation, the prefixes server_
24506 and client_ are used on option names that are specific to either the server or
24507 the client function, respectively. Server and client functions are disabled if
24508 none of their options are set. If an authenticator is to be used for both
24509 server and client functions, a single definition, using both sets of options,
24510 is required. For example:
24511
24512 cram:
24513 driver = cram_md5
24514 public_name = CRAM-MD5
24515 server_secret = ${if eq{$auth1}{ph10}{secret1}fail}
24516 client_name = ph10
24517 client_secret = secret2
24518
24519 The server_ option is used when Exim is acting as a server, and the client_
24520 options when it is acting as a client.
24521
24522 Descriptions of the individual authenticators are given in subsequent chapters.
24523 The remainder of this chapter covers the generic options for the
24524 authenticators, followed by general discussion of the way authentication works
24525 in Exim.
24526
24527 Beware: the meaning of $auth1, $auth2, ... varies on a per-driver and
24528 per-mechanism basis. Please read carefully to determine which variables hold
24529 account labels such as usercodes and which hold passwords or other
24530 authenticating data.
24531
24532 Note that some mechanisms support two different identifiers for accounts: the
24533 authentication id and the authorization id. The contractions authn and authz
24534 are commonly encountered. The American spelling is standard here. Conceptually,
24535 authentication data such as passwords are tied to the identifier used to
24536 authenticate; servers may have rules to permit one user to act as a second
24537 user, so that after login the session is treated as though that second user had
24538 logged in. That second user is the authorization id. A robust configuration
24539 might confirm that the authz field is empty or matches the authn field. Often
24540 this is just ignored. The authn can be considered as verified data, the authz
24541 as an unverified request which the server might choose to honour.
24542
24543 A realm is a text string, typically a domain name, presented by a server to a
24544 client to help it select an account and credentials to use. In some mechanisms,
24545 the client and server provably agree on the realm, but clients typically can
24546 not treat the realm as secure data to be blindly trusted.
24547
24548
24549 33.1 Generic options for authenticators
24550 ---------------------------------------
24551
24552 +-----------------------------------------------------------------+
24553 |client_condition|Use: authenticators|Type: string*|Default: unset|
24554 +-----------------------------------------------------------------+
24555
24556 When Exim is authenticating as a client, it skips any authenticator whose
24557 client_condition expansion yields "0", "no", or "false". This can be used, for
24558 example, to skip plain text authenticators when the connection is not encrypted
24559 by a setting such as:
24560
24561 client_condition = ${if !eq{$tls_out_cipher}{}}
24562
24563 +--------------------------------------------------------------+
24564 |client_set_id|Use: authenticators|Type: string*|Default: unset|
24565 +--------------------------------------------------------------+
24566
24567 When client authentication succeeds, this condition is expanded; the result is
24568 used in the log lines for outbound messages. Typically it will be the user name
24569 used for authentication.
24570
24571 +------------------------------------------------------+
24572 |driver|Use: authenticators|Type: string|Default: unset|
24573 +------------------------------------------------------+
24574
24575 This option must always be set. It specifies which of the available
24576 authenticators is to be used.
24577
24578 +-----------------------------------------------------------+
24579 |public_name|Use: authenticators|Type: string|Default: unset|
24580 +-----------------------------------------------------------+
24581
24582 This option specifies the name of the authentication mechanism that the driver
24583 implements, and by which it is known to the outside world. These names should
24584 contain only upper case letters, digits, underscores, and hyphens (RFC 2222),
24585 but Exim in fact matches them caselessly. If public_name is not set, it
24586 defaults to the driver's instance name.
24587
24588 +---------------------------------------------------------------------------+
24589 |server_advertise_condition|Use: authenticators|Type: string*|Default: unset|
24590 +---------------------------------------------------------------------------+
24591
24592 When a server is about to advertise an authentication mechanism, the condition
24593 is expanded. If it yields the empty string, "0", "no", or "false", the
24594 mechanism is not advertised. If the expansion fails, the mechanism is not
24595 advertised. If the failure was not forced, and was not caused by a lookup
24596 defer, the incident is logged. See section 33.3 below for further discussion.
24597
24598 +-----------------------------------------------------------------+
24599 |server_condition|Use: authenticators|Type: string*|Default: unset|
24600 +-----------------------------------------------------------------+
24601
24602 This option must be set for a plaintext server authenticator, where it is used
24603 directly to control authentication. See section 34.2 for details.
24604
24605 For the gsasl authenticator, this option is required for various mechanisms;
24606 see chapter 38 for details.
24607
24608 For the other authenticators, server_condition can be used as an additional
24609 authentication or authorization mechanism that is applied after the other
24610 authenticator conditions succeed. If it is set, it is expanded when the
24611 authenticator would otherwise return a success code. If the expansion is forced
24612 to fail, authentication fails. Any other expansion failure causes a temporary
24613 error code to be returned. If the result of a successful expansion is an empty
24614 string, "0", "no", or "false", authentication fails. If the result of the
24615 expansion is "1", "yes", or "true", authentication succeeds. For any other
24616 result, a temporary error code is returned, with the expanded string as the
24617 error text.
24618
24619 +-------------------------------------------------------------------+
24620 |server_debug_print|Use: authenticators|Type: string*|Default: unset|
24621 +-------------------------------------------------------------------+
24622
24623 If this option is set and authentication debugging is enabled (see the -d
24624 command line option), the string is expanded and included in the debugging
24625 output when the authenticator is run as a server. This can help with checking
24626 out the values of variables. If expansion of the string fails, the error
24627 message is written to the debugging output, and Exim carries on processing.
24628
24629 +--------------------------------------------------------------+
24630 |server_set_id|Use: authenticators|Type: string*|Default: unset|
24631 +--------------------------------------------------------------+
24632
24633 When an Exim server successfully authenticates a client, this string is
24634 expanded using data from the authentication, and preserved for any incoming
24635 messages in the variable $authenticated_id. It is also included in the log
24636 lines for incoming messages. For example, a user/password authenticator
24637 configuration might preserve the user name that was used to authenticate, and
24638 refer to it subsequently during delivery of the message. On a failing
24639 authentication the expansion result is instead saved in the
24640 $authenticated_fail_id variable. If expansion fails, the option is ignored.
24641
24642 +---------------------------------------------------------------------------+
24643 |server_mail_auth_condition|Use: authenticators|Type: string*|Default: unset|
24644 +---------------------------------------------------------------------------+
24645
24646 This option allows a server to discard authenticated sender addresses supplied
24647 as part of MAIL commands in SMTP connections that are authenticated by the
24648 driver on which server_mail_auth_condition is set. The option is not used as
24649 part of the authentication process; instead its (unexpanded) value is
24650 remembered for later use. How it is used is described in the following section.
24651
24652
24653 33.2 The AUTH parameter on MAIL commands
24654 ----------------------------------------
24655
24656 When a client supplied an AUTH= item on a MAIL command, Exim applies the
24657 following checks before accepting it as the authenticated sender of the
24658 message:
24659
24660 * If the connection is not using extended SMTP (that is, HELO was used rather
24661 than EHLO), the use of AUTH= is a syntax error.
24662
24663 * If the value of the AUTH= parameter is "<>", it is ignored.
24664
24665 * If acl_smtp_mailauth is defined, the ACL it specifies is run. While it is
24666 running, the value of $authenticated_sender is set to the value obtained
24667 from the AUTH= parameter. If the ACL does not yield "accept", the value of
24668 $authenticated_sender is deleted. The acl_smtp_mailauth ACL may not return
24669 "drop" or "discard". If it defers, a temporary error code (451) is given
24670 for the MAIL command.
24671
24672 * If acl_smtp_mailauth is not defined, the value of the AUTH= parameter is
24673 accepted and placed in $authenticated_sender only if the client has
24674 authenticated.
24675
24676 * If the AUTH= value was accepted by either of the two previous rules, and
24677 the client has authenticated, and the authenticator has a setting for the
24678 server_mail_auth_condition, the condition is checked at this point. The
24679 valued that was saved from the authenticator is expanded. If the expansion
24680 fails, or yields an empty string, "0", "no", or "false", the value of
24681 $authenticated_sender is deleted. If the expansion yields any other value,
24682 the value of $authenticated_sender is retained and passed on with the
24683 message.
24684
24685 When $authenticated_sender is set for a message, it is passed on to other hosts
24686 to which Exim authenticates as a client. Do not confuse this value with
24687 $authenticated_id, which is a string obtained from the authentication process,
24688 and which is not usually a complete email address.
24689
24690 Whenever an AUTH= value is ignored, the incident is logged. The ACL for MAIL,
24691 if defined, is run after AUTH= is accepted or ignored. It can therefore make
24692 use of $authenticated_sender. The converse is not true: the value of
24693 $sender_address is not yet set up when the acl_smtp_mailauth ACL is run.
24694
24695
24696 33.3 Authentication on an Exim server
24697 -------------------------------------
24698
24699 When Exim receives an EHLO command, it advertises the public names of those
24700 authenticators that are configured as servers, subject to the following
24701 conditions:
24702
24703 * The client host must match auth_advertise_hosts (default *).
24704
24705 * It the server_advertise_condition option is set, its expansion must not
24706 yield the empty string, "0", "no", or "false".
24707
24708 The order in which the authenticators are defined controls the order in which
24709 the mechanisms are advertised.
24710
24711 Some mail clients (for example, some versions of Netscape) require the user to
24712 provide a name and password for authentication whenever AUTH is advertised,
24713 even though authentication may not in fact be needed (for example, Exim may be
24714 set up to allow unconditional relaying from the client by an IP address check).
24715 You can make such clients more friendly by not advertising AUTH to them. For
24716 example, if clients on the 10.9.8.0/24 network are permitted (by the ACL that
24717 runs for RCPT) to relay without authentication, you should set
24718
24719 auth_advertise_hosts = ! 10.9.8.0/24
24720
24721 so that no authentication mechanisms are advertised to them.
24722
24723 The server_advertise_condition controls the advertisement of individual
24724 authentication mechanisms. For example, it can be used to restrict the
24725 advertisement of a particular mechanism to encrypted connections, by a setting
24726 such as:
24727
24728 server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}}
24729
24730 If the session is encrypted, $tls_in_cipher is not empty, and so the expansion
24731 yields "yes", which allows the advertisement to happen.
24732
24733 When an Exim server receives an AUTH command from a client, it rejects it
24734 immediately if AUTH was not advertised in response to an earlier EHLO command.
24735 This is the case if
24736
24737 * The client host does not match auth_advertise_hosts; or
24738
24739 * No authenticators are configured with server options; or
24740
24741 * Expansion of server_advertise_condition blocked the advertising of all the
24742 server authenticators.
24743
24744 Otherwise, Exim runs the ACL specified by acl_smtp_auth in order to decide
24745 whether to accept the command. If acl_smtp_auth is not set, AUTH is accepted
24746 from any client host.
24747
24748 If AUTH is not rejected by the ACL, Exim searches its configuration for a
24749 server authentication mechanism that was advertised in response to EHLO and
24750 that matches the one named in the AUTH command. If it finds one, it runs the
24751 appropriate authentication protocol, and authentication either succeeds or
24752 fails. If there is no matching advertised mechanism, the AUTH command is
24753 rejected with a 504 error.
24754
24755 When a message is received from an authenticated host, the value of
24756 $received_protocol is set to "esmtpa" or "esmtpsa" instead of "esmtp" or
24757 "esmtps", and $sender_host_authenticated contains the name (not the public
24758 name) of the authenticator driver that successfully authenticated the client
24759 from which the message was received. This variable is empty if there was no
24760 successful authentication.
24761
24762 Successful authentication sets up information used by the $authresults
24763 expansion item.
24764
24765
24766 33.4 Testing server authentication
24767 ----------------------------------
24768
24769 Exim's -bh option can be useful for testing server authentication
24770 configurations. The data for the AUTH command has to be sent using base64
24771 encoding. A quick way to produce such data for testing is the following Perl
24772 script:
24773
24774 use MIME::Base64;
24775 printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
24776
24777 This interprets its argument as a Perl string, and then encodes it. The
24778 interpretation as a Perl string allows binary zeros, which are required for
24779 some kinds of authentication, to be included in the data. For example, a
24780 command line to run this script on such data might be
24781
24782 encode '\0user\0password'
24783
24784 Note the use of single quotes to prevent the shell interpreting the
24785 backslashes, so that they can be interpreted by Perl to specify characters
24786 whose code value is zero.
24787
24788 Warning 1: If either of the user or password strings starts with an octal
24789 digit, you must use three zeros instead of one after the leading backslash. If
24790 you do not, the octal digit that starts your string will be incorrectly
24791 interpreted as part of the code for the first character.
24792
24793 Warning 2: If there are characters in the strings that Perl interprets
24794 specially, you must use a Perl escape to prevent them being misinterpreted. For
24795 example, a command such as
24796
24797 encode '\0user@domain.com\0pas$$word'
24798
24799 gives an incorrect answer because of the unescaped "@" and "$" characters.
24800
24801 If you have the mimencode command installed, another way to do produce
24802 base64-encoded strings is to run the command
24803
24804 echo -e -n `\0user\0password' | mimencode
24805
24806 The -e option of echo enables the interpretation of backslash escapes in the
24807 argument, and the -n option specifies no newline at the end of its output.
24808 However, not all versions of echo recognize these options, so you should check
24809 your version before relying on this suggestion.
24810
24811
24812 33.5 Authentication by an Exim client
24813 -------------------------------------
24814
24815 The smtp transport has two options called hosts_require_auth and hosts_try_auth
24816 . When the smtp transport connects to a server that announces support for
24817 authentication, and the host matches an entry in either of these options, Exim
24818 (as a client) tries to authenticate as follows:
24819
24820 * For each authenticator that is configured as a client, in the order in
24821 which they are defined in the configuration, it searches the authentication
24822 mechanisms announced by the server for one whose name matches the public
24823 name of the authenticator.
24824
24825 * When it finds one that matches, it runs the authenticator's client code.
24826 The variables $host and $host_address are available for any string
24827 expansions that the client might do. They are set to the server's name and
24828 IP address. If any expansion is forced to fail, the authentication attempt
24829 is abandoned, and Exim moves on to the next authenticator. Otherwise an
24830 expansion failure causes delivery to be deferred.
24831
24832 * If the result of the authentication attempt is a temporary error or a
24833 timeout, Exim abandons trying to send the message to the host for the
24834 moment. It will try again later. If there are any backup hosts available,
24835 they are tried in the usual way.
24836
24837 * If the response to authentication is a permanent error (5xx code), Exim
24838 carries on searching the list of authenticators and tries another one if
24839 possible. If all authentication attempts give permanent errors, or if there
24840 are no attempts because no mechanisms match (or option expansions force
24841 failure), what happens depends on whether the host matches
24842 hosts_require_auth or hosts_try_auth. In the first case, a temporary error
24843 is generated, and delivery is deferred. The error can be detected in the
24844 retry rules, and thereby turned into a permanent error if you wish. In the
24845 second case, Exim tries to deliver the message unauthenticated.
24846
24847 Note that the hostlist test for whether to do authentication can be confused if
24848 name-IP lookups change between the time the peer is decided upon and the time
24849 that the transport runs. For example, with a manualroute router given a host
24850 name, and with DNS "round-robin" used by that name: if the local resolver cache
24851 times out between the router and the transport running, the transport may get
24852 an IP for the name for its authentication check which does not match the
24853 connection peer IP. No authentication will then be done, despite the names
24854 being identical.
24855
24856 For such cases use a separate transport which always authenticates.
24857
24858 When Exim has authenticated itself to a remote server, it adds the AUTH
24859 parameter to the MAIL commands it sends, if it has an authenticated sender for
24860 the message. If the message came from a remote host, the authenticated sender
24861 is the one that was receiving on an incoming MAIL command, provided that the
24862 incoming connection was authenticated and the server_mail_auth condition
24863 allowed the authenticated sender to be retained. If a local process calls Exim
24864 to send a message, the sender address that is built from the login name and
24865 qualify_domain is treated as authenticated. However, if the
24866 authenticated_sender option is set on the smtp transport, it overrides the
24867 authenticated sender that was received with the message.
24868
24869
24870
24871 ===============================================================================
24872 34. THE PLAINTEXT AUTHENTICATOR
24873
24874 The plaintext authenticator can be configured to support the PLAIN and LOGIN
24875 authentication mechanisms, both of which transfer authentication data as plain
24876 (unencrypted) text (though base64 encoded). The use of plain text is a security
24877 risk; you are strongly advised to insist on the use of SMTP encryption (see
24878 chapter 42) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted
24879 plain text, you should not use the same passwords for SMTP connections as you
24880 do for login accounts.
24881
24882
24883 34.1 Plaintext options
24884 ----------------------
24885
24886 When configured as a server, plaintext uses the following options:
24887
24888 +-----------------------------------------------------------------+
24889 |server_condition|Use: authenticators|Type: string*|Default: unset|
24890 +-----------------------------------------------------------------+
24891
24892 This is actually a global authentication option, but it must be set in order to
24893 configure the plaintext driver as a server. Its use is described below.
24894
24895 +----------------------------------------------------------+
24896 |server_prompts|Use: plaintext|Type: string*|Default: unset|
24897 +----------------------------------------------------------+
24898
24899 The contents of this option, after expansion, must be a colon-separated list of
24900 prompt strings. If expansion fails, a temporary authentication rejection is
24901 given.
24902
24903
24904 34.2 Using plaintext in a server
24905 --------------------------------
24906
24907 When running as a server, plaintext performs the authentication test by
24908 expanding a string. The data sent by the client with the AUTH command, or in
24909 response to subsequent prompts, is base64 encoded, and so may contain any byte
24910 values when decoded. If any data is supplied with the command, it is treated as
24911 a list of strings, separated by NULs (binary zeros), the first three of which
24912 are placed in the expansion variables $auth1, $auth2, and $auth3 (neither LOGIN
24913 nor PLAIN uses more than three strings).
24914
24915 For compatibility with previous releases of Exim, the values are also placed in
24916 the expansion variables $1, $2, and $3. However, the use of these variables for
24917 this purpose is now deprecated, as it can lead to confusion in string
24918 expansions that also use them for other things.
24919
24920 If there are more strings in server_prompts than the number of strings supplied
24921 with the AUTH command, the remaining prompts are used to obtain more data. Each
24922 response from the client may be a list of NUL-separated strings.
24923
24924 Once a sufficient number of data strings have been received, server_condition
24925 is expanded. If the expansion is forced to fail, authentication fails. Any
24926 other expansion failure causes a temporary error code to be returned. If the
24927 result of a successful expansion is an empty string, "0", "no", or "false",
24928 authentication fails. If the result of the expansion is "1", "yes", or "true",
24929 authentication succeeds and the generic server_set_id option is expanded and
24930 saved in $authenticated_id. For any other result, a temporary error code is
24931 returned, with the expanded string as the error text.
24932
24933 Warning: If you use a lookup in the expansion to find the user's password, be
24934 sure to make the authentication fail if the user is unknown. There are good and
24935 bad examples at the end of the next section.
24936
24937
24938 34.3 The PLAIN authentication mechanism
24939 ---------------------------------------
24940
24941 The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
24942 sent as one item of data (that is, one combined string containing two NUL
24943 separators). The data is sent either as part of the AUTH command, or
24944 subsequently in response to an empty prompt from the server.
24945
24946 The second and third strings are a user name and a corresponding password.
24947 Using a single fixed user name and password as an example, this could be
24948 configured as follows:
24949
24950 fixed_plain:
24951 driver = plaintext
24952 public_name = PLAIN
24953 server_prompts = :
24954 server_condition = \
24955 ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}}
24956 server_set_id = $auth2
24957
24958 Note that the default result strings from if ("true" or an empty string) are
24959 exactly what we want here, so they need not be specified. Obviously, if the
24960 password contains expansion-significant characters such as dollar, backslash,
24961 or closing brace, they have to be escaped.
24962
24963 The server_prompts setting specifies a single, empty prompt (empty items at the
24964 end of a string list are ignored). If all the data comes as part of the AUTH
24965 command, as is commonly the case, the prompt is not used. This authenticator is
24966 advertised in the response to EHLO as
24967
24968 250-AUTH PLAIN
24969
24970 and a client host can authenticate itself by sending the command
24971
24972 AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0
24973
24974 As this contains three strings (more than the number of prompts), no further
24975 data is required from the client. Alternatively, the client may just send
24976
24977 AUTH PLAIN
24978
24979 to initiate authentication, in which case the server replies with an empty
24980 prompt. The client must respond with the combined data string.
24981
24982 The data string is base64 encoded, as required by the RFC. This example, when
24983 decoded, is <NUL>"username"<NUL>"mysecret", where <NUL> represents a zero byte.
24984 This is split up into three strings, the first of which is empty. The
24985 server_condition option in the authenticator checks that the second two are
24986 "username" and "mysecret" respectively.
24987
24988 Having just one fixed user name and password, as in this example, is not very
24989 realistic, though for a small organization with only a handful of
24990 authenticating clients it could make sense.
24991
24992 A more sophisticated instance of this authenticator could use the user name in
24993 $auth2 to look up a password in a file or database, and maybe do an encrypted
24994 comparison (see crypteq in chapter 11). Here is a example of this approach,
24995 where the passwords are looked up in a DBM file. Warning: This is an incorrect
24996 example:
24997
24998 server_condition = \
24999 ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}}
25000
25001 The expansion uses the user name ($auth2) as the key to look up a password,
25002 which it then compares to the supplied password ($auth3). Why is this example
25003 incorrect? It works fine for existing users, but consider what happens if a
25004 non-existent user name is given. The lookup fails, but as no success/failure
25005 strings are given for the lookup, it yields an empty string. Thus, to defeat
25006 the authentication, all a client has to do is to supply a non-existent user
25007 name and an empty password. The correct way of writing this test is:
25008
25009 server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
25010 {${if eq{$value}{$auth3}}} {false}}
25011
25012 In this case, if the lookup succeeds, the result is checked; if the lookup
25013 fails, "false" is returned and authentication fails. If crypteq is being used
25014 instead of eq, the first example is in fact safe, because crypteq always fails
25015 if its second argument is empty. However, the second way of writing the test
25016 makes the logic clearer.
25017
25018
25019 34.4 The LOGIN authentication mechanism
25020 ---------------------------------------
25021
25022 The LOGIN authentication mechanism is not documented in any RFC, but is in use
25023 in a number of programs. No data is sent with the AUTH command. Instead, a user
25024 name and password are supplied separately, in response to prompts. The
25025 plaintext authenticator can be configured to support this as in this example:
25026
25027 fixed_login:
25028 driver = plaintext
25029 public_name = LOGIN
25030 server_prompts = User Name : Password
25031 server_condition = \
25032 ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}}
25033 server_set_id = $auth1
25034
25035 Because of the way plaintext operates, this authenticator accepts data supplied
25036 with the AUTH command (in contravention of the specification of LOGIN), but if
25037 the client does not supply it (as is the case for LOGIN clients), the prompt
25038 strings are used to obtain two data items.
25039
25040 Some clients are very particular about the precise text of the prompts. For
25041 example, Outlook Express is reported to recognize only "Username:" and
25042 "Password:". Here is an example of a LOGIN authenticator that uses those
25043 strings. It uses the ldapauth expansion condition to check the user name and
25044 password by binding to an LDAP server:
25045
25046 login:
25047 driver = plaintext
25048 public_name = LOGIN
25049 server_prompts = Username:: : Password::
25050 server_condition = ${if and{{ \
25051 !eq{}{$auth1} }{ \
25052 ldapauth{\
25053 user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
25054 pass=${quote:$auth2} \
25055 ldap://ldap.example.org/} }} }
25056 server_set_id = uid=$auth1,ou=people,o=example.org
25057
25058 We have to check that the username is not empty before using it, because LDAP
25059 does not permit empty DN components. We must also use the quote_ldap_dn
25060 operator to correctly quote the DN for authentication. However, the basic quote
25061 operator, rather than any of the LDAP quoting operators, is the correct one to
25062 use for the password, because quoting is needed only to make the password
25063 conform to the Exim syntax. At the LDAP level, the password is an uninterpreted
25064 string.
25065
25066
25067 34.5 Support for different kinds of authentication
25068 --------------------------------------------------
25069
25070 A number of string expansion features are provided for the purpose of
25071 interfacing to different ways of user authentication. These include checking
25072 traditionally encrypted passwords from /etc/passwd (or equivalent), PAM,
25073 Radius, ldapauth, pwcheck, and saslauthd. For details see section 11.7.
25074
25075
25076 34.6 Using plaintext in a client
25077 --------------------------------
25078
25079 The plaintext authenticator has two client options:
25080
25081 +------------------------------------------------------------------------+
25082 |client_ignore_invalid_base64|Use: plaintext|Type: boolean|Default: false|
25083 +------------------------------------------------------------------------+
25084
25085 If the client receives a server prompt that is not a valid base64 string,
25086 authentication is abandoned by default. However, if this option is set true,
25087 the error in the challenge is ignored and the client sends the response as
25088 usual.
25089
25090 +-------------------------------------------------------+
25091 |client_send|Use: plaintext|Type: string*|Default: unset|
25092 +-------------------------------------------------------+
25093
25094 The string is a colon-separated list of authentication data strings. Each
25095 string is independently expanded before being sent to the server. The first
25096 string is sent with the AUTH command; any more strings are sent in response to
25097 prompts from the server. Before each string is expanded, the value of the most
25098 recent prompt is placed in the next $auth<n> variable, starting with $auth1 for
25099 the first prompt. Up to three prompts are stored in this way. Thus, the prompt
25100 that is received in response to sending the first string (with the AUTH
25101 command) can be used in the expansion of the second string, and so on. If an
25102 invalid base64 string is received when client_ignore_invalid_base64 is set, an
25103 empty string is put in the $auth<n> variable.
25104
25105 Note: You cannot use expansion to create multiple strings, because splitting
25106 takes priority and happens first.
25107
25108 Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in
25109 the data, further processing is applied to each string before it is sent. If
25110 there are any single circumflex characters in the string, they are converted to
25111 NULs. Should an actual circumflex be required as data, it must be doubled in
25112 the string.
25113
25114 This is an example of a client configuration that implements the PLAIN
25115 authentication mechanism with a fixed user name and password:
25116
25117 fixed_plain:
25118 driver = plaintext
25119 public_name = PLAIN
25120 client_send = ^username^mysecret
25121
25122 The lack of colons means that the entire text is sent with the AUTH command,
25123 with the circumflex characters converted to NULs. A similar example that uses
25124 the LOGIN mechanism is:
25125
25126 fixed_login:
25127 driver = plaintext
25128 public_name = LOGIN
25129 client_send = : username : mysecret
25130
25131 The initial colon means that the first string is empty, so no data is sent with
25132 the AUTH command itself. The remaining strings are sent in response to prompts.
25133
25134
25135
25136 ===============================================================================
25137 35. THE CRAM_MD5 AUTHENTICATOR
25138
25139 The CRAM-MD5 authentication mechanism is described in RFC 2195. The server
25140 sends a challenge string to the client, and the response consists of a user
25141 name and the CRAM-MD5 digest of the challenge string combined with a secret
25142 string (password) which is known to both server and client. Thus, the secret is
25143 not sent over the network as plain text, which makes this authenticator more
25144 secure than plaintext. However, the downside is that the secret has to be
25145 available in plain text at either end.
25146
25147
25148 35.1 Using cram_md5 as a server
25149 -------------------------------
25150
25151 This authenticator has one server option, which must be set to configure the
25152 authenticator as a server:
25153
25154 +--------------------------------------------------------+
25155 |server_secret|Use: cram_md5|Type: string*|Default: unset|
25156 +--------------------------------------------------------+
25157
25158 When the server receives the client's response, the user name is placed in the
25159 expansion variable $auth1, and server_secret is expanded to obtain the password
25160 for that user. The server then computes the CRAM-MD5 digest that the client
25161 should have sent, and checks that it received the correct string. If the
25162 expansion of server_secret is forced to fail, authentication fails. If the
25163 expansion fails for some other reason, a temporary error code is returned to
25164 the client.
25165
25166 For compatibility with previous releases of Exim, the user name is also placed
25167 in $1. However, the use of this variables for this purpose is now deprecated,
25168 as it can lead to confusion in string expansions that also use numeric
25169 variables for other things.
25170
25171 For example, the following authenticator checks that the user name given by the
25172 client is "ph10", and if so, uses "secret" as the password. For any other user
25173 name, authentication fails.
25174
25175 fixed_cram:
25176 driver = cram_md5
25177 public_name = CRAM-MD5
25178 server_secret = ${if eq{$auth1}{ph10}{secret}fail}
25179 server_set_id = $auth1
25180
25181 If authentication succeeds, the setting of server_set_id preserves the user
25182 name in $authenticated_id. A more typical configuration might look up the
25183 secret string in a file, using the user name as the key. For example:
25184
25185 lookup_cram:
25186 driver = cram_md5
25187 public_name = CRAM-MD5
25188 server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\
25189 {$value}fail}
25190 server_set_id = $auth1
25191
25192 Note that this expansion explicitly forces failure if the lookup fails because
25193 $auth1 contains an unknown user name.
25194
25195 As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
25196 using the relevant libraries, you need to know the realm to specify in the
25197 lookup and then ask for the "userPassword" attribute for that user in that
25198 realm, with:
25199
25200 cyrusless_crammd5:
25201 driver = cram_md5
25202 public_name = CRAM-MD5
25203 server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
25204 dbmjz{/etc/sasldb2}{$value}fail}
25205 server_set_id = $auth1
25206
25207
25208 35.2 Using cram_md5 as a client
25209 -------------------------------
25210
25211 When used as a client, the cram_md5 authenticator has two options:
25212
25213 +----------------------------------------------------------------------+
25214 |client_name|Use: cram_md5|Type: string*|Default: the primary host name|
25215 +----------------------------------------------------------------------+
25216
25217 This string is expanded, and the result used as the user name data when
25218 computing the response to the server's challenge.
25219
25220 +--------------------------------------------------------+
25221 |client_secret|Use: cram_md5|Type: string*|Default: unset|
25222 +--------------------------------------------------------+
25223
25224 This option must be set for the authenticator to work as a client. Its value is
25225 expanded and the result used as the secret string when computing the response.
25226
25227 Different user names and secrets can be used for different servers by referring
25228 to $host or $host_address in the options. Forced failure of either expansion
25229 string is treated as an indication that this authenticator is not prepared to
25230 handle this case. Exim moves on to the next configured client authenticator.
25231 Any other expansion failure causes Exim to give up trying to send the message
25232 to the current server.
25233
25234 A simple example configuration of a cram_md5 authenticator, using fixed
25235 strings, is:
25236
25237 fixed_cram:
25238 driver = cram_md5
25239 public_name = CRAM-MD5
25240 client_name = ph10
25241 client_secret = secret
25242
25243
25244
25245 ===============================================================================
25246 36. THE CYRUS_SASL AUTHENTICATOR
25247
25248 The code for this authenticator was provided by Matthew Byng-Maddick while at A
25249 L Digital Ltd.
25250
25251 The cyrus_sasl authenticator provides server support for the Cyrus SASL library
25252 implementation of the RFC 2222 ("Simple Authentication and Security Layer").
25253 This library supports a number of authentication mechanisms, including PLAIN
25254 and LOGIN, but also several others that Exim does not support directly. In
25255 particular, there is support for Kerberos authentication.
25256
25257 The cyrus_sasl authenticator provides a gatewaying mechanism directly to the
25258 Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, then
25259 so can the cyrus_sasl authenticator. By default it uses the public name of the
25260 driver to determine which mechanism to support.
25261
25262 Where access to some kind of secret file is required, for example, in GSSAPI or
25263 CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and
25264 that the Cyrus SASL library has no way of escalating privileges by default. You
25265 may also find you need to set environment variables, depending on the driver
25266 you are using.
25267
25268 The application name provided by Exim is "exim", so various SASL options may be
25269 set in exim.conf in your SASL directory. If you are using GSSAPI for Kerberos,
25270 note that because of limitations in the GSSAPI interface, changing the server
25271 keytab might need to be communicated down to the Kerberos layer independently.
25272 The mechanism for doing so is dependent upon the Kerberos implementation.
25273
25274 For example, for older releases of Heimdal, the environment variable
25275 KRB5_KTNAME may be set to point to an alternative keytab file. Exim will pass
25276 this variable through from its own inherited environment when started as root
25277 or the Exim user. The keytab file needs to be readable by the Exim user. With
25278 newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
25279 environment variable. In practice, for those releases, the Cyrus authenticator
25280 is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider
25281 the heimdal_gssapi authenticator, described in chapter 39
25282
25283
25284 36.1 Using cyrus_sasl as a server
25285 ---------------------------------
25286
25287 The cyrus_sasl authenticator has four private options. It puts the username (on
25288 a successful authentication) into $auth1. For compatibility with previous
25289 releases of Exim, the username is also placed in $1. However, the use of this
25290 variable for this purpose is now deprecated, as it can lead to confusion in
25291 string expansions that also use numeric variables for other things.
25292
25293 +----------------------------------------------------------------+
25294 |server_hostname|Use: cyrus_sasl|Type: string*|Default: see below|
25295 +----------------------------------------------------------------+
25296
25297 This option selects the hostname that is used when communicating with the
25298 library. The default value is "$primary_hostname". It is up to the underlying
25299 SASL plug-in what it does with this data.
25300
25301 +-----------------------------------------------------------+
25302 |server_mech|Use: cyrus_sasl|Type: string|Default: see below|
25303 +-----------------------------------------------------------+
25304
25305 This option selects the authentication mechanism this driver should use. The
25306 default is the value of the generic public_name option. This option allows you
25307 to use a different underlying mechanism from the advertised name. For example:
25308
25309 sasl:
25310 driver = cyrus_sasl
25311 public_name = X-ANYTHING
25312 server_mech = CRAM-MD5
25313 server_set_id = $auth1
25314
25315 +---------------------------------------------------------+
25316 |server_realm|Use: cyrus_sasl|Type: string*|Default: unset|
25317 +---------------------------------------------------------+
25318
25319 This specifies the SASL realm that the server claims to be in.
25320
25321 +-----------------------------------------------------------+
25322 |server_service|Use: cyrus_sasl|Type: string|Default: "smtp"|
25323 +-----------------------------------------------------------+
25324
25325 This is the SASL service that the server claims to implement.
25326
25327 For straightforward cases, you do not need to set any of the authenticator's
25328 private options. All you need to do is to specify an appropriate mechanism as
25329 the public name. Thus, if you have a SASL library that supports CRAM-MD5 and
25330 PLAIN, you could have two authenticators as follows:
25331
25332 sasl_cram_md5:
25333 driver = cyrus_sasl
25334 public_name = CRAM-MD5
25335 server_set_id = $auth1
25336
25337 sasl_plain:
25338 driver = cyrus_sasl
25339 public_name = PLAIN
25340 server_set_id = $auth2
25341
25342 Cyrus SASL does implement the LOGIN authentication method, even though it is
25343 not a standard method. It is disabled by default in the source distribution,
25344 but it is present in many binary distributions.
25345
25346
25347
25348 ===============================================================================
25349 37. THE DOVECOT AUTHENTICATOR
25350
25351 This authenticator is an interface to the authentication facility of the
25352 Dovecot POP/IMAP server, which can support a number of authentication methods.
25353 Note that Dovecot must be configured to use auth-client not auth-userdb. If you
25354 are using Dovecot to authenticate POP/IMAP clients, it might be helpful to use
25355 the same mechanisms for SMTP authentication. This is a server authenticator
25356 only. There is only one option:
25357
25358 +------------------------------------------------------+
25359 |server_socket|Use: dovecot|Type: string|Default: unset|
25360 +------------------------------------------------------+
25361
25362 This option must specify the UNIX socket that is the interface to Dovecot
25363 authentication. The public_name option must specify an authentication mechanism
25364 that Dovecot is configured to support. You can have several authenticators for
25365 different mechanisms. For example:
25366
25367 dovecot_plain:
25368 driver = dovecot
25369 public_name = PLAIN
25370 server_socket = /var/run/dovecot/auth-client
25371 server_set_id = $auth1
25372
25373 dovecot_ntlm:
25374 driver = dovecot
25375 public_name = NTLM
25376 server_socket = /var/run/dovecot/auth-client
25377 server_set_id = $auth1
25378
25379 If the SMTP connection is encrypted, or if $sender_host_address is equal to
25380 $received_ip_address (that is, the connection is local), the "secured" option
25381 is passed in the Dovecot authentication command. If, for a TLS connection, a
25382 client certificate has been verified, the "valid-client-cert" option is passed.
25383 When authentication succeeds, the identity of the user who authenticated is
25384 placed in $auth1.
25385
25386
25387
25388 ===============================================================================
25389 38. THE GSASL AUTHENTICATOR
25390
25391 The gsasl authenticator provides server integration for the GNU SASL library
25392 and the mechanisms it provides. This is new as of the 4.80 release and there
25393 are a few areas where the library does not let Exim smoothly scale to handle
25394 future authentication mechanisms, so no guarantee can be made that any
25395 particular new authentication mechanism will be supported without code changes
25396 in Exim.
25397
25398 Exim's gsasl authenticator does not have client-side support at this time; only
25399 the server-side support is implemented. Patches welcome.
25400
25401 +-------------------------------------------------------------+
25402 |server_channelbinding|Use: gsasl|Type: boolean|Default: false|
25403 +-------------------------------------------------------------+
25404
25405 Do not set this true without consulting a cryptographic engineer.
25406
25407 Some authentication mechanisms are able to use external context at both ends of
25408 the session to bind the authentication to that context, and fail the
25409 authentication process if that context differs. Specifically, some TLS
25410 ciphersuites can provide identifying information about the cryptographic
25411 context.
25412
25413 This should have meant that certificate identity and verification becomes a
25414 non-issue, as a man-in-the-middle attack will cause the correct client and
25415 server to see different identifiers and authentication will fail.
25416
25417 This is currently only supported when using the GnuTLS library. This is only
25418 usable by mechanisms which support "channel binding"; at time of writing,
25419 that's the SCRAM family.
25420
25421 This defaults off to ensure smooth upgrade across Exim releases, in case this
25422 option causes some clients to start failing. Some future release of Exim might
25423 have switched the default to be true.
25424
25425 However, Channel Binding in TLS has proven to be broken in current versions. Do
25426 not plan to rely upon this feature for security, ever, without consulting with
25427 a subject matter expert (a cryptographic engineer).
25428
25429 +-----------------------------------------------------------+
25430 |server_hostname|Use: gsasl|Type: string*|Default: see below|
25431 +-----------------------------------------------------------+
25432
25433 This option selects the hostname that is used when communicating with the
25434 library. The default value is "$primary_hostname". Some mechanisms will use
25435 this data.
25436
25437 +------------------------------------------------------+
25438 |server_mech|Use: gsasl|Type: string|Default: see below|
25439 +------------------------------------------------------+
25440
25441 This option selects the authentication mechanism this driver should use. The
25442 default is the value of the generic public_name option. This option allows you
25443 to use a different underlying mechanism from the advertised name. For example:
25444
25445 sasl:
25446 driver = gsasl
25447 public_name = X-ANYTHING
25448 server_mech = CRAM-MD5
25449 server_set_id = $auth1
25450
25451 +-------------------------------------------------------+
25452 |server_password|Use: gsasl|Type: string*|Default: unset|
25453 +-------------------------------------------------------+
25454
25455 Various mechanisms need access to the cleartext password on the server, so that
25456 proof-of-possession can be demonstrated on the wire, without sending the
25457 password itself.
25458
25459 The data available for lookup varies per mechanism. In all cases, $auth1 is set
25460 to the authentication id. The $auth2 variable will always be the authorization
25461 id (authz) if available, else the empty string. The $auth3 variable will always
25462 be the realm if available, else the empty string.
25463
25464 A forced failure will cause authentication to defer.
25465
25466 If using this option, it may make sense to set the server_condition option to
25467 be simply "true".
25468
25469 +----------------------------------------------------+
25470 |server_realm|Use: gsasl|Type: string*|Default: unset|
25471 +----------------------------------------------------+
25472
25473 This specifies the SASL realm that the server claims to be in. Some mechanisms
25474 will use this data.
25475
25476 +---------------------------------------------------------+
25477 |server_scram_iter|Use: gsasl|Type: string*|Default: unset|
25478 +---------------------------------------------------------+
25479
25480 This option provides data for the SCRAM family of mechanisms. $auth1 is not
25481 available at evaluation time. (This may change, as we receive feedback on use)
25482
25483 +---------------------------------------------------------+
25484 |server_scram_salt|Use: gsasl|Type: string*|Default: unset|
25485 +---------------------------------------------------------+
25486
25487 This option provides data for the SCRAM family of mechanisms. $auth1 is not
25488 available at evaluation time. (This may change, as we receive feedback on use)
25489
25490 +------------------------------------------------------+
25491 |server_service|Use: gsasl|Type: string|Default: "smtp"|
25492 +------------------------------------------------------+
25493
25494 This is the SASL service that the server claims to implement. Some mechanisms
25495 will use this data.
25496
25497
25498 38.1 gsasl auth variables
25499 -------------------------
25500
25501 These may be set when evaluating specific options, as detailed above. They will
25502 also be set when evaluating server_condition.
25503
25504 Unless otherwise stated below, the gsasl integration will use the following
25505 meanings for these variables:
25506
25507 * $auth1: the authentication id
25508
25509 * $auth2: the authorization id
25510
25511 * $auth3: the realm
25512
25513 On a per-mechanism basis:
25514
25515 * EXTERNAL: only $auth1 is set, to the possibly empty authorization id; the
25516 server_condition option must be present.
25517
25518 * ANONYMOUS: only $auth1 is set, to the possibly empty anonymous token; the
25519 server_condition option must be present.
25520
25521 * GSSAPI: $auth1 will be set to the GSSAPI Display Name; $auth2 will be set
25522 to the authorization id, the server_condition option must be present.
25523
25524 An anonymous token is something passed along as an unauthenticated identifier;
25525 this is analogous to FTP anonymous authentication passing an email address, or
25526 software-identifier@, as the "password".
25527
25528 An example showing the password having the realm specified in the callback and
25529 demonstrating a Cyrus SASL to GSASL migration approach is:
25530
25531 gsasl_cyrusless_crammd5:
25532 driver = gsasl
25533 public_name = CRAM-MD5
25534 server_realm = imap.example.org
25535 server_password = ${lookup{$auth1:$auth3:userPassword}\
25536 dbmjz{/etc/sasldb2}{$value}fail}
25537 server_set_id = ${quote:$auth1}
25538 server_condition = yes
25539
25540
25541
25542 ===============================================================================
25543 39. THE HEIMDAL_GSSAPI AUTHENTICATOR
25544
25545 The heimdal_gssapi authenticator provides server integration for the Heimdal
25546 GSSAPI/Kerberos library, permitting Exim to set a keytab pathname reliably.
25547
25548 +--------------------------------------------------------------------+
25549 |server_hostname|Use: heimdal_gssapi|Type: string*|Default: see below|
25550 +--------------------------------------------------------------------+
25551
25552 This option selects the hostname that is used, with server_service, for
25553 constructing the GSS server name, as a GSS_C_NT_HOSTBASED_SERVICE identifier.
25554 The default value is "$primary_hostname".
25555
25556 +--------------------------------------------------------------+
25557 |server_keytab|Use: heimdal_gssapi|Type: string*|Default: unset|
25558 +--------------------------------------------------------------+
25559
25560 If set, then Heimdal will not use the system default keytab (typically /etc/
25561 krb5.keytab) but instead the pathname given in this option. The value should be
25562 a pathname, with no "file:" prefix.
25563
25564 +--------------------------------------------------------------+
25565 |server_service|Use: heimdal_gssapi|Type: string*|Default: smtp|
25566 +--------------------------------------------------------------+
25567
25568 This option specifies the service identifier used, in conjunction with
25569 server_hostname, for building the identifier for finding credentials from the
25570 keytab.
25571
25572
25573 39.1 heimdal_gssapi auth variables
25574 ----------------------------------
25575
25576 Beware that these variables will typically include a realm, thus will appear to
25577 be roughly like an email address already. The authzid in $auth2 is not
25578 verified, so a malicious client can set it to anything.
25579
25580 The $auth1 field should be safely trustable as a value from the Key
25581 Distribution Center. Note that these are not quite email addresses. Each
25582 identifier is for a role, and so the left-hand-side may include a role suffix.
25583 For instance, "joe/admin@EXAMPLE.ORG".
25584
25585 * $auth1: the authentication id, set to the GSS Display Name.
25586
25587 * $auth2: the authorization id, sent within SASL encapsulation after
25588 authentication. If that was empty, this will also be set to the GSS Display
25589 Name.
25590
25591
25592
25593 ===============================================================================
25594 40. THE SPA AUTHENTICATOR
25595
25596 The spa authenticator provides client support for Microsoft's Secure Password
25597 Authentication mechanism, which is also sometimes known as NTLM (NT LanMan).
25598 The code for client side of this authenticator was contributed by Marc
25599 Prud'hommeaux, and much of it is taken from the Samba project (https://
25600 www.samba.org/). The code for the server side was subsequently contributed by
25601 Tom Kistner. The mechanism works as follows:
25602
25603 * After the AUTH command has been accepted, the client sends an SPA
25604 authentication request based on the user name and optional domain.
25605
25606 * The server sends back a challenge.
25607
25608 * The client builds a challenge response which makes use of the user's
25609 password and sends it to the server, which then accepts or rejects it.
25610
25611 Encryption is used to protect the password in transit.
25612
25613
25614 40.1 Using spa as a server
25615 --------------------------
25616
25617 The spa authenticator has just one server option:
25618
25619 +-----------------------------------------------------+
25620 |server_password|Use: spa|Type: string*|Default: unset|
25621 +-----------------------------------------------------+
25622
25623 This option is expanded, and the result must be the cleartext password for the
25624 authenticating user, whose name is at this point in $auth1. For compatibility
25625 with previous releases of Exim, the user name is also placed in $1. However,
25626 the use of this variable for this purpose is now deprecated, as it can lead to
25627 confusion in string expansions that also use numeric variables for other
25628 things. For example:
25629
25630 spa:
25631 driver = spa
25632 public_name = NTLM
25633 server_password = \
25634 ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail}
25635
25636 If the expansion is forced to fail, authentication fails. Any other expansion
25637 failure causes a temporary error code to be returned.
25638
25639
25640 40.2 Using spa as a client
25641 --------------------------
25642
25643 The spa authenticator has the following client options:
25644
25645 +---------------------------------------------------+
25646 |client_domain|Use: spa|Type: string*|Default: unset|
25647 +---------------------------------------------------+
25648
25649 This option specifies an optional domain for the authentication.
25650
25651 +-----------------------------------------------------+
25652 |client_password|Use: spa|Type: string*|Default: unset|
25653 +-----------------------------------------------------+
25654
25655 This option specifies the user's password, and must be set.
25656
25657 +-----------------------------------------------------+
25658 |client_username|Use: spa|Type: string*|Default: unset|
25659 +-----------------------------------------------------+
25660
25661 This option specifies the user name, and must be set. Here is an example of a
25662 configuration of this authenticator for use with the mail servers at msn.com:
25663
25664 msn:
25665 driver = spa
25666 public_name = MSN
25667 client_username = msn/msn_username
25668 client_password = msn_plaintext_password
25669 client_domain = DOMAIN_OR_UNSET
25670
25671
25672
25673 ===============================================================================
25674 41. THE TLS AUTHENTICATOR
25675
25676 The tls authenticator provides server support for authentication based on
25677 client certificates.
25678
25679 It is not an SMTP authentication mechanism and is not advertised by the server
25680 as part of the SMTP EHLO response. It is an Exim authenticator in the sense
25681 that it affects the protocol element of the log line, can be tested for by the
25682 authenticated ACL condition, and can set the $authenticated_id variable.
25683
25684 The client must present a verifiable certificate, for which it must have been
25685 requested via the tls_verify_hosts or tls_try_verify_hosts main options (see 42
25686 ).
25687
25688 If an authenticator of this type is configured it is run before any SMTP-level
25689 communication is done, and can authenticate the connection. If it does, SMTP
25690 authentication is not offered.
25691
25692 A maximum of one authenticator of this type may be present.
25693
25694 The tls authenticator has three server options:
25695
25696 +---------------------------------------------------+
25697 |server_param1|Use: tls|Type: string*|Default: unset|
25698 +---------------------------------------------------+
25699
25700 This option is expanded after the TLS negotiation and the result is placed in
25701 $auth1. If the expansion is forced to fail, authentication fails. Any other
25702 expansion failure causes a temporary error code to be returned.
25703
25704 +---------------------------------------------------+
25705 |server_param2|Use: tls|Type: string*|Default: unset|
25706 +---------------------------------------------------+
25707
25708 +---------------------------------------------------+
25709 |server_param3|Use: tls|Type: string*|Default: unset|
25710 +---------------------------------------------------+
25711
25712 As above, for $auth2 and $auth3.
25713
25714 server_param1 may also be spelled server_param.
25715
25716 Example:
25717
25718 tls:
25719 driver = tls
25720 server_param1 = ${certextract {subj_altname,mail,>:} \
25721 {$tls_in_peercert}}
25722 server_condition = ${if and { {eq{$tls_in_certificate_verified}{1}} \
25723 {forany {$auth1} \
25724 {!= {0} \
25725 {${lookup ldap{ldap:///\
25726 mailname=${quote_ldap_dn:${lc:$item}},\
25727 ou=users,LDAP_DC?mailid} {$value}{0} \
25728 } } } }}}
25729 server_set_id = ${if = {1}{${listcount:$auth1}} {$auth1}{}}
25730
25731 This accepts a client certificate that is verifiable against any of your
25732 configured trust-anchors (which usually means the full set of public CAs) and
25733 which has a SAN with a good account name.
25734
25735 Note that, up to TLS1.2, the client cert is on the wire in-clear, including the
25736 SAN, The account name is therefore guessable by an opponent. TLS 1.3 protects
25737 both server and client certificates, and is not vulnerable in this way.
25738 Likewise, a traditional plaintext SMTP AUTH done inside TLS is not.
25739
25740 Note that because authentication is traditionally an SMTP operation, the
25741 authenticated ACL condition cannot be used in a connect- or helo-ACL.
25742
25743
25744
25745 ===============================================================================
25746 42. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL
25747
25748 Support for TLS (Transport Layer Security), formerly known as SSL (Secure
25749 Sockets Layer), is implemented by making use of the OpenSSL library or the
25750 GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no
25751 cryptographic code in the Exim distribution itself for implementing TLS. In
25752 order to use this feature you must install OpenSSL or GnuTLS, and then build a
25753 version of Exim that includes TLS support (see section 4.7). You also need to
25754 understand the basic concepts of encryption at a managerial level, and in
25755 particular, the way that public keys, private keys, and certificates are used.
25756
25757 RFC 3207 defines how SMTP connections can make use of encryption. Once a
25758 connection is established, the client issues a STARTTLS command. If the server
25759 accepts this, the client and the server negotiate an encryption mechanism. If
25760 the negotiation succeeds, the data that subsequently passes between them is
25761 encrypted.
25762
25763 Exim's ACLs can detect whether the current SMTP session is encrypted or not,
25764 and if so, what cipher suite is in use, whether the client supplied a
25765 certificate, and whether or not that certificate was verified. This makes it
25766 possible for an Exim server to deny or accept certain commands based on the
25767 encryption state.
25768
25769 Warning: Certain types of firewall and certain anti-virus products can disrupt
25770 TLS connections. You need to turn off SMTP scanning for these products in order
25771 to get TLS to work.
25772
25773
25774 42.1 Support for the "submissions" (aka "ssmtp" and "smtps") protocol
25775 ---------------------------------------------------------------------
25776
25777 The history of port numbers for TLS in SMTP is a little messy and has been
25778 contentious. As of RFC 8314, the common practice of using the historically
25779 allocated port 465 for "email submission but with TLS immediately upon connect
25780 instead of using STARTTLS" is officially blessed by the IETF, and recommended
25781 by them in preference to STARTTLS.
25782
25783 The name originally assigned to the port was "ssmtp" or "smtps", but as clarity
25784 emerged over the dual roles of SMTP, for MX delivery and Email Submission,
25785 nomenclature has shifted. The modern name is now "submissions".
25786
25787 This approach was, for a while, officially abandoned when encrypted SMTP was
25788 standardized, but many clients kept using it, even as the TCP port number was
25789 reassigned for other use. Thus you may encounter guidance claiming that you
25790 shouldn't enable use of this port. In practice, a number of mail-clients have
25791 only ever supported submissions, not submission with STARTTLS upgrade. Ideally,
25792 offer both submission (587) and submissions (465) service.
25793
25794 Exim supports TLS-on-connect by means of the tls_on_connect_ports global
25795 option. Its value must be a list of port numbers; the most common use is
25796 expected to be:
25797
25798 tls_on_connect_ports = 465
25799
25800 The port numbers specified by this option apply to all SMTP connections, both
25801 via the daemon and via inetd. You still need to specify all the ports that the
25802 daemon uses (by setting daemon_smtp_ports or local_interfaces or the -oX
25803 command line option) because tls_on_connect_ports does not add an extra port -
25804 rather, it specifies different behaviour on a port that is defined elsewhere.
25805
25806 There is also a -tls-on-connect command line option. This overrides
25807 tls_on_connect_ports; it forces the TLS-only behaviour for all ports.
25808
25809
25810 42.2 OpenSSL vs GnuTLS
25811 ----------------------
25812
25813 The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS
25814 followed later, when the first versions of GnuTLS were released. To build Exim
25815 to use GnuTLS, you need to set
25816
25817 USE_GNUTLS=yes
25818
25819 in Local/Makefile, in addition to
25820
25821 SUPPORT_TLS=yes
25822
25823 You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the include
25824 files and libraries for GnuTLS can be found.
25825
25826 There are some differences in usage when using GnuTLS instead of OpenSSL:
25827
25828 * The tls_verify_certificates option cannot be the path of a directory for
25829 GnuTLS versions before 3.3.6 (for later versions, or OpenSSL, it can be
25830 either).
25831
25832 * The default value for tls_dhparam differs for historical reasons.
25833
25834 * Distinguished Name (DN) strings reported by the OpenSSL library use a slash
25835 for separating fields; GnuTLS uses commas, in accordance with RFC 2253.
25836 This affects the value of the $tls_in_peerdn and $tls_out_peerdn variables.
25837
25838 * OpenSSL identifies cipher suites using hyphens as separators, for example:
25839 DES-CBC3-SHA. GnuTLS historically used underscores, for example:
25840 RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present
25841 in a cipher list. To make life simpler, Exim changes underscores to hyphens
25842 for OpenSSL and passes the string unchanged to GnuTLS (expecting the
25843 library to handle its own older variants) when processing lists of cipher
25844 suites in the tls_require_ciphers options (the global option and the smtp
25845 transport option).
25846
25847 * The tls_require_ciphers options operate differently, as described in the
25848 sections 42.4 and 42.5.
25849
25850 * The tls_dh_min_bits SMTP transport option is only honoured by GnuTLS. When
25851 using OpenSSL, this option is ignored. (If an API is found to let OpenSSL
25852 be configured in this way, let the Exim Maintainers know and we'll likely
25853 use it).
25854
25855 * With GnuTLS, if an explicit list is used for the tls_privatekey main option
25856 main option, it must be ordered to match the tls_certificate list.
25857
25858 * Some other recently added features may only be available in one or the
25859 other. This should be documented with the feature. If the documentation
25860 does not explicitly state that the feature is infeasible in the other TLS
25861 implementation, then patches are welcome.
25862
25863
25864 42.3 GnuTLS parameter computation
25865 ---------------------------------
25866
25867 This section only applies if tls_dhparam is set to "historic" or to an explicit
25868 path; if the latter, then the text about generation still applies, but not the
25869 chosen filename. By default, as of Exim 4.80 a hard-coded D-H prime is used.
25870 See the documentation of tls_dhparam for more information.
25871
25872 GnuTLS uses D-H parameters that may take a substantial amount of time to
25873 compute. It is unreasonable to re-compute them for every TLS session.
25874 Therefore, Exim keeps this data in a file in its spool directory, called
25875 gnutls-params-NNNN for some value of NNNN, corresponding to the number of bits
25876 requested. The file is owned by the Exim user and is readable only by its
25877 owner. Every Exim process that start up GnuTLS reads the D-H parameters from
25878 this file. If the file does not exist, the first Exim process that needs it
25879 computes the data and writes it to a temporary file which is renamed once it is
25880 complete. It does not matter if several Exim processes do this simultaneously
25881 (apart from wasting a few resources). Once a file is in place, new Exim
25882 processes immediately start using it.
25883
25884 For maximum security, the parameters that are stored in this file should be
25885 recalculated periodically, the frequency depending on your paranoia level. If
25886 you are avoiding using the fixed D-H primes published in RFCs, then you are
25887 concerned about some advanced attacks and will wish to do this; if you do not
25888 regenerate then you might as well stick to the standard primes.
25889
25890 Arranging this is easy in principle; just delete the file when you want new
25891 values to be computed. However, there may be a problem. The calculation of new
25892 parameters needs random numbers, and these are obtained from /dev/random. If
25893 the system is not very active, /dev/random may delay returning data until
25894 enough randomness (entropy) is available. This may cause Exim to hang for a
25895 substantial amount of time, causing timeouts on incoming connections.
25896
25897 The solution is to generate the parameters externally to Exim. They are stored
25898 in gnutls-params-N in PEM format, which means that they can be generated
25899 externally using the certtool command that is part of GnuTLS.
25900
25901 To replace the parameters with new ones, instead of deleting the file and
25902 letting Exim re-create it, you can generate new parameters using certtool and,
25903 when this has been done, replace Exim's cache file by renaming. The relevant
25904 commands are something like this:
25905
25906 # ls
25907 [ look for file; assume gnutls-params-2236 is the most recent ]
25908 # rm -f new-params
25909 # touch new-params
25910 # chown exim:exim new-params
25911 # chmod 0600 new-params
25912 # certtool --generate-dh-params --bits 2236 >>new-params
25913 # openssl dhparam -noout -text -in new-params | head
25914 [ check the first line, make sure it's not more than 2236;
25915 if it is, then go back to the start ("rm") and repeat
25916 until the size generated is at most the size requested ]
25917 # chmod 0400 new-params
25918 # mv new-params gnutls-params-2236
25919
25920 If Exim never has to generate the parameters itself, the possibility of
25921 stalling is removed.
25922
25923 The filename changed in Exim 4.80, to gain the -bits suffix. The value which
25924 Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS,
25925 the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is a
25926 way for Exim to ask for the "normal" number of bits for D-H public-key usage,
25927 and Exim does so. This attempt to remove Exim from TLS policy decisions failed,
25928 as GnuTLS 2.12 returns a value higher than the current hard-coded limit of the
25929 NSS library. Thus Exim gains the tls_dh_max_bits global option, which applies
25930 to all D-H usage, client or server. If the value returned by GnuTLS is greater
25931 than tls_dh_max_bits then the value will be clamped down to tls_dh_max_bits.
25932 The default value has been set at the current NSS limit, which is still much
25933 higher than Exim historically used.
25934
25935 The filename and bits used will change as the GnuTLS maintainers change the
25936 value for their parameter "GNUTLS_SEC_PARAM_NORMAL", as clamped by
25937 tls_dh_max_bits. At the time of writing (mid 2012), GnuTLS 2.12 recommends 2432
25938 bits, while NSS is limited to 2236 bits.
25939
25940 In fact, the requested value will be *lower* than tls_dh_max_bits, to increase
25941 the chance of the generated prime actually being within acceptable bounds, as
25942 GnuTLS has been observed to overshoot. Note the check step in the procedure
25943 above. There is no sane procedure available to Exim to double-check the size of
25944 the generated prime, so it might still be too large.
25945
25946
25947 42.4 Requiring specific ciphers in OpenSSL
25948 ------------------------------------------
25949
25950 There is a function in the OpenSSL library that can be passed a list of cipher
25951 suites before the cipher negotiation takes place. This specifies which ciphers
25952
25953 are acceptable for TLS versions prior to 1.3.
25954
25955 The list is colon separated and may contain names like DES-CBC3-SHA. Exim
25956 passes the expanded value of tls_require_ciphers directly to this function
25957 call. Many systems will install the OpenSSL manual-pages, so you may have
25958 ciphers(1) available to you. The following quotation from the OpenSSL
25959 documentation specifies what forms of item are allowed in the cipher string:
25960
25961 * It can consist of a single cipher suite such as RC4-SHA.
25962
25963 * It can represent a list of cipher suites containing a certain algorithm, or
25964 cipher suites of a certain type. For example SHA1 represents all ciphers
25965 suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3
25966 algorithms.
25967
25968 * Lists of cipher suites can be combined in a single cipher string using the
25969 + character. This is used as a logical and operation. For example SHA1+DES
25970 represents all cipher suites containing the SHA1 and the DES algorithms.
25971
25972 Each cipher string can be optionally preceded by one of the characters "!", "-"
25973 or "+".
25974
25975 * If "!" is used, the ciphers are permanently deleted from the list. The
25976 ciphers deleted can never reappear in the list even if they are explicitly
25977 stated.
25978
25979 * If "-" is used, the ciphers are deleted from the list, but some or all of
25980 the ciphers can be added again by later options.
25981
25982 * If "+" is used, the ciphers are moved to the end of the list. This option
25983 does not add any new ciphers; it just moves matching existing ones.
25984
25985 If none of these characters is present, the string is interpreted as a list of
25986 ciphers to be appended to the current preference list. If the list includes any
25987 ciphers already present they will be ignored: that is, they will not be moved
25988 to the end of the list.
25989
25990 The OpenSSL ciphers(1) command may be used to test the results of a given
25991 string:
25992
25993 # note single-quotes to get ! past any shell history expansion
25994 $ openssl ciphers 'HIGH:!MD5:!SHA1'
25995
25996 This example will let the library defaults be permitted on the MX port, where
25997 there's probably no identity verification anyway, but ups the ante on the
25998 submission ports where the administrator might have some influence on the
25999 choice of clients used:
26000
26001 # OpenSSL variant; see man ciphers(1)
26002 tls_require_ciphers = ${if =={$received_port}{25}\
26003 {DEFAULT}\
26004 {HIGH:!MD5:!SHA1}}
26005
26006 This example will prefer ECDSA-authenticated ciphers over RSA ones:
26007
26008 tls_require_ciphers = ECDSA:RSA:!COMPLEMENTOFDEFAULT
26009
26010 For TLS version 1.3 the control available is less fine-grained and Exim does
26011 not provide access to it at present. The value of the tls_require_ciphers
26012 option is ignored when TLS version 1.3 is negotiated.
26013
26014 As of writing the library default cipher suite list for TLSv1.3 is
26015
26016 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
26017
26018
26019 42.5 Requiring specific ciphers or other parameters in GnuTLS
26020 -------------------------------------------------------------
26021
26022 The GnuTLS library allows the caller to provide a "priority string", documented
26023 as part of the gnutls_priority_init function. This is very similar to the
26024 ciphersuite specification in OpenSSL.
26025
26026 The tls_require_ciphers option is treated as the GnuTLS priority string and
26027 controls both protocols and ciphers.
26028
26029 The tls_require_ciphers option is available both as an global option,
26030 controlling how Exim behaves as a server, and also as an option of the smtp
26031 transport, controlling how Exim behaves as a client. In both cases the value is
26032 string expanded. The resulting string is not an Exim list and the string is
26033 given to the GnuTLS library, so that Exim does not need to be aware of future
26034 feature enhancements of GnuTLS.
26035
26036 Documentation of the strings accepted may be found in the GnuTLS manual, under
26037 "Priority strings". This is online as https://www.gnutls.org/manual/html_node/
26038 Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be
26039 newer than the version installed on your system. If you are using GnuTLS 3,
26040 then the example code https://www.gnutls.org/manual/gnutls.html#
26041 Listing-the-ciphersuites-in-a-priority-string on that site can be used to test
26042 a given string.
26043
26044 For example:
26045
26046 # Disable older versions of protocols
26047 tls_require_ciphers = NORMAL:%LATEST_RECORD_VERSION:-VERS-SSL3.0
26048
26049 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
26050 additional options, "gnutls_require_kx", "gnutls_require_mac" and "
26051 gnutls_require_protocols". tls_require_ciphers was an Exim list.
26052
26053 This example will let the library defaults be permitted on the MX port, where
26054 there's probably no identity verification anyway, and lowers security further
26055 by increasing compatibility; but this ups the ante on the submission ports
26056 where the administrator might have some influence on the choice of clients
26057 used:
26058
26059 # GnuTLS variant
26060 tls_require_ciphers = ${if =={$received_port}{25}\
26061 {NORMAL:%COMPAT}\
26062 {SECURE128}}
26063
26064
26065 42.6 Configuring an Exim server to use TLS
26066 ------------------------------------------
26067
26068 When Exim has been built with TLS support, it advertises the availability of
26069 the STARTTLS command to client hosts that match tls_advertise_hosts, but not to
26070 any others. The default value of this option is *, which means that STARTTLS is
26071 always advertised. Set it to blank to never advertise; this is reasonable for
26072 systems that want to use TLS only as a client.
26073
26074 If STARTTLS is to be used you need to set some other options in order to make
26075 TLS available.
26076
26077 If a client issues a STARTTLS command and there is some configuration problem
26078 in the server, the command is rejected with a 454 error. If the client persists
26079 in trying to issue SMTP commands, all except QUIT are rejected with the error
26080
26081 554 Security failure
26082
26083 If a STARTTLS command is issued within an existing TLS session, it is rejected
26084 with a 554 error code.
26085
26086 To enable TLS operations on a server, the tls_advertise_hosts option must be
26087 set to match some hosts. The default is * which matches all hosts.
26088
26089 If this is all you do, TLS encryption will be enabled but not authentication -
26090 meaning that the peer has no assurance it is actually you he is talking to. You
26091 gain protection from a passive sniffer listening on the wire but not from
26092 someone able to intercept the communication.
26093
26094 Further protection requires some further configuration at the server end.
26095
26096 To make TLS work you need to set, in the server,
26097
26098 tls_certificate = /some/file/name
26099 tls_privatekey = /some/file/name
26100
26101 These options are, in fact, expanded strings, so you can make them depend on
26102 the identity of the client that is connected if you wish. The first file
26103 contains the server's X509 certificate, and the second contains the private key
26104 that goes with it. These files need to be PEM format and readable by the Exim
26105 user, and must always be given as full path names. The key must not be
26106 password-protected. They can be the same file if both the certificate and the
26107 key are contained within it. If tls_privatekey is not set, or if its expansion
26108 is forced to fail or results in an empty string, this is assumed to be the
26109 case. The certificate file may also contain intermediate certificates that need
26110 to be sent to the client to enable it to authenticate the server's certificate.
26111
26112 For dual-stack (eg. RSA and ECDSA) configurations, these options can be
26113 colon-separated lists of file paths. Ciphers using given authentication
26114 algorithms require the presence of a suitable certificate to supply the
26115 public-key. The server selects among the certificates to present to the client
26116 depending on the selected cipher, hence the priority ordering for ciphers will
26117 affect which certificate is used.
26118
26119 If you do not understand about certificates and keys, please try to find a
26120 source of this background information, which is not Exim-specific. (There are a
26121 few comments below in section 42.12.)
26122
26123 Note: These options do not apply when Exim is operating as a client - they
26124 apply only in the case of a server. If you need to use a certificate in an Exim
26125 client, you must set the options of the same names in an smtp transport.
26126
26127 With just these options, an Exim server will be able to use TLS. It does not
26128 require the client to have a certificate (but see below for how to insist on
26129 this). There is one other option that may be needed in other situations. If
26130
26131 tls_dhparam = /some/file/name
26132
26133 is set, the SSL library is initialized for the use of Diffie-Hellman ciphers
26134 with the parameters contained in the file. Set this to "none" to disable use of
26135 DH entirely, by making no prime available:
26136
26137 tls_dhparam = none
26138
26139 This may also be set to a string identifying a standard prime to be used for
26140 DH; if it is set to "default" or, for OpenSSL, is unset, then the prime used is
26141 "ike23". There are a few standard primes available, see the documentation for
26142 tls_dhparam for the complete list.
26143
26144 See the command
26145
26146 openssl dhparam
26147
26148 for a way of generating file data.
26149
26150 The strings supplied for these three options are expanded every time a client
26151 host connects. It is therefore possible to use different certificates and keys
26152 for different hosts, if you so wish, by making use of the client's IP address
26153 in $sender_host_address to control the expansion. If a string expansion is
26154 forced to fail, Exim behaves as if the option is not set.
26155
26156 The variable $tls_in_cipher is set to the cipher suite that was negotiated for
26157 an incoming TLS connection. It is included in the Received: header of an
26158 incoming message (by default - you can, of course, change this), and it is also
26159 included in the log line that records a message's arrival, keyed by "X=",
26160 unless the tls_cipher log selector is turned off. The encrypted condition can
26161 be used to test for specific cipher suites in ACLs.
26162
26163 Once TLS has been established, the ACLs that run for subsequent SMTP commands
26164 can check the name of the cipher suite and vary their actions accordingly. The
26165 cipher suite names vary, depending on which TLS library is being used. For
26166 example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other
26167 contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS
26168 documentation for more details.
26169
26170 For outgoing SMTP deliveries, $tls_out_cipher is used and logged (again
26171 depending on the tls_cipher log selector).
26172
26173
26174 42.7 Requesting and verifying client certificates
26175 -------------------------------------------------
26176
26177 If you want an Exim server to request a certificate when negotiating a TLS
26178 session with a client, you must set either tls_verify_hosts or
26179 tls_try_verify_hosts. You can, of course, set either of them to * to apply to
26180 all TLS connections. For any host that matches one of these options, Exim
26181 requests a certificate as part of the setup of the TLS session. The contents of
26182 the certificate are verified by comparing it with a list of expected
26183 trust-anchors or certificates. These may be the system default set (depending
26184 on library version), an explicit file or, depending on library version, a
26185 directory, identified by tls_verify_certificates.
26186
26187 A file can contain multiple certificates, concatenated end to end. If a
26188 directory is used (OpenSSL only), each certificate must be in a separate file,
26189 with a name (or a symbolic link) of the form <hash>.0, where <hash> is a hash
26190 value constructed from the certificate. You can compute the relevant hash by
26191 running the command
26192
26193 openssl x509 -hash -noout -in /cert/file
26194
26195 where /cert/file contains a single certificate.
26196
26197 There is no checking of names of the client against the certificate Subject
26198 Name or Subject Alternate Names.
26199
26200 The difference between tls_verify_hosts and tls_try_verify_hosts is what
26201 happens if the client does not supply a certificate, or if the certificate does
26202 not match any of the certificates in the collection named by
26203 tls_verify_certificates. If the client matches tls_verify_hosts, the attempt to
26204 set up a TLS session is aborted, and the incoming connection is dropped. If the
26205 client matches tls_try_verify_hosts, the (encrypted) SMTP session continues.
26206 ACLs that run for subsequent SMTP commands can detect the fact that no
26207 certificate was verified, and vary their actions accordingly. For example, you
26208 can insist on a certificate before accepting a message for relaying, but not
26209 when the message is destined for local delivery.
26210
26211 When a client supplies a certificate (whether it verifies or not), the value of
26212 the Distinguished Name of the certificate is made available in the variable
26213 $tls_in_peerdn during subsequent processing of the message.
26214
26215 Because it is often a long text string, it is not included in the log line or
26216 Received: header by default. You can arrange for it to be logged, keyed by "DN=
26217 ", by setting the tls_peerdn log selector, and you can use received_header_text
26218 to change the Received: header. When no certificate is supplied, $tls_in_peerdn
26219 is empty.
26220
26221
26222 42.8 Revoked certificates
26223 -------------------------
26224
26225 Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
26226 certificates are revoked. If you have such a list, you can pass it to an Exim
26227 server using the global option called tls_crl and to an Exim client using an
26228 identically named option for the smtp transport. In each case, the value of the
26229 option is expanded and must then be the name of a file that contains a CRL in
26230 PEM format. The downside is that clients have to periodically re-download a
26231 potentially huge file from every certificate authority they know of.
26232
26233 The way with most moving parts at query time is Online Certificate Status
26234 Protocol (OCSP), where the client verifies the certificate against an OCSP
26235 server run by the CA. This lets the CA track all usage of the certs. It
26236 requires running software with access to the private key of the CA, to sign the
26237 responses to the OCSP queries. OCSP is based on HTTP and can be proxied
26238 accordingly.
26239
26240 The only widespread OCSP server implementation (known to this writer) comes as
26241 part of OpenSSL and aborts on an invalid request, such as connecting to the
26242 port and then disconnecting. This requires re-entering the passphrase each time
26243 some random client does this.
26244
26245 The third way is OCSP Stapling; in this, the server using a certificate issued
26246 by the CA periodically requests an OCSP proof of validity from the OCSP server,
26247 then serves it up inline as part of the TLS negotiation. This approach adds no
26248 extra round trips, does not let the CA track users, scales well with number of
26249 certs issued by the CA and is resilient to temporary OCSP server failures, as
26250 long as the server starts retrying to fetch an OCSP proof some time before its
26251 current proof expires. The downside is that it requires server support.
26252
26253 Unless Exim is built with the support disabled, or with GnuTLS earlier than
26254 version 3.3.16 / 3.4.8 support for OCSP stapling is included.
26255
26256 There is a global option called tls_ocsp_file. The file specified therein is
26257 expected to be in DER format, and contain an OCSP proof. Exim will serve it as
26258 part of the TLS handshake. This option will be re-expanded for SNI, if the
26259 tls_certificate option contains "tls_in_sni", as per other TLS options.
26260
26261 Exim does not at this time implement any support for fetching a new OCSP proof.
26262 The burden is on the administrator to handle this, outside of Exim. The file
26263 specified should be replaced atomically, so that the contents are always valid.
26264 Exim will expand the tls_ocsp_file option on each connection, so a new file
26265 will be handled transparently on the next connection.
26266
26267 When built with OpenSSL Exim will check for a valid next update timestamp in
26268 the OCSP proof; if not present, or if the proof has expired, it will be
26269 ignored.
26270
26271 For the client to be able to verify the stapled OCSP the server must also
26272 supply, in its stapled information, any intermediate certificates for the chain
26273 leading to the OCSP proof from the signer of the server certificate. There may
26274 be zero or one such. These intermediate certificates should be added to the
26275 server OCSP stapling file named by tls_ocsp_file.
26276
26277 Note that the proof only covers the terminal server certificate, not any of the
26278 chain from CA to it.
26279
26280 There is no current way to staple a proof for a client certificate.
26281
26282 A helper script "ocsp_fetch.pl" for fetching a proof from a CA
26283 OCSP server is supplied. The server URL may be included in the
26284 server certificate, if the CA is helpful.
26285
26286 One failure mode seen was the OCSP Signer cert expiring before the end
26287 of validity of the OCSP proof. The checking done by Exim/OpenSSL
26288 noted this as invalid overall, but the re-fetch script did not.
26289
26290
26291 42.9 Configuring an Exim client to use TLS
26292 ------------------------------------------
26293
26294 The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries
26295 as well as to incoming, the latter one causing logging of the server
26296 certificate's DN. The remaining client configuration for TLS is all within the
26297 smtp transport.
26298
26299 It is not necessary to set any options to have TLS work in the smtp transport.
26300 If Exim is built with TLS support, and TLS is advertised by a server, the smtp
26301 transport always tries to start a TLS session. However, this can be prevented
26302 by setting hosts_avoid_tls (an option of the transport) to a list of server
26303 hosts for which TLS should not be used.
26304
26305 If you do not want Exim to attempt to send messages unencrypted when an attempt
26306 to set up an encrypted connection fails in any way, you can set
26307 hosts_require_tls to a list of hosts for which encryption is mandatory. For
26308 those hosts, delivery is always deferred if an encrypted connection cannot be
26309 set up. If there are any other hosts for the address, they are tried in the
26310 usual way.
26311
26312 When the server host is not in hosts_require_tls, Exim may try to deliver the
26313 message unencrypted. It always does this if the response to STARTTLS is a 5xx
26314 code. For a temporary error code, or for a failure to negotiate a TLS session
26315 after a success response code, what happens is controlled by the
26316 tls_tempfail_tryclear option of the smtp transport. If it is false, delivery to
26317 this host is deferred, and other hosts (if available) are tried. If it is true,
26318 Exim attempts to deliver unencrypted after a 4xx response to STARTTLS, and if
26319 STARTTLS is accepted, but the subsequent TLS negotiation fails, Exim closes the
26320 current connection (because it is in an unknown state), opens a new one to the
26321 same host, and then tries the delivery unencrypted.
26322
26323 The tls_certificate and tls_privatekey options of the smtp transport provide
26324 the client with a certificate, which is passed to the server if it requests it.
26325 If the server is Exim, it will request a certificate only if tls_verify_hosts
26326 or tls_try_verify_hosts matches the client.
26327
26328 If the tls_verify_certificates option is set on the smtp transport, it
26329 specifies a collection of expected server certificates. These may be the system
26330 default set (depending on library version), a file, or (depending on library
26331 version) a directory. The client verifies the server's certificate against this
26332 collection, taking into account any revoked certificates that are in the list
26333 defined by tls_crl. Failure to verify fails the TLS connection unless either of
26334 the tls_verify_hosts or tls_try_verify_hosts options are set.
26335
26336 The tls_verify_hosts and tls_try_verify_hosts options restrict certificate
26337 verification to the listed servers. Verification either must or need not
26338 succeed respectively.
26339
26340 The tls_verify_cert_hostnames option lists hosts for which additional checks
26341 are made: that the host name (the one in the DNS A record) is valid for the
26342 certificate. The option defaults to always checking.
26343
26344 The smtp transport has two OCSP-related options: hosts_require_ocsp; a
26345 host-list for which a Certificate Status is requested and required for the
26346 connection to proceed. The default value is empty. hosts_request_ocsp; a
26347 host-list for which (additionally) a Certificate Status is requested (but not
26348 necessarily verified). The default value is "*" meaning that requests are made
26349 unless configured otherwise.
26350
26351 The host(s) should also be in hosts_require_tls, and tls_verify_certificates
26352 configured for the transport, for OCSP to be relevant.
26353
26354 If tls_require_ciphers is set on the smtp transport, it must contain a list of
26355 permitted cipher suites. If either of these checks fails, delivery to the
26356 current host is abandoned, and the smtp transport tries to deliver to
26357 alternative hosts, if any.
26358
26359 Note: These options must be set in the smtp transport for Exim to use TLS when
26360 it is operating as a client. Exim does not assume that a server certificate
26361 (set by the global options of the same name) should also be used when operating
26362 as a client.
26363
26364 All the TLS options in the smtp transport are expanded before use, with $host
26365 and $host_address containing the name and address of the server to which the
26366 client is connected. Forced failure of an expansion causes Exim to behave as if
26367 the relevant option were unset.
26368
26369 Before an SMTP connection is established, the $tls_out_bits, $tls_out_cipher,
26370 $tls_out_peerdn and $tls_out_sni variables are emptied. (Until the first
26371 connection, they contain the values that were set when the message was
26372 received.) If STARTTLS is subsequently successfully obeyed, these variables are
26373 set to the relevant values for the outgoing connection.
26374
26375
26376 42.10 Use of TLS Server Name Indication
26377 ---------------------------------------
26378
26379 With TLS1.0 or above, there is an extension mechanism by which extra
26380 information can be included at various points in the protocol. One of these
26381 extensions, documented in RFC 6066 (and before that RFC 4366) is "Server Name
26382 Indication", commonly "SNI". This extension is sent by the client in the
26383 initial handshake, so that the server can examine the servername within and
26384 possibly choose to use different certificates and keys (and more) for this
26385 session.
26386
26387 This is analogous to HTTP's "Host:" header, and is the main mechanism by which
26388 HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address.
26389
26390 With SMTP to MX, there are the same problems here as in choosing the identity
26391 against which to validate a certificate: you can't rely on insecure DNS to
26392 provide the identity which you then cryptographically verify. So this will be
26393 of limited use in that environment.
26394
26395 With SMTP to Submission, there is a well-defined hostname which clients are
26396 connecting to and can validate certificates against. Thus clients can choose to
26397 include this information in the TLS negotiation. If this becomes wide-spread,
26398 then hosters can choose to present different certificates to different clients.
26399 Or even negotiate different cipher suites.
26400
26401 The tls_sni option on an SMTP transport is an expanded string; the result, if
26402 not empty, will be sent on a TLS session as part of the handshake. There's
26403 nothing more to it. Choosing a sensible value not derived insecurely is the
26404 only point of caution. The $tls_out_sni variable will be set to this string for
26405 the lifetime of the client connection (including during authentication).
26406
26407 Except during SMTP client sessions, if $tls_in_sni is set then it is a string
26408 received from a client. It can be logged with the log_selector item "+tls_sni".
26409
26410 If the string "tls_in_sni" appears in the main section's tls_certificate option
26411 (prior to expansion) then the following options will be re-expanded during TLS
26412 session handshake, to permit alternative values to be chosen:
26413
26414 * tls_certificate
26415
26416 * tls_crl
26417
26418 * tls_privatekey
26419
26420 * tls_verify_certificates
26421
26422 * tls_ocsp_file
26423
26424 Great care should be taken to deal with matters of case, various injection
26425 attacks in the string ("../" or SQL), and ensuring that a valid filename can
26426 always be referenced; it is important to remember that $tls_in_sni is arbitrary
26427 unverified data provided prior to authentication. Further, the initial
26428 certificate is loaded before SNI is arrived, so an expansion for
26429 tls_certificate must have a default which is used when $tls_in_sni is empty.
26430
26431 The Exim developers are proceeding cautiously and so far no other TLS options
26432 are re-expanded.
26433
26434 When Exim is built against OpenSSL, OpenSSL must have been built with support
26435 for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with
26436 enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see
26437 "-servername" in the output, then OpenSSL has support.
26438
26439 When Exim is built against GnuTLS, SNI support is available as of GnuTLS
26440 0.5.10. (Its presence predates the current API which Exim uses, so if Exim
26441 built, then you have SNI support).
26442
26443
26444 42.11 Multiple messages on the same encrypted TCP/IP connection
26445 ---------------------------------------------------------------
26446
26447 Exim sends multiple messages down the same TCP/IP connection by starting up an
26448 entirely new delivery process for each message, passing the socket from one
26449 process to the next. This implementation does not fit well with the use of TLS,
26450 because there is quite a lot of state information associated with a TLS
26451 connection, not just a socket identification. Passing all the state information
26452 to a new process is not feasible. Consequently, for sending using TLS Exim
26453 starts an additional proxy process for handling the encryption, piping the
26454 unencrypted data stream from and to the delivery processes.
26455
26456 An older mode of operation can be enabled on a per-host basis by the
26457 hosts_noproxy_tls option on the smtp transport. If the host matches this list
26458 the proxy process described above is not used; instead Exim shuts down an
26459 existing TLS session being run by the delivery process before passing the
26460 socket to a new process. The new process may then try to start a new TLS
26461 session, and if successful, may try to re-authenticate if AUTH is in use,
26462 before sending the next message.
26463
26464 The RFC is not clear as to whether or not an SMTP session continues in clear
26465 after TLS has been shut down, or whether TLS may be restarted again later, as
26466 just described. However, if the server is Exim, this shutdown and
26467 reinitialization works. It is not known which (if any) other servers operate
26468 successfully if the client closes a TLS session and continues with unencrypted
26469 SMTP, but there are certainly some that do not work. For such servers, Exim
26470 should not pass the socket to another process, because the failure of the
26471 subsequent attempt to use it would cause Exim to record a temporary host error,
26472 and delay other deliveries to that host.
26473
26474 To test for this case, Exim sends an EHLO command to the server after closing
26475 down the TLS session. If this fails in any way, the connection is closed
26476 instead of being passed to a new delivery process, but no retry information is
26477 recorded.
26478
26479 There is also a manual override; you can set hosts_nopass_tls on the smtp
26480 transport to match those hosts for which Exim should not pass connections to
26481 new processes if TLS has been used.
26482
26483
26484 42.12 Certificates and all that
26485 -------------------------------
26486
26487 In order to understand fully how TLS works, you need to know about
26488 certificates, certificate signing, and certificate authorities. This is a large
26489 topic and an introductory guide is unsuitable for the Exim reference manual, so
26490 instead we provide pointers to existing documentation.
26491
26492 The Apache web-server was for a long time the canonical guide, so their
26493 documentation is a good place to start; their SSL module's Introduction
26494 document is currently at
26495
26496 https://httpd.apache.org/docs/current/ssl/ssl_intro.html
26497
26498 and their FAQ is at
26499
26500 https://httpd.apache.org/docs/current/ssl/ssl_faq.html
26501
26502 Eric Rescorla's book, SSL and TLS, published by Addison-Wesley (ISBN
26503 0-201-61598-3) in 2001, contains both introductory and more in-depth
26504 descriptions. More recently Ivan Risti?'s book Bulletproof SSL and TLS,
26505 published by Feisty Duck (ISBN 978-1907117046) in 2013 is good. Ivan is the
26506 author of the popular TLS testing tools at https://www.ssllabs.com/.
26507
26508
26509 42.13 Certificate chains
26510 ------------------------
26511
26512 The file named by tls_certificate may contain more than one certificate. This
26513 is useful in the case where the certificate that is being sent is validated by
26514 an intermediate certificate which the other end does not have. Multiple
26515 certificates must be in the correct order in the file. First the host's
26516 certificate itself, then the first intermediate certificate to validate the
26517 issuer of the host certificate, then the next intermediate certificate to
26518 validate the issuer of the first intermediate certificate, and so on, until
26519 finally (optionally) the root certificate. The root certificate must already be
26520 trusted by the recipient for validation to succeed, of course, but if it's not
26521 preinstalled, sending the root certificate along with the rest makes it
26522 available for the user to install if the receiving end is a client MUA that can
26523 interact with a user.
26524
26525 Note that certificates using MD5 are unlikely to work on today's Internet; even
26526 if your libraries allow loading them for use in Exim when acting as a server,
26527 increasingly clients will not accept such certificates. The error diagnostics
26528 in such a case can be frustratingly vague.
26529
26530
26531 42.14 Self-signed certificates
26532 ------------------------------
26533
26534 You can create a self-signed certificate using the req command provided with
26535 OpenSSL, like this:
26536
26537 openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \
26538 -days 9999 -nodes
26539
26540 file1 and file2 can be the same file; the key and the certificate are delimited
26541 and so can be identified independently. The -days option specifies a period for
26542 which the certificate is valid. The -nodes option is important: if you do not
26543 set it, the key is encrypted with a passphrase that you are prompted for, and
26544 any use that is made of the key causes more prompting for the passphrase. This
26545 is not helpful if you are going to use this certificate and key in an MTA,
26546 where prompting is not possible.
26547
26548 NB: we are now past the point where 9999 days takes us past the 32-bit Unix
26549 epoch. If your system uses unsigned time_t (most do) and is 32-bit, then the
26550 above command might produce a date in the past. Think carefully about the
26551 lifetime of the systems you're deploying, and either reduce the duration of the
26552 certificate or reconsider your platform deployment. (At time of writing,
26553 reducing the duration is the most likely choice, but the inexorable progression
26554 of time takes us steadily towards an era where this will not be a sensible
26555 resolution).
26556
26557 A self-signed certificate made in this way is sufficient for testing, and may
26558 be adequate for all your requirements if you are mainly interested in
26559 encrypting transfers, and not in secure identification.
26560
26561 However, many clients require that the certificate presented by the server be a
26562 user (also called "leaf" or "site") certificate, and not a self-signed
26563 certificate. In this situation, the self-signed certificate described above
26564 must be installed on the client host as a trusted root certification authority
26565 (CA), and the certificate used by Exim must be a user certificate signed with
26566 that self-signed certificate.
26567
26568 For information on creating self-signed CA certificates and using them to sign
26569 user certificates, see the General implementation overview chapter of the
26570 Open-source PKI book, available online at https://sourceforge.net/projects/
26571 ospkibook/.
26572
26573
26574 42.15 DANE
26575 ----------
26576
26577 DNS-based Authentication of Named Entities, as applied to SMTP over TLS,
26578 provides assurance to a client that it is actually talking to the server it
26579 wants to rather than some attacker operating a Man In The Middle (MITM)
26580 operation. The latter can terminate the TLS connection you make, and make
26581 another one to the server (so both you and the server still think you have an
26582 encrypted connection) and, if one of the "well known" set of Certificate
26583 Authorities has been suborned - something which *has* been seen already (2014),
26584 a verifiable certificate (if you're using normal root CAs, eg. the Mozilla set,
26585 as your trust anchors).
26586
26587 What DANE does is replace the CAs with the DNS as the trust anchor. The
26588 assurance is limited to a) the possibility that the DNS has been suborned, b)
26589 mistakes made by the admins of the target server. The attack surface presented
26590 by (a) is thought to be smaller than that of the set of root CAs.
26591
26592 It also allows the server to declare (implicitly) that connections to it should
26593 use TLS. An MITM could simply fail to pass on a server's STARTTLS.
26594
26595 DANE scales better than having to maintain (and side-channel communicate)
26596 copies of server certificates for every possible target server. It also scales
26597 (slightly) better than having to maintain on an SMTP client a copy of the
26598 standard CAs bundle. It also means not having to pay a CA for certificates.
26599
26600 DANE requires a server operator to do three things: 1) run DNSSEC. This
26601 provides assurance to clients that DNS lookups they do for the server have not
26602 been tampered with. The domain MX record applying to this server, its A record,
26603 its TLSA record and any associated CNAME records must all be covered by DNSSEC.
26604 2) add TLSA DNS records. These say what the server certificate for a TLS
26605 connection should be. 3) offer a server certificate, or certificate chain, in
26606 TLS connections which is is anchored by one of the TLSA records.
26607
26608 There are no changes to Exim specific to server-side operation of DANE. Support
26609 for client-side operation of DANE can be included at compile time by defining
26610 SUPPORT_DANE=yes in Local/Makefile. If it has been included, the macro
26611 "_HAVE_DANE" will be defined.
26612
26613 The TLSA record for the server may have "certificate usage" of DANE-TA(2) or
26614 DANE-EE(3). These are the "Trust Anchor" and "End Entity" variants. The latter
26615 specifies the End Entity directly, i.e. the certificate involved is that of the
26616 server (and if only DANE-EE is used then it should be the sole one transmitted
26617 during the TLS handshake); this is appropriate for a single system, using a
26618 self-signed certificate. DANE-TA usage is effectively declaring a specific CA
26619 to be used; this might be a private CA or a public, well-known one. A private
26620 CA at simplest is just a self-signed certificate (with certain attributes)
26621 which is used to sign server certificates, but running one securely does
26622 require careful arrangement. With DANE-TA, as implemented in Exim and commonly
26623 in other MTAs, the server TLS handshake must transmit the entire certificate
26624 chain from CA to server-certificate. DANE-TA is commonly used for several
26625 services and/or servers, each having a TLSA query-domain CNAME record, all of
26626 which point to a single TLSA record. DANE-TA and DANE-EE can both be used
26627 together.
26628
26629 Our recommendation is to use DANE with a certificate from a public CA, because
26630 this enables a variety of strategies for remote clients to verify your
26631 certificate. You can then publish information both via DANE and another
26632 technology, "MTA-STS", described below.
26633
26634 When you use DANE-TA to publish trust anchor information, you ask entities
26635 outside your administrative control to trust the Certificate Authority for
26636 connections to you. If using a private CA then you should expect others to
26637 still apply the technical criteria they'd use for a public CA to your
26638 certificates. In particular, you should probably try to follow current best
26639 practices for CA operation around hash algorithms and key sizes. Do not expect
26640 other organizations to lower their security expectations just because a
26641 particular profile might be reasonable for your own internal use.
26642
26643 When this text was last updated, this in practice means to avoid use of SHA-1
26644 and MD5; if using RSA to use key sizes of at least 2048 bits (and no larger
26645 than 4096, for interoperability); to use keyUsage fields correctly; to use
26646 random serial numbers. The list of requirements is subject to change as best
26647 practices evolve. If you're not already using a private CA, or it doesn't meet
26648 these requirements, then we encourage you to avoid all these issues and use a
26649 public CA such as Let's Encrypt instead.
26650
26651 The TLSA record should have a Selector field of SPKI(1) and a Matching Type
26652 field of SHA2-512(2).
26653
26654 At the time of writing, https://www.huque.com/bin/gen_tlsa is useful for
26655 quickly generating TLSA records; and commands like
26656
26657 openssl x509 -in -pubkey -noout <certificate.pem \
26658 | openssl rsa -outform der -pubin 2>/dev/null \
26659 | openssl sha512 \
26660 | awk '{print $2}'
26661
26662 are workable for 4th-field hashes.
26663
26664 For use with the DANE-TA model, server certificates must have a correct name
26665 (SubjectName or SubjectAltName).
26666
26667 The Certificate issued by the CA published in the DANE-TA model should be
26668 issued using a strong hash algorithm. Exim, and importantly various other MTAs
26669 sending to you, will not re-enable hash algorithms which have been disabled by
26670 default in TLS libraries. This means no MD5 and no SHA-1. SHA2-256 is the
26671 minimum for reliable interoperability (and probably the maximum too, in 2018).
26672
26673 The use of OCSP-stapling should be considered, allowing for fast revocation of
26674 certificates (which would otherwise be limited by the DNS TTL on the TLSA
26675 records). However, this is likely to only be usable with DANE-TA. NOTE: the
26676 default of requesting OCSP for all hosts is modified iff DANE is in use, to:
26677
26678 hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \
26679 {= {4}{$tls_out_tlsa_usage}} } \
26680 {*}{}}
26681
26682 The (new) variable $tls_out_tlsa_usage is a bitfield with numbered bits set for
26683 TLSA record usage codes. The zero above means DANE was not in use, the four
26684 means that only DANE-TA usage TLSA records were found. If the definition of
26685 hosts_request_ocsp includes the string "tls_out_tlsa_usage", they are
26686 re-expanded in time to control the OCSP request.
26687
26688 This modification of hosts_request_ocsp is only done if it has the default
26689 value of "*". Admins who change it, and those who use hosts_require_ocsp,
26690 should consider the interaction with DANE in their OCSP settings.
26691
26692 For client-side DANE there are three new smtp transport options, hosts_try_dane
26693 , hosts_require_dane and dane_require_tls_ciphers. The require variant will
26694 result in failure if the target host is not DNSSEC-secured.
26695
26696 DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA
26697 records.
26698
26699 A TLSA lookup will be done if either of the above options match and the
26700 host-lookup succeeded using dnssec. If a TLSA lookup is done and succeeds, a
26701 DANE-verified TLS connection will be required for the host. If it does not, the
26702 host will not be used; there is no fallback to non-DANE or non-TLS.
26703
26704 If DANE is requested and usable, then the TLS cipher list configuration prefers
26705 to use the option dane_require_tls_ciphers and falls back to
26706 tls_require_ciphers only if that is unset. This lets you configure "decent
26707 crypto" for DANE and "better than nothing crypto" as the default. Note though
26708 that while GnuTLS lets the string control which versions of TLS/SSL will be
26709 negotiated, OpenSSL does not and you're limited to ciphersuite constraints.
26710
26711 If DANE is requested and useable (see above) the following transport options
26712 are ignored:
26713
26714 hosts_require_tls
26715 tls_verify_hosts
26716 tls_try_verify_hosts
26717 tls_verify_certificates
26718 tls_crl
26719 tls_verify_cert_hostnames
26720
26721 If DANE is not usable, whether requested or not, and CA-anchored verification
26722 evaluation is wanted, the above variables should be set appropriately.
26723
26724 Currently the dnssec_request_domains must be active and dnssec_require_domains
26725 is ignored.
26726
26727 If verification was successful using DANE then the "CV" item in the delivery
26728 log line will show as "CV=dane".
26729
26730 There is a new variable $tls_out_dane which will have "yes" if verification
26731 succeeded using DANE and "no" otherwise (only useful in combination with
26732 events; see 60), and a new variable $tls_out_tlsa_usage (detailed above).
26733
26734 An event (see 60) of type "dane:fail" will be raised on failures to achieve
26735 DANE-verified connection, if one was either requested and offered, or required.
26736 This is intended to support TLS-reporting as defined in https://tools.ietf.org/
26737 html/draft-ietf-uta-smtp-tlsrpt-17. The $event_data will be one of the Result
26738 Types defined in Section 4.3 of that document.
26739
26740 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
26741
26742 DANE is specified in published RFCs and decouples certificate authority trust
26743 selection from a "race to the bottom" of "you must trust everything for mail to
26744 get through". There is an alternative technology called MTA-STS, which instead
26745 publishes MX trust anchor information on an HTTPS website. At the time this
26746 text was last updated, MTA-STS was still a draft, not yet an RFC. Exim has no
26747 support for MTA-STS as a client, but Exim mail server operators can choose to
26748 publish information describing their TLS configuration using MTA-STS to let
26749 those clients who do use that protocol derive trust information.
26750
26751 The MTA-STS design requires a certificate from a public Certificate Authority
26752 which is recognized by clients sending to you. That selection of which CAs are
26753 trusted by others is outside your control.
26754
26755 The most interoperable course of action is probably to use Let's Encrypt, with
26756 automated certificate renewal; to publish the anchor information in
26757 DNSSEC-secured DNS via TLSA records for DANE clients (such as Exim and Postfix)
26758 and to publish anchor information for MTA-STS as well. This is what is done for
26759 the exim.org domain itself (with caveats around occasionally broken MTA-STS
26760 because of incompatible specification changes prior to reaching RFC status).
26761
26762
26763
26764 ===============================================================================
26765 43. ACCESS CONTROL LISTS
26766
26767 Access Control Lists (ACLs) are defined in a separate section of the runtime
26768 configuration file, headed by "begin acl". Each ACL definition starts with a
26769 name, terminated by a colon. Here is a complete ACL section that contains just
26770 one very small ACL:
26771
26772 begin acl
26773 small_acl:
26774 accept hosts = one.host.only
26775
26776 You can have as many lists as you like in the ACL section, and the order in
26777 which they appear does not matter. The lists are self-terminating.
26778
26779 The majority of ACLs are used to control Exim's behaviour when it receives
26780 certain SMTP commands. This applies both to incoming TCP/IP connections, and
26781 when a local process submits a message using SMTP by specifying the -bs option.
26782 The most common use is for controlling which recipients are accepted in
26783 incoming messages. In addition, you can define an ACL that is used to check
26784 local non-SMTP messages. The default configuration file contains an example of
26785 a realistic ACL for checking RCPT commands. This is discussed in chapter 7.
26786
26787
26788 43.1 Testing ACLs
26789 -----------------
26790
26791 The -bh command line option provides a way of testing your ACL configuration
26792 locally by running a fake SMTP session with which you interact.
26793
26794
26795 43.2 Specifying when ACLs are used
26796 ----------------------------------
26797
26798 In order to cause an ACL to be used, you have to name it in one of the relevant
26799 options in the main part of the configuration. These options are:
26800
26801 acl_not_smtp ACL for non-SMTP messages
26802 acl_not_smtp_mime ACL for non-SMTP MIME parts
26803 acl_not_smtp_start ACL at start of non-SMTP message
26804 acl_smtp_auth ACL for AUTH
26805 acl_smtp_connect ACL for start of SMTP connection
26806 acl_smtp_data ACL after DATA is complete
26807 acl_smtp_data_prdr ACL for each recipient, after DATA is complete
26808 acl_smtp_dkim ACL for each DKIM signer
26809 acl_smtp_etrn ACL for ETRN
26810 acl_smtp_expn ACL for EXPN
26811 acl_smtp_helo ACL for HELO or EHLO
26812 acl_smtp_mail ACL for MAIL
26813 acl_smtp_mailauth ACL for the AUTH parameter of MAIL
26814 acl_smtp_mime ACL for content-scanning MIME parts
26815 acl_smtp_notquit ACL for non-QUIT terminations
26816 acl_smtp_predata ACL at start of DATA command
26817 acl_smtp_quit ACL for QUIT
26818 acl_smtp_rcpt ACL for RCPT
26819 acl_smtp_starttls ACL for STARTTLS
26820 acl_smtp_vrfy ACL for VRFY
26821
26822 For example, if you set
26823
26824 acl_smtp_rcpt = small_acl
26825
26826 the little ACL defined above is used whenever Exim receives a RCPT command in
26827 an SMTP dialogue. The majority of policy tests on incoming messages can be done
26828 when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to
26829 give up on the recipient address contained in the RCPT command, whereas
26830 rejection at other times may cause the client MTA to keep on trying to deliver
26831 the message. It is therefore recommended that you do as much testing as
26832 possible at RCPT time.
26833
26834
26835 43.3 The non-SMTP ACLs
26836 ----------------------
26837
26838 The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
26839 apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not
26840 really SMTP.) Many of the ACL conditions (for example, host tests, and tests on
26841 the state of the SMTP connection such as encryption and authentication) are not
26842 relevant and are forbidden in these ACLs. However, the sender and recipients
26843 are known, so the senders and sender_domains conditions and the $sender_address
26844 and $recipients variables can be used. Variables such as $authenticated_sender
26845 are also available. You can specify added header lines in any of these ACLs.
26846
26847 The acl_not_smtp_start ACL is run right at the start of receiving a non-SMTP
26848 message, before any of the message has been read. (This is the analogue of the
26849 acl_smtp_predata ACL for SMTP input.) In the case of batched SMTP input, it
26850 runs after the DATA command has been reached. The result of this ACL is
26851 ignored; it cannot be used to reject a message. If you really need to, you
26852 could set a value in an ACL variable here and reject based on that in the
26853 acl_not_smtp ACL. However, this ACL can be used to set controls, and in
26854 particular, it can be used to set
26855
26856 control = suppress_local_fixups
26857
26858 This cannot be used in the other non-SMTP ACLs because by the time they are
26859 run, it is too late.
26860
26861 The acl_not_smtp_mime ACL is available only when Exim is compiled with the
26862 content-scanning extension. For details, see chapter 44.
26863
26864 The acl_not_smtp ACL is run just before the local_scan() function. Any kind of
26865 rejection is treated as permanent, because there is no way of sending a
26866 temporary error for these kinds of message.
26867
26868
26869 43.4 The SMTP connect ACL
26870 -------------------------
26871
26872 The ACL test specified by acl_smtp_connect happens at the start of an SMTP
26873 session, after the test specified by host_reject_connection (which is now an
26874 anomaly) and any TCP Wrappers testing (if configured). If the connection is
26875 accepted by an accept verb that has a message modifier, the contents of the
26876 message override the banner message that is otherwise specified by the
26877 smtp_banner option.
26878
26879
26880 43.5 The EHLO/HELO ACL
26881 ----------------------
26882
26883 The ACL test specified by acl_smtp_helo happens when the client issues an EHLO
26884 or HELO command, after the tests specified by helo_accept_junk_hosts,
26885 helo_allow_chars, helo_verify_hosts, and helo_try_verify_hosts. Note that a
26886 client may issue more than one EHLO or HELO command in an SMTP session, and
26887 indeed is required to issue a new EHLO or HELO after successfully setting up
26888 encryption following a STARTTLS command.
26889
26890 Note also that a deny neither forces the client to go away nor means that mail
26891 will be refused on the connection. Consider checking for $sender_helo_name
26892 being defined in a MAIL or RCPT ACL to do that.
26893
26894 If the command is accepted by an accept verb that has a message modifier, the
26895 message may not contain more than one line (it will be truncated at the first
26896 newline and a panic logged if it does). Such a message cannot affect the EHLO
26897 options that are listed on the second and subsequent lines of an EHLO response.
26898
26899
26900 43.6 The DATA ACLs
26901 ------------------
26902
26903 Two ACLs are associated with the DATA command, because it is two-stage command,
26904 with two responses being sent to the client. When the DATA command is received,
26905 the ACL defined by acl_smtp_predata is obeyed. This gives you control after all
26906 the RCPT commands, but before the message itself is received. It offers the
26907 opportunity to give a negative response to the DATA command before the data is
26908 transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this
26909 time, but any that are defined here are visible when the acl_smtp_data ACL is
26910 run.
26911
26912 You cannot test the contents of the message, for example, to verify addresses
26913 in the headers, at RCPT time or when the DATA command is received. Such tests
26914 have to appear in the ACL that is run after the message itself has been
26915 received, before the final response to the DATA command is sent. This is the
26916 ACL specified by acl_smtp_data, which is the second ACL that is associated with
26917 the DATA command.
26918
26919 If CHUNKING was advertised and a BDAT command sequence is received, the
26920 acl_smtp_predata ACL is not run. The acl_smtp_data is run after the last BDAT
26921 command and all of the data specified is received.
26922
26923 For both of these ACLs, it is not possible to reject individual recipients. An
26924 error response rejects the entire message. Unfortunately, it is known that some
26925 MTAs do not treat hard (5xx) responses to the DATA command (either before or
26926 after the data) correctly - they keep the message on their queues and try again
26927 later, but that is their problem, though it does waste some of your resources.
26928
26929 The acl_smtp_data ACL is run after the acl_smtp_data_prdr, the acl_smtp_dkim
26930 and the acl_smtp_mime ACLs.
26931
26932
26933 43.7 The SMTP DKIM ACL
26934 ----------------------
26935
26936 The acl_smtp_dkim ACL is available only when Exim is compiled with DKIM support
26937 enabled (which is the default).
26938
26939 The ACL test specified by acl_smtp_dkim happens after a message has been
26940 received, and is executed for each DKIM signature found in a message. If not
26941 otherwise specified, the default action is to accept.
26942
26943 This ACL is evaluated before acl_smtp_mime and acl_smtp_data.
26944
26945 For details on the operation of DKIM, see section 57.1.
26946
26947
26948 43.8 The SMTP MIME ACL
26949 ----------------------
26950
26951 The acl_smtp_mime option is available only when Exim is compiled with the
26952 content-scanning extension. For details, see chapter 44.
26953
26954 This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data.
26955
26956
26957 43.9 The SMTP PRDR ACL
26958 ----------------------
26959
26960 The acl_smtp_data_prdr ACL is available only when Exim is compiled with PRDR
26961 support enabled (which is the default). It becomes active only when the PRDR
26962 feature is negotiated between client and server for a message, and more than
26963 one recipient has been accepted.
26964
26965 The ACL test specified by acl_smtp_data_prdr happens after a message has been
26966 received, and is executed once for each recipient of the message with
26967 $local_part and $domain valid. The test may accept, defer or deny for
26968 individual recipients. The acl_smtp_data will still be called after this ACL
26969 and can reject the message overall, even if this ACL has accepted it for some
26970 or all recipients.
26971
26972 PRDR may be used to support per-user content filtering. Without it one must
26973 defer any recipient after the first that has a different content-filter
26974 configuration. With PRDR, the RCPT-time check for this can be disabled when the
26975 variable $prdr_requested is "yes". Any required difference in behaviour of the
26976 main DATA-time ACL should however depend on the PRDR-time ACL having run, as
26977 Exim will avoid doing so in some situations (e.g. single-recipient mails).
26978
26979 See also the prdr_enable global option and the hosts_try_prdr smtp transport
26980 option.
26981
26982 This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. If the ACL
26983 is not defined, processing completes as if the feature was not requested by the
26984 client.
26985
26986
26987 43.10 The QUIT ACL
26988 ------------------
26989
26990 The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL
26991 does not affect the response code to QUIT, which is always 221. Thus, the ACL
26992 does not in fact control any access. For this reason, it may only accept or
26993 warn as its final result.
26994
26995 This ACL can be used for tasks such as custom logging at the end of an SMTP
26996 session. For example, you can use ACL variables in other ACLs to count
26997 messages, recipients, etc., and log the totals at QUIT time using one or more
26998 logwrite modifiers on a warn verb.
26999
27000 Warning: Only the $acl_cx variables can be used for this, because the $acl_mx
27001 variables are reset at the end of each incoming message.
27002
27003 You do not need to have a final accept, but if you do, you can use a message
27004 modifier to specify custom text that is sent as part of the 221 response to
27005 QUIT.
27006
27007 This ACL is run only for a "normal" QUIT. For certain kinds of disastrous
27008 failure (for example, failure to open a log file, or when Exim is bombing out
27009 because it has detected an unrecoverable error), all SMTP commands from the
27010 client are given temporary error responses until QUIT is received or the
27011 connection is closed. In these special cases, the QUIT ACL does not run.
27012
27013
27014 43.11 The not-QUIT ACL
27015 ----------------------
27016
27017 The not-QUIT ACL, specified by acl_smtp_notquit, is run in most cases when an
27018 SMTP session ends without sending QUIT. However, when Exim itself is in bad
27019 trouble, such as being unable to write to its log files, this ACL is not run,
27020 because it might try to do things (such as write to log files) that make the
27021 situation even worse.
27022
27023 Like the QUIT ACL, this ACL is provided to make it possible to do customized
27024 logging or to gather statistics, and its outcome is ignored. The delay modifier
27025 is forbidden in this ACL, and the only permitted verbs are accept and warn.
27026
27027 When the not-QUIT ACL is running, the variable $smtp_notquit_reason is set to a
27028 string that indicates the reason for the termination of the SMTP connection.
27029 The possible values are:
27030
27031 "acl-drop" Another ACL issued a drop command
27032 "bad-commands" Too many unknown or non-mail commands
27033 "command-timeout" Timeout while reading SMTP commands
27034 "connection-lost" The SMTP connection has been lost
27035 "data-timeout" Timeout while reading message data
27036 "local-scan-error" The local_scan() function crashed
27037 "local-scan-timeout" The local_scan() function timed out
27038 "signal-exit" SIGTERM or SIGINT
27039 "synchronization-error" SMTP synchronization error
27040 "tls-failed" TLS failed to start
27041
27042 In most cases when an SMTP connection is closed without having received QUIT,
27043 Exim sends an SMTP response message before actually closing the connection.
27044 With the exception of the "acl-drop" case, the default message can be
27045 overridden by the message modifier in the not-QUIT ACL. In the case of a drop
27046 verb in another ACL, it is the message from the other ACL that is used.
27047
27048
27049 43.12 Finding an ACL to use
27050 ---------------------------
27051
27052 The value of an acl_smtp_xxx option is expanded before use, so you can use
27053 different ACLs in different circumstances. For example,
27054
27055 acl_smtp_rcpt = ${if ={25}{$interface_port} \
27056 {acl_check_rcpt} {acl_check_rcpt_submit} }
27057
27058 In the default configuration file there are some example settings for providing
27059 an RFC 4409 message "submission" service on port 587 and an RFC 8314
27060 "submissions" service on port 465. You can use a string expansion like this to
27061 choose an ACL for MUAs on these ports which is more appropriate for this
27062 purpose than the default ACL on port 25.
27063
27064 The expanded string does not have to be the name of an ACL in the configuration
27065 file; there are other possibilities. Having expanded the string, Exim searches
27066 for an ACL as follows:
27067
27068 * If the string begins with a slash, Exim uses it as a filename, and reads
27069 its contents as an ACL. The lines are processed in the same way as lines in
27070 the Exim configuration file. In particular, continuation lines are
27071 supported, blank lines are ignored, as are lines whose first non-whitespace
27072 character is "#". If the file does not exist or cannot be read, an error
27073 occurs (typically causing a temporary failure of whatever caused the ACL to
27074 be run). For example:
27075
27076 acl_smtp_data = /etc/acls/\
27077 ${lookup{$sender_host_address}lsearch\
27078 {/etc/acllist}{$value}{default}}
27079
27080 This looks up an ACL file to use on the basis of the host's IP address,
27081 falling back to a default if the lookup fails. If an ACL is successfully
27082 read from a file, it is retained in memory for the duration of the Exim
27083 process, so that it can be re-used without having to re-read the file.
27084
27085 * If the string does not start with a slash, and does not contain any spaces,
27086 Exim searches the ACL section of the configuration for an ACL whose name
27087 matches the string.
27088
27089 * If no named ACL is found, or if the string contains spaces, Exim parses the
27090 string as an inline ACL. This can save typing in cases where you just want
27091 to have something like
27092
27093 acl_smtp_vrfy = accept
27094
27095 in order to allow free use of the VRFY command. Such a string may contain
27096 newlines; it is processed in the same way as an ACL that is read from a
27097 file.
27098
27099
27100 43.13 ACL return codes
27101 ----------------------
27102
27103 Except for the QUIT ACL, which does not affect the SMTP return code (see
27104 section 43.10 above), the result of running an ACL is either "accept" or
27105 "deny", or, if some test cannot be completed (for example, if a database is
27106 down), "defer". These results cause 2xx, 5xx, and 4xx return codes,
27107 respectively, to be used in the SMTP dialogue. A fourth return, "error", occurs
27108 when there is an error such as invalid syntax in the ACL. This also causes a 4
27109 xx return code.
27110
27111 For the non-SMTP ACL, "defer" and "error" are treated in the same way as
27112 "deny", because there is no mechanism for passing temporary errors to the
27113 submitters of non-SMTP messages.
27114
27115 ACLs that are relevant to message reception may also return "discard". This has
27116 the effect of "accept", but causes either the entire message or an individual
27117 recipient address to be discarded. In other words, it is a blackholing
27118 facility. Use it with care.
27119
27120 If the ACL for MAIL returns "discard", all recipients are discarded, and no ACL
27121 is run for subsequent RCPT commands. The effect of "discard" in a RCPT ACL is
27122 to discard just the one recipient address. If there are no recipients left when
27123 the message's data is received, the DATA ACL is not run. A "discard" return
27124 from the DATA or the non-SMTP ACL discards all the remaining recipients. The
27125 "discard" return is not permitted for the acl_smtp_predata ACL.
27126
27127 If the ACL for VRFY returns "accept", a recipient verify (without callout) is
27128 done on the address and the result determines the SMTP response.
27129
27130 The local_scan() function is always run, even if there are no remaining
27131 recipients; it may create new recipients.
27132
27133
27134 43.14 Unset ACL options
27135 -----------------------
27136
27137 The default actions when any of the acl_xxx options are unset are not all the
27138 same. Note: These defaults apply only when the relevant ACL is not defined at
27139 all. For any defined ACL, the default action when control reaches the end of
27140 the ACL statements is "deny".
27141
27142 For acl_smtp_quit and acl_not_smtp_start there is no default because these two
27143 are ACLs that are used only for their side effects. They cannot be used to
27144 accept or reject anything.
27145
27146 For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo
27147 , acl_smtp_mail, acl_smtp_mailauth, acl_smtp_mime, acl_smtp_predata, and
27148 acl_smtp_starttls, the action when the ACL is not defined is "accept".
27149
27150 For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy
27151 ), the action when the ACL is not defined is "deny". This means that
27152 acl_smtp_rcpt must be defined in order to receive any messages over an SMTP
27153 connection. For an example, see the ACL in the default configuration file.
27154
27155
27156 43.15 Data for message ACLs
27157 ---------------------------
27158
27159 When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables
27160 that contain information about the host and the message's sender (for example,
27161 $sender_host_address and $sender_address) are set, and can be used in ACL
27162 statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part
27163 are set from the argument address. The entire SMTP command is available in
27164 $smtp_command.
27165
27166 When an ACL for the AUTH parameter of MAIL is running, the variables that
27167 contain information about the host are set, but $sender_address is not yet set.
27168 Section 33.2 contains a discussion of this parameter and how it is used.
27169
27170 The $message_size variable is set to the value of the SIZE parameter on the
27171 MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not
27172 given. The value is updated to the true message size by the time the final DATA
27173 ACL is run (after the message data has been received).
27174
27175 The $rcpt_count variable increases by one for each RCPT command received. The
27176 $recipients_count variable increases by one each time a RCPT command is
27177 accepted, so while an ACL for RCPT is being processed, it contains the number
27178 of previously accepted recipients. At DATA time (for both the DATA ACLs),
27179 $rcpt_count contains the total number of RCPT commands, and $recipients_count
27180 contains the total number of accepted recipients.
27181
27182
27183 43.16 Data for non-message ACLs
27184 -------------------------------
27185
27186 When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY,
27187 the remainder of the SMTP command line is placed in $smtp_command_argument, and
27188 the entire SMTP command is available in $smtp_command. These variables can be
27189 tested using a condition condition. For example, here is an ACL for use with
27190 AUTH, which insists that either the session is encrypted, or the CRAM-MD5
27191 authentication method is used. In other words, it does not permit
27192 authentication methods that use cleartext passwords on unencrypted connections.
27193
27194 acl_check_auth:
27195 accept encrypted = *
27196 accept condition = ${if eq{${uc:$smtp_command_argument}}\
27197 {CRAM-MD5}}
27198 deny message = TLS encryption or CRAM-MD5 required
27199
27200 (Another way of applying this restriction is to arrange for the authenticators
27201 that use cleartext passwords not to be advertised when the connection is not
27202 encrypted. You can use the generic server_advertise_condition authenticator
27203 option to do this.)
27204
27205
27206 43.17 Format of an ACL
27207 ----------------------
27208
27209 An individual ACL consists of a number of statements. Each statement starts
27210 with a verb, optionally followed by a number of conditions and "modifiers".
27211 Modifiers can change the way the verb operates, define error and log messages,
27212 set variables, insert delays, and vary the processing of accepted messages.
27213
27214 If all the conditions are met, the verb is obeyed. The same condition may be
27215 used (with different arguments) more than once in the same statement. This
27216 provides a means of specifying an "and" conjunction between conditions. For
27217 example:
27218
27219 deny dnslists = list1.example
27220 dnslists = list2.example
27221
27222 If there are no conditions, the verb is always obeyed. Exim stops evaluating
27223 the conditions and modifiers when it reaches a condition that fails. What
27224 happens then depends on the verb (and in one case, on a special modifier). Not
27225 all the conditions make sense at every testing point. For example, you cannot
27226 test a sender address in the ACL that is run for a VRFY command.
27227
27228
27229 43.18 ACL verbs
27230 ---------------
27231
27232 The ACL verbs are as follows:
27233
27234 * accept: If all the conditions are met, the ACL returns "accept". If any of
27235 the conditions are not met, what happens depends on whether endpass appears
27236 among the conditions (for syntax see below). If the failing condition is
27237 before endpass, control is passed to the next ACL statement; if it is after
27238 endpass, the ACL returns "deny". Consider this statement, used to check a
27239 RCPT command:
27240
27241 accept domains = +local_domains
27242 endpass
27243 verify = recipient
27244
27245 If the recipient domain does not match the domains condition, control
27246 passes to the next statement. If it does match, the recipient is verified,
27247 and the command is accepted if verification succeeds. However, if
27248 verification fails, the ACL yields "deny", because the failing condition is
27249 after endpass.
27250
27251 The endpass feature has turned out to be confusing to many people, so its
27252 use is not recommended nowadays. It is always possible to rewrite an ACL so
27253 that endpass is not needed, and it is no longer used in the default
27254 configuration.
27255
27256 If a message modifier appears on an accept statement, its action depends on
27257 whether or not endpass is present. In the absence of endpass (when an
27258 accept verb either accepts or passes control to the next statement),
27259 message can be used to vary the message that is sent when an SMTP command
27260 is accepted. For example, in a RCPT ACL you could have:
27261
27262 accept <some conditions>
27263 message = OK, I will allow you through today
27264
27265 You can specify an SMTP response code, optionally followed by an "extended
27266 response code" at the start of the message, but the first digit must be the
27267 same as would be sent by default, which is 2 for an accept verb.
27268
27269 If endpass is present in an accept statement, message specifies an error
27270 message that is used when access is denied. This behaviour is retained for
27271 backward compatibility, but current "best practice" is to avoid the use of
27272 endpass.
27273
27274 * defer: If all the conditions are true, the ACL returns "defer" which, in an
27275 SMTP session, causes a 4xx response to be given. For a non-SMTP ACL, defer
27276 is the same as deny, because there is no way of sending a temporary error.
27277 For a RCPT command, defer is much the same as using a redirect router and
27278 ":defer:" while verifying, but the defer verb can be used in any ACL, and
27279 even for a recipient it might be a simpler approach.
27280
27281 * deny: If all the conditions are met, the ACL returns "deny". If any of the
27282 conditions are not met, control is passed to the next ACL statement. For
27283 example,
27284
27285 deny dnslists = blackholes.mail-abuse.org
27286
27287 rejects commands from hosts that are on a DNS black list.
27288
27289 * discard: This verb behaves like accept, except that it returns "discard"
27290 from the ACL instead of "accept". It is permitted only on ACLs that are
27291 concerned with receiving messages. When all the conditions are true, the
27292 sending entity receives a "success" response. However, discard causes
27293 recipients to be discarded. If it is used in an ACL for RCPT, just the one
27294 recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all
27295 the message's recipients are discarded. Recipients that are discarded
27296 before DATA do not appear in the log line when the received_recipients log
27297 selector is set.
27298
27299 If the log_message modifier is set when discard operates, its contents are
27300 added to the line that is automatically written to the log. The message
27301 modifier operates exactly as it does for accept.
27302
27303 * drop: This verb behaves like deny, except that an SMTP connection is
27304 forcibly closed after the 5xx error message has been sent. For example:
27305
27306 drop message = I don't take more than 20 RCPTs
27307 condition = ${if > {$rcpt_count}{20}}
27308
27309 There is no difference between deny and drop for the connect-time ACL. The
27310 connection is always dropped after sending a 550 response.
27311
27312 * require: If all the conditions are met, control is passed to the next ACL
27313 statement. If any of the conditions are not met, the ACL returns "deny".
27314 For example, when checking a RCPT command,
27315
27316 require message = Sender did not verify
27317 verify = sender
27318
27319 passes control to subsequent statements only if the message's sender can be
27320 verified. Otherwise, it rejects the command. Note the positioning of the
27321 message modifier, before the verify condition. The reason for this is
27322 discussed in section 43.20.
27323
27324 * warn: If all the conditions are true, a line specified by the log_message
27325 modifier is written to Exim's main log. Control always passes to the next
27326 ACL statement. If any condition is false, the log line is not written. If
27327 an identical log line is requested several times in the same message, only
27328 one copy is actually written to the log. If you want to force duplicates to
27329 be written, use the logwrite modifier instead.
27330
27331 If log_message is not present, a warn verb just checks its conditions and
27332 obeys any "immediate" modifiers (such as control, set, logwrite, add_header
27333 , and remove_header) that appear before the first failing condition. There
27334 is more about adding header lines in section 43.24.
27335
27336 If any condition on a warn statement cannot be completed (that is, there is
27337 some sort of defer), the log line specified by log_message is not written.
27338 This does not include the case of a forced failure from a lookup, which is
27339 considered to be a successful completion. After a defer, no further
27340 conditions or modifiers in the warn statement are processed. The incident
27341 is logged, and the ACL continues to be processed, from the next statement
27342 onwards.
27343
27344 When one of the warn conditions is an address verification that fails, the
27345 text of the verification failure message is in $acl_verify_message. If you
27346 want this logged, you must set it up explicitly. For example:
27347
27348 warn !verify = sender
27349 log_message = sender verify failed: $acl_verify_message
27350
27351 At the end of each ACL there is an implicit unconditional deny.
27352
27353 As you can see from the examples above, the conditions and modifiers are
27354 written one to a line, with the first one on the same line as the verb, and
27355 subsequent ones on following lines. If you have a very long condition, you can
27356 continue it onto several physical lines by the usual backslash continuation
27357 mechanism. It is conventional to align the conditions vertically.
27358
27359
27360 43.19 ACL variables
27361 -------------------
27362
27363 There are some special variables that can be set during ACL processing. They
27364 can be used to pass information between different ACLs, different invocations
27365 of the same ACL in the same SMTP connection, and between ACLs and the routers,
27366 transports, and filters that are used to deliver a message. The names of these
27367 variables must begin with $acl_c or $acl_m, followed either by a digit or an
27368 underscore, but the remainder of the name can be any sequence of alphanumeric
27369 characters and underscores that you choose. There is no limit on the number of
27370 ACL variables. The two sets act as follows:
27371
27372 * The values of those variables whose names begin with $acl_c persist
27373 throughout an SMTP connection. They are never reset. Thus, a value that is
27374 set while receiving one message is still available when receiving the next
27375 message on the same SMTP connection.
27376
27377 * The values of those variables whose names begin with $acl_m persist only
27378 while a message is being received. They are reset afterwards. They are also
27379 reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session.
27380
27381 When a message is accepted, the current values of all the ACL variables are
27382 preserved with the message and are subsequently made available at delivery
27383 time. The ACL variables are set by a modifier called set. For example:
27384
27385 accept hosts = whatever
27386 set acl_m4 = some value
27387 accept authenticated = *
27388 set acl_c_auth = yes
27389
27390 Note: A leading dollar sign is not used when naming a variable that is to be
27391 set. If you want to set a variable without taking any action, you can use a
27392 warn verb without any other modifiers or conditions.
27393
27394 What happens if a syntactically valid but undefined ACL variable is referenced
27395 depends on the setting of the strict_acl_vars option. If it is false (the
27396 default), an empty string is substituted; if it is true, an error is generated.
27397
27398 Versions of Exim before 4.64 have a limited set of numbered variables, but
27399 their names are compatible, so there is no problem with upgrading.
27400
27401
27402 43.20 Condition and modifier processing
27403 ---------------------------------------
27404
27405 An exclamation mark preceding a condition negates its result. For example:
27406
27407 deny domains = *.dom.example
27408 !verify = recipient
27409
27410 causes the ACL to return "deny" if the recipient domain ends in dom.example and
27411 the recipient address cannot be verified. Sometimes negation can be used on the
27412 right-hand side of a condition. For example, these two statements are
27413 equivalent:
27414
27415 deny hosts = !192.168.3.4
27416 deny !hosts = 192.168.3.4
27417
27418 However, for many conditions (verify being a good example), only left-hand side
27419 negation of the whole condition is possible.
27420
27421 The arguments of conditions and modifiers are expanded. A forced failure of an
27422 expansion causes a condition to be ignored, that is, it behaves as if the
27423 condition is true. Consider these two statements:
27424
27425 accept senders = ${lookup{$host_name}lsearch\
27426 {/some/file}{$value}fail}
27427 accept senders = ${lookup{$host_name}lsearch\
27428 {/some/file}{$value}{}}
27429
27430 Each attempts to look up a list of acceptable senders. If the lookup succeeds,
27431 the returned list is searched, but if the lookup fails the behaviour is
27432 different in the two cases. The fail in the first statement causes the
27433 condition to be ignored, leaving no further conditions. The accept verb
27434 therefore succeeds. The second statement, however, generates an empty list when
27435 the lookup fails. No sender can match an empty list, so the condition fails,
27436 and therefore the accept also fails.
27437
27438 ACL modifiers appear mixed in with conditions in ACL statements. Some of them
27439 specify actions that are taken as the conditions for a statement are checked;
27440 others specify text for messages that are used when access is denied or a
27441 warning is generated. The control modifier affects the way an incoming message
27442 is handled.
27443
27444 The positioning of the modifiers in an ACL statement is important, because the
27445 processing of a verb ceases as soon as its outcome is known. Only those
27446 modifiers that have already been encountered will take effect. For example,
27447 consider this use of the message modifier:
27448
27449 require message = Can't verify sender
27450 verify = sender
27451 message = Can't verify recipient
27452 verify = recipient
27453 message = This message cannot be used
27454
27455 If sender verification fails, Exim knows that the result of the statement is
27456 "deny", so it goes no further. The first message modifier has been seen, so its
27457 text is used as the error message. If sender verification succeeds, but
27458 recipient verification fails, the second message is used. If recipient
27459 verification succeeds, the third message becomes "current", but is never used
27460 because there are no more conditions to cause failure.
27461
27462 For the deny verb, on the other hand, it is always the last message modifier
27463 that is used, because all the conditions must be true for rejection to happen.
27464 Specifying more than one message modifier does not make sense, and the message
27465 can even be specified after all the conditions. For example:
27466
27467 deny hosts = ...
27468 !senders = *@my.domain.example
27469 message = Invalid sender from client host
27470
27471 The "deny" result does not happen until the end of the statement is reached, by
27472 which time Exim has set up the message.
27473
27474
27475 43.21 ACL modifiers
27476 -------------------
27477
27478 The ACL modifiers are as follows:
27479
27480 add_header = <text>
27481
27482 This modifier specifies one or more header lines that are to be added to an
27483 incoming message, assuming, of course, that the message is ultimately
27484 accepted. For details, see section 43.24.
27485
27486 continue = <text>
27487
27488 This modifier does nothing of itself, and processing of the ACL always
27489 continues with the next condition or modifier. The value of continue is in
27490 the side effects of expanding its argument. Typically this could be used to
27491 update a database. It is really just a syntactic tidiness, to avoid having
27492 to write rather ugly lines like this:
27493
27494 condition = ${if eq{0}{<some expansion>}{true}{true}}
27495
27496 Instead, all you need is
27497
27498 continue = <some expansion>
27499
27500 control = <text>
27501
27502 This modifier affects the subsequent processing of the SMTP connection or
27503 of an incoming message that is accepted. The effect of the first type of
27504 control lasts for the duration of the connection, whereas the effect of the
27505 second type lasts only until the current message has been received. The
27506 message-specific controls always apply to the whole message, not to
27507 individual recipients, even if the control modifier appears in a RCPT ACL.
27508
27509 As there are now quite a few controls that can be applied, they are
27510 described separately in section 43.22. The control modifier can be used in
27511 several different ways. For example:
27512
27513 + It can be at the end of an accept statement:
27514
27515 accept ...some conditions
27516 control = queue_only
27517
27518 In this case, the control is applied when this statement yields
27519 "accept", in other words, when the conditions are all true.
27520
27521 + It can be in the middle of an accept statement:
27522
27523 accept ...some conditions...
27524 control = queue_only
27525 ...some more conditions...
27526
27527 If the first set of conditions are true, the control is applied, even
27528 if the statement does not accept because one of the second set of
27529 conditions is false. In this case, some subsequent statement must yield
27530 "accept" for the control to be relevant.
27531
27532 + It can be used with warn to apply the control, leaving the decision
27533 about accepting or denying to a subsequent verb. For example:
27534
27535 warn ...some conditions...
27536 control = freeze
27537 accept ...
27538
27539 This example of warn does not contain message, log_message, or logwrite
27540 , so it does not add anything to the message and does not write a log
27541 entry.
27542
27543 + If you want to apply a control unconditionally, you can use it with a
27544 require verb. For example:
27545
27546 require control = no_multiline_responses
27547
27548 delay = <time>
27549
27550 This modifier may appear in any ACL except notquit. It causes Exim to wait
27551 for the time interval before proceeding. However, when testing Exim using
27552 the -bh option, the delay is not actually imposed (an appropriate message
27553 is output instead). The time is given in the usual Exim notation, and the
27554 delay happens as soon as the modifier is processed. In an SMTP session,
27555 pending output is flushed before the delay is imposed.
27556
27557 Like control, delay can be used with accept or deny, for example:
27558
27559 deny ...some conditions...
27560 delay = 30s
27561
27562 The delay happens if all the conditions are true, before the statement
27563 returns "deny". Compare this with:
27564
27565 deny delay = 30s
27566 ...some conditions...
27567
27568 which waits for 30s before processing the conditions. The delay modifier
27569 can also be used with warn and together with control:
27570
27571 warn ...some conditions...
27572 delay = 2m
27573 control = freeze
27574 accept ...
27575
27576 If delay is encountered when the SMTP PIPELINING extension is in use,
27577 responses to several commands are no longer buffered and sent in one packet
27578 (as they would normally be) because all output is flushed before imposing
27579 the delay. This optimization is disabled so that a number of small delays
27580 do not appear to the client as one large aggregated delay that might
27581 provoke an unwanted timeout. You can, however, disable output flushing for
27582 delay by using a control modifier to set no_delay_flush.
27583
27584 endpass
27585
27586 This modifier, which has no argument, is recognized only in accept and
27587 discard statements. It marks the boundary between the conditions whose
27588 failure causes control to pass to the next statement, and the conditions
27589 whose failure causes the ACL to return "deny". This concept has proved to
27590 be confusing to some people, so the use of endpass is no longer recommended
27591 as "best practice". See the description of accept above for more details.
27592
27593 log_message = <text>
27594
27595 This modifier sets up a message that is used as part of the log message if
27596 the ACL denies access or a warn statement's conditions are true. For
27597 example:
27598
27599 require log_message = wrong cipher suite $tls_in_cipher
27600 encrypted = DES-CBC3-SHA
27601
27602 log_message is also used when recipients are discarded by discard. For
27603 example:
27604
27605 discard <some conditions>
27606 log_message = Discarded $local_part@$domain because...
27607
27608 When access is denied, log_message adds to any underlying error message
27609 that may exist because of a condition failure. For example, while verifying
27610 a recipient address, a :fail: redirection might have already set up a
27611 message.
27612
27613 The message may be defined before the conditions to which it applies,
27614 because the string expansion does not happen until Exim decides that access
27615 is to be denied. This means that any variables that are set by the
27616 condition are available for inclusion in the message. For example, the
27617 $dnslist_<xxx> variables are set after a DNS black list lookup succeeds. If
27618 the expansion of log_message fails, or if the result is an empty string,
27619 the modifier is ignored.
27620
27621 If you want to use a warn statement to log the result of an address
27622 verification, you can use $acl_verify_message to include the verification
27623 error message.
27624
27625 If log_message is used with a warn statement, "Warning:" is added to the
27626 start of the logged message. If the same warning log message is requested
27627 more than once while receiving a single email message, only one copy is
27628 actually logged. If you want to log multiple copies, use logwrite instead
27629 of log_message. In the absence of log_message and logwrite, nothing is
27630 logged for a successful warn statement.
27631
27632 If log_message is not present and there is no underlying error message (for
27633 example, from the failure of address verification), but message is present,
27634 the message text is used for logging rejections. However, if any text for
27635 logging contains newlines, only the first line is logged. In the absence of
27636 both log_message and message, a default built-in message is used for
27637 logging rejections.
27638
27639 log_reject_target = <log name list>
27640
27641 This modifier makes it possible to specify which logs are used for messages
27642 about ACL rejections. Its argument is a colon-separated list of words that
27643 can be "main", "reject", or "panic". The default is "main:reject". The list
27644 may be empty, in which case a rejection is not logged at all. For example,
27645 this ACL fragment writes no logging information when access is denied:
27646
27647 deny <some conditions>
27648 log_reject_target =
27649
27650 This modifier can be used in SMTP and non-SMTP ACLs. It applies to both
27651 permanent and temporary rejections. Its effect lasts for the rest of the
27652 current ACL.
27653
27654 logwrite = <text>
27655
27656 This modifier writes a message to a log file as soon as it is encountered
27657 when processing an ACL. (Compare log_message, which, except in the case of
27658 warn and discard, is used only if the ACL statement denies access.) The
27659 logwrite modifier can be used to log special incidents in ACLs. For
27660 example:
27661
27662 accept <some special conditions>
27663 control = freeze
27664 logwrite = froze message because ...
27665
27666 By default, the message is written to the main log. However, it may begin
27667 with a colon, followed by a comma-separated list of log names, and then
27668 another colon, to specify exactly which logs are to be written. For
27669 example:
27670
27671 logwrite = :main,reject: text for main and reject logs
27672 logwrite = :panic: text for panic log only
27673
27674 message = <text>
27675
27676 This modifier sets up a text string that is expanded and used as a response
27677 message when an ACL statement terminates the ACL with an "accept", "deny",
27678 or "defer" response. (In the case of the accept and discard verbs, there is
27679 some complication if endpass is involved; see the description of accept for
27680 details.)
27681
27682 The expansion of the message happens at the time Exim decides that the ACL
27683 is to end, not at the time it processes message. If the expansion fails, or
27684 generates an empty string, the modifier is ignored. Here is an example
27685 where message must be specified first, because the ACL ends with a
27686 rejection if the hosts condition fails:
27687
27688 require message = Host not recognized
27689 hosts = 10.0.0.0/8
27690
27691 (Once a condition has failed, no further conditions or modifiers are
27692 processed.)
27693
27694 For ACLs that are triggered by SMTP commands, the message is returned as
27695 part of the SMTP response. The use of message with accept (or discard) is
27696 meaningful only for SMTP, as no message is returned when a non-SMTP message
27697 is accepted. In the case of the connect ACL, accepting with a message
27698 modifier overrides the value of smtp_banner. For the EHLO/HELO ACL, a
27699 customized accept message may not contain more than one line (otherwise it
27700 will be truncated at the first newline and a panic logged), and it cannot
27701 affect the EHLO options.
27702
27703 When SMTP is involved, the message may begin with an overriding response
27704 code, consisting of three digits optionally followed by an "extended
27705 response code" of the form n.n.n, each code being followed by a space. For
27706 example:
27707
27708 deny message = 599 1.2.3 Host not welcome
27709 hosts = 192.168.34.0/24
27710
27711 The first digit of the supplied response code must be the same as would be
27712 sent by default. A panic occurs if it is not. Exim uses a 550 code when it
27713 denies access, but for the predata ACL, note that the default success code
27714 is 354, not 2xx.
27715
27716 Notwithstanding the previous paragraph, for the QUIT ACL, unlike the
27717 others, the message modifier cannot override the 221 response code.
27718
27719 The text in a message modifier is literal; any quotes are taken as
27720 literals, but because the string is expanded, backslash escapes are
27721 processed anyway. If the message contains newlines, this gives rise to a
27722 multi-line SMTP response.
27723
27724 For ACLs that are called by an acl = ACL condition, the message is stored
27725 in $acl_verify_message, from which the calling ACL may use it.
27726
27727 If message is used on a statement that verifies an address, the message
27728 specified overrides any message that is generated by the verification
27729 process. However, the original message is available in the variable
27730 $acl_verify_message, so you can incorporate it into your message if you
27731 wish. In particular, if you want the text from :fail: items in redirect
27732 routers to be passed back as part of the SMTP response, you should either
27733 not use a message modifier, or make use of $acl_verify_message.
27734
27735 For compatibility with previous releases of Exim, a message modifier that
27736 is used with a warn verb behaves in a similar way to the add_header
27737 modifier, but this usage is now deprecated. However, message acts only when
27738 all the conditions are true, wherever it appears in an ACL command, whereas
27739 add_header acts as soon as it is encountered. If message is used with warn
27740 in an ACL that is not concerned with receiving a message, it has no effect.
27741
27742 queue = <text>
27743
27744 This modifier specifies the use of a named queue for spool files for the
27745 message. It can only be used before the message is received (i.e. not in
27746 the DATA ACL). This could be used, for example, for known high-volume burst
27747 sources of traffic, or for quarantine of messages. Separate queue-runner
27748 processes will be needed for named queues. If the text after expansion is
27749 empty, the default queue is used.
27750
27751 remove_header = <text>
27752
27753 This modifier specifies one or more header names in a colon-separated list
27754 that are to be removed from an incoming message, assuming, of course, that
27755 the message is ultimately accepted. For details, see section 43.25.
27756
27757 set <acl_name> = <value>
27758
27759 This modifier puts a value into one of the ACL variables (see section 43.19
27760 ).
27761
27762 udpsend = <parameters>
27763
27764 This modifier sends a UDP packet, for purposes such as statistics
27765 collection or behaviour monitoring. The parameters are expanded, and the
27766 result of the expansion must be a colon-separated list consisting of a
27767 destination server, port number, and the packet contents. The server can be
27768 specified as a host name or IPv4 or IPv6 address. The separator can be
27769 changed with the usual angle bracket syntax. For example, you might want to
27770 collect information on which hosts connect when:
27771
27772 udpsend = <; 2001:dB8::dead:beef ; 1234 ;\
27773 $tod_zulu $sender_host_address
27774
27775
27776 43.22 Use of the control modifier
27777 ---------------------------------
27778
27779 The control modifier supports the following settings:
27780
27781 control = allow_auth_unadvertised
27782
27783 This modifier allows a client host to use the SMTP AUTH command even when
27784 it has not been advertised in response to EHLO. Furthermore, because there
27785 are apparently some really broken clients that do this, Exim will accept
27786 AUTH after HELO (rather than EHLO) when this control is set. It should be
27787 used only if you really need it, and you should limit its use to those
27788 broken clients that do not work without it. For example:
27789
27790 warn hosts = 192.168.34.25
27791 control = allow_auth_unadvertised
27792
27793 Normally, when an Exim server receives an AUTH command, it checks the name
27794 of the authentication mechanism that is given in the command to ensure that
27795 it matches an advertised mechanism. When this control is set, the check
27796 that a mechanism has been advertised is bypassed. Any configured mechanism
27797 can be used by the client. This control is permitted only in the connection
27798 and HELO ACLs.
27799
27800 control = caseful_local_part, control = caselower_local_part
27801
27802 These two controls are permitted only in the ACL specified by acl_smtp_rcpt
27803 (that is, during RCPT processing). By default, the contents of $local_part
27804 are lower cased before ACL processing. If "caseful_local_part" is
27805 specified, any uppercase letters in the original local part are restored in
27806 $local_part for the rest of the ACL, or until a control that sets
27807 "caselower_local_part" is encountered.
27808
27809 These controls affect only the current recipient. Moreover, they apply only
27810 to local part handling that takes place directly in the ACL (for example,
27811 as a key in lookups). If a test to verify the recipient is obeyed, the
27812 case-related handling of the local part during the verification is
27813 controlled by the router configuration (see the caseful_local_part generic
27814 router option).
27815
27816 This facility could be used, for example, to add a spam score to local
27817 parts containing upper case letters. For example, using $acl_m4 to
27818 accumulate the spam score:
27819
27820 warn control = caseful_local_part
27821 set acl_m4 = ${eval:\
27822 $acl_m4 + \
27823 ${if match{$local_part}{[A-Z]}{1}{0}}\
27824 }
27825 control = caselower_local_part
27826
27827 Notice that we put back the lower cased version afterwards, assuming that
27828 is what is wanted for subsequent tests.
27829
27830 control = cutthrough_delivery/<options>
27831
27832 This option requests delivery be attempted while the item is being
27833 received.
27834
27835 The option is usable in the RCPT ACL. If enabled for a message received via
27836 smtp and routed to an smtp transport, and only one transport, interface,
27837 destination host and port combination is used for all recipients of the
27838 message, then the delivery connection is made while the receiving
27839 connection is open and data is copied from one to the other.
27840
27841 An attempt to set this option for any recipient but the first for a mail
27842 will be quietly ignored. If a recipient-verify callout (with use_sender)
27843 connection is subsequently requested in the same ACL it is held open and
27844 used for any subsequent recipients and the data, otherwise one is made
27845 after the initial RCPT ACL completes.
27846
27847 Note that routers are used in verify mode, and cannot depend on content of
27848 received headers. Note also that headers cannot be modified by any of the
27849 post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers
27850 (subject to the above) and transports. The Received-By: header is generated
27851 as soon as the body reception starts, rather than the traditional time
27852 after the full message is received; this will affect the timestamp.
27853
27854 All the usual ACLs are called; if one results in the message being
27855 rejected, all effort spent in delivery (including the costs on the ultimate
27856 destination) will be wasted. Note that in the case of data-time ACLs this
27857 includes the entire message body.
27858
27859 Cutthrough delivery is not supported via transport-filters or when DKIM
27860 signing of outgoing messages is done, because it sends data to the ultimate
27861 destination before the entire message has been received from the source. It
27862 is not supported for messages received with the SMTP PRDR or CHUNKING
27863 options in use.
27864
27865 Should the ultimate destination system positively accept or reject the
27866 mail, a corresponding indication is given to the source system and nothing
27867 is queued. If the item is successfully delivered in cutthrough mode the
27868 delivery log lines are tagged with ">>" rather than "=>" and appear before
27869 the acceptance "<=" line.
27870
27871 If there is a temporary error the item is queued for later delivery in the
27872 usual fashion. This behaviour can be adjusted by appending the option defer
27873 =<value> to the control; the default value is "spool" and the alternate
27874 value "pass" copies an SMTP defer response from the target back to the
27875 initiator and does not queue the message. Note that this is independent of
27876 any recipient verify conditions in the ACL.
27877
27878 Delivery in this mode avoids the generation of a bounce mail to a (possibly
27879 faked) sender when the destination system is doing content-scan based
27880 rejection.
27881
27882 control = debug/<options>
27883
27884 This control turns on debug logging, almost as though Exim had been invoked
27885 with "-d", with the output going to a new logfile in the usual logs
27886 directory, by default called debuglog. The filename can be adjusted with
27887 the tag option, which may access any variables already defined. The logging
27888 may be adjusted with the opts option, which takes the same values as the
27889 "-d" command-line option. Logging started this way may be stopped, and the
27890 file removed, with the kill option. Some examples (which depend on
27891 variables that don't exist in all contexts):
27892
27893 control = debug
27894 control = debug/tag=.$sender_host_address
27895 control = debug/opts=+expand+acl
27896 control = debug/tag=.$message_exim_id/opts=+expand
27897 control = debug/kill
27898
27899 control = dkim_disable_verify
27900
27901 This control turns off DKIM verification processing entirely. For details
27902 on the operation and configuration of DKIM, see section 57.1.
27903
27904 control = dscp/<value>
27905
27906 This option causes the DSCP value associated with the socket for the
27907 inbound connection to be adjusted to a given value, given as one of a
27908 number of fixed strings or to numeric value. The -bI:dscp option may be
27909 used to ask Exim which names it knows of. Common values include
27910 "throughput", "mincost", and on newer systems "ef", "af41", etc. Numeric
27911 values may be in the range 0 to 0x3F.
27912
27913 The outbound packets from Exim will be marked with this value in the header
27914 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no
27915 guarantee that these values will have any effect, not be stripped by
27916 networking equipment, or do much of anything without cooperation with your
27917 Network Engineer and those of all network operators between the source and
27918 destination.
27919
27920 control = enforce_sync, control = no_enforce_sync
27921
27922 These controls make it possible to be selective about when SMTP
27923 synchronization is enforced. The global option smtp_enforce_sync specifies
27924 the initial state of the switch (it is true by default). See the
27925 description of this option in chapter 14 for details of SMTP
27926 synchronization checking.
27927
27928 The effect of these two controls lasts for the remainder of the SMTP
27929 connection. They can appear in any ACL except the one for the non-SMTP
27930 messages. The most straightforward place to put them is in the ACL defined
27931 by acl_smtp_connect, which is run at the start of an incoming SMTP
27932 connection, before the first synchronization check. The expected use is to
27933 turn off the synchronization checks for badly-behaved hosts that you
27934 nevertheless need to work with.
27935
27936 control = fakedefer/<message>
27937
27938 This control works in exactly the same way as fakereject (described below)
27939 except that it causes an SMTP 450 response after the message data instead
27940 of a 550 response. You must take care when using fakedefer because it
27941 causes the messages to be duplicated when the sender retries. Therefore,
27942 you should not use fakedefer if the message is to be delivered normally.
27943
27944 control = fakereject/<message>
27945
27946 This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
27947 words, only when an SMTP message is being received. If Exim accepts the
27948 message, instead the final 250 response, a 550 rejection message is sent.
27949 However, Exim proceeds to deliver the message as normal. The control
27950 applies only to the current message, not to any subsequent ones that may be
27951 received in the same SMTP connection.
27952
27953 The text for the 550 response is taken from the control modifier. If no
27954 message is supplied, the following is used:
27955
27956 550-Your message has been rejected but is being
27957 550-kept for evaluation.
27958 550-If it was a legitimate message, it may still be
27959 550 delivered to the target recipient(s).
27960
27961 This facility should be used with extreme caution.
27962
27963 control = freeze
27964
27965 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs,
27966 in other words, only when a message is being received. If the message is
27967 accepted, it is placed on Exim's queue and frozen. The control applies only
27968 to the current message, not to any subsequent ones that may be received in
27969 the same SMTP connection.
27970
27971 This modifier can optionally be followed by "/no_tell". If the global
27972 option freeze_tell is set, it is ignored for the current message (that is,
27973 nobody is told about the freezing), provided all the control=freeze
27974 modifiers that are obeyed for the current message have the "/no_tell"
27975 option.
27976
27977 control = no_delay_flush
27978
27979 Exim normally flushes SMTP output before implementing a delay in an ACL, to
27980 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is
27981 in use. This control, as long as it is encountered before the delay
27982 modifier, disables such output flushing.
27983
27984 control = no_callout_flush
27985
27986 Exim normally flushes SMTP output before performing a callout in an ACL, to
27987 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is
27988 in use. This control, as long as it is encountered before the verify
27989 condition that causes the callout, disables such output flushing.
27990
27991 control = no_mbox_unspool
27992
27993 This control is available when Exim is compiled with the content scanning
27994 extension. Content scanning may require a copy of the current message, or
27995 parts of it, to be written in "mbox format" to a spool file, for passing to
27996 a virus or spam scanner. Normally, such copies are deleted when they are no
27997 longer needed. If this control is set, the copies are not deleted. The
27998 control applies only to the current message, not to any subsequent ones
27999 that may be received in the same SMTP connection. It is provided for
28000 debugging purposes and is unlikely to be useful in production.
28001
28002 control = no_multiline_responses
28003
28004 This control is permitted for any ACL except the one for non-SMTP messages.
28005 It seems that there are broken clients in use that cannot handle multiline
28006 SMTP responses, despite the fact that RFC 821 defined them over 20 years
28007 ago.
28008
28009 If this control is set, multiline SMTP responses from ACL rejections are
28010 suppressed. One way of doing this would have been to put out these
28011 responses as one long line. However, RFC 2821 specifies a maximum of 512
28012 bytes per response ("use multiline responses for more" it says - ha!), and
28013 some of the responses might get close to that. So this facility, which is
28014 after all only a sop to broken clients, is implemented by doing two very
28015 easy things:
28016
28017 + Extra information that is normally output as part of a rejection caused
28018 by sender verification failure is omitted. Only the final line
28019 (typically "sender verification failed") is sent.
28020
28021 + If a message modifier supplies a multiline response, only the first
28022 line is output.
28023
28024 The setting of the switch can, of course, be made conditional on the
28025 calling host. Its effect lasts until the end of the SMTP connection.
28026
28027 control = no_pipelining
28028
28029 This control turns off the advertising of the PIPELINING extension to SMTP
28030 in the current session. To be useful, it must be obeyed before Exim sends
28031 its response to an EHLO command. Therefore, it should normally appear in an
28032 ACL controlled by acl_smtp_connect or acl_smtp_helo. See also
28033 pipelining_advertise_hosts.
28034
28035 control = queue_only
28036
28037 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs,
28038 in other words, only when a message is being received. If the message is
28039 accepted, it is placed on Exim's queue and left there for delivery by a
28040 subsequent queue runner. No immediate delivery process is started. In other
28041 words, it has the effect as the queue_only global option. However, the
28042 control applies only to the current message, not to any subsequent ones
28043 that may be received in the same SMTP connection.
28044
28045 control = submission/<options>
28046
28047 This control is permitted only for the MAIL, RCPT, and start of data ACLs
28048 (the latter is the one defined by acl_smtp_predata). Setting it tells Exim
28049 that the current message is a submission from a local MUA. In this case,
28050 Exim operates in "submission mode", and applies certain fixups to the
28051 message if necessary. For example, it adds a Date: header line if one is
28052 not present. This control is not permitted in the acl_smtp_data ACL,
28053 because that is too late (the message has already been created).
28054
28055 Chapter 47 describes the processing that Exim applies to messages. Section
28056 47.1 covers the processing that happens in submission mode; the available
28057 options for this control are described there. The control applies only to
28058 the current message, not to any subsequent ones that may be received in the
28059 same SMTP connection.
28060
28061 control = suppress_local_fixups
28062
28063 This control applies to locally submitted (non TCP/IP) messages, and is the
28064 complement of "control = submission". It disables the fixups that are
28065 normally applied to locally-submitted messages. Specifically:
28066
28067 + Any Sender: header line is left alone (in this respect, it is a dynamic
28068 version of local_sender_retain).
28069
28070 + No Message-ID:, From:, or Date: header lines are added.
28071
28072 + There is no check that From: corresponds to the actual sender.
28073
28074 This control may be useful when a remotely-originated message is accepted,
28075 passed to some scanning program, and then re-submitted for delivery. It can
28076 be used only in the acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, and
28077 acl_not_smtp_start ACLs, because it has to be set before the message's data
28078 is read.
28079
28080 Note: This control applies only to the current message, not to any others
28081 that are being submitted at the same time using -bs or -bS.
28082
28083 control = utf8_downconvert
28084
28085 This control enables conversion of UTF-8 in message addresses to a-label
28086 form. For details see section 59.1.
28087
28088
28089 43.23 Summary of message fixup control
28090 --------------------------------------
28091
28092 All four possibilities for message fixups can be specified:
28093
28094 * Locally submitted, fixups applied: the default.
28095
28096 * Locally submitted, no fixups applied: use "control =
28097 suppress_local_fixups".
28098
28099 * Remotely submitted, no fixups applied: the default.
28100
28101 * Remotely submitted, fixups applied: use "control = submission".
28102
28103
28104 43.24 Adding header lines in ACLs
28105 ---------------------------------
28106
28107 The add_header modifier can be used to add one or more extra header lines to an
28108 incoming message, as in this example:
28109
28110 warn dnslists = sbl.spamhaus.org : \
28111 dialup.mail-abuse.org
28112 add_header = X-blacklisted-at: $dnslist_domain
28113
28114 The add_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME,
28115 DKIM, and non-SMTP ACLs (in other words, those that are concerned with
28116 receiving a message). The message must ultimately be accepted for add_header to
28117 have any significant effect. You can use add_header with any ACL verb,
28118 including deny (though this is potentially useful only in a RCPT ACL).
28119
28120 Headers will not be added to the message if the modifier is used in DATA, MIME
28121 or DKIM ACLs for a message delivered by cutthrough routing.
28122
28123 Leading and trailing newlines are removed from the data for the add_header
28124 modifier; if it then contains one or more newlines that are not followed by a
28125 space or a tab, it is assumed to contain multiple header lines. Each one is
28126 checked for valid syntax; "X-ACL-Warn:" is added to the front of any line that
28127 is not a valid header line.
28128
28129 Added header lines are accumulated during the MAIL, RCPT, and predata ACLs.
28130 They are added to the message before processing the DATA and MIME ACLs.
28131 However, if an identical header line is requested more than once, only one copy
28132 is actually added to the message. Further header lines may be accumulated
28133 during the DATA and MIME ACLs, after which they are added to the message, again
28134 with duplicates suppressed. Thus, it is possible to add two identical header
28135 lines to an SMTP message, but only if one is added before DATA and one after.
28136 In the case of non-SMTP messages, new headers are accumulated during the
28137 non-SMTP ACLs, and are added to the message after all the ACLs have run. If a
28138 message is rejected after DATA or by the non-SMTP ACL, all added header lines
28139 are included in the entry that is written to the reject log.
28140
28141 Header lines are not visible in string expansions of message headers until they
28142 are added to the message. It follows that header lines defined in the MAIL,
28143 RCPT, and predata ACLs are not visible until the DATA ACL and MIME ACLs are
28144 run. Similarly, header lines that are added by the DATA or MIME ACLs are not
28145 visible in those ACLs. Because of this restriction, you cannot use header lines
28146 as a way of passing data between (for example) the MAIL and RCPT ACLs. If you
28147 want to do this, you can use ACL variables, as described in section 43.19.
28148
28149 The list of headers yet to be added is given by the $headers_added variable.
28150
28151 The add_header modifier acts immediately as it is encountered during the
28152 processing of an ACL. Notice the difference between these two cases:
28153
28154 accept add_header = ADDED: some text
28155 <some condition>
28156
28157 accept <some condition>
28158 add_header = ADDED: some text
28159
28160 In the first case, the header line is always added, whether or not the
28161 condition is true. In the second case, the header line is added only if the
28162 condition is true. Multiple occurrences of add_header may occur in the same ACL
28163 statement. All those that are encountered before a condition fails are
28164 honoured.
28165
28166 For compatibility with previous versions of Exim, a message modifier for a warn
28167 verb acts in the same way as add_header, except that it takes effect only if
28168 all the conditions are true, even if it appears before some of them.
28169 Furthermore, only the last occurrence of message is honoured. This usage of
28170 message is now deprecated. If both add_header and message are present on a warn
28171 verb, both are processed according to their specifications.
28172
28173 By default, new header lines are added to a message at the end of the existing
28174 header lines. However, you can specify that any particular header line should
28175 be added right at the start (before all the Received: lines), immediately after
28176 the first block of Received: lines, or immediately before any line that is not
28177 a Received: or Resent-something: header.
28178
28179 This is done by specifying ":at_start:", ":after_received:", or
28180 ":at_start_rfc:" (or, for completeness, ":at_end:") before the text of the
28181 header line, respectively. (Header text cannot start with a colon, as there has
28182 to be a header name first.) For example:
28183
28184 warn add_header = \
28185 :after_received:X-My-Header: something or other...
28186
28187 If more than one header line is supplied in a single add_header modifier, each
28188 one is treated independently and can therefore be placed differently. If you
28189 add more than one line at the start, or after the Received: block, they end up
28190 in reverse order.
28191
28192 Warning: This facility currently applies only to header lines that are added in
28193 an ACL. It does NOT work for header lines that are added in a system filter or
28194 in a router or transport.
28195
28196
28197 43.25 Removing header lines in ACLs
28198 -----------------------------------
28199
28200 The remove_header modifier can be used to remove one or more header lines from
28201 an incoming message, as in this example:
28202
28203 warn message = Remove internal headers
28204 remove_header = x-route-mail1 : x-route-mail2
28205
28206 The remove_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME,
28207 DKIM, and non-SMTP ACLs (in other words, those that are concerned with
28208 receiving a message). The message must ultimately be accepted for remove_header
28209 to have any significant effect. You can use remove_header with any ACL verb,
28210 including deny, though this is really not useful for any verb that doesn't
28211 result in a delivered message.
28212
28213 Headers will not be removed from the message if the modifier is used in DATA,
28214 MIME or DKIM ACLs for a message delivered by cutthrough routing.
28215
28216 More than one header can be removed at the same time by using a colon separated
28217 list of header names. The header matching is case insensitive. Wildcards are
28218 not permitted, nor is list expansion performed, so you cannot use hostlists to
28219 create a list of headers, however both connection and message variable
28220 expansion are performed ($acl_c_* and $acl_m_*), illustrated in this example:
28221
28222 warn hosts = +internal_hosts
28223 set acl_c_ihdrs = x-route-mail1 : x-route-mail2
28224 warn message = Remove internal headers
28225 remove_header = $acl_c_ihdrs
28226
28227 Header names for removal are accumulated during the MAIL, RCPT, and predata
28228 ACLs. Matching header lines are removed from the message before processing the
28229 DATA and MIME ACLs. If multiple header lines match, all are removed. There is
28230 no harm in attempting to remove the same header twice nor in removing a
28231 non-existent header. Further header lines to be removed may be accumulated
28232 during the DATA and MIME ACLs, after which they are removed from the message,
28233 if present. In the case of non-SMTP messages, headers to be removed are
28234 accumulated during the non-SMTP ACLs, and are removed from the message after
28235 all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
28236 ACL, there really is no effect because there is no logging of what headers
28237 would have been removed.
28238
28239 Header lines are not visible in string expansions until the DATA phase when it
28240 is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are
28241 not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are
28242 removed by the DATA or MIME ACLs are still visible in those ACLs. Because of
28243 this restriction, you cannot use header lines as a way of controlling data
28244 passed between (for example) the MAIL and RCPT ACLs. If you want to do this,
28245 you should instead use ACL variables, as described in section 43.19.
28246
28247 The remove_header modifier acts immediately as it is encountered during the
28248 processing of an ACL. Notice the difference between these two cases:
28249
28250 accept remove_header = X-Internal
28251 <some condition>
28252
28253 accept <some condition>
28254 remove_header = X-Internal
28255
28256 In the first case, the header line is always removed, whether or not the
28257 condition is true. In the second case, the header line is removed only if the
28258 condition is true. Multiple occurrences of remove_header may occur in the same
28259 ACL statement. All those that are encountered before a condition fails are
28260 honoured.
28261
28262 Warning: This facility currently applies only to header lines that are present
28263 during ACL processing. It does NOT remove header lines that are added in a
28264 system filter or in a router or transport.
28265
28266
28267 43.26 ACL conditions
28268 --------------------
28269
28270 Some of the conditions listed in this section are available only when Exim is
28271 compiled with the content-scanning extension. They are included here briefly
28272 for completeness. More detailed descriptions can be found in the discussion on
28273 content scanning in chapter 44.
28274
28275 Not all conditions are relevant in all circumstances. For example, testing
28276 senders and recipients does not make sense in an ACL that is being run as the
28277 result of the arrival of an ETRN command, and checks on message headers can be
28278 done only in the ACLs specified by acl_smtp_data and acl_not_smtp. You can use
28279 the same condition (with different parameters) more than once in the same ACL
28280 statement. This provides a way of specifying an "and" conjunction. The
28281 conditions are as follows:
28282
28283 acl = <name of acl or ACL string or file name >
28284
28285 The possible values of the argument are the same as for the acl_smtp_xxx
28286 options. The named or inline ACL is run. If it returns "accept" the
28287 condition is true; if it returns "deny" the condition is false. If it
28288 returns "defer", the current ACL returns "defer" unless the condition is on
28289 a warn verb. In that case, a "defer" return makes the condition false. This
28290 means that further processing of the warn verb ceases, but processing of
28291 the ACL continues.
28292
28293 If the argument is a named ACL, up to nine space-separated optional values
28294 can be appended; they appear within the called ACL in $acl_arg1 to
28295 $acl_arg9, and $acl_narg is set to the count of values. Previous values of
28296 these variables are restored after the call returns. The name and values
28297 are expanded separately. Note that spaces in complex expansions which are
28298 used as arguments will act as argument separators.
28299
28300 If the nested acl returns "drop" and the outer condition denies access, the
28301 connection is dropped. If it returns "discard", the verb must be accept or
28302 discard, and the action is taken immediately - no further conditions are
28303 tested.
28304
28305 ACLs may be nested up to 20 deep; the limit exists purely to catch runaway
28306 loops. This condition allows you to use different ACLs in different
28307 circumstances. For example, different ACLs can be used to handle RCPT
28308 commands for different local users or different local domains.
28309
28310 authenticated = <string list>
28311
28312 If the SMTP connection is not authenticated, the condition is false.
28313 Otherwise, the name of the authenticator is tested against the list. To
28314 test for authentication by any authenticator, you can set
28315
28316 authenticated = *
28317
28318 condition = <string>
28319
28320 This feature allows you to make up custom conditions. If the result of
28321 expanding the string is an empty string, the number zero, or one of the
28322 strings "no" or "false", the condition is false. If the result is any
28323 non-zero number, or one of the strings "yes" or "true", the condition is
28324 true. For any other value, some error is assumed to have occurred, and the
28325 ACL returns "defer". However, if the expansion is forced to fail, the
28326 condition is ignored. The effect is to treat it as true, whether it is
28327 positive or negative.
28328
28329 decode = <location>
28330
28331 This condition is available only when Exim is compiled with the
28332 content-scanning extension, and it is allowed only in the ACL defined by
28333 acl_smtp_mime. It causes the current MIME part to be decoded into a file.
28334 If all goes well, the condition is true. It is false only if there are
28335 problems such as a syntax error or a memory shortage. For more details, see
28336 chapter 44.
28337
28338 dnslists = <list of domain names and other data>
28339
28340 This condition checks for entries in DNS black lists. These are also known
28341 as "RBL lists", after the original Realtime Blackhole List, but note that
28342 the use of the lists at mail-abuse.org now carries a charge. There are too
28343 many different variants of this condition to describe briefly here. See
28344 sections 43.27-43.37 for details.
28345
28346 domains = <domain list>
28347
28348 This condition is relevant only after a RCPT command. It checks that the
28349 domain of the recipient address is in the domain list. If percent-hack
28350 processing is enabled, it is done before this test is done. If the check
28351 succeeds with a lookup, the result of the lookup is placed in $domain_data
28352 until the next domains test.
28353
28354 Note carefully (because many people seem to fall foul of this): you cannot
28355 use domains in a DATA ACL.
28356
28357 encrypted = <string list>
28358
28359 If the SMTP connection is not encrypted, the condition is false. Otherwise,
28360 the name of the cipher suite in use is tested against the list. To test for
28361 encryption without testing for any specific cipher suite(s), set
28362
28363 encrypted = *
28364
28365 hosts = <host list>
28366
28367 This condition tests that the calling host matches the host list. If you
28368 have name lookups or wildcarded host names and IP addresses in the same
28369 host list, you should normally put the IP addresses first. For example, you
28370 could have:
28371
28372 accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
28373
28374 The lookup in this example uses the host name for its key. This is implied
28375 by the lookup type "dbm". (For a host address lookup you would use
28376 "net-dbm" and it wouldn't matter which way round you had these two items.)
28377
28378 The reason for the problem with host names lies in the left-to-right way
28379 that Exim processes lists. It can test IP addresses without doing any DNS
28380 lookups, but when it reaches an item that requires a host name, it fails if
28381 it cannot find a host name to compare with the pattern. If the above list
28382 is given in the opposite order, the accept statement fails for a host whose
28383 name cannot be found, even if its IP address is 10.9.8.7.
28384
28385 If you really do want to do the name check first, and still recognize the
28386 IP address even if the name lookup fails, you can rewrite the ACL like
28387 this:
28388
28389 accept hosts = dbm;/etc/friendly/hosts
28390 accept hosts = 10.9.8.7
28391
28392 The default action on failing to find the host name is to assume that the
28393 host is not in the list, so the first accept statement fails. The second
28394 statement can then check the IP address.
28395
28396 If a hosts condition is satisfied by means of a lookup, the result of the
28397 lookup is made available in the $host_data variable. This allows you, for
28398 example, to set up a statement like this:
28399
28400 deny hosts = net-lsearch;/some/file
28401 message = $host_data
28402
28403 which gives a custom error message for each denied host.
28404
28405 local_parts = <local part list>
28406
28407 This condition is relevant only after a RCPT command. It checks that the
28408 local part of the recipient address is in the list. If percent-hack
28409 processing is enabled, it is done before this test. If the check succeeds
28410 with a lookup, the result of the lookup is placed in $local_part_data,
28411 which remains set until the next local_parts test.
28412
28413 malware = <option>
28414
28415 This condition is available only when Exim is compiled with the
28416 content-scanning extension. It causes the incoming message to be scanned
28417 for viruses. For details, see chapter 44.
28418
28419 mime_regex = <list of regular expressions>
28420
28421 This condition is available only when Exim is compiled with the
28422 content-scanning extension, and it is allowed only in the ACL defined by
28423 acl_smtp_mime. It causes the current MIME part to be scanned for a match
28424 with any of the regular expressions. For details, see chapter 44.
28425
28426 ratelimit = <parameters>
28427
28428 This condition can be used to limit the rate at which a user or host
28429 submits messages. Details are given in section 43.38.
28430
28431 recipients = <address list>
28432
28433 This condition is relevant only after a RCPT command. It checks the entire
28434 recipient address against a list of recipients.
28435
28436 regex = <list of regular expressions>
28437
28438 This condition is available only when Exim is compiled with the
28439 content-scanning extension, and is available only in the DATA, MIME, and
28440 non-SMTP ACLs. It causes the incoming message to be scanned for a match
28441 with any of the regular expressions. For details, see chapter 44.
28442
28443 sender_domains = <domain list>
28444
28445 This condition tests the domain of the sender of the message against the
28446 given domain list. Note: The domain of the sender address is in
28447 $sender_address_domain. It is not put in $domain during the testing of this
28448 condition. This is an exception to the general rule for testing domain
28449 lists. It is done this way so that, if this condition is used in an ACL for
28450 a RCPT command, the recipient's domain (which is in $domain) can be used to
28451 influence the sender checking.
28452
28453 Warning: It is a bad idea to use this condition on its own as a control on
28454 relaying, because sender addresses are easily, and commonly, forged.
28455
28456 senders = <address list>
28457
28458 This condition tests the sender of the message against the given list. To
28459 test for a bounce message, which has an empty sender, set
28460
28461 senders = :
28462
28463 Warning: It is a bad idea to use this condition on its own as a control on
28464 relaying, because sender addresses are easily, and commonly, forged.
28465
28466 spam = <username>
28467
28468 This condition is available only when Exim is compiled with the
28469 content-scanning extension. It causes the incoming message to be scanned by
28470 SpamAssassin. For details, see chapter 44.
28471
28472 verify = certificate
28473
28474 This condition is true in an SMTP session if the session is encrypted, and
28475 a certificate was received from the client, and the certificate was
28476 verified. The server requests a certificate only if the client matches
28477 tls_verify_hosts or tls_try_verify_hosts (see chapter 42).
28478
28479 verify = csa
28480
28481 This condition checks whether the sending host (the client) is authorized
28482 to send email. Details of how this works are given in section 43.50.
28483
28484 verify = header_names_ascii
28485
28486 This condition is relevant only in an ACL that is run after a message has
28487 been received, that is, in an ACL specified by acl_smtp_data or
28488 acl_not_smtp. It checks all header names (not the content) to make sure
28489 there are no non-ASCII characters, also excluding control characters. The
28490 allowable characters are decimal ASCII values 33 through 126.
28491
28492 Exim itself will handle headers with non-ASCII characters, but it can cause
28493 problems for downstream applications, so this option will allow their
28494 detection and rejection in the DATA ACL's.
28495
28496 verify = header_sender/<options>
28497
28498 This condition is relevant only in an ACL that is run after a message has
28499 been received, that is, in an ACL specified by acl_smtp_data or
28500 acl_not_smtp. It checks that there is a verifiable address in at least one
28501 of the Sender:, Reply-To:, or From: header lines. Such an address is
28502 loosely thought of as a "sender" address (hence the name of the test).
28503 However, an address that appears in one of these headers need not be an
28504 address that accepts bounce messages; only sender addresses in envelopes
28505 are required to accept bounces. Therefore, if you use the callout option on
28506 this check, you might want to arrange for a non-empty address in the MAIL
28507 command.
28508
28509 Details of address verification and the options are given later, starting
28510 at section 43.44 (callouts are described in section 43.45). You can combine
28511 this condition with the senders condition to restrict it to bounce messages
28512 only:
28513
28514 deny senders = :
28515 message = A valid sender header is required for bounces
28516 !verify = header_sender
28517
28518 verify = header_syntax
28519
28520 This condition is relevant only in an ACL that is run after a message has
28521 been received, that is, in an ACL specified by acl_smtp_data or
28522 acl_not_smtp. It checks the syntax of all header lines that can contain
28523 lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:),
28524 returning true if there are no problems. Unqualified addresses (local parts
28525 without domains) are permitted only in locally generated messages and from
28526 hosts that match sender_unqualified_hosts or recipient_unqualified_hosts,
28527 as appropriate.
28528
28529 Note that this condition is a syntax check only. However, a common spamming
28530 ploy used to be to send syntactically invalid headers such as
28531
28532 To: @
28533
28534 and this condition can be used to reject such messages, though they are not
28535 as common as they used to be.
28536
28537 verify = helo
28538
28539 This condition is true if a HELO or EHLO command has been received from the
28540 client host, and its contents have been verified. If there has been no
28541 previous attempt to verify the HELO/EHLO contents, it is carried out when
28542 this condition is encountered. See the description of the helo_verify_hosts
28543 and helo_try_verify_hosts options for details of how to request
28544 verification independently of this condition.
28545
28546 For SMTP input that does not come over TCP/IP (the -bs command line
28547 option), this condition is always true.
28548
28549 verify = not_blind
28550
28551 This condition checks that there are no blind (bcc) recipients in the
28552 message. Every envelope recipient must appear either in a To: header line
28553 or in a Cc: header line for this condition to be true. Local parts are
28554 checked case-sensitively; domains are checked case-insensitively. If
28555 Resent-To: or Resent-Cc: header lines exist, they are also checked. This
28556 condition can be used only in a DATA or non-SMTP ACL.
28557
28558 There are, of course, many legitimate messages that make use of blind (bcc)
28559 recipients. This check should not be used on its own for blocking messages.
28560
28561 verify = recipient/<options>
28562
28563 This condition is relevant only after a RCPT command. It verifies the
28564 current recipient. Details of address verification are given later,
28565 starting at section 43.44. After a recipient has been verified, the value
28566 of $address_data is the last value that was set while routing the address.
28567 This applies even if the verification fails. When an address that is being
28568 verified is redirected to a single address, verification continues with the
28569 new address, and in that case, the subsequent value of $address_data is the
28570 value for the child address.
28571
28572 verify = reverse_host_lookup/<options>
28573
28574 This condition ensures that a verified host name has been looked up from
28575 the IP address of the client host. (This may have happened already if the
28576 host name was needed for checking a host list, or if the host matched
28577 host_lookup.) Verification ensures that the host name obtained from a
28578 reverse DNS lookup, or one of its aliases, does, when it is itself looked
28579 up in the DNS, yield the original IP address.
28580
28581 There is one possible option, "defer_ok". If this is present and a DNS
28582 operation returns a temporary error, the verify condition succeeds.
28583
28584 If this condition is used for a locally generated message (that is, when
28585 there is no client host involved), it always succeeds.
28586
28587 verify = sender/<options>
28588
28589 This condition is relevant only after a MAIL or RCPT command, or after a
28590 message has been received (the acl_smtp_data or acl_not_smtp ACLs). If the
28591 message's sender is empty (that is, this is a bounce message), the
28592 condition is true. Otherwise, the sender address is verified.
28593
28594 If there is data in the $address_data variable at the end of routing, its
28595 value is placed in $sender_address_data at the end of verification. This
28596 value can be used in subsequent conditions and modifiers in the same ACL
28597 statement. It does not persist after the end of the current statement. If
28598 you want to preserve the value for longer, you can save it in an ACL
28599 variable.
28600
28601 Details of verification are given later, starting at section 43.44. Exim
28602 caches the result of sender verification, to avoid doing it more than once
28603 per message.
28604
28605 verify = sender=<address>/<options>
28606
28607 This is a variation of the previous option, in which a modified address is
28608 verified as a sender.
28609
28610 Note that '/' is legal in local-parts; if the address may have such (eg. is
28611 generated from the received message) they must be protected from the
28612 options parsing by doubling:
28613
28614 verify = sender=${sg{${address:$h_sender:}}{/}{//}}
28615
28616
28617 43.27 Using DNS lists
28618 ---------------------
28619
28620 In its simplest form, the dnslists condition tests whether the calling host is
28621 on at least one of a number of DNS lists by looking up the inverted IP address
28622 in one or more DNS domains. (Note that DNS list domains are not mail domains,
28623 so the "+" syntax for named lists doesn't work - it is used for special options
28624 instead.) For example, if the calling host's IP address is 192.168.62.43, and
28625 the ACL statement is
28626
28627 deny dnslists = blackholes.mail-abuse.org : \
28628 dialups.mail-abuse.org
28629
28630 the following records are looked up:
28631
28632 43.62.168.192.blackholes.mail-abuse.org
28633 43.62.168.192.dialups.mail-abuse.org
28634
28635 As soon as Exim finds an existing DNS record, processing of the list stops.
28636 Thus, multiple entries on the list provide an "or" conjunction. If you want to
28637 test that a host is on more than one list (an "and" conjunction), you can use
28638 two separate conditions:
28639
28640 deny dnslists = blackholes.mail-abuse.org
28641 dnslists = dialups.mail-abuse.org
28642
28643 If a DNS lookup times out or otherwise fails to give a decisive answer, Exim
28644 behaves as if the host does not match the list item, that is, as if the DNS
28645 record does not exist. If there are further items in the DNS list, they are
28646 processed.
28647
28648 This is usually the required action when dnslists is used with deny (which is
28649 the most common usage), because it prevents a DNS failure from blocking mail.
28650 However, you can change this behaviour by putting one of the following special
28651 items in the list:
28652
28653 +include_unknown behave as if the item is on the list
28654 +exclude_unknown behave as if the item is not on the list (default)
28655 +defer_unknown give a temporary error
28656
28657 Each of these applies to any subsequent items on the list. For example:
28658
28659 deny dnslists = +defer_unknown : foo.bar.example
28660
28661 Testing the list of domains stops as soon as a match is found. If you want to
28662 warn for one list and block for another, you can use two different statements:
28663
28664 deny dnslists = blackholes.mail-abuse.org
28665 warn message = X-Warn: sending host is on dialups list
28666 dnslists = dialups.mail-abuse.org
28667
28668 DNS list lookups are cached by Exim for the duration of the SMTP session (but
28669 limited by the DNS return TTL value), so a lookup based on the IP address is
28670 done at most once for any incoming connection (assuming long-enough TTL). Exim
28671 does not share information between multiple incoming connections (but your
28672 local name server cache should be active).
28673
28674 There are a number of DNS lists to choose from, some commercial, some free, or
28675 free for small deployments. An overview can be found at https://
28676 en.wikipedia.org/wiki/Comparison_of_DNS_blacklists.
28677
28678
28679 43.28 Specifying the IP address for a DNS list lookup
28680 -----------------------------------------------------
28681
28682 By default, the IP address that is used in a DNS list lookup is the IP address
28683 of the calling host. However, you can specify another IP address by listing it
28684 after the domain name, introduced by a slash. For example:
28685
28686 deny dnslists = black.list.tld/192.168.1.2
28687
28688 This feature is not very helpful with explicit IP addresses; it is intended for
28689 use with IP addresses that are looked up, for example, the IP addresses of the
28690 MX hosts or nameservers of an email sender address. For an example, see section
28691 43.30 below.
28692
28693
28694 43.29 DNS lists keyed on domain names
28695 -------------------------------------
28696
28697 There are some lists that are keyed on domain names rather than inverted IP
28698 addresses (see, e.g., the domain based zones link at http://
28699 www.rfc-ignorant.org/). No reversing of components is used with these lists.
28700 You can change the name that is looked up in a DNS list by listing it after the
28701 domain name, introduced by a slash. For example,
28702
28703 deny message = Sender's domain is listed at $dnslist_domain
28704 dnslists = dsn.rfc-ignorant.org/$sender_address_domain
28705
28706 This particular example is useful only in ACLs that are obeyed after the RCPT
28707 or DATA commands, when a sender address is available. If (for example) the
28708 message's sender is user@tld.example the name that is looked up by this example
28709 is
28710
28711 tld.example.dsn.rfc-ignorant.org
28712
28713 A single dnslists condition can contain entries for both names and IP
28714 addresses. For example:
28715
28716 deny dnslists = sbl.spamhaus.org : \
28717 dsn.rfc-ignorant.org/$sender_address_domain
28718
28719 The first item checks the sending host's IP address; the second checks a domain
28720 name. The whole condition is true if either of the DNS lookups succeeds.
28721
28722
28723 43.30 Multiple explicit keys for a DNS list
28724 -------------------------------------------
28725
28726 The syntax described above for looking up explicitly-defined values (either
28727 names or IP addresses) in a DNS blacklist is a simplification. After the domain
28728 name for the DNS list, what follows the slash can in fact be a list of items.
28729 As with all lists in Exim, the default separator is a colon. However, because
28730 this is a sublist within the list of DNS blacklist domains, it is necessary
28731 either to double the separators like this:
28732
28733 dnslists = black.list.tld/name.1::name.2
28734
28735 or to change the separator character, like this:
28736
28737 dnslists = black.list.tld/<;name.1;name.2
28738
28739 If an item in the list is an IP address, it is inverted before the DNS
28740 blacklist domain is appended. If it is not an IP address, no inversion occurs.
28741 Consider this condition:
28742
28743 dnslists = black.list.tld/<;192.168.1.2;a.domain
28744
28745 The DNS lookups that occur are:
28746
28747 2.1.168.192.black.list.tld
28748 a.domain.black.list.tld
28749
28750 Once a DNS record has been found (that matches a specific IP return address, if
28751 specified - see section 43.33), no further lookups are done. If there is a
28752 temporary DNS error, the rest of the sublist of domains or IP addresses is
28753 tried. A temporary error for the whole dnslists item occurs only if no other
28754 DNS lookup in this sublist succeeds. In other words, a successful lookup for
28755 any of the items in the sublist overrides a temporary error for a previous
28756 item.
28757
28758 The ability to supply a list of items after the slash is in some sense just a
28759 syntactic convenience. These two examples have the same effect:
28760
28761 dnslists = black.list.tld/a.domain : black.list.tld/b.domain
28762 dnslists = black.list.tld/a.domain::b.domain
28763
28764 However, when the data for the list is obtained from a lookup, the second form
28765 is usually much more convenient. Consider this example:
28766
28767 deny message = The mail servers for the domain \
28768 $sender_address_domain \
28769 are listed at $dnslist_domain ($dnslist_value); \
28770 see $dnslist_text.
28771 dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\
28772 ${lookup dnsdb {>|mxh=\
28773 $sender_address_domain} }} }
28774
28775 Note the use of ">|" in the dnsdb lookup to specify the separator for multiple
28776 DNS records. The inner dnsdb lookup produces a list of MX hosts and the outer
28777 dnsdb lookup finds the IP addresses for these hosts. The result of expanding
28778 the condition might be something like this:
28779
28780 dnslists = sbl.spamhaus.org/<|192.168.2.3|192.168.5.6|...
28781
28782 Thus, this example checks whether or not the IP addresses of the sender
28783 domain's mail servers are on the Spamhaus black list.
28784
28785 The key that was used for a successful DNS list lookup is put into the variable
28786 $dnslist_matched (see section 43.32).
28787
28788
28789 43.31 Data returned by DNS lists
28790 --------------------------------
28791
28792 DNS lists are constructed using address records in the DNS. The original RBL
28793 just used the address 127.0.0.1 on the right hand side of each record, but the
28794 RBL+ list and some other lists use a number of values with different meanings.
28795 The values used on the RBL+ list are:
28796
28797 127.1.0.1 RBL
28798 127.1.0.2 DUL
28799 127.1.0.3 DUL and RBL
28800 127.1.0.4 RSS
28801 127.1.0.5 RSS and RBL
28802 127.1.0.6 RSS and DUL
28803 127.1.0.7 RSS and DUL and RBL
28804
28805 Section 43.33 below describes how you can distinguish between different values.
28806 Some DNS lists may return more than one address record; see section 43.35 for
28807 details of how they are checked.
28808
28809
28810 43.32 Variables set from DNS lists
28811 ----------------------------------
28812
28813 When an entry is found in a DNS list, the variable $dnslist_domain contains the
28814 name of the overall domain that matched (for example, "spamhaus.example"),
28815 $dnslist_matched contains the key within that domain (for example,
28816 "192.168.5.3"), and $dnslist_value contains the data from the DNS record. When
28817 the key is an IP address, it is not reversed in $dnslist_matched (though it is,
28818 of course, in the actual lookup). In simple cases, for example:
28819
28820 deny dnslists = spamhaus.example
28821
28822 the key is also available in another variable (in this case,
28823 $sender_host_address). In more complicated cases, however, this is not true.
28824 For example, using a data lookup (as described in section 43.30) might generate
28825 a dnslists lookup like this:
28826
28827 deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
28828
28829 If this condition succeeds, the value in $dnslist_matched might be
28830 "192.168.6.7" (for example).
28831
28832 If more than one address record is returned by the DNS lookup, all the IP
28833 addresses are included in $dnslist_value, separated by commas and spaces. The
28834 variable $dnslist_text contains the contents of any associated TXT record. For
28835 lists such as RBL+ the TXT record for a merged entry is often not very
28836 meaningful. See section 43.36 for a way of obtaining more information.
28837
28838 You can use the DNS list variables in message or log_message modifiers -
28839 although these appear before the condition in the ACL, they are not expanded
28840 until after it has failed. For example:
28841
28842 deny hosts = !+local_networks
28843 message = $sender_host_address is listed \
28844 at $dnslist_domain
28845 dnslists = rbl-plus.mail-abuse.example
28846
28847
28848 43.33 Additional matching conditions for DNS lists
28849 --------------------------------------------------
28850
28851 You can add an equals sign and an IP address after a dnslists domain name in
28852 order to restrict its action to DNS records with a matching right hand side.
28853 For example,
28854
28855 deny dnslists = rblplus.mail-abuse.org=127.0.0.2
28856
28857 rejects only those hosts that yield 127.0.0.2. Without this additional data,
28858 any address record is considered to be a match. For the moment, we assume that
28859 the DNS lookup returns just one record. Section 43.35 describes how multiple
28860 records are handled.
28861
28862 More than one IP address may be given for checking, using a comma as a
28863 separator. These are alternatives - if any one of them matches, the dnslists
28864 condition is true. For example:
28865
28866 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
28867
28868 If you want to specify a constraining address list and also specify names or IP
28869 addresses to be looked up, the constraining address list must be specified
28870 first. For example:
28871
28872 deny dnslists = dsn.rfc-ignorant.org\
28873 =127.0.0.2/$sender_address_domain
28874
28875 If the character "&" is used instead of "=", the comparison for each listed IP
28876 address is done by a bitwise "and" instead of by an equality test. In other
28877 words, the listed addresses are used as bit masks. The comparison is true if
28878 all the bits in the mask are present in the address that is being tested. For
28879 example:
28880
28881 dnslists = a.b.c&0.0.0.3
28882
28883 matches if the address is x.x.x.3, x.x.x.7, x.x.x.11, etc. If you want to test
28884 whether one bit or another bit is present (as opposed to both being present),
28885 you must use multiple values. For example:
28886
28887 dnslists = a.b.c&0.0.0.1,0.0.0.2
28888
28889 matches if the final component of the address is an odd number or two times an
28890 odd number.
28891
28892
28893 43.34 Negated DNS matching conditions
28894 -------------------------------------
28895
28896 You can supply a negative list of IP addresses as part of a dnslists condition.
28897 Whereas
28898
28899 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
28900
28901 means "deny if the host is in the black list at the domain a.b.c and the IP
28902 address yielded by the list is either 127.0.0.2 or 127.0.0.3",
28903
28904 deny dnslists = a.b.c!=127.0.0.2,127.0.0.3
28905
28906 means "deny if the host is in the black list at the domain a.b.c and the IP
28907 address yielded by the list is not 127.0.0.2 and not 127.0.0.3". In other
28908 words, the result of the test is inverted if an exclamation mark appears before
28909 the "=" (or the "&") sign.
28910
28911 Note: This kind of negation is not the same as negation in a domain, host, or
28912 address list (which is why the syntax is different).
28913
28914 If you are using just one list, the negation syntax does not gain you much. The
28915 previous example is precisely equivalent to
28916
28917 deny dnslists = a.b.c
28918 !dnslists = a.b.c=127.0.0.2,127.0.0.3
28919
28920 However, if you are using multiple lists, the negation syntax is clearer.
28921 Consider this example:
28922
28923 deny dnslists = sbl.spamhaus.org : \
28924 list.dsbl.org : \
28925 dnsbl.njabl.org!=127.0.0.3 : \
28926 relays.ordb.org
28927
28928 Using only positive lists, this would have to be:
28929
28930 deny dnslists = sbl.spamhaus.org : \
28931 list.dsbl.org
28932 deny dnslists = dnsbl.njabl.org
28933 !dnslists = dnsbl.njabl.org=127.0.0.3
28934 deny dnslists = relays.ordb.org
28935
28936 which is less clear, and harder to maintain.
28937
28938
28939 43.35 Handling multiple DNS records from a DNS list
28940 ---------------------------------------------------
28941
28942 A DNS lookup for a dnslists condition may return more than one DNS record,
28943 thereby providing more than one IP address. When an item in a dnslists list is
28944 followed by "=" or "&" and a list of IP addresses, in order to restrict the
28945 match to specific results from the DNS lookup, there are two ways in which the
28946 checking can be handled. For example, consider the condition:
28947
28948 dnslists = a.b.c=127.0.0.1
28949
28950 What happens if the DNS lookup for the incoming IP address yields both
28951 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the condition
28952 true because at least one given value was found, or is it false because at
28953 least one of the found values was not listed? And how does this affect negated
28954 conditions? Both possibilities are provided for with the help of additional
28955 separators "==" and "=&".
28956
28957 * If "=" or "&" is used, the condition is true if any one of the looked up IP
28958 addresses matches one of the listed addresses. For the example above, the
28959 condition is true because 127.0.0.1 matches.
28960
28961 * If "==" or "=&" is used, the condition is true only if every one of the
28962 looked up IP addresses matches one of the listed addresses. If the
28963 condition is changed to:
28964
28965 dnslists = a.b.c==127.0.0.1
28966
28967 and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
28968 false because 127.0.0.2 is not listed. You would need to have:
28969
28970 dnslists = a.b.c==127.0.0.1,127.0.0.2
28971
28972 for the condition to be true.
28973
28974 When "!" is used to negate IP address matching, it inverts the result, giving
28975 the precise opposite of the behaviour above. Thus:
28976
28977 * If "!=" or "!&" is used, the condition is true if none of the looked up IP
28978 addresses matches one of the listed addresses. Consider:
28979
28980 dnslists = a.b.c!&0.0.0.1
28981
28982 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
28983 false because 127.0.0.1 matches.
28984
28985 * If "!==" or "!=&" is used, the condition is true if there is at least one
28986 looked up IP address that does not match. Consider:
28987
28988 dnslists = a.b.c!=&0.0.0.1
28989
28990 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
28991 true, because 127.0.0.2 does not match. You would need to have:
28992
28993 dnslists = a.b.c!=&0.0.0.1,0.0.0.2
28994
28995 for the condition to be false.
28996
28997 When the DNS lookup yields only a single IP address, there is no difference
28998 between "=" and "==" and between "&" and "=&".
28999
29000
29001 43.36 Detailed information from merged DNS lists
29002 ------------------------------------------------
29003
29004 When the facility for restricting the matching IP values in a DNS list is used,
29005 the text from the TXT record that is set in $dnslist_text may not reflect the
29006 true reason for rejection. This happens when lists are merged and the IP
29007 address in the A record is used to distinguish them; unfortunately there is
29008 only one TXT record. One way round this is not to use merged lists, but that
29009 can be inefficient because it requires multiple DNS lookups where one would do
29010 in the vast majority of cases when the host of interest is not on any of the
29011 lists.
29012
29013 A less inefficient way of solving this problem is available. If two domain
29014 names, comma-separated, are given, the second is used first to do an initial
29015 check, making use of any IP value restrictions that are set. If there is a
29016 match, the first domain is used, without any IP value restrictions, to get the
29017 TXT record. As a byproduct of this, there is also a check that the IP being
29018 tested is indeed on the first list. The first domain is the one that is put in
29019 $dnslist_domain. For example:
29020
29021 deny message = \
29022 rejected because $sender_host_address is blacklisted \
29023 at $dnslist_domain\n$dnslist_text
29024 dnslists = \
29025 sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
29026 dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
29027
29028 For the first blacklist item, this starts by doing a lookup in
29029 sbl-xbl.spamhaus.org and testing for a 127.0.0.2 return. If there is a match,
29030 it then looks in sbl.spamhaus.org, without checking the return value, and as
29031 long as something is found, it looks for the corresponding TXT record. If there
29032 is no match in sbl-xbl.spamhaus.org, nothing more is done. The second blacklist
29033 item is processed similarly.
29034
29035 If you are interested in more than one merged list, the same list must be given
29036 several times, but because the results of the DNS lookups are cached, the DNS
29037 calls themselves are not repeated. For example:
29038
29039 deny dnslists = \
29040 http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
29041 socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
29042 misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
29043 dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
29044
29045 In this case there is one lookup in dnsbl.sorbs.net, and if none of the IP
29046 values matches (or if no record is found), this is the only lookup that is
29047 done. Only if there is a match is one of the more specific lists consulted.
29048
29049
29050 43.37 DNS lists and IPv6
29051 ------------------------
29052
29053 If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
29054 nibble by nibble. For example, if the calling host's IP address is
29055 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up
29056
29057 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8.
29058 f.f.f.f.e.f.f.3.blackholes.mail-abuse.org
29059
29060 (split over two lines here to fit on the page). Unfortunately, some of the DNS
29061 lists contain wildcard records, intended for IPv4, that interact badly with
29062 IPv6. For example, the DNS entry
29063
29064 *.3.some.list.example. A 127.0.0.1
29065
29066 is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list.
29067 Unfortunately, it also matches the entire 3::/4 IPv6 network.
29068
29069 You can exclude IPv6 addresses from DNS lookups by making use of a suitable
29070 condition condition, as in this example:
29071
29072 deny condition = ${if isip4{$sender_host_address}}
29073 dnslists = some.list.example
29074
29075 If an explicit key is being used for a DNS lookup and it may be an IPv6 address
29076 you should specify alternate list separators for both the outer (DNS list name)
29077 list and inner (lookup keys) list:
29078
29079 dnslists = <; dnsbl.example.com/<|$acl_m_addrslist
29080
29081
29082 43.38 Rate limiting incoming messages
29083 -------------------------------------
29084
29085 The ratelimit ACL condition can be used to measure and control the rate at
29086 which clients can send email. This is more powerful than the smtp_ratelimit_*
29087 options, because those options control the rate of commands in a single SMTP
29088 session only, whereas the ratelimit condition works across all connections
29089 (concurrent and sequential) from the same client host. The syntax of the
29090 ratelimit condition is:
29091
29092 ratelimit = <m> / <p> / <options> / <key>
29093
29094 If the average client sending rate is less than m messages per time period p
29095 then the condition is false; otherwise it is true.
29096
29097 As a side-effect, the ratelimit condition sets the expansion variable
29098 $sender_rate to the client's computed rate, $sender_rate_limit to the
29099 configured value of m, and $sender_rate_period to the configured value of p.
29100
29101 The parameter p is the smoothing time constant, in the form of an Exim time
29102 interval, for example, "8h" for eight hours. A larger time constant means that
29103 it takes Exim longer to forget a client's past behaviour. The parameter m is
29104 the maximum number of messages that a client is permitted to send in each time
29105 interval. It also specifies the number of messages permitted in a fast burst.
29106 By increasing both m and p but keeping m/p constant, you can allow a client to
29107 send more messages in a burst without changing its long-term sending rate
29108 limit. Conversely, if m and p are both small, messages must be sent at an even
29109 rate.
29110
29111 There is a script in util/ratelimit.pl which extracts sending rates from log
29112 files, to assist with choosing appropriate settings for m and p when deploying
29113 the ratelimit ACL condition. The script prints usage instructions when it is
29114 run with no arguments.
29115
29116 The key is used to look up the data for calculating the client's average
29117 sending rate. This data is stored in Exim's spool directory, alongside the
29118 retry and other hints databases. The default key is $sender_host_address, which
29119 means Exim computes the sending rate of each client host IP address. By
29120 changing the key you can change how Exim identifies clients for the purpose of
29121 ratelimiting. For example, to limit the sending rate of each authenticated
29122 user, independent of the computer they are sending from, set the key to
29123 $authenticated_id. You must ensure that the lookup key is meaningful; for
29124 example, $authenticated_id is only meaningful if the client has authenticated
29125 (which you can check with the authenticated ACL condition).
29126
29127 The lookup key does not have to identify clients: If you want to limit the rate
29128 at which a recipient receives messages, you can use the key
29129 "$local_part@$domain" with the per_rcpt option (see below) in a RCPT ACL.
29130
29131 Each ratelimit condition can have up to four options. A per_* option specifies
29132 what Exim measures the rate of, for example, messages or recipients or bytes.
29133 You can adjust the measurement using the unique= and/or count= options. You can
29134 also control when Exim updates the recorded rate using a strict, leaky, or
29135 readonly option. The options are separated by a slash, like the other
29136 parameters. They may appear in any order.
29137
29138 Internally, Exim appends the smoothing constant p onto the lookup key with any
29139 options that alter the meaning of the stored data. The limit m is not stored,
29140 so you can alter the configured maximum rate and Exim will still remember
29141 clients' past behaviour. If you change the per_* mode or add or remove the
29142 unique= option, the lookup key changes so Exim will forget past behaviour. The
29143 lookup key is not affected by changes to the update mode and the count= option.
29144
29145
29146 43.39 Ratelimit options for what is being measured
29147 --------------------------------------------------
29148
29149 The per_conn option limits the client's connection rate. It is not normally
29150 used in the acl_not_smtp, acl_not_smtp_mime, or acl_not_smtp_start ACLs.
29151
29152 The per_mail option limits the client's rate of sending messages. This is the
29153 default if none of the per_* options is specified. It can be used in
29154 acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, acl_smtp_data,
29155 or acl_not_smtp.
29156
29157 The per_byte option limits the sender's email bandwidth. It can be used in the
29158 same ACLs as the per_mail option, though it is best to use this option in the
29159 acl_smtp_mime, acl_smtp_data or acl_not_smtp ACLs; if it is used in an earlier
29160 ACL, Exim relies on the SIZE parameter given by the client in its MAIL command,
29161 which may be inaccurate or completely missing. You can follow the limit m in
29162 the configuration with K, M, or G to specify limits in kilobytes, megabytes, or
29163 gigabytes, respectively.
29164
29165 The per_rcpt option causes Exim to limit the rate at which recipients are
29166 accepted. It can be used in the acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime,
29167 acl_smtp_data, or acl_smtp_rcpt ACLs. In acl_smtp_rcpt the rate is updated one
29168 recipient at a time; in the other ACLs the rate is updated with the total
29169 (accepted) recipient count in one go. Note that in either case the rate
29170 limiting engine will see a message with many recipients as a large high-speed
29171 burst.
29172
29173 The per_addr option is like the per_rcpt option, except it counts the number of
29174 different recipients that the client has sent messages to in the last time
29175 period. That is, if the client repeatedly sends messages to the same recipient,
29176 its measured rate is not increased. This option can only be used in
29177 acl_smtp_rcpt.
29178
29179 The per_cmd option causes Exim to recompute the rate every time the condition
29180 is processed. This can be used to limit the rate of any SMTP command. If it is
29181 used in multiple ACLs it can limit the aggregate rate of multiple different
29182 commands.
29183
29184 The count= option can be used to alter how much Exim adds to the client's
29185 measured rate. For example, the per_byte option is equivalent to "per_mail/
29186 count=$message_size". If there is no count= option, Exim increases the measured
29187 rate by one (except for the per_rcpt option in ACLs other than acl_smtp_rcpt).
29188 The count does not have to be an integer.
29189
29190 The unique= option is described in section 43.42 below.
29191
29192
29193 43.40 Ratelimit update modes
29194 ----------------------------
29195
29196 You can specify one of three options with the ratelimit condition to control
29197 when its database is updated. This section describes the readonly mode, and the
29198 next section describes the strict and leaky modes.
29199
29200 If the ratelimit condition is used in readonly mode, Exim looks up a
29201 previously-computed rate to check against the limit.
29202
29203 For example, you can test the client's sending rate and deny it access (when it
29204 is too fast) in the connect ACL. If the client passes this check then it can go
29205 on to send a message, in which case its recorded rate will be updated in the
29206 MAIL ACL. Subsequent connections from the same client will check this new rate.
29207
29208 acl_check_connect:
29209 deny ratelimit = 100 / 5m / readonly
29210 log_message = RATE CHECK: $sender_rate/$sender_rate_period \
29211 (max $sender_rate_limit)
29212 # ...
29213 acl_check_mail:
29214 warn ratelimit = 100 / 5m / strict
29215 log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
29216 (max $sender_rate_limit)
29217
29218 If Exim encounters multiple ratelimit conditions with the same key when
29219 processing a message then it may increase the client's measured rate more than
29220 it should. For example, this will happen if you check the per_rcpt option in
29221 both acl_smtp_rcpt and acl_smtp_data. However it's OK to check the same
29222 ratelimit condition multiple times in the same ACL. You can avoid any multiple
29223 update problems by using the readonly option on later ratelimit checks.
29224
29225 The per_* options described above do not make sense in some ACLs. If you use a
29226 per_* option in an ACL where it is not normally permitted then the update mode
29227 defaults to readonly and you cannot specify the strict or leaky modes. In other
29228 ACLs the default update mode is leaky (see the next section) so you must
29229 specify the readonly option explicitly.
29230
29231
29232 43.41 Ratelimit options for handling fast clients
29233 -------------------------------------------------
29234
29235 If a client's average rate is greater than the maximum, the rate limiting
29236 engine can react in two possible ways, depending on the presence of the strict
29237 or leaky update modes. This is independent of the other counter-measures (such
29238 as rejecting the message) that may be specified by the rest of the ACL.
29239
29240 The leaky (default) option means that the client's recorded rate is not updated
29241 if it is above the limit. The effect of this is that Exim measures the client's
29242 average rate of successfully sent email,
29243
29244 up to the given limit. This is appropriate if the countermeasure when the
29245 condition is true consists of refusing the message, and is generally the better
29246 choice if you have clients that retry automatically. If the action when true is
29247 anything more complex then this option is likely not what is wanted.
29248
29249 The strict option means that the client's recorded rate is always updated. The
29250 effect of this is that Exim measures the client's average rate of attempts to
29251 send email, which can be much higher than the maximum it is actually allowed.
29252 If the client is over the limit it may be subjected to counter-measures by the
29253 ACL. It must slow down and allow sufficient time to pass that its computed rate
29254 falls below the maximum before it can send email again. The time (the number of
29255 smoothing periods) it must wait and not attempt to send mail can be calculated
29256 with this formula:
29257
29258 ln(peakrate/maxrate)
29259
29260
29261 43.42 Limiting the rate of different events
29262 -------------------------------------------
29263
29264 The ratelimit unique= option controls a mechanism for counting the rate of
29265 different events. For example, the per_addr option uses this mechanism to count
29266 the number of different recipients that the client has sent messages to in the
29267 last time period; it is equivalent to "per_rcpt/unique=$local_part@$domain".
29268 You could use this feature to measure the rate that a client uses different
29269 sender addresses with the options "per_mail/unique=$sender_address".
29270
29271 For each ratelimit key Exim stores the set of unique= values that it has seen
29272 for that key. The whole set is thrown away when it is older than the rate
29273 smoothing period p, so each different event is counted at most once per period.
29274 In the leaky update mode, an event that causes the client to go over the limit
29275 is not added to the set, in the same way that the client's recorded rate is not
29276 updated in the same situation.
29277
29278 When you combine the unique= and readonly options, the specific unique= value
29279 is ignored, and Exim just retrieves the client's stored rate.
29280
29281 The unique= mechanism needs more space in the ratelimit database than the other
29282 ratelimit options in order to store the event set. The number of unique values
29283 is potentially as large as the rate limit, so the extra space required
29284 increases with larger limits.
29285
29286 The uniqueification is not perfect: there is a small probability that Exim will
29287 think a new event has happened before. If the sender's rate is less than the
29288 limit, Exim should be more than 99.9% correct. However in strict mode the
29289 measured rate can go above the limit, in which case Exim may under-count events
29290 by a significant margin. Fortunately, if the rate is high enough (2.7 times the
29291 limit) that the false positive rate goes above 9%, then Exim will throw away
29292 the over-full event set before the measured rate falls below the limit.
29293 Therefore the only harm should be that exceptionally high sending rates are
29294 logged incorrectly; any countermeasures you configure will be as effective as
29295 intended.
29296
29297
29298 43.43 Using rate limiting
29299 -------------------------
29300
29301 Exim's other ACL facilities are used to define what counter-measures are taken
29302 when the rate limit is exceeded. This might be anything from logging a warning
29303 (for example, while measuring existing sending rates in order to define
29304 policy), through time delays to slow down fast senders, up to rejecting the
29305 message. For example:
29306
29307 # Log all senders' rates
29308 warn ratelimit = 0 / 1h / strict
29309 log_message = Sender rate $sender_rate / $sender_rate_period
29310
29311 # Slow down fast senders; note the need to truncate $sender_rate
29312 # at the decimal point.
29313 warn ratelimit = 100 / 1h / per_rcpt / strict
29314 delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
29315 $sender_rate_limit }s
29316
29317 # Keep authenticated users under control
29318 deny authenticated = *
29319 ratelimit = 100 / 1d / strict / $authenticated_id
29320
29321 # System-wide rate limit
29322 defer message = Sorry, too busy. Try again later.
29323 ratelimit = 10 / 1s / $primary_hostname
29324
29325 # Restrict incoming rate from each host, with a default
29326 # set using a macro and special cases looked up in a table.
29327 defer message = Sender rate exceeds $sender_rate_limit \
29328 messages per $sender_rate_period
29329 ratelimit = ${lookup {$sender_host_address} \
29330 cdb {DB/ratelimits.cdb} \
29331 {$value} {RATELIMIT} }
29332
29333 Warning: If you have a busy server with a lot of ratelimit tests, especially
29334 with the per_rcpt option, you may suffer from a performance bottleneck caused
29335 by locking on the ratelimit hints database. Apart from making your ACLs less
29336 complicated, you can reduce the problem by using a RAM disk for Exim's hints
29337 directory (usually /var/spool/exim/db/). However this means that Exim will lose
29338 its hints data after a reboot (including retry hints, the callout cache, and
29339 ratelimit data).
29340
29341
29342 43.44 Address verification
29343 --------------------------
29344
29345 Several of the verify conditions described in section 43.26 cause addresses to
29346 be verified. Section 43.48 discusses the reporting of sender verification
29347 failures. The verification conditions can be followed by options that modify
29348 the verification process. The options are separated from the keyword and from
29349 each other by slashes, and some of them contain parameters. For example:
29350
29351 verify = sender/callout
29352 verify = recipient/defer_ok/callout=10s,defer_ok
29353
29354 The first stage of address verification, which always happens, is to run the
29355 address through the routers, in "verify mode". Routers can detect the
29356 difference between verification and routing for delivery, and their actions can
29357 be varied by a number of generic options such as verify and verify_only (see
29358 chapter 15). If routing fails, verification fails. The available options are as
29359 follows:
29360
29361 * If the callout option is specified, successful routing to one or more
29362 remote hosts is followed by a "callout" to those hosts as an additional
29363 check. Callouts and their sub-options are discussed in the next section.
29364
29365 * If there is a defer error while doing verification routing, the ACL
29366 normally returns "defer". However, if you include defer_ok in the options,
29367 the condition is forced to be true instead. Note that this is a main
29368 verification option as well as a suboption for callouts.
29369
29370 * The no_details option is covered in section 43.48, which discusses the
29371 reporting of sender address verification failures.
29372
29373 * The success_on_redirect option causes verification always to succeed
29374 immediately after a successful redirection. By default, if a redirection
29375 generates just one address, that address is also verified. See further
29376 discussion in section 43.49.
29377
29378 After an address verification failure, $acl_verify_message contains the error
29379 message that is associated with the failure. It can be preserved by coding like
29380 this:
29381
29382 warn !verify = sender
29383 set acl_m0 = $acl_verify_message
29384
29385 If you are writing your own custom rejection message or log message when
29386 denying access, you can use this variable to include information about the
29387 verification failure.
29388
29389 In addition, $sender_verify_failure or $recipient_verify_failure (as
29390 appropriate) contains one of the following words:
29391
29392 * qualify: The address was unqualified (no domain), and the message was
29393 neither local nor came from an exempted host.
29394
29395 * route: Routing failed.
29396
29397 * mail: Routing succeeded, and a callout was attempted; rejection occurred at
29398 or before the MAIL command (that is, on initial connection, HELO, or MAIL).
29399
29400 * recipient: The RCPT command in a callout was rejected.
29401
29402 * postmaster: The postmaster check in a callout was rejected.
29403
29404 The main use of these variables is expected to be to distinguish between
29405 rejections of MAIL and rejections of RCPT in callouts.
29406
29407 The above variables may also be set after a successful address verification to:
29408
29409 * random: A random local-part callout succeeded
29410
29411
29412 43.45 Callout verification
29413 --------------------------
29414
29415 For non-local addresses, routing verifies the domain, but is unable to do any
29416 checking of the local part. There are situations where some means of verifying
29417 the local part is desirable. One way this can be done is to make an SMTP
29418 callback to a delivery host for the sender address or a callforward to a
29419 subsequent host for a recipient address, to see if the host accepts the
29420 address. We use the term callout to cover both cases. Note that for a sender
29421 address, the callback is not to the client host that is trying to deliver the
29422 message, but to one of the hosts that accepts incoming mail for the sender's
29423 domain.
29424
29425 Exim does not do callouts by default. If you want them to happen, you must
29426 request them by setting appropriate options on the verify condition, as
29427 described below. This facility should be used with care, because it can add a
29428 lot of resource usage to the cost of verifying an address. However, Exim does
29429 cache the results of callouts, which helps to reduce the cost. Details of
29430 caching are in section 43.47.
29431
29432 Recipient callouts are usually used only between hosts that are controlled by
29433 the same administration. For example, a corporate gateway host could use
29434 callouts to check for valid recipients on an internal mailserver. A successful
29435 callout does not guarantee that a real delivery to the address would succeed;
29436 on the other hand, a failing callout does guarantee that a delivery would fail.
29437
29438 If the callout option is present on a condition that verifies an address, a
29439 second stage of verification occurs if the address is successfully routed to
29440 one or more remote hosts. The usual case is routing by a dnslookup or a
29441 manualroute router, where the router specifies the hosts. However, if a router
29442 that does not set up hosts routes to an smtp transport with a hosts setting,
29443 the transport's hosts are used. If an smtp transport has hosts_override set,
29444 its hosts are always used, whether or not the router supplies a host list.
29445 Callouts are only supported on smtp transports.
29446
29447 The port that is used is taken from the transport, if it is specified and is a
29448 remote transport. (For routers that do verification only, no transport need be
29449 specified.) Otherwise, the default SMTP port is used. If a remote transport
29450 specifies an outgoing interface, this is used; otherwise the interface is not
29451 specified. Likewise, the text that is used for the HELO command is taken from
29452 the transport's helo_data option; if there is no transport, the value of
29453 $smtp_active_hostname is used.
29454
29455 For a sender callout check, Exim makes SMTP connections to the remote hosts, to
29456 test whether a bounce message could be delivered to the sender address. The
29457 following SMTP commands are sent:
29458
29459 HELO <local host name>
29460 MAIL FROM:<>
29461 RCPT TO:<the address to be tested>
29462 QUIT
29463
29464 LHLO is used instead of HELO if the transport's protocol option is set to
29465 "lmtp".
29466
29467 The callout may use EHLO, AUTH and/or STARTTLS given appropriate option
29468 settings.
29469
29470 A recipient callout check is similar. By default, it also uses an empty address
29471 for the sender. This default is chosen because most hosts do not make use of
29472 the sender address when verifying a recipient. Using the same address means
29473 that a single cache entry can be used for each recipient. Some sites, however,
29474 do make use of the sender address when verifying. These are catered for by the
29475 use_sender and use_postmaster options, described in the next section.
29476
29477 If the response to the RCPT command is a 2xx code, the verification succeeds.
29478 If it is 5xx, the verification fails. For any other condition, Exim tries the
29479 next host, if any. If there is a problem with all the remote hosts, the ACL
29480 yields "defer", unless the defer_ok parameter of the callout option is given,
29481 in which case the condition is forced to succeed.
29482
29483 A callout may take a little time. For this reason, Exim normally flushes SMTP
29484 output before performing a callout in an ACL, to avoid unexpected timeouts in
29485 clients when the SMTP PIPELINING extension is in use. The flushing can be
29486 disabled by using a control modifier to set no_callout_flush.
29487
29488
29489 43.46 Additional parameters for callouts
29490 ----------------------------------------
29491
29492 The callout option can be followed by an equals sign and a number of optional
29493 parameters, separated by commas. For example:
29494
29495 verify = recipient/callout=10s,defer_ok
29496
29497 The old syntax, which had callout_defer_ok and check_postmaster as separate
29498 verify options, is retained for backwards compatibility, but is now deprecated.
29499 The additional parameters for callout are as follows:
29500
29501 <a time interval>
29502
29503 This specifies the timeout that applies for the callout attempt to each
29504 host. For example:
29505
29506 verify = sender/callout=5s
29507
29508 The default is 30 seconds. The timeout is used for each response from the
29509 remote host. It is also used for the initial connection, unless overridden
29510 by the connect parameter.
29511
29512 connect = <time interval>
29513
29514 This parameter makes it possible to set a different (usually smaller)
29515 timeout for making the SMTP connection. For example:
29516
29517 verify = sender/callout=5s,connect=1s
29518
29519 If not specified, this timeout defaults to the general timeout value.
29520
29521 defer_ok
29522
29523 When this parameter is present, failure to contact any host, or any other
29524 kind of temporary error, is treated as success by the ACL. However, the
29525 cache is not updated in this circumstance.
29526
29527 fullpostmaster
29528
29529 This operates like the postmaster option (see below), but if the check for
29530 postmaster@domain fails, it tries just postmaster, without a domain, in
29531 accordance with the specification in RFC 2821. The RFC states that the
29532 unqualified address postmaster should be accepted.
29533
29534 mailfrom = <email address>
29535
29536 When verifying addresses in header lines using the header_sender
29537 verification option, Exim behaves by default as if the addresses are
29538 envelope sender addresses from a message. Callout verification therefore
29539 tests to see whether a bounce message could be delivered, by using an empty
29540 address in the MAIL command. However, it is arguable that these addresses
29541 might never be used as envelope senders, and could therefore justifiably
29542 reject bounce messages (empty senders). The mailfrom callout parameter
29543 allows you to specify what address to use in the MAIL command. For example:
29544
29545 require verify = header_sender/callout=mailfrom=abcd@x.y.z
29546
29547 This parameter is available only for the header_sender verification option.
29548
29549 maxwait = <time interval>
29550
29551 This parameter sets an overall timeout for performing a callout
29552 verification. For example:
29553
29554 verify = sender/callout=5s,maxwait=30s
29555
29556 This timeout defaults to four times the callout timeout for individual SMTP
29557 commands. The overall timeout applies when there is more than one host that
29558 can be tried. The timeout is checked before trying the next host. This
29559 prevents very long delays if there are a large number of hosts and all are
29560 timing out (for example, when network connections are timing out).
29561
29562 no_cache
29563
29564 When this parameter is given, the callout cache is neither read nor
29565 updated.
29566
29567 postmaster
29568
29569 When this parameter is set, a successful callout check is followed by a
29570 similar check for the local part postmaster at the same domain. If this
29571 address is rejected, the callout fails (but see fullpostmaster above). The
29572 result of the postmaster check is recorded in a cache record; if it is a
29573 failure, this is used to fail subsequent callouts for the domain without a
29574 connection being made, until the cache record expires.
29575
29576 postmaster_mailfrom = <email address>
29577
29578 The postmaster check uses an empty sender in the MAIL command by default.
29579 You can use this parameter to do a postmaster check using a different
29580 address. For example:
29581
29582 require verify = sender/callout=postmaster_mailfrom=abc@x.y.z
29583
29584 If both postmaster and postmaster_mailfrom are present, the rightmost one
29585 overrides. The postmaster parameter is equivalent to this example:
29586
29587 require verify = sender/callout=postmaster_mailfrom=
29588
29589 Warning: The caching arrangements for postmaster checking do not take
29590 account of the sender address. It is assumed that either the empty address
29591 or a fixed non-empty address will be used. All that Exim remembers is that
29592 the postmaster check for the domain succeeded or failed.
29593
29594 random
29595
29596 When this parameter is set, before doing the normal callout check, Exim
29597 does a check for a "random" local part at the same domain. The local part
29598 is not really random - it is defined by the expansion of the option
29599 callout_random_local_part, which defaults to
29600
29601 $primary_hostname-$tod_epoch-testing
29602
29603 The idea here is to try to determine whether the remote host accepts all
29604 local parts without checking. If it does, there is no point in doing
29605 callouts for specific local parts. If the "random" check succeeds, the
29606 result is saved in a cache record, and used to force the current and
29607 subsequent callout checks to succeed without a connection being made, until
29608 the cache record expires.
29609
29610 use_postmaster
29611
29612 This parameter applies to recipient callouts only. For example:
29613
29614 deny !verify = recipient/callout=use_postmaster
29615
29616 It causes a non-empty postmaster address to be used in the MAIL command
29617 when performing the callout for the recipient, and also for a "random"
29618 check if that is configured. The local part of the address is "postmaster"
29619 and the domain is the contents of $qualify_domain.
29620
29621 use_sender
29622
29623 This option applies to recipient callouts only. For example:
29624
29625 require verify = recipient/callout=use_sender
29626
29627 It causes the message's actual sender address to be used in the MAIL
29628 command when performing the callout, instead of an empty address. There is
29629 no need to use this option unless you know that the called hosts make use
29630 of the sender when checking recipients. If used indiscriminately, it
29631 reduces the usefulness of callout caching.
29632
29633 hold
29634
29635 This option applies to recipient callouts only. For example:
29636
29637 require verify = recipient/callout=use_sender,hold
29638
29639 It causes the connection to be held open and used for any further
29640 recipients and for eventual delivery (should that be done quickly). Doing
29641 this saves on TCP and SMTP startup costs, and TLS costs also when that is
29642 used for the connections. The advantage is only gained if there are no
29643 callout cache hits (which could be enforced by the no_cache option), if the
29644 use_sender option is used, if neither the random nor the use_postmaster
29645 option is used, and if no other callouts intervene.
29646
29647 If you use any of the parameters that set a non-empty sender for the MAIL
29648 command (mailfrom, postmaster_mailfrom, use_postmaster, or use_sender), you
29649 should think about possible loops. Recipient checking is usually done between
29650 two hosts that are under the same management, and the host that receives the
29651 callouts is not normally configured to do callouts itself. Therefore, it is
29652 normally safe to use use_postmaster or use_sender in these circumstances.
29653
29654 However, if you use a non-empty sender address for a callout to an arbitrary
29655 host, there is the likelihood that the remote host will itself initiate a
29656 callout check back to your host. As it is checking what appears to be a message
29657 sender, it is likely to use an empty address in MAIL, thus avoiding a callout
29658 loop. However, to be on the safe side it would be best to set up your own ACLs
29659 so that they do not do sender verification checks when the recipient is the
29660 address you use for header sender or postmaster callout checking.
29661
29662 Another issue to think about when using non-empty senders for callouts is
29663 caching. When you set mailfrom or use_sender, the cache record is keyed by the
29664 sender/recipient combination; thus, for any given recipient, many more actual
29665 callouts are performed than when an empty sender or postmaster is used.
29666
29667
29668 43.47 Callout caching
29669 ---------------------
29670
29671 Exim caches the results of callouts in order to reduce the amount of resources
29672 used, unless you specify the no_cache parameter with the callout option. A
29673 hints database called "callout" is used for the cache. Two different record
29674 types are used: one records the result of a callout check for a specific
29675 address, and the other records information that applies to the entire domain
29676 (for example, that it accepts the local part postmaster).
29677
29678 When an original callout fails, a detailed SMTP error message is given about
29679 the failure. However, for subsequent failures use the cache data, this message
29680 is not available.
29681
29682 The expiry times for negative and positive address cache records are
29683 independent, and can be set by the global options callout_negative_expire
29684 (default 2h) and callout_positive_expire (default 24h), respectively.
29685
29686 If a host gives a negative response to an SMTP connection, or rejects any
29687 commands up to and including
29688
29689 MAIL FROM:<>
29690
29691 (but not including the MAIL command with a non-empty address), any callout
29692 attempt is bound to fail. Exim remembers such failures in a domain cache
29693 record, which it uses to fail callouts for the domain without making new
29694 connections, until the domain record times out. There are two separate expiry
29695 times for domain cache records: callout_domain_negative_expire (default 3h) and
29696 callout_domain_positive_expire (default 7d).
29697
29698 Domain records expire when the negative expiry time is reached if callouts
29699 cannot be made for the domain, or if the postmaster check failed. Otherwise,
29700 they expire when the positive expiry time is reached. This ensures that, for
29701 example, a host that stops accepting "random" local parts will eventually be
29702 noticed.
29703
29704 The callout caching mechanism is based on the domain of the address that is
29705 being tested. If the domain routes to several hosts, it is assumed that their
29706 behaviour will be the same.
29707
29708
29709 43.48 Sender address verification reporting
29710 -------------------------------------------
29711
29712 See section 43.44 for a general discussion of verification. When sender
29713 verification fails in an ACL, the details of the failure are given as
29714 additional output lines before the 550 response to the relevant SMTP command
29715 (RCPT or DATA). For example, if sender callout is in use, you might see:
29716
29717 MAIL FROM:<xyz@abc.example>
29718 250 OK
29719 RCPT TO:<pqr@def.example>
29720 550-Verification failed for <xyz@abc.example>
29721 550-Called: 192.168.34.43
29722 550-Sent: RCPT TO:<xyz@abc.example>
29723 550-Response: 550 Unknown local part xyz in <xyz@abc.example>
29724 550 Sender verification failed
29725
29726 If more than one RCPT command fails in the same way, the details are given only
29727 for the first of them. However, some administrators do not want to send out
29728 this much information. You can suppress the details by adding "/no_details" to
29729 the ACL statement that requests sender verification. For example:
29730
29731 verify = sender/no_details
29732
29733
29734 43.49 Redirection while verifying
29735 ---------------------------------
29736
29737 A dilemma arises when a local address is redirected by aliasing or forwarding
29738 during verification: should the generated addresses themselves be verified, or
29739 should the successful expansion of the original address be enough to verify it?
29740 By default, Exim takes the following pragmatic approach:
29741
29742 * When an incoming address is redirected to just one child address,
29743 verification continues with the child address, and if that fails to verify,
29744 the original verification also fails.
29745
29746 * When an incoming address is redirected to more than one child address,
29747 verification does not continue. A success result is returned.
29748
29749 This seems the most reasonable behaviour for the common use of aliasing as a
29750 way of redirecting different local parts to the same mailbox. It means, for
29751 example, that a pair of alias entries of the form
29752
29753 A.Wol: aw123
29754 aw123: :fail: Gone away, no forwarding address
29755
29756 work as expected, with both local parts causing verification failure. When a
29757 redirection generates more than one address, the behaviour is more like a
29758 mailing list, where the existence of the alias itself is sufficient for
29759 verification to succeed.
29760
29761 It is possible, however, to change the default behaviour so that all successful
29762 redirections count as successful verifications, however many new addresses are
29763 generated. This is specified by the success_on_redirect verification option.
29764 For example:
29765
29766 require verify = recipient/success_on_redirect/callout=10s
29767
29768 In this example, verification succeeds if a router generates a new address, and
29769 the callout does not occur, because no address was routed to a remote host.
29770
29771 When verification is being tested via the -bv option, the treatment of
29772 redirections is as just described, unless the -v or any debugging option is
29773 also specified. In that case, full verification is done for every generated
29774 address and a report is output for each of them.
29775
29776
29777 43.50 Client SMTP authorization (CSA)
29778 -------------------------------------
29779
29780 Client SMTP Authorization is a system that allows a site to advertise which
29781 machines are and are not permitted to send email. This is done by placing
29782 special SRV records in the DNS; these are looked up using the client's HELO
29783 domain. At the time of writing, CSA is still an Internet Draft. Client SMTP
29784 Authorization checks in Exim are performed by the ACL condition:
29785
29786 verify = csa
29787
29788 This fails if the client is not authorized. If there is a DNS problem, or if no
29789 valid CSA SRV record is found, or if the client is authorized, the condition
29790 succeeds. These three cases can be distinguished using the expansion variable
29791 $csa_status, which can take one of the values "fail", "defer", "unknown", or
29792 "ok". The condition does not itself defer because that would be likely to cause
29793 problems for legitimate email.
29794
29795 The error messages produced by the CSA code include slightly more detail. If
29796 $csa_status is "defer", this may be because of problems looking up the CSA SRV
29797 record, or problems looking up the CSA target address record. There are four
29798 reasons for $csa_status being "fail":
29799
29800 * The client's host name is explicitly not authorized.
29801
29802 * The client's IP address does not match any of the CSA target IP addresses.
29803
29804 * The client's host name is authorized but it has no valid target IP
29805 addresses (for example, the target's addresses are IPv6 and the client is
29806 using IPv4).
29807
29808 * The client's host name has no CSA SRV record but a parent domain has
29809 asserted that all subdomains must be explicitly authorized.
29810
29811 The csa verification condition can take an argument which is the domain to use
29812 for the DNS query. The default is:
29813
29814 verify = csa/$sender_helo_name
29815
29816 This implementation includes an extension to CSA. If the query domain is an
29817 address literal such as [192.0.2.95], or if it is a bare IP address, Exim
29818 searches for CSA SRV records in the reverse DNS as if the HELO domain was (for
29819 example) 95.2.0.192.in-addr.arpa. Therefore it is meaningful to say:
29820
29821 verify = csa/$sender_host_address
29822
29823 In fact, this is the check that Exim performs if the client does not say HELO.
29824 This extension can be turned off by setting the main configuration option
29825 dns_csa_use_reverse to be false.
29826
29827 If a CSA SRV record is not found for the domain itself, a search is performed
29828 through its parent domains for a record which might be making assertions about
29829 subdomains. The maximum depth of this search is limited using the main
29830 configuration option dns_csa_search_limit, which is 5 by default. Exim does not
29831 look for CSA SRV records in a top level domain, so the default settings handle
29832 HELO domains as long as seven (hostname.five.four.three.two.one.com). This
29833 encompasses the vast majority of legitimate HELO domains.
29834
29835 The dnsdb lookup also has support for CSA. Although dnsdb also supports direct
29836 SRV lookups, this is not sufficient because of the extra parent domain search
29837 behaviour of CSA, and (as with PTR lookups) dnsdb also turns IP addresses into
29838 lookups in the reverse DNS space. The result of a successful lookup such as:
29839
29840 ${lookup dnsdb {csa=$sender_helo_name}}
29841
29842 has two space-separated fields: an authorization code and a target host name.
29843 The authorization code can be "Y" for yes, "N" for no, "X" for explicit
29844 authorization required but absent, or "?" for unknown.
29845
29846
29847 43.51 Bounce address tag validation
29848 -----------------------------------
29849
29850 Bounce address tag validation (BATV) is a scheme whereby the envelope senders
29851 of outgoing messages have a cryptographic, timestamped "tag" added to them.
29852 Genuine incoming bounce messages should therefore always be addressed to
29853 recipients that have a valid tag. This scheme is a way of detecting unwanted
29854 bounce messages caused by sender address forgeries (often called "collateral
29855 spam"), because the recipients of such messages do not include valid tags.
29856
29857 There are two expansion items to help with the implementation of the BATV
29858 "prvs" (private signature) scheme in an Exim configuration. This scheme signs
29859 the original envelope sender address by using a simple key to add a hash of the
29860 address and some time-based randomizing information. The prvs expansion item
29861 creates a signed address, and the prvscheck expansion item checks one. The
29862 syntax of these expansion items is described in section 11.5. The validity
29863 period on signed addresses is seven days.
29864
29865 As an example, suppose the secret per-address keys are stored in an MySQL
29866 database. A query to look up the key for an address could be defined as a macro
29867 like this:
29868
29869 PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \
29870 WHERE sender='${quote_mysql:$prvscheck_address}'\
29871 }{$value}}
29872
29873 Suppose also that the senders who make use of BATV are defined by an address
29874 list called batv_senders. Then, in the ACL for RCPT commands, you could use
29875 this:
29876
29877 # Bounces: drop unsigned addresses for BATV senders
29878 deny message = This address does not send an unsigned reverse path
29879 senders = :
29880 recipients = +batv_senders
29881
29882 # Bounces: In case of prvs-signed address, check signature.
29883 deny message = Invalid reverse path signature.
29884 senders = :
29885 condition = ${prvscheck {$local_part@$domain}\
29886 {PRVSCHECK_SQL}{1}}
29887 !condition = $prvscheck_result
29888
29889 The first statement rejects recipients for bounce messages that are addressed
29890 to plain BATV sender addresses, because it is known that BATV senders do not
29891 send out messages with plain sender addresses. The second statement rejects
29892 recipients that are prvs-signed, but with invalid signatures (either because
29893 the key is wrong, or the signature has timed out).
29894
29895 A non-prvs-signed address is not rejected by the second statement, because the
29896 prvscheck expansion yields an empty string if its first argument is not a
29897 prvs-signed address, thus causing the condition condition to be false. If the
29898 first argument is a syntactically valid prvs-signed address, the yield is the
29899 third string (in this case "1"), whether or not the cryptographic and timeout
29900 checks succeed. The $prvscheck_result variable contains the result of the
29901 checks (empty for failure, "1" for success).
29902
29903 There is one more issue you must consider when implementing prvs-signing: you
29904 have to ensure that the routers accept prvs-signed addresses and deliver them
29905 correctly. The easiest way to handle this is to use a redirect router to remove
29906 the signature with a configuration along these lines:
29907
29908 batv_redirect:
29909 driver = redirect
29910 data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}}
29911
29912 This works because, if the third argument of prvscheck is empty, the result of
29913 the expansion of a prvs-signed address is the decoded value of the original
29914 address. This router should probably be the first of your routers that handles
29915 local addresses.
29916
29917 To create BATV-signed addresses in the first place, a transport of this form
29918 can be used:
29919
29920 external_smtp_batv:
29921 driver = smtp
29922 return_path = ${prvs {$return_path} \
29923 {${lookup mysql{SELECT \
29924 secret FROM batv_prvs WHERE \
29925 sender='${quote_mysql:$sender_address}'} \
29926 {$value}fail}}}
29927
29928 If no key can be found for the existing return path, no signing takes place.
29929
29930
29931 43.52 Using an ACL to control relaying
29932 --------------------------------------
29933
29934 An MTA is said to relay a message if it receives it from some host and delivers
29935 it directly to another host as a result of a remote address contained within
29936 it. Redirecting a local address via an alias or forward file and then passing
29937 the message on to another host is not relaying, but a redirection as a result
29938 of the "percent hack" is.
29939
29940 Two kinds of relaying exist, which are termed "incoming" and "outgoing". A host
29941 which is acting as a gateway or an MX backup is concerned with incoming
29942 relaying from arbitrary hosts to a specific set of domains. On the other hand,
29943 a host which is acting as a smart host for a number of clients is concerned
29944 with outgoing relaying from those clients to the Internet at large. Often the
29945 same host is fulfilling both functions, but in principle these two kinds of
29946 relaying are entirely independent. What is not wanted is the transmission of
29947 mail from arbitrary remote hosts through your system to arbitrary domains.
29948
29949 You can implement relay control by means of suitable statements in the ACL that
29950 runs for each RCPT command. For convenience, it is often easiest to use Exim's
29951 named list facility to define the domains and hosts involved. For example,
29952 suppose you want to do the following:
29953
29954 * Deliver a number of domains to mailboxes on the local host (or process them
29955 locally in some other way). Let's say these are my.dom1.example and
29956 my.dom2.example.
29957
29958 * Relay mail for a number of other domains for which you are the secondary
29959 MX. These might be friend1.example and friend2.example.
29960
29961 * Relay mail from the hosts on your local LAN, to whatever domains are
29962 involved. Suppose your LAN is 192.168.45.0/24.
29963
29964 In the main part of the configuration, you put the following definitions:
29965
29966 domainlist local_domains = my.dom1.example : my.dom2.example
29967 domainlist relay_to_domains = friend1.example : friend2.example
29968 hostlist relay_from_hosts = 192.168.45.0/24
29969
29970 Now you can use these definitions in the ACL that is run for every RCPT
29971 command:
29972
29973 acl_check_rcpt:
29974 accept domains = +local_domains : +relay_to_domains
29975 accept hosts = +relay_from_hosts
29976
29977 The first statement accepts any RCPT command that contains an address in the
29978 local or relay domains. For any other domain, control passes to the second
29979 statement, which accepts the command only if it comes from one of the relay
29980 hosts. In practice, you will probably want to make your ACL more sophisticated
29981 than this, for example, by including sender and recipient verification. The
29982 default configuration includes a more comprehensive example, which is described
29983 in chapter 7.
29984
29985
29986 43.53 Checking a relay configuration
29987 ------------------------------------
29988
29989 You can check the relay characteristics of your configuration in the same way
29990 that you can test any ACL behaviour for an incoming SMTP connection, by using
29991 the -bh option to run a fake SMTP session with which you interact.
29992
29993
29994
29995 ===============================================================================
29996 44. CONTENT SCANNING AT ACL TIME
29997
29998 The extension of Exim to include content scanning at ACL time, formerly known
29999 as "exiscan", was originally implemented as a patch by Tom Kistner. The code
30000 was integrated into the main source for Exim release 4.50, and Tom continues to
30001 maintain it. Most of the wording of this chapter is taken from Tom's
30002 specification.
30003
30004 It is also possible to scan the content of messages at other times. The
30005 local_scan() function (see chapter 45) allows for content scanning after all
30006 the ACLs have run. A transport filter can be used to scan messages at delivery
30007 time (see the transport_filter option, described in chapter 24).
30008
30009 If you want to include the ACL-time content-scanning features when you compile
30010 Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your Local/
30011 Makefile. When you do that, the Exim binary is built with:
30012
30013 * Two additional ACLs (acl_smtp_mime and acl_not_smtp_mime) that are run for
30014 all MIME parts for SMTP and non-SMTP messages, respectively.
30015
30016 * Additional ACL conditions and modifiers: decode, malware, mime_regex, regex
30017 , and spam. These can be used in the ACL that is run at the end of message
30018 reception (the acl_smtp_data ACL).
30019
30020 * An additional control feature ("no_mbox_unspool") that saves spooled copies
30021 of messages, or parts of messages, for debugging purposes.
30022
30023 * Additional expansion variables that are set in the new ACL and by the new
30024 conditions.
30025
30026 * Two new main configuration options: av_scanner and spamd_address.
30027
30028 Content-scanning is continually evolving, and new features are still being
30029 added. While such features are still unstable and liable to incompatible
30030 changes, they are made available in Exim by setting options whose names begin
30031 EXPERIMENTAL_ in Local/Makefile. Such features are not documented in this
30032 manual. You can find out about them by reading the file called doc/
30033 experimental.txt.
30034
30035 All the content-scanning facilities work on a MBOX copy of the message that is
30036 temporarily created in a file called:
30037
30038 <spool_directory>/scan/<message_id>/<message_id>.eml
30039
30040 The .eml extension is a friendly hint to virus scanners that they can expect an
30041 MBOX-like structure inside that file. The file is created when the first
30042 content scanning facility is called. Subsequent calls to content scanning
30043 conditions open the same file again. The directory is recursively removed when
30044 the acl_smtp_data ACL has finished running, unless
30045
30046 control = no_mbox_unspool
30047
30048 has been encountered. When the MIME ACL decodes files, they are put into the
30049 same directory by default.
30050
30051
30052 44.1 Scanning for viruses
30053 -------------------------
30054
30055 The malware ACL condition lets you connect virus scanner software to Exim. It
30056 supports a "generic" interface to scanners called via the shell, and
30057 specialized interfaces for "daemon" type virus scanners, which are resident in
30058 memory and thus are much faster.
30059
30060 A timeout of 2 minutes is applied to a scanner call (by default); if it expires
30061 then a defer action is taken.
30062
30063 You can set the av_scanner option in the main part of the configuration to
30064 specify which scanner to use, together with any additional options that are
30065 needed. The basic syntax is as follows:
30066
30067 av_scanner = <scanner-type>:<option1>:<option2>:[...]
30068
30069 If you do not set av_scanner, it defaults to
30070
30071 av_scanner = sophie:/var/run/sophie
30072
30073 If the value of av_scanner starts with a dollar character, it is expanded
30074 before use. The usual list-parsing of the content (see 6.20) applies. The
30075 following scanner types are supported in this release, though individual ones
30076 can be included or not at build time:
30077
30078 avast
30079
30080 This is the scanner daemon of Avast. It has been tested with Avast Core
30081 Security (currently at version 2.2.0). You can get a trial version at
30082 https://www.avast.com or for Linux at https://www.avast.com/
30083 linux-server-antivirus. This scanner type takes one option, which can be
30084 either a full path to a UNIX socket, or host and port specifiers separated
30085 by white space. The host may be a name or an IP address; the port is either
30086 a single number or a pair of numbers with a dash between. A list of options
30087 may follow. These options are interpreted on the Exim's side of the malware
30088 scanner, or are given on separate lines to the daemon as options before the
30089 main scan command.
30090
30091 If "pass_unscanned" is set, any files the Avast scanner can't scan (e.g.
30092 decompression bombs, or invalid archives) are considered clean. Use with
30093 care.
30094
30095 For example:
30096
30097 av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup
30098 av_scanner = avast:/var/run/avast/scan.sock:pass_unscanned:FLAGS -fullfiles:SENSITIVITY -pup
30099 av_scanner = avast:192.168.2.22 5036
30100
30101 If you omit the argument, the default path /var/run/avast/scan.sock is
30102 used. If you use a remote host, you need to make Exim's spool directory
30103 available to it, as the scanner is passed a file path, not file contents.
30104 For information about available commands and their options you may use
30105
30106 $ socat UNIX:/var/run/avast/scan.sock STDIO:
30107 FLAGS
30108 SENSITIVITY
30109 PACK
30110
30111 If the scanner returns a temporary failure (e.g. license issues, or
30112 permission problems), the message is deferred and a paniclog entry is
30113 written. The usual "defer_ok" option is available.
30114
30115 aveserver
30116
30117 This is the scanner daemon of Kaspersky Version 5. You can get a trial
30118 version at https://www.kaspersky.com/. This scanner type takes one option,
30119 which is the path to the daemon's UNIX socket. The default is shown in this
30120 example:
30121
30122 av_scanner = aveserver:/var/run/aveserver
30123
30124 clamd
30125
30126 This daemon-type scanner is GPL and free. You can get it at https://
30127 www.clamav.net/. Some older versions of clamd do not seem to unpack MIME
30128 containers, so it used to be recommended to unpack MIME attachments in the
30129 MIME ACL. This is no longer believed to be necessary.
30130
30131 The options are a list of server specifiers, which may be a UNIX socket
30132 specification, a TCP socket specification, or a (global) option.
30133
30134 A socket specification consists of a space-separated list. For a Unix
30135 socket the first element is a full path for the socket, for a TCP socket
30136 the first element is the IP address and the second a port number, Any
30137 further elements are per-server (non-global) options. These per-server
30138 options are supported:
30139
30140 retry=<timespec> Retry on connect fail
30141
30142 The "retry" option specifies a time after which a single retry for a failed
30143 connect is made. The default is to not retry.
30144
30145 If a Unix socket file is specified, only one server is supported.
30146
30147 Examples:
30148
30149 av_scanner = clamd:/opt/clamd/socket
30150 av_scanner = clamd:192.0.2.3 1234
30151 av_scanner = clamd:192.0.2.3 1234:local
30152 av_scanner = clamd:192.0.2.3 1234 retry=10s
30153 av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234
30154
30155 If the value of av_scanner points to a UNIX socket file or contains the
30156 "local" option, then the ClamAV interface will pass a filename containing
30157 the data to be scanned, which should normally result in less I/O happening
30158 and be more efficient. Normally in the TCP case, the data is streamed to
30159 ClamAV as Exim does not assume that there is a common filesystem with the
30160 remote host.
30161
30162 The final example shows that multiple TCP targets can be specified. Exim
30163 will randomly use one for each incoming email (i.e. it load balances them).
30164 Note that only TCP targets may be used if specifying a list of scanners; a
30165 UNIX socket cannot be mixed in with TCP targets. If one of the servers
30166 becomes unavailable, Exim will try the remaining one(s) until it finds one
30167 that works. When a clamd server becomes unreachable, Exim will log a
30168 message. Exim does not keep track of scanner state between multiple
30169 messages, and the scanner selection is random, so the message will get
30170 logged in the mainlog for each email that the down scanner gets chosen
30171 first (message wrapped to be readable):
30172
30173 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition:
30174 clamd: connection to localhost, port 3310 failed
30175 (Connection refused)
30176
30177 If the option is unset, the default is /tmp/clamd. Thanks to David Saez for
30178 contributing the code for this scanner.
30179
30180 cmdline
30181
30182 This is the keyword for the generic command line scanner interface. It can
30183 be used to attach virus scanners that are invoked from the shell. This
30184 scanner type takes 3 mandatory options:
30185
30186 1. The full path and name of the scanner binary, with all command line
30187 options, and a placeholder ("%s") for the directory to scan.
30188
30189 2. A regular expression to match against the STDOUT and STDERR output of
30190 the virus scanner. If the expression matches, a virus was found. You
30191 must make absolutely sure that this expression matches on "virus
30192 found". This is called the "trigger" expression.
30193
30194 3. Another regular expression, containing exactly one pair of parentheses,
30195 to match the name of the virus found in the scanners output. This is
30196 called the "name" expression.
30197
30198 For example, Sophos Sweep reports a virus on a line like this:
30199
30200 Virus 'W32/Magistr-B' found in file ./those.bat
30201
30202 For the trigger expression, we can match the phrase "found in file". For
30203 the name expression, we want to extract the W32/Magistr-B string, so we can
30204 match for the single quotes left and right of it. Altogether, this makes
30205 the configuration setting:
30206
30207 av_scanner = cmdline:\
30208 /path/to/sweep -ss -all -rec -archive %s:\
30209 found in file:'(.+)'
30210
30211 drweb
30212
30213 The DrWeb daemon scanner (https://www.sald.ru/) interface takes one option,
30214 either a full path to a UNIX socket, or host and port specifiers separated
30215 by white space. The host may be a name or an IP address; the port is either
30216 a single number or a pair of numbers with a dash between. For example:
30217
30218 av_scanner = drweb:/var/run/drwebd.sock
30219 av_scanner = drweb:192.168.2.20 31337
30220
30221 If you omit the argument, the default path /usr/local/drweb/run/drwebd.sock
30222 is used. Thanks to Alex Miller for contributing the code for this scanner.
30223
30224 f-protd
30225
30226 The f-protd scanner is accessed via HTTP over TCP. One argument is taken,
30227 being a space-separated hostname and port number (or port-range). For
30228 example:
30229
30230 av_scanner = f-protd:localhost 10200-10204
30231
30232 If you omit the argument, the default values shown above are used.
30233
30234 f-prot6d
30235
30236 The f-prot6d scanner is accessed using the FPSCAND protocol over TCP. One
30237 argument is taken, being a space-separated hostname and port number. For
30238 example:
30239
30240 av_scanner = f-prot6d:localhost 10200
30241
30242 If you omit the argument, the default values show above are used.
30243
30244 fsecure
30245
30246 The F-Secure daemon scanner (https://www.f-secure.com/) takes one argument
30247 which is the path to a UNIX socket. For example:
30248
30249 av_scanner = fsecure:/path/to/.fsav
30250
30251 If no argument is given, the default is /var/run/.fsav. Thanks to Johan
30252 Thelmen for contributing the code for this scanner.
30253
30254 kavdaemon
30255
30256 This is the scanner daemon of Kaspersky Version 4. This version of the
30257 Kaspersky scanner is outdated. Please upgrade (see aveserver above). This
30258 scanner type takes one option, which is the path to the daemon's UNIX
30259 socket. For example:
30260
30261 av_scanner = kavdaemon:/opt/AVP/AvpCtl
30262
30263 The default path is /var/run/AvpCtl.
30264
30265 mksd
30266
30267 This was a daemon type scanner that is aimed mainly at Polish users, though
30268 some documentation was available in English. The history can be shown at
30269 https://en.wikipedia.org/wiki/Mks_vir and this appears to be a candidate
30270 for removal from Exim, unless we are informed of other virus scanners which
30271 use the same protocol to integrate. The only option for this scanner type
30272 is the maximum number of processes used simultaneously to scan the
30273 attachments, provided that mksd has been run with at least the same number
30274 of child processes. For example:
30275
30276 av_scanner = mksd:2
30277
30278 You can safely omit this option (the default value is 1).
30279
30280 sock
30281
30282 This is a general-purpose way of talking to simple scanner daemons running
30283 on the local machine. There are four options: an address (which may be an
30284 IP address and port, or the path of a Unix socket), a commandline to send
30285 (may include a single %s which will be replaced with the path to the mail
30286 file to be scanned), an RE to trigger on from the returned data, and an RE
30287 to extract malware_name from the returned data. For example:
30288
30289 av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)$
30290
30291 Note that surrounding whitespace is stripped from each option, meaning
30292 there is no way to specify a trailing newline. The socket specifier and
30293 both regular-expressions are required. Default for the commandline is %s\n
30294 (note this does have a trailing newline); specify an empty element to get
30295 this.
30296
30297 sophie
30298
30299 Sophie is a daemon that uses Sophos' libsavi library to scan for viruses.
30300 You can get Sophie at http://sophie.sourceforge.net/. The only option for
30301 this scanner type is the path to the UNIX socket that Sophie uses for
30302 client communication. For example:
30303
30304 av_scanner = sophie:/tmp/sophie
30305
30306 The default path is /var/run/sophie, so if you are using this, you can omit
30307 the option.
30308
30309 When av_scanner is correctly set, you can use the malware condition in the DATA
30310 ACL. Note: You cannot use the malware condition in the MIME ACL.
30311
30312 The av_scanner option is expanded each time malware is called. This makes it
30313 possible to use different scanners. See further below for an example. The
30314 malware condition caches its results, so when you use it multiple times for the
30315 same message, the actual scanning process is only carried out once. However,
30316 using expandable items in av_scanner disables this caching, in which case each
30317 use of the malware condition causes a new scan of the message.
30318
30319 The malware condition takes a right-hand argument that is expanded before use
30320 and taken as a list, slash-separated by default. The first element can then be
30321 one of
30322
30323 * "true", "*", or "1", in which case the message is scanned for viruses. The
30324 condition succeeds if a virus was found, and fail otherwise. This is the
30325 recommended usage.
30326
30327 * "false" or "0" or an empty string, in which case no scanning is done and
30328 the condition fails immediately.
30329
30330 * A regular expression, in which case the message is scanned for viruses. The
30331 condition succeeds if a virus is found and its name matches the regular
30332 expression. This allows you to take special actions on certain types of
30333 virus. Note that "/" characters in the RE must be doubled due to the
30334 list-processing, unless the separator is changed (in the usual way 6.21).
30335
30336 You can append a "defer_ok" element to the malware argument list to accept
30337 messages even if there is a problem with the virus scanner. Otherwise, such a
30338 problem causes the ACL to defer.
30339
30340 You can append a "tmo=<val>" element to the malware argument list to specify a
30341 non-default timeout. The default is two minutes. For example:
30342
30343 malware = * / defer_ok / tmo=10s
30344
30345 A timeout causes the ACL to defer.
30346
30347 When a connection is made to the scanner the expansion variable
30348 $callout_address is set to record the actual address used.
30349
30350 When a virus is found, the condition sets up an expansion variable called
30351 $malware_name that contains the name of the virus. You can use it in a message
30352 modifier that specifies the error returned to the sender, and/or in logging
30353 data.
30354
30355 Beware the interaction of Exim's message_size_limit with any size limits
30356 imposed by your anti-virus scanner.
30357
30358 Here is a very simple scanning example:
30359
30360 deny message = This message contains malware ($malware_name)
30361 malware = *
30362
30363 The next example accepts messages when there is a problem with the scanner:
30364
30365 deny message = This message contains malware ($malware_name)
30366 malware = */defer_ok
30367
30368 The next example shows how to use an ACL variable to scan with both sophie and
30369 aveserver. It assumes you have set:
30370
30371 av_scanner = $acl_m0
30372
30373 in the main Exim configuration.
30374
30375 deny message = This message contains malware ($malware_name)
30376 set acl_m0 = sophie
30377 malware = *
30378
30379 deny message = This message contains malware ($malware_name)
30380 set acl_m0 = aveserver
30381 malware = *
30382
30383
30384 44.2 Scanning with SpamAssassin and Rspamd
30385 ------------------------------------------
30386
30387 The spam ACL condition calls SpamAssassin's spamd daemon to get a spam score
30388 and a report for the message. Support is also provided for Rspamd.
30389
30390 For more information about installation and configuration of SpamAssassin or
30391 Rspamd refer to their respective websites at https://spamassassin.apache.org/
30392 and https://www.rspamd.com/
30393
30394 SpamAssassin can be installed with CPAN by running:
30395
30396 perl -MCPAN -e 'install Mail::SpamAssassin'
30397
30398 SpamAssassin has its own set of configuration files. Please review its
30399 documentation to see how you can tweak it. The default installation should work
30400 nicely, however.
30401
30402 By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you intend
30403 to use an instance running on the local host you do not need to set
30404 spamd_address. If you intend to use another host or port for SpamAssassin, you
30405 must set the spamd_address option in the global part of the Exim configuration
30406 as follows (example):
30407
30408 spamd_address = 192.168.99.45 783
30409
30410 The SpamAssassin protocol relies on a TCP half-close from the client. If your
30411 SpamAssassin client side is running a Linux system with an iptables firewall,
30412 consider setting net.netfilter.nf_conntrack_tcp_timeout_close_wait to at least
30413 the timeout, Exim uses when waiting for a response from the SpamAssassin server
30414 (currently defaulting to 120s). With a lower value the Linux connection
30415 tracking may consider your half-closed connection as dead too soon.
30416
30417 To use Rspamd (which by default listens on all local addresses on TCP port
30418 11333) you should add variant=rspamd after the address/port pair, for example:
30419
30420 spamd_address = 127.0.0.1 11333 variant=rspamd
30421
30422 As of version 2.60, SpamAssassin also supports communication over UNIX sockets.
30423 If you want to us these, supply spamd_address with an absolute filename instead
30424 of an address/port pair:
30425
30426 spamd_address = /var/run/spamd_socket
30427
30428 You can have multiple spamd servers to improve scalability. These can reside on
30429 other hardware reachable over the network. To specify multiple spamd servers,
30430 put multiple address/port pairs in the spamd_address option, separated with
30431 colons (the separator can be changed in the usual way 6.21):
30432
30433 spamd_address = 192.168.2.10 783 : \
30434 192.168.2.11 783 : \
30435 192.168.2.12 783
30436
30437 Up to 32 spamd servers are supported. When a server fails to respond to the
30438 connection attempt, all other servers are tried until one succeeds. If no
30439 server responds, the spam condition defers.
30440
30441 Unix and TCP socket specifications may be mixed in any order. Each element of
30442 the list is a list itself, space-separated by default and changeable in the
30443 usual way (6.21); take care to not double the separator.
30444
30445 For TCP socket specifications a host name or IP (v4 or v6, but subject to
30446 list-separator quoting rules) address can be used, and the port can be one or a
30447 dash-separated pair. In the latter case, the range is tried in strict order.
30448
30449 Elements after the first for Unix sockets, or second for TCP socket, are
30450 options. The supported options are:
30451
30452 pri=<priority> Selection priority
30453 weight=<value> Selection bias
30454 time=<start>-<end> Use only between these times of day
30455 retry=<timespec> Retry on connect fail
30456 tmo=<timespec> Connection time limit
30457 variant=rspamd Use Rspamd rather than SpamAssassin protocol
30458
30459 The "pri" option specifies a priority for the server within the list, higher
30460 values being tried first. The default priority is 1.
30461
30462 The "weight" option specifies a selection bias. Within a priority set servers
30463 are queried in a random fashion, weighted by this value. The default value for
30464 selection bias is 1.
30465
30466 Time specifications for the "time" option are <hour>.<minute>.<second> in the
30467 local time zone; each element being one or more digits. Either the seconds or
30468 both minutes and seconds, plus the leading "." characters, may be omitted and
30469 will be taken as zero.
30470
30471 Timeout specifications for the "retry" and "tmo" options are the usual Exim
30472 time interval standard, e.g. "20s" or "1m".
30473
30474 The "tmo" option specifies an overall timeout for communication. The default
30475 value is two minutes.
30476
30477 The "retry" option specifies a time after which a single retry for a failed
30478 connect is made. The default is to not retry.
30479
30480 The spamd_address variable is expanded before use if it starts with a dollar
30481 sign. In this case, the expansion may return a string that is used as the list
30482 so that multiple spamd servers can be the result of an expansion.
30483
30484 When a connection is made to the server the expansion variable $callout_address
30485 is set to record the actual address used.
30486
30487
30488 44.3 Calling SpamAssassin from an Exim ACL
30489 ------------------------------------------
30490
30491 Here is a simple example of the use of the spam condition in a DATA ACL:
30492
30493 deny message = This message was classified as SPAM
30494 spam = joe
30495
30496 The right-hand side of the spam condition specifies a name. This is relevant if
30497 you have set up multiple SpamAssassin profiles. If you do not want to scan
30498 using a specific profile, but rather use the SpamAssassin system-wide default
30499 profile, you can scan for an unknown name, or simply use "nobody". Rspamd does
30500 not use this setting. However, you must put something on the right-hand side.
30501
30502 The name allows you to use per-domain or per-user antispam profiles in
30503 principle, but this is not straightforward in practice, because a message may
30504 have multiple recipients, not necessarily all in the same domain. Because the
30505 spam condition has to be called from a DATA-time ACL in order to be able to
30506 read the contents of the message, the variables $local_part and $domain are not
30507 set. Careful enforcement of single-recipient messages (e.g. by responding with
30508 defer in the recipient ACL for all recipients after the first), or the use of
30509 PRDR, are needed to use this feature.
30510
30511 The right-hand side of the spam condition is expanded before being used, so you
30512 can put lookups or conditions there. When the right-hand side evaluates to "0"
30513 or "false", no scanning is done and the condition fails immediately.
30514
30515 Scanning with SpamAssassin uses a lot of resources. If you scan every message,
30516 large ones may cause significant performance degradation. As most spam messages
30517 are quite small, it is recommended that you do not scan the big ones. For
30518 example:
30519
30520 deny message = This message was classified as SPAM
30521 condition = ${if < {$message_size}{10K}}
30522 spam = nobody
30523
30524 The spam condition returns true if the threshold specified in the user's
30525 SpamAssassin profile has been matched or exceeded. If you want to use the spam
30526 condition for its side effects (see the variables below), you can make it
30527 always return "true" by appending ":true" to the username.
30528
30529 When the spam condition is run, it sets up a number of expansion variables.
30530 Except for $spam_report, these variables are saved with the received message so
30531 are available for use at delivery time.
30532
30533 $spam_score
30534
30535 The spam score of the message, for example, "3.4" or "30.5". This is useful
30536 for inclusion in log or reject messages.
30537
30538 $spam_score_int
30539
30540 The spam score of the message, multiplied by ten, as an integer value. For
30541 example "34" or "305". It may appear to disagree with $spam_score because
30542 $spam_score is rounded and $spam_score_int is truncated. The integer value
30543 is useful for numeric comparisons in conditions.
30544
30545 $spam_bar
30546
30547 A string consisting of a number of "+" or "-" characters, representing the
30548 integer part of the spam score value. A spam score of 4.4 would have a
30549 $spam_bar value of "++++". This is useful for inclusion in warning headers,
30550 since MUAs can match on such strings. The maximum length of the spam bar is
30551 50 characters.
30552
30553 $spam_report
30554
30555 A multiline text table, containing the full SpamAssassin report for the
30556 message. Useful for inclusion in headers or reject messages. This variable
30557 is only usable in a DATA-time ACL. Beware that SpamAssassin may return
30558 non-ASCII characters, especially when running in country-specific locales,
30559 which are not legal unencoded in headers.
30560
30561 $spam_action
30562
30563 For SpamAssassin either 'reject' or 'no action' depending on the spam score
30564 versus threshold. For Rspamd, the recommended action.
30565
30566 The spam condition caches its results unless expansion in spamd_address was
30567 used. If you call it again with the same user name, it does not scan again, but
30568 rather returns the same values as before.
30569
30570 The spam condition returns DEFER if there is any error while running the
30571 message through SpamAssassin or if the expansion of spamd_address failed. If
30572 you want to treat DEFER as FAIL (to pass on to the next ACL statement block),
30573 append "/defer_ok" to the right-hand side of the spam condition, like this:
30574
30575 deny message = This message was classified as SPAM
30576 spam = joe/defer_ok
30577
30578 This causes messages to be accepted even if there is a problem with spamd.
30579
30580 Here is a longer, commented example of the use of the spam condition:
30581
30582 # put headers in all messages (no matter if spam or not)
30583 warn spam = nobody:true
30584 add_header = X-Spam-Score: $spam_score ($spam_bar)
30585 add_header = X-Spam-Report: $spam_report
30586
30587 # add second subject line with *SPAM* marker when message
30588 # is over threshold
30589 warn spam = nobody
30590 add_header = Subject: *SPAM* $h_Subject:
30591
30592 # reject spam at high scores (> 12)
30593 deny message = This message scored $spam_score spam points.
30594 spam = nobody:true
30595 condition = ${if >{$spam_score_int}{120}{1}{0}}
30596
30597
30598 44.4 Scanning MIME parts
30599 ------------------------
30600
30601 The acl_smtp_mime global option specifies an ACL that is called once for each
30602 MIME part of an SMTP message, including multipart types, in the sequence of
30603 their position in the message. Similarly, the acl_not_smtp_mime option
30604 specifies an ACL that is used for the MIME parts of non-SMTP messages. These
30605 options may both refer to the same ACL if you want the same processing in both
30606 cases.
30607
30608 These ACLs are called (possibly many times) just before the acl_smtp_data ACL
30609 in the case of an SMTP message, or just before the acl_not_smtp ACL in the case
30610 of a non-SMTP message. However, a MIME ACL is called only if the message
30611 contains a Content-Type: header line. When a call to a MIME ACL does not yield
30612 "accept", ACL processing is aborted and the appropriate result code is sent to
30613 the client. In the case of an SMTP message, the acl_smtp_data ACL is not called
30614 when this happens.
30615
30616 You cannot use the malware or spam conditions in a MIME ACL; these can only be
30617 used in the DATA or non-SMTP ACLs. However, you can use the regex condition to
30618 match against the raw MIME part. You can also use the mime_regex condition to
30619 match against the decoded MIME part (see section 44.5).
30620
30621 At the start of a MIME ACL, a number of variables are set from the header
30622 information for the relevant MIME part. These are described below. The contents
30623 of the MIME part are not by default decoded into a disk file except for MIME
30624 parts whose content-type is "message/rfc822". If you want to decode a MIME part
30625 into a disk file, you can use the decode condition. The general syntax is:
30626
30627 decode = [/<path>/]<filename>
30628
30629 The right hand side is expanded before use. After expansion, the value can be:
30630
30631 1. "0" or "false", in which case no decoding is done.
30632
30633 2. The string "default". In that case, the file is put in the temporary
30634 "default" directory <spool_directory>/scan/<message_id>/ with a sequential
30635 filename consisting of the message id and a sequence number. The full path
30636 and name is available in $mime_decoded_filename after decoding.
30637
30638 3. A full path name starting with a slash. If the full name is an existing
30639 directory, it is used as a replacement for the default directory. The
30640 filename is then sequentially assigned. If the path does not exist, it is
30641 used as the full path and filename.
30642
30643 4. If the string does not start with a slash, it is used as the filename, and
30644 the default path is then used.
30645
30646 The decode condition normally succeeds. It is only false for syntax errors or
30647 unusual circumstances such as memory shortages. You can easily decode a file
30648 with its original, proposed filename using
30649
30650 decode = $mime_filename
30651
30652 However, you should keep in mind that $mime_filename might contain anything. If
30653 you place files outside of the default path, they are not automatically
30654 unlinked.
30655
30656 For RFC822 attachments (these are messages attached to messages, with a
30657 content-type of "message/rfc822"), the ACL is called again in the same manner
30658 as for the primary message, only that the $mime_is_rfc822 expansion variable is
30659 set (see below). Attached messages are always decoded to disk before being
30660 checked, and the files are unlinked once the check is done.
30661
30662 The MIME ACL supports the regex and mime_regex conditions. These can be used to
30663 match regular expressions against raw and decoded MIME parts, respectively.
30664 They are described in section 44.5.
30665
30666 The following list describes all expansion variables that are available in the
30667 MIME ACL:
30668
30669 $mime_boundary
30670
30671 If the current part is a multipart (see $mime_is_multipart) below, it
30672 should have a boundary string, which is stored in this variable. If the
30673 current part has no boundary parameter in the Content-Type: header, this
30674 variable contains the empty string.
30675
30676 $mime_charset
30677
30678 This variable contains the character set identifier, if one was found in
30679 the Content-Type: header. Examples for charset identifiers are:
30680
30681 us-ascii
30682 gb2312 (Chinese)
30683 iso-8859-1
30684
30685 Please note that this value is not normalized, so you should do matches
30686 case-insensitively.
30687
30688 $mime_content_description
30689
30690 This variable contains the normalized content of the Content-Description:
30691 header. It can contain a human-readable description of the parts content.
30692 Some implementations repeat the filename for attachments here, but they are
30693 usually only used for display purposes.
30694
30695 $mime_content_disposition
30696
30697 This variable contains the normalized content of the Content-Disposition:
30698 header. You can expect strings like "attachment" or "inline" here.
30699
30700 $mime_content_id
30701
30702 This variable contains the normalized content of the Content-ID: header.
30703 This is a unique ID that can be used to reference a part from another part.
30704
30705 $mime_content_size
30706
30707 This variable is set only after the decode modifier (see above) has been
30708 successfully run. It contains the size of the decoded part in kilobytes.
30709 The size is always rounded up to full kilobytes, so only a completely empty
30710 part has a $mime_content_size of zero.
30711
30712 $mime_content_transfer_encoding
30713
30714 This variable contains the normalized content of the
30715 Content-transfer-encoding: header. This is a symbolic name for an encoding
30716 type. Typical values are "base64" and "quoted-printable".
30717
30718 $mime_content_type
30719
30720 If the MIME part has a Content-Type: header, this variable contains its
30721 value, lowercased, and without any options (like "name" or "charset"). Here
30722 are some examples of popular MIME types, as they may appear in this
30723 variable:
30724
30725 text/plain
30726 text/html
30727 application/octet-stream
30728 image/jpeg
30729 audio/midi
30730
30731 If the MIME part has no Content-Type: header, this variable contains the
30732 empty string.
30733
30734 $mime_decoded_filename
30735
30736 This variable is set only after the decode modifier (see above) has been
30737 successfully run. It contains the full path and filename of the file
30738 containing the decoded data.
30739
30740 $mime_filename
30741
30742 This is perhaps the most important of the MIME variables. It contains a
30743 proposed filename for an attachment, if one was found in either the
30744 Content-Type: or Content-Disposition: headers. The filename will be RFC2047
30745 or RFC2231 decoded, but no additional sanity checks are done. If no
30746 filename was found, this variable contains the empty string.
30747
30748 $mime_is_coverletter
30749
30750 This variable attempts to differentiate the "cover letter" of an e-mail
30751 from attached data. It can be used to clamp down on flashy or unnecessarily
30752 encoded content in the cover letter, while not restricting attachments at
30753 all.
30754
30755 The variable contains 1 (true) for a MIME part believed to be part of the
30756 cover letter, and 0 (false) for an attachment. At present, the algorithm is
30757 as follows:
30758
30759 1. The outermost MIME part of a message is always a cover letter.
30760
30761 2. If a multipart/alternative or multipart/related MIME part is a cover
30762 letter, so are all MIME subparts within that multipart.
30763
30764 3. If any other multipart is a cover letter, the first subpart is a cover
30765 letter, and the rest are attachments.
30766
30767 4. All parts contained within an attachment multipart are attachments.
30768
30769 As an example, the following will ban "HTML mail" (including that sent with
30770 alternative plain text), while allowing HTML files to be attached. HTML
30771 coverletter mail attached to non-HTML coverletter mail will also be
30772 allowed:
30773
30774 deny message = HTML mail is not accepted here
30775 !condition = $mime_is_rfc822
30776 condition = $mime_is_coverletter
30777 condition = ${if eq{$mime_content_type}{text/html}{1}{0}}
30778
30779 $mime_is_multipart
30780
30781 This variable has the value 1 (true) when the current part has the main
30782 type "multipart", for example, "multipart/alternative" or "multipart/
30783 mixed". Since multipart entities only serve as containers for other parts,
30784 you may not want to carry out specific actions on them.
30785
30786 $mime_is_rfc822
30787
30788 This variable has the value 1 (true) if the current part is not a part of
30789 the checked message itself, but part of an attached message. Attached
30790 message decoding is fully recursive.
30791
30792 $mime_part_count
30793
30794 This variable is a counter that is raised for each processed MIME part. It
30795 starts at zero for the very first part (which is usually a multipart). The
30796 counter is per-message, so it is reset when processing RFC822 attachments
30797 (see $mime_is_rfc822). The counter stays set after acl_smtp_mime is
30798 complete, so you can use it in the DATA ACL to determine the number of MIME
30799 parts of a message. For non-MIME messages, this variable contains the value
30800 -1.
30801
30802
30803 44.5 Scanning with regular expressions
30804 --------------------------------------
30805
30806 You can specify your own custom regular expression matches on the full body of
30807 the message, or on individual MIME parts.
30808
30809 The regex condition takes one or more regular expressions as arguments and
30810 matches them against the full message (when called in the DATA ACL) or a raw
30811 MIME part (when called in the MIME ACL). The regex condition matches linewise,
30812 with a maximum line length of 32K characters. That means you cannot have
30813 multiline matches with the regex condition.
30814
30815 The mime_regex condition can be called only in the MIME ACL. It matches up to
30816 32K of decoded content (the whole content at once, not linewise). If the part
30817 has not been decoded with the decode modifier earlier in the ACL, it is decoded
30818 automatically when mime_regex is executed (using default path and filename
30819 values). If the decoded data is larger than 32K, only the first 32K characters
30820 are checked.
30821
30822 The regular expressions are passed as a colon-separated list. To include a
30823 literal colon, you must double it. Since the whole right-hand side string is
30824 expanded before being used, you must also escape dollar signs and backslashes
30825 with more backslashes, or use the "\N" facility to disable expansion. Here is a
30826 simple example that contains two regular expressions:
30827
30828 deny message = contains blacklisted regex ($regex_match_string)
30829 regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL
30830
30831 The conditions returns true if any one of the regular expressions matches. The
30832 $regex_match_string expansion variable is then set up and contains the matching
30833 regular expression. The expansion variables $regex1 $regex2 etc are set to any
30834 substrings captured by the regular expression.
30835
30836 Warning: With large messages, these conditions can be fairly CPU-intensive.
30837
30838
30839
30840 ===============================================================================
30841 45. ADDING A LOCAL SCAN FUNCTION TO EXIM
30842
30843 In these days of email worms, viruses, and ever-increasing spam, some sites
30844 want to apply a lot of checking to messages before accepting them.
30845
30846 The content scanning extension (chapter 44) has facilities for passing messages
30847 to external virus and spam scanning software. You can also do a certain amount
30848 in Exim itself through string expansions and the condition condition in the ACL
30849 that runs after the SMTP DATA command or the ACL for non-SMTP messages (see
30850 chapter 43), but this has its limitations.
30851
30852 To allow for further customization to a site's own requirements, there is the
30853 possibility of linking Exim with a private message scanning function, written
30854 in C. If you want to run code that is written in something other than C, you
30855 can of course use a little C stub to call it.
30856
30857 The local scan function is run once for every incoming message, at the point
30858 when Exim is just about to accept the message. It can therefore be used to
30859 control non-SMTP messages from local processes as well as messages arriving via
30860 SMTP.
30861
30862 Exim applies a timeout to calls of the local scan function, and there is an
30863 option called local_scan_timeout for setting it. The default is 5 minutes. Zero
30864 means "no timeout". Exim also sets up signal handlers for SIGSEGV, SIGILL,
30865 SIGFPE, and SIGBUS before calling the local scan function, so that the most
30866 common types of crash are caught. If the timeout is exceeded or one of those
30867 signals is caught, the incoming message is rejected with a temporary error if
30868 it is an SMTP message. For a non-SMTP message, the message is dropped and Exim
30869 ends with a non-zero code. The incident is logged on the main and reject logs.
30870
30871
30872 45.1 Building Exim to use a local scan function
30873 -----------------------------------------------
30874
30875 To make use of the local scan function feature, you must tell Exim where your
30876 function is before building Exim, by setting
30877
30878 both HAVE_LOCAL_SCAN and
30879
30880 LOCAL_SCAN_SOURCE in your Local/Makefile. A recommended place to put it is in
30881 the Local directory, so you might set
30882
30883 HAVE_LOCAL_SCAN=yes
30884 LOCAL_SCAN_SOURCE=Local/local_scan.c
30885
30886 for example. The function must be called local_scan(). It is called by Exim
30887 after it has received a message, when the success return code is about to be
30888 sent. This is after all the ACLs have been run. The return code from your
30889 function controls whether the message is actually accepted or not. There is a
30890 commented template function (that just accepts the message) in the file _src/
30891 local_scan.c_.
30892
30893 If you want to make use of Exim's runtime configuration file to set options for
30894 your local_scan() function, you must also set
30895
30896 LOCAL_SCAN_HAS_OPTIONS=yes
30897
30898 in Local/Makefile (see section 45.3 below).
30899
30900
30901 45.2 API for local_scan()
30902 -------------------------
30903
30904 You must include this line near the start of your code:
30905
30906 #include "local_scan.h"
30907
30908 This header file defines a number of variables and other values, and the
30909 prototype for the function itself. Exim is coded to use unsigned char values
30910 almost exclusively, and one of the things this header defines is a shorthand
30911 for "unsigned char" called "uschar". It also contains the following macro
30912 definitions, to simplify casting character strings and pointers to character
30913 strings:
30914
30915 #define CS (char *)
30916 #define CCS (const char *)
30917 #define CSS (char **)
30918 #define US (unsigned char *)
30919 #define CUS (const unsigned char *)
30920 #define USS (unsigned char **)
30921
30922 The function prototype for local_scan() is:
30923
30924 extern int local_scan(int fd, uschar **return_text);
30925
30926 The arguments are as follows:
30927
30928 * fd is a file descriptor for the file that contains the body of the message
30929 (the -D file). The file is open for reading and writing, but updating it is
30930 not recommended. Warning: You must not close this file descriptor.
30931
30932 The descriptor is positioned at character 19 of the file, which is the
30933 first character of the body itself, because the first 19 characters are the
30934 message id followed by "-D" and a newline. If you rewind the file, you
30935 should use the macro SPOOL_DATA_START_OFFSET to reset to the start of the
30936 data, just in case this changes in some future version.
30937
30938 * return_text is an address which you can use to return a pointer to a text
30939 string at the end of the function. The value it points to on entry is NULL.
30940
30941 The function must return an int value which is one of the following macros:
30942
30943 "LOCAL_SCAN_ACCEPT"
30944
30945 The message is accepted. If you pass back a string of text, it is saved
30946 with the message, and made available in the variable $local_scan_data. No
30947 newlines are permitted (if there are any, they are turned into spaces) and
30948 the maximum length of text is 1000 characters.
30949
30950 "LOCAL_SCAN_ACCEPT_FREEZE"
30951
30952 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
30953 queued without immediate delivery, and is frozen.
30954
30955 "LOCAL_SCAN_ACCEPT_QUEUE"
30956
30957 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
30958 queued without immediate delivery.
30959
30960 "LOCAL_SCAN_REJECT"
30961
30962 The message is rejected; the returned text is used as an error message
30963 which is passed back to the sender and which is also logged. Newlines are
30964 permitted - they cause a multiline response for SMTP rejections, but are
30965 converted to "\n" in log lines. If no message is given, "Administrative
30966 prohibition" is used.
30967
30968 "LOCAL_SCAN_TEMPREJECT"
30969
30970 The message is temporarily rejected; the returned text is used as an error
30971 message as for LOCAL_SCAN_REJECT. If no message is given, "Temporary local
30972 problem" is used.
30973
30974 "LOCAL_SCAN_REJECT_NOLOGHDR"
30975
30976 This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected
30977 message is not written to the reject log. It has the effect of unsetting
30978 the rejected_header log selector for just this rejection. If
30979 rejected_header is already unset (see the discussion of the log_selection
30980 option in section 52.15), this code is the same as LOCAL_SCAN_REJECT.
30981
30982 "LOCAL_SCAN_TEMPREJECT_NOLOGHDR"
30983
30984 This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that
30985 LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT.
30986
30987 If the message is not being received by interactive SMTP, rejections are
30988 reported by writing to stderr or by sending an email, as configured by the -oe
30989 command line options.
30990
30991
30992 45.3 Configuration options for local_scan()
30993 -------------------------------------------
30994
30995 It is possible to have option settings in the main configuration file that set
30996 values in static variables in the local_scan() module. If you want to do this,
30997 you must have the line
30998
30999 LOCAL_SCAN_HAS_OPTIONS=yes
31000
31001 in your Local/Makefile when you build Exim. (This line is in OS/
31002 Makefile-Default, commented out). Then, in the local_scan() source file, you
31003 must define static variables to hold the option values, and a table to define
31004 them.
31005
31006 The table must be a vector called local_scan_options, of type "optionlist".
31007 Each entry is a triplet, consisting of a name, an option type, and a pointer to
31008 the variable that holds the value. The entries must appear in alphabetical
31009 order. Following local_scan_options you must also define a variable called
31010 local_scan_options_count that contains the number of entries in the table. Here
31011 is a short example, showing two kinds of option:
31012
31013 static int my_integer_option = 42;
31014 static uschar *my_string_option = US"a default string";
31015
31016 optionlist local_scan_options[] = {
31017 { "my_integer", opt_int, &my_integer_option },
31018 { "my_string", opt_stringptr, &my_string_option }
31019 };
31020
31021 int local_scan_options_count =
31022 sizeof(local_scan_options)/sizeof(optionlist);
31023
31024 The values of the variables can now be changed from Exim's runtime
31025 configuration file by including a local scan section as in this example:
31026
31027 begin local_scan
31028 my_integer = 99
31029 my_string = some string of text...
31030
31031 The available types of option data are as follows:
31032
31033 opt_bool
31034
31035 This specifies a boolean (true/false) option. The address should point to a
31036 variable of type "BOOL", which will be set to TRUE or FALSE, which are
31037 macros that are defined as "1" and "0", respectively. If you want to detect
31038 whether such a variable has been set at all, you can initialize it to
31039 TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than
31040 two values.)
31041
31042 opt_fixed
31043
31044 This specifies a fixed point number, such as is used for load averages. The
31045 address should point to a variable of type "int". The value is stored
31046 multiplied by 1000, so, for example, 1.4142 is truncated and stored as
31047 1414.
31048
31049 opt_int
31050
31051 This specifies an integer; the address should point to a variable of type
31052 "int". The value may be specified in any of the integer formats accepted by
31053 Exim.
31054
31055 opt_mkint
31056
31057 This is the same as opt_int, except that when such a value is output in a
31058 -bP listing, if it is an exact number of kilobytes or megabytes, it is
31059 printed with the suffix K or M.
31060
31061 opt_octint
31062
31063 This also specifies an integer, but the value is always interpreted as an
31064 octal integer, whether or not it starts with the digit zero, and it is
31065 always output in octal.
31066
31067 opt_stringptr
31068
31069 This specifies a string value; the address must be a pointer to a variable
31070 that points to a string (for example, of type "uschar *").
31071
31072 opt_time
31073
31074 This specifies a time interval value. The address must point to a variable
31075 of type "int". The value that is placed there is a number of seconds.
31076
31077 If the -bP command line option is followed by "local_scan", Exim prints out the
31078 values of all the local_scan() options.
31079
31080
31081 45.4 Available Exim variables
31082 -----------------------------
31083
31084 The header local_scan.h gives you access to a number of C variables. These are
31085 the only ones that are guaranteed to be maintained from release to release.
31086 Note, however, that you can obtain the value of any Exim expansion variable,
31087 including $recipients, by calling expand_string(). The exported C variables are
31088 as follows:
31089
31090 int body_linecount
31091
31092 This variable contains the number of lines in the message's body. It is not
31093 valid if the spool_files_wireformat option is used.
31094
31095 int body_zerocount
31096
31097 This variable contains the number of binary zero bytes in the message's
31098 body. It is not valid if the spool_files_wireformat option is used.
31099
31100 unsigned int debug_selector
31101
31102 This variable is set to zero when no debugging is taking place. Otherwise,
31103 it is a bitmap of debugging selectors. Two bits are identified for use in
31104 local_scan(); they are defined as macros:
31105
31106 + The "D_v" bit is set when -v was present on the command line. This is a
31107 testing option that is not privileged - any caller may set it. All the
31108 other selector bits can be set only by admin users.
31109
31110 + The "D_local_scan" bit is provided for use by local_scan(); it is set
31111 by the "+local_scan" debug selector. It is not included in the default
31112 set of debugging bits.
31113
31114 Thus, to write to the debugging output only when "+local_scan" has been
31115 selected, you should use code like this:
31116
31117 if ((debug_selector & D_local_scan) != 0)
31118 debug_printf("xxx", ...);
31119
31120 uschar *expand_string_message
31121
31122 After a failing call to expand_string() (returned value NULL), the variable
31123 expand_string_message contains the error message, zero-terminated.
31124
31125 header_line *header_list
31126
31127 A pointer to a chain of header lines. The header_line structure is
31128 discussed below.
31129
31130 header_line *header_last
31131
31132 A pointer to the last of the header lines.
31133
31134 uschar *headers_charset
31135
31136 The value of the headers_charset configuration option.
31137
31138 BOOL host_checking
31139
31140 This variable is TRUE during a host checking session that is initiated by
31141 the -bh command line option.
31142
31143 uschar *interface_address
31144
31145 The IP address of the interface that received the message, as a string.
31146 This is NULL for locally submitted messages.
31147
31148 int interface_port
31149
31150 The port on which this message was received. When testing with the -bh
31151 command line option, the value of this variable is -1 unless a port has
31152 been specified via the -oMi option.
31153
31154 uschar *message_id
31155
31156 This variable contains Exim's message id for the incoming message (the
31157 value of $message_exim_id) as a zero-terminated string.
31158
31159 uschar *received_protocol
31160
31161 The name of the protocol by which the message was received.
31162
31163 int recipients_count
31164
31165 The number of accepted recipients.
31166
31167 recipient_item *recipients_list
31168
31169 The list of accepted recipients, held in a vector of length
31170 recipients_count. The recipient_item structure is discussed below. You can
31171 add additional recipients by calling receive_add_recipient() (see below).
31172 You can delete recipients by removing them from the vector and adjusting
31173 the value in recipients_count. In particular, by setting recipients_count
31174 to zero you remove all recipients. If you then return the value
31175 "LOCAL_SCAN_ACCEPT", the message is accepted, but immediately blackholed.
31176 To replace the recipients, you can set recipients_count to zero and then
31177 call receive_add_recipient() as often as needed.
31178
31179 uschar *sender_address
31180
31181 The envelope sender address. For bounce messages this is the empty string.
31182
31183 uschar *sender_host_address
31184
31185 The IP address of the sending host, as a string. This is NULL for
31186 locally-submitted messages.
31187
31188 uschar *sender_host_authenticated
31189
31190 The name of the authentication mechanism that was used, or NULL if the
31191 message was not received over an authenticated SMTP connection.
31192
31193 uschar *sender_host_name
31194
31195 The name of the sending host, if known.
31196
31197 int sender_host_port
31198
31199 The port on the sending host.
31200
31201 BOOL smtp_input
31202
31203 This variable is TRUE for all SMTP input, including BSMTP.
31204
31205 BOOL smtp_batched_input
31206
31207 This variable is TRUE for BSMTP input.
31208
31209 int store_pool
31210
31211 The contents of this variable control which pool of memory is used for new
31212 requests. See section 45.8 for details.
31213
31214
31215 45.5 Structure of header lines
31216 ------------------------------
31217
31218 The header_line structure contains the members listed below. You can add
31219 additional header lines by calling the header_add() function (see below). You
31220 can cause header lines to be ignored (deleted) by setting their type to *.
31221
31222 struct header_line *next
31223
31224 A pointer to the next header line, or NULL for the last line.
31225
31226 int type
31227
31228 A code identifying certain headers that Exim recognizes. The codes are
31229 printing characters, and are documented in chapter 56 of this manual.
31230 Notice in particular that any header line whose type is * is not
31231 transmitted with the message. This flagging is used for header lines that
31232 have been rewritten, or are to be removed (for example, Envelope-sender:
31233 header lines.) Effectively, * means "deleted".
31234
31235 int slen
31236
31237 The number of characters in the header line, including the terminating and
31238 any internal newlines.
31239
31240 uschar *text
31241
31242 A pointer to the text of the header. It always ends with a newline,
31243 followed by a zero byte. Internal newlines are preserved.
31244
31245
31246 45.6 Structure of recipient items
31247 ---------------------------------
31248
31249 The recipient_item structure contains these members:
31250
31251 uschar *address
31252
31253 This is a pointer to the recipient address as it was received.
31254
31255 int pno
31256
31257 This is used in later Exim processing when top level addresses are created
31258 by the one_time option. It is not relevant at the time local_scan() is run
31259 and must always contain -1 at this stage.
31260
31261 uschar *errors_to
31262
31263 If this value is not NULL, bounce messages caused by failing to deliver to
31264 the recipient are sent to the address it contains. In other words, it
31265 overrides the envelope sender for this one recipient. (Compare the
31266 errors_to generic router option.) If a local_scan() function sets an
31267 errors_to field to an unqualified address, Exim qualifies it using the
31268 domain from qualify_recipient. When local_scan() is called, the errors_to
31269 field is NULL for all recipients.
31270
31271
31272 45.7 Available Exim functions
31273 -----------------------------
31274
31275 The header local_scan.h gives you access to a number of Exim functions. These
31276 are the only ones that are guaranteed to be maintained from release to release:
31277
31278 pid_t child_open
31279 (uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr,
31280 BOOL make_leader)
31281
31282 This function creates a child process that runs the command specified by
31283 argv. The environment for the process is specified by envp, which can be
31284 NULL if no environment variables are to be passed. A new umask is supplied
31285 for the process in newumask.
31286
31287 Pipes to the standard input and output of the new process are set up and
31288 returned to the caller via the infdptr and outfdptr arguments. The standard
31289 error is cloned to the standard output. If there are any file descriptors
31290 "in the way" in the new process, they are closed. If the final argument is
31291 TRUE, the new process is made into a process group leader.
31292
31293 The function returns the pid of the new process, or -1 if things go wrong.
31294
31295 int child_close(pid_t pid, int timeout)
31296
31297 This function waits for a child process to terminate, or for a timeout (in
31298 seconds) to expire. A timeout value of zero means wait as long as it takes.
31299 The return value is as follows:
31300
31301 + >= 0
31302
31303 The process terminated by a normal exit and the value is the process
31304 ending status.
31305
31306 + < 0 and > -256
31307
31308 The process was terminated by a signal and the value is the negation of
31309 the signal number.
31310
31311 + -256
31312
31313 The process timed out.
31314
31315 + -257
31316
31317 The was some other error in wait(); errno is still set.
31318
31319 pid_t child_open_exim(int *fd)
31320
31321 This function provide you with a means of submitting a new message to Exim.
31322 (Of course, you can also call /usr/sbin/sendmail yourself if you want, but
31323 this packages it all up for you.) The function creates a pipe, forks a
31324 subprocess that is running
31325
31326 exim -t -oem -oi -f <>
31327
31328 and returns to you (via the "int *" argument) a file descriptor for the
31329 pipe that is connected to the standard input. The yield of the function is
31330 the PID of the subprocess. You can then write a message to the file
31331 descriptor, with recipients in To:, Cc:, and/or Bcc: header lines.
31332
31333 When you have finished, call child_close() to wait for the process to
31334 finish and to collect its ending status. A timeout value of zero is usually
31335 fine in this circumstance. Unless you have made a mistake with the
31336 recipient addresses, you should get a return code of zero.
31337
31338 pid_t child_open_exim2(int *fd, uschar *sender, uschar *sender_authentication)
31339
31340 This function is a more sophisticated version of child_open(). The command
31341 that it runs is:
31342
31343 exim -t -oem -oi -f sender -oMas sender_authentication
31344
31345 The third argument may be NULL, in which case the -oMas option is omitted.
31346
31347 void debug_printf(char *, ...)
31348
31349 This is Exim's debugging function, with arguments as for (printf(). The
31350 output is written to the standard error stream. If no debugging is
31351 selected, calls to debug_printf() have no effect. Normally, you should make
31352 calls conditional on the "local_scan" debug selector by coding like this:
31353
31354 if ((debug_selector & D_local_scan) != 0)
31355 debug_printf("xxx", ...);
31356
31357 uschar *expand_string(uschar *string)
31358
31359 This is an interface to Exim's string expansion code. The return value is
31360 the expanded string, or NULL if there was an expansion failure. The C
31361 variable expand_string_message contains an error message after an expansion
31362 failure. If expansion does not change the string, the return value is the
31363 pointer to the input string. Otherwise, the return value points to a new
31364 block of memory that was obtained by a call to store_get(). See section
31365 45.8 below for a discussion of memory handling.
31366
31367 void header_add(int type, char *format, ...)
31368
31369 This function allows you to an add additional header line at the end of the
31370 existing ones. The first argument is the type, and should normally be a
31371 space character. The second argument is a format string and any number of
31372 substitution arguments as for sprintf(). You may include internal newlines
31373 if you want, and you must ensure that the string ends with a newline.
31374
31375 void header_add_at_position
31376 (BOOL after, uschar *name, BOOL topnot, int type, char *format, ...)
31377
31378 This function adds a new header line at a specified point in the header
31379 chain. The header itself is specified as for header_add().
31380
31381 If name is NULL, the new header is added at the end of the chain if after
31382 is true, or at the start if after is false. If name is not NULL, the header
31383 lines are searched for the first non-deleted header that matches the name.
31384 If one is found, the new header is added before it if after is false. If
31385 after is true, the new header is added after the found header and any
31386 adjacent subsequent ones with the same name (even if marked "deleted"). If
31387 no matching non-deleted header is found, the topnot option controls where
31388 the header is added. If it is true, addition is at the top; otherwise at
31389 the bottom. Thus, to add a header after all the Received: headers, or at
31390 the top if there are no Received: headers, you could use
31391
31392 header_add_at_position(TRUE, US"Received", TRUE,
31393 ' ', "X-xxx: ...");
31394
31395 Normally, there is always at least one non-deleted Received: header, but
31396 there may not be if received_header_text expands to an empty string.
31397
31398 void header_remove(int occurrence, uschar *name)
31399
31400 This function removes header lines. If occurrence is zero or negative, all
31401 occurrences of the header are removed. If occurrence is greater than zero,
31402 that particular instance of the header is removed. If no header(s) can be
31403 found that match the specification, the function does nothing.
31404
31405 BOOL header_testname(header_line *hdr, uschar *name, int length, BOOL notdel)
31406
31407 This function tests whether the given header has the given name. It is not
31408 just a string comparison, because white space is permitted between the name
31409 and the colon. If the notdel argument is true, a false return is forced for
31410 all "deleted" headers; otherwise they are not treated specially. For
31411 example:
31412
31413 if (header_testname(h, US"X-Spam", 6, TRUE)) ...
31414
31415 uschar *lss_b64encode(uschar *cleartext, int length)
31416
31417 This function base64-encodes a string, which is passed by address and
31418 length. The text may contain bytes of any value, including zero. The result
31419 is passed back in dynamic memory that is obtained by calling store_get().
31420 It is zero-terminated.
31421
31422 int lss_b64decode(uschar *codetext, uschar **cleartext)
31423
31424 This function decodes a base64-encoded string. Its arguments are a
31425 zero-terminated base64-encoded string and the address of a variable that is
31426 set to point to the result, which is in dynamic memory. The length of the
31427 decoded string is the yield of the function. If the input is invalid base64
31428 data, the yield is -1. A zero byte is added to the end of the output string
31429 to make it easy to interpret as a C string (assuming it contains no zeros
31430 of its own). The added zero byte is not included in the returned count.
31431
31432 int lss_match_domain(uschar *domain, uschar *list)
31433
31434 This function checks for a match in a domain list. Domains are always
31435 matched caselessly. The return value is one of the following:
31436
31437 OK match succeeded
31438 FAIL match failed
31439 DEFER match deferred
31440
31441 DEFER is usually caused by some kind of lookup defer, such as the inability
31442 to contact a database.
31443
31444 int lss_match_local_part(uschar *localpart, uschar *list, BOOL caseless)
31445
31446 This function checks for a match in a local part list. The third argument
31447 controls case-sensitivity. The return values are as for lss_match_domain().
31448
31449 int lss_match_address(uschar *address, uschar *list, BOOL caseless)
31450
31451 This function checks for a match in an address list. The third argument
31452 controls the case-sensitivity of the local part match. The domain is always
31453 matched caselessly. The return values are as for lss_match_domain().
31454
31455 int lss_match_host(uschar *host_name, uschar *host_address, uschar *list)
31456
31457 This function checks for a match in a host list. The most common usage is
31458 expected to be
31459
31460 lss_match_host(sender_host_name, sender_host_address, ...)
31461
31462 An empty address field matches an empty item in the host list. If the host
31463 name is NULL, the name corresponding to $sender_host_address is
31464 automatically looked up if a host name is required to match an item in the
31465 list. The return values are as for lss_match_domain(), but in addition,
31466 lss_match_host() returns ERROR in the case when it had to look up a host
31467 name, but the lookup failed.
31468
31469 void log_write(unsigned int selector, int which, char *format, ...)
31470
31471 This function writes to Exim's log files. The first argument should be zero
31472 (it is concerned with log_selector). The second argument can be "LOG_MAIN"
31473 or "LOG_REJECT" or "LOG_PANIC" or the inclusive "or" of any combination of
31474 them. It specifies to which log or logs the message is written. The
31475 remaining arguments are a format and relevant insertion arguments. The
31476 string should not contain any newlines, not even at the end.
31477
31478 void receive_add_recipient(uschar *address, int pno)
31479
31480 This function adds an additional recipient to the message. The first
31481 argument is the recipient address. If it is unqualified (has no domain), it
31482 is qualified with the qualify_recipient domain. The second argument must
31483 always be -1.
31484
31485 This function does not allow you to specify a private errors_to address (as
31486 described with the structure of recipient_item above), because it pre-dates
31487 the addition of that field to the structure. However, it is easy to add
31488 such a value afterwards. For example:
31489
31490 receive_add_recipient(US"monitor@mydom.example", -1);
31491 recipients_list[recipients_count-1].errors_to =
31492 US"postmaster@mydom.example";
31493
31494 BOOL receive_remove_recipient(uschar *recipient)
31495
31496 This is a convenience function to remove a named recipient from the list of
31497 recipients. It returns true if a recipient was removed, and false if no
31498 matching recipient could be found. The argument must be a complete email
31499 address.
31500
31501 uschar rfc2047_decode
31502 (uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr,
31503 uschar **error)
31504
31505 This function decodes strings that are encoded according to RFC 2047.
31506 Typically these are the contents of header lines. First, each "encoded
31507 word" is decoded from the Q or B encoding into a byte-string. Then, if
31508 provided with the name of a charset encoding, and if the iconv() function
31509 is available, an attempt is made to translate the result to the named
31510 character set. If this fails, the binary string is returned with an error
31511 message.
31512
31513 The first argument is the string to be decoded. If lencheck is TRUE, the
31514 maximum MIME word length is enforced. The third argument is the target
31515 encoding, or NULL if no translation is wanted.
31516
31517 If a binary zero is encountered in the decoded string, it is replaced by
31518 the contents of the zeroval argument. For use with Exim headers, the value
31519 must not be 0 because header lines are handled as zero-terminated strings.
31520
31521 The function returns the result of processing the string, zero-terminated;
31522 if lenptr is not NULL, the length of the result is set in the variable to
31523 which it points. When zeroval is 0, lenptr should not be NULL.
31524
31525 If an error is encountered, the function returns NULL and uses the error
31526 argument to return an error message. The variable pointed to by error is
31527 set to NULL if there is no error; it may be set non-NULL even when the
31528 function returns a non-NULL value if decoding was successful, but there was
31529 a problem with translation.
31530
31531 int smtp_fflush(void)
31532
31533 This function is used in conjunction with smtp_printf(), as described
31534 below.
31535
31536 void smtp_printf(char *, ...)
31537
31538 The arguments of this function are like printf(); it writes to the SMTP
31539 output stream. You should use this function only when there is an SMTP
31540 output stream, that is, when the incoming message is being received via
31541 interactive SMTP. This is the case when smtp_input is TRUE and
31542 smtp_batched_input is FALSE. If you want to test for an incoming message
31543 from another host (as opposed to a local process that used the -bs command
31544 line option), you can test the value of sender_host_address, which is
31545 non-NULL when a remote host is involved.
31546
31547 If an SMTP TLS connection is established, smtp_printf() uses the TLS output
31548 function, so it can be used for all forms of SMTP connection.
31549
31550 Strings that are written by smtp_printf() from within local_scan() must
31551 start with an appropriate response code: 550 if you are going to return
31552 LOCAL_SCAN_REJECT, 451 if you are going to return LOCAL_SCAN_TEMPREJECT,
31553 and 250 otherwise. Because you are writing the initial lines of a
31554 multi-line response, the code must be followed by a hyphen to indicate that
31555 the line is not the final response line. You must also ensure that the
31556 lines you write terminate with CRLF. For example:
31557
31558 smtp_printf("550-this is some extra info\r\n");
31559 return LOCAL_SCAN_REJECT;
31560
31561 Note that you can also create multi-line responses by including newlines in
31562 the data returned via the return_text argument. The added value of using
31563 smtp_printf() is that, for instance, you could introduce delays between
31564 multiple output lines.
31565
31566 The smtp_printf() function does not return any error indication, because it
31567 does not automatically flush pending output, and therefore does not test
31568 the state of the stream. (In the main code of Exim, flushing and error
31569 detection is done when Exim is ready for the next SMTP input command.) If
31570 you want to flush the output and check for an error (for example, the
31571 dropping of a TCP/IP connection), you can call smtp_fflush(), which has no
31572 arguments. It flushes the output stream, and returns a non-zero value if
31573 there is an error.
31574
31575 void *store_get(int)
31576
31577 This function accesses Exim's internal store (memory) manager. It gets a
31578 new chunk of memory whose size is given by the argument. Exim bombs out if
31579 it ever runs out of memory. See the next section for a discussion of memory
31580 handling.
31581
31582 void *store_get_perm(int)
31583
31584 This function is like store_get(), but it always gets memory from the
31585 permanent pool. See the next section for a discussion of memory handling.
31586
31587 uschar *string_copy(uschar *string)
31588
31589 See below.
31590
31591 uschar *string_copyn(uschar *string, int length)
31592
31593 See below.
31594
31595 uschar *string_sprintf(char *format, ...)
31596
31597 These three functions create strings using Exim's dynamic memory
31598 facilities. The first makes a copy of an entire string. The second copies
31599 up to a maximum number of characters, indicated by the second argument. The
31600 third uses a format and insertion arguments to create a new string. In each
31601 case, the result is a pointer to a new string in the current memory pool.
31602 See the next section for more discussion.
31603
31604
31605 45.8 More about Exim's memory handling
31606 --------------------------------------
31607
31608 No function is provided for freeing memory, because that is never needed. The
31609 dynamic memory that Exim uses when receiving a message is automatically
31610 recycled if another message is received by the same process (this applies only
31611 to incoming SMTP connections - other input methods can supply only one message
31612 at a time). After receiving the last message, a reception process terminates.
31613
31614 Because it is recycled, the normal dynamic memory cannot be used for holding
31615 data that must be preserved over a number of incoming messages on the same SMTP
31616 connection. However, Exim in fact uses two pools of dynamic memory; the second
31617 one is not recycled, and can be used for this purpose.
31618
31619 If you want to allocate memory that remains available for subsequent messages
31620 in the same SMTP connection, you should set
31621
31622 store_pool = POOL_PERM
31623
31624 before calling the function that does the allocation. There is no need to
31625 restore the value if you do not need to; however, if you do want to revert to
31626 the normal pool, you can either restore the previous value of store_pool or set
31627 it explicitly to POOL_MAIN.
31628
31629 The pool setting applies to all functions that get dynamic memory, including
31630 expand_string(), store_get(), and the string_xxx() functions. There is also a
31631 convenience function called store_get_perm() that gets a block of memory from
31632 the permanent pool while preserving the value of store_pool.
31633
31634
31635
31636 ===============================================================================
31637 46. SYSTEM-WIDE MESSAGE FILTERING
31638
31639 The previous chapters (on ACLs and the local scan function) describe checks
31640 that can be applied to messages before they are accepted by a host. There is
31641 also a mechanism for checking messages once they have been received, but before
31642 they are delivered. This is called the system filter.
31643
31644 The system filter operates in a similar manner to users' filter files, but it
31645 is run just once per message (however many recipients the message has). It
31646 should not normally be used as a substitute for routing, because deliver
31647 commands in a system router provide new envelope recipient addresses. The
31648 system filter must be an Exim filter. It cannot be a Sieve filter.
31649
31650 The system filter is run at the start of a delivery attempt, before any routing
31651 is done. If a message fails to be completely delivered at the first attempt,
31652 the system filter is run again at the start of every retry. If you want your
31653 filter to do something only once per message, you can make use of the
31654 first_delivery condition in an if command in the filter to prevent it happening
31655 on retries.
31656
31657 Warning: Because the system filter runs just once, variables that are specific
31658 to individual recipient addresses, such as $local_part and $domain, are not
31659 set, and the "personal" condition is not meaningful. If you want to run a
31660 centrally-specified filter for each recipient address independently, you can do
31661 so by setting up a suitable redirect router, as described in section 46.8
31662 below.
31663
31664
31665 46.1 Specifying a system filter
31666 -------------------------------
31667
31668 The name of the file that contains the system filter must be specified by
31669 setting system_filter. If you want the filter to run under a uid and gid other
31670 than root, you must also set system_filter_user and system_filter_group as
31671 appropriate. For example:
31672
31673 system_filter = /etc/mail/exim.filter
31674 system_filter_user = exim
31675
31676 If a system filter generates any deliveries directly to files or pipes (via the
31677 save or pipe commands), transports to handle these deliveries must be specified
31678 by setting system_filter_file_transport and system_filter_pipe_transport,
31679 respectively. Similarly, system_filter_reply_transport must be set to handle
31680 any messages generated by the reply command.
31681
31682
31683 46.2 Testing a system filter
31684 ----------------------------
31685
31686 You can run simple tests of a system filter in the same way as for a user
31687 filter, but you should use -bF rather than -bf, so that features that are
31688 permitted only in system filters are recognized.
31689
31690 If you want to test the combined effect of a system filter and a user filter,
31691 you can use both -bF and -bf on the same command line.
31692
31693
31694 46.3 Contents of a system filter
31695 --------------------------------
31696
31697 The language used to specify system filters is the same as for users' filter
31698 files. It is described in the separate end-user document Exim's interface to
31699 mail filtering. However, there are some additional features that are available
31700 only in system filters; these are described in subsequent sections. If they are
31701 encountered in a user's filter file or when testing with -bf, they cause
31702 errors.
31703
31704 There are two special conditions which, though available in users' filter
31705 files, are designed for use in system filters. The condition first_delivery is
31706 true only for the first attempt at delivering a message, and manually_thawed is
31707 true only if the message has been frozen, and subsequently thawed by an admin
31708 user. An explicit forced delivery counts as a manual thaw, but thawing as a
31709 result of the auto_thaw setting does not.
31710
31711 Warning: If a system filter uses the first_delivery condition to specify an
31712 "unseen" (non-significant) delivery, and that delivery does not succeed, it
31713 will not be tried again. If you want Exim to retry an unseen delivery until it
31714 succeeds, you should arrange to set it up every time the filter runs.
31715
31716 When a system filter finishes running, the values of the variables $n0 - $n9
31717 are copied into $sn0 - $sn9 and are thereby made available to users' filter
31718 files. Thus a system filter can, for example, set up "scores" to which users'
31719 filter files can refer.
31720
31721
31722 46.4 Additional variable for system filters
31723 -------------------------------------------
31724
31725 The expansion variable $recipients, containing a list of all the recipients of
31726 the message (separated by commas and white space), is available in system
31727 filters. It is not available in users' filters for privacy reasons.
31728
31729
31730 46.5 Defer, freeze, and fail commands for system filters
31731 --------------------------------------------------------
31732
31733 There are three extra commands (defer, freeze and fail) which are always
31734 available in system filters, but are not normally enabled in users' filters.
31735 (See the allow_defer, allow_freeze and allow_fail options for the redirect
31736 router.) These commands can optionally be followed by the word text and a
31737 string containing an error message, for example:
31738
31739 fail text "this message looks like spam to me"
31740
31741 The keyword text is optional if the next character is a double quote.
31742
31743 The defer command defers delivery of the original recipients of the message.
31744 The fail command causes all the original recipients to be failed, and a bounce
31745 message to be created. The freeze command suspends all delivery attempts for
31746 the original recipients. In all cases, any new deliveries that are specified by
31747 the filter are attempted as normal after the filter has run.
31748
31749 The freeze command is ignored if the message has been manually unfrozen and not
31750 manually frozen since. This means that automatic freezing by a system filter
31751 can be used as a way of checking out suspicious messages. If a message is found
31752 to be all right, manually unfreezing it allows it to be delivered.
31753
31754 The text given with a fail command is used as part of the bounce message as
31755 well as being written to the log. If the message is quite long, this can fill
31756 up a lot of log space when such failures are common. To reduce the size of the
31757 log message, Exim interprets the text in a special way if it starts with the
31758 two characters "<<" and contains ">>" later. The text between these two strings
31759 is written to the log, and the rest of the text is used in the bounce message.
31760 For example:
31761
31762 fail "<<filter test 1>>Your message is rejected \
31763 because it contains attachments that we are \
31764 not prepared to receive."
31765
31766 Take great care with the fail command when basing the decision to fail on the
31767 contents of the message, because the bounce message will of course include the
31768 contents of the original message and will therefore trigger the fail command
31769 again (causing a mail loop) unless steps are taken to prevent this. Testing the
31770 error_message condition is one way to prevent this. You could use, for example
31771
31772 if $message_body contains "this is spam" and not error_message
31773 then fail text "spam is not wanted here" endif
31774
31775 though of course that might let through unwanted bounce messages. The
31776 alternative is clever checking of the body and/or headers to detect bounces
31777 generated by the filter.
31778
31779 The interpretation of a system filter file ceases after a defer, freeze, or
31780 fail command is obeyed. However, any deliveries that were set up earlier in the
31781 filter file are honoured, so you can use a sequence such as
31782
31783 mail ...
31784 freeze
31785
31786 to send a specified message when the system filter is freezing (or deferring or
31787 failing) a message. The normal deliveries for the message do not, of course,
31788 take place.
31789
31790
31791 46.6 Adding and removing headers in a system filter
31792 ---------------------------------------------------
31793
31794 Two filter commands that are available only in system filters are:
31795
31796 headers add <string>
31797 headers remove <string>
31798
31799 The argument for the headers add is a string that is expanded and then added to
31800 the end of the message's headers. It is the responsibility of the filter
31801 maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is
31802 ignored, and if the string is otherwise empty, or if the expansion is forced to
31803 fail, the command has no effect.
31804
31805 You can use "\n" within the string, followed by white space, to specify
31806 continued header lines. More than one header may be added in one command by
31807 including "\n" within the string without any following white space. For
31808 example:
31809
31810 headers add "X-header-1: ....\n \
31811 continuation of X-header-1 ...\n\
31812 X-header-2: ...."
31813
31814 Note that the header line continuation white space after the first newline must
31815 be placed before the backslash that continues the input string, because white
31816 space after input continuations is ignored.
31817
31818 The argument for headers remove is a colon-separated list of header names. This
31819 command applies only to those headers that are stored with the message; those
31820 that are added at delivery time (such as Envelope-To: and Return-Path:) cannot
31821 be removed by this means. If there is more than one header with the same name,
31822 they are all removed.
31823
31824 The headers command in a system filter makes an immediate change to the set of
31825 header lines that was received with the message (with possible additions from
31826 ACL processing). Subsequent commands in the system filter operate on the
31827 modified set, which also forms the basis for subsequent message delivery.
31828 Unless further modified during routing or transporting, this set of headers is
31829 used for all recipients of the message.
31830
31831 During routing and transporting, the variables that refer to the contents of
31832 header lines refer only to those lines that are in this set. Thus, header lines
31833 that are added by a system filter are visible to users' filter files and to all
31834 routers and transports. This contrasts with the manipulation of header lines by
31835 routers and transports, which is not immediate, but which instead is saved up
31836 until the message is actually being written (see section 47.17).
31837
31838 If the message is not delivered at the first attempt, header lines that were
31839 added by the system filter are stored with the message, and so are still
31840 present at the next delivery attempt. Header lines that were removed are still
31841 present, but marked "deleted" so that they are not transported with the
31842 message. For this reason, it is usual to make the headers command conditional
31843 on first_delivery so that the set of header lines is not modified more than
31844 once.
31845
31846 Because header modification in a system filter acts immediately, you have to
31847 use an indirect approach if you want to modify the contents of a header line.
31848 For example:
31849
31850 headers add "Old-Subject: $h_subject:"
31851 headers remove "Subject"
31852 headers add "Subject: new subject (was: $h_old-subject:)"
31853 headers remove "Old-Subject"
31854
31855
31856 46.7 Setting an errors address in a system filter
31857 -------------------------------------------------
31858
31859 In a system filter, if a deliver command is followed by
31860
31861 errors_to <some address>
31862
31863 in order to change the envelope sender (and hence the error reporting) for that
31864 delivery, any address may be specified. (In a user filter, only the current
31865 user's address can be set.) For example, if some mail is being monitored, you
31866 might use
31867
31868 unseen deliver monitor@spying.example errors_to root@local.example
31869
31870 to take a copy which would not be sent back to the normal error reporting
31871 address if its delivery failed.
31872
31873
31874 46.8 Per-address filtering
31875 --------------------------
31876
31877 In contrast to the system filter, which is run just once per message for each
31878 delivery attempt, it is also possible to set up a system-wide filtering
31879 operation that runs once for each recipient address. In this case, variables
31880 such as $local_part and $domain can be used, and indeed, the choice of filter
31881 file could be made dependent on them. This is an example of a router which
31882 implements such a filter:
31883
31884 central_filter:
31885 check_local_user
31886 driver = redirect
31887 domains = +local_domains
31888 file = /central/filters/$local_part
31889 no_verify
31890 allow_filter
31891 allow_freeze
31892
31893 The filter is run in a separate process under its own uid. Therefore, either
31894 check_local_user must be set (as above), in which case the filter is run as the
31895 local user, or the user option must be used to specify which user to use. If
31896 both are set, user overrides.
31897
31898 Care should be taken to ensure that none of the commands in the filter file
31899 specify a significant delivery if the message is to go on to be delivered to
31900 its intended recipient. The router will not then claim to have dealt with the
31901 address, so it will be passed on to subsequent routers to be delivered in the
31902 normal way.
31903
31904
31905
31906 ===============================================================================
31907 47. MESSAGE PROCESSING
31908
31909 Exim performs various transformations on the sender and recipient addresses of
31910 all messages that it handles, and also on the messages' header lines. Some of
31911 these are optional and configurable, while others always take place. All of
31912 this processing, except rewriting as a result of routing, and the addition or
31913 removal of header lines while delivering, happens when a message is received,
31914 before it is placed on Exim's queue.
31915
31916 Some of the automatic processing takes place by default only for
31917 "locally-originated" messages. This adjective is used to describe messages that
31918 are not received over TCP/IP, but instead are passed to an Exim process on its
31919 standard input. This includes the interactive "local SMTP" case that is set up
31920 by the -bs command line option.
31921
31922 Note: Messages received over TCP/IP on the loopback interface (127.0.0.1 or
31923 ::1) are not considered to be locally-originated. Exim does not treat the
31924 loopback interface specially in any way.
31925
31926 If you want the loopback interface to be treated specially, you must ensure
31927 that there are appropriate entries in your ACLs.
31928
31929
31930 47.1 Submission mode for non-local messages
31931 -------------------------------------------
31932
31933 Processing that happens automatically for locally-originated messages (unless
31934 suppress_local_fixups is set) can also be requested for messages that are
31935 received over TCP/IP. The term "submission mode" is used to describe this
31936 state. Submission mode is set by the modifier
31937
31938 control = submission
31939
31940 in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 43.21
31941 and 43.22). This makes Exim treat the message as a local submission, and is
31942 normally used when the source of the message is known to be an MUA running on a
31943 client host (as opposed to an MTA). For example, to set submission mode for
31944 messages originating on the IPv4 loopback interface, you could include the
31945 following in the MAIL ACL:
31946
31947 warn hosts = 127.0.0.1
31948 control = submission
31949
31950 There are some options that can be used when setting submission mode. A slash
31951 is used to separate options. For example:
31952
31953 control = submission/sender_retain
31954
31955 Specifying sender_retain has the effect of setting local_sender_retain true and
31956 local_from_check false for the current incoming message. The first of these
31957 allows an existing Sender: header in the message to remain, and the second
31958 suppresses the check to ensure that From: matches the authenticated sender.
31959 With this setting, Exim still fixes up messages by adding Date: and Message-ID:
31960 header lines if they are missing, but makes no attempt to check sender
31961 authenticity in header lines.
31962
31963 When sender_retain is not set, a submission mode setting may specify a domain
31964 to be used when generating a From: or Sender: header line. For example:
31965
31966 control = submission/domain=some.domain
31967
31968 The domain may be empty. How this value is used is described in sections 47.11
31969 and 47.16. There is also a name option that allows you to specify the user's
31970 full name for inclusion in a created Sender: or From: header line. For example:
31971
31972 accept authenticated = *
31973 control = submission/domain=wonderland.example/\
31974 name=${lookup {$authenticated_id} \
31975 lsearch {/etc/exim/namelist}}
31976
31977 Because the name may contain any characters, including slashes, the name option
31978 must be given last. The remainder of the string is used as the name. For the
31979 example above, if /etc/exim/namelist contains:
31980
31981 bigegg: Humpty Dumpty
31982
31983 then when the sender has authenticated as bigegg, the generated Sender: line
31984 would be:
31985
31986 Sender: Humpty Dumpty <bigegg@wonderland.example>
31987
31988 By default, submission mode forces the return path to the same address as is
31989 used to create the Sender: header. However, if sender_retain is specified, the
31990 return path is also left unchanged.
31991
31992 Note: The changes caused by submission mode take effect after the predata ACL.
31993 This means that any sender checks performed before the fix-ups use the
31994 untrusted sender address specified by the user, not the trusted sender address
31995 specified by submission mode. Although this might be slightly unexpected, it
31996 does mean that you can configure ACL checks to spot that a user is trying to
31997 spoof another's address.
31998
31999
32000 47.2 Line endings
32001 -----------------
32002
32003 RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
32004 linefeed) is the line ending for messages transmitted over the Internet using
32005 SMTP over TCP/IP. However, within individual operating systems, different
32006 conventions are used. For example, Unix-like systems use just LF, but others
32007 use CRLF or just CR.
32008
32009 Exim was designed for Unix-like systems, and internally, it stores messages
32010 using the system's convention of a single LF as a line terminator. When
32011 receiving a message, all line endings are translated to this standard format.
32012 Originally, it was thought that programs that passed messages directly to an
32013 MTA within an operating system would use that system's convention. Experience
32014 has shown that this is not the case; for example, there are Unix applications
32015 that use CRLF in this circumstance. For this reason, and for compatibility with
32016 other MTAs, the way Exim handles line endings for all messages is now as
32017 follows:
32018
32019 * LF not preceded by CR is treated as a line ending.
32020
32021 * CR is treated as a line ending; if it is immediately followed by LF, the LF
32022 is ignored.
32023
32024 * The sequence "CR, dot, CR" does not terminate an incoming SMTP message, nor
32025 a local message in the state where a line containing only a dot is a
32026 terminator.
32027
32028 * If a bare CR is encountered within a header line, an extra space is added
32029 after the line terminator so as not to end the header line. The reasoning
32030 behind this is that bare CRs in header lines are most likely either to be
32031 mistakes, or people trying to play silly games.
32032
32033 * If the first header line received in a message ends with CRLF, a subsequent
32034 bare LF in a header line is treated in the same way as a bare CR in a
32035 header line.
32036
32037
32038 47.3 Unqualified addresses
32039 --------------------------
32040
32041 By default, Exim expects every envelope address it receives from an external
32042 host to be fully qualified. Unqualified addresses cause negative responses to
32043 SMTP commands. However, because SMTP is used as a means of transporting
32044 messages from MUAs running on personal workstations, there is sometimes a
32045 requirement to accept unqualified addresses from specific hosts or IP networks.
32046
32047 Exim has two options that separately control which hosts may send unqualified
32048 sender or recipient addresses in SMTP commands, namely sender_unqualified_hosts
32049 and recipient_unqualified_hosts. In both cases, if an unqualified address is
32050 accepted, it is qualified by adding the value of qualify_domain or
32051 qualify_recipient, as appropriate.
32052
32053 Unqualified addresses in header lines are automatically qualified for messages
32054 that are locally originated, unless the -bnq option is given on the command
32055 line. For messages received over SMTP, unqualified addresses in header lines
32056 are qualified only if unqualified addresses are permitted in SMTP commands. In
32057 other words, such qualification is also controlled by sender_unqualified_hosts
32058 and recipient_unqualified_hosts,
32059
32060
32061 47.4 The UUCP From line
32062 -----------------------
32063
32064 Messages that have come from UUCP (and some other applications) often begin
32065 with a line containing the envelope sender and a timestamp, following the word
32066 "From". Examples of two common formats are:
32067
32068 From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996
32069 From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT
32070
32071 This line precedes the RFC 2822 header lines. For compatibility with Sendmail,
32072 Exim recognizes such lines at the start of messages that are submitted to it
32073 via the command line (that is, on the standard input). It does not recognize
32074 such lines in incoming SMTP messages, unless the sending host matches
32075 ignore_fromline_hosts or the -bs option was used for a local message and
32076 ignore_fromline_local is set. The recognition is controlled by a regular
32077 expression that is defined by the uucp_from_pattern option, whose default value
32078 matches the two common cases shown above and puts the address that follows
32079 "From" into $1.
32080
32081 When the caller of Exim for a non-SMTP message that contains a "From" line is a
32082 trusted user, the message's sender address is constructed by expanding the
32083 contents of uucp_sender_address, whose default value is "$1". This is then
32084 parsed as an RFC 2822 address. If there is no domain, the local part is
32085 qualified with qualify_domain unless it is the empty string. However, if the
32086 command line -f option is used, it overrides the "From" line.
32087
32088 If the caller of Exim is not trusted, the "From" line is recognized, but the
32089 sender address is not changed. This is also the case for incoming SMTP messages
32090 that are permitted to contain "From" lines.
32091
32092 Only one "From" line is recognized. If there is more than one, the second is
32093 treated as a data line that starts the body of the message, as it is not valid
32094 as a header line. This also happens if a "From" line is present in an incoming
32095 SMTP message from a source that is not permitted to send them.
32096
32097
32098 47.5 Resent- header lines
32099 -------------------------
32100
32101 RFC 2822 makes provision for sets of header lines starting with the string
32102 "Resent-" to be added to a message when it is resent by the original recipient
32103 to somebody else. These headers are Resent-Date:, Resent-From:, Resent-Sender:,
32104 Resent-To:, Resent-Cc:, Resent-Bcc: and Resent-Message-ID:. The RFC says:
32105
32106 Resent fields are strictly informational. They MUST NOT be used in the
32107 normal processing of replies or other such automatic actions on messages.
32108
32109 This leaves things a bit vague as far as other processing actions such as
32110 address rewriting are concerned. Exim treats Resent- header lines as follows:
32111
32112 * A Resent-From: line that just contains the login id of the submitting user
32113 is automatically rewritten in the same way as From: (see below).
32114
32115 * If there's a rewriting rule for a particular header line, it is also
32116 applied to Resent- header lines of the same type. For example, a rule that
32117 rewrites From: also rewrites Resent-From:.
32118
32119 * For local messages, if Sender: is removed on input, Resent-Sender: is also
32120 removed.
32121
32122 * For a locally-submitted message, if there are any Resent- header lines but
32123 no Resent-Date:, Resent-From:, or Resent-Message-Id:, they are added as
32124 necessary. It is the contents of Resent-Message-Id: (rather than
32125 Message-Id:) which are included in log lines in this case.
32126
32127 * The logic for adding Sender: is duplicated for Resent-Sender: when any
32128 Resent- header lines are present.
32129
32130
32131 47.6 The Auto-Submitted: header line
32132 ------------------------------------
32133
32134 Whenever Exim generates an autoreply, a bounce, or a delay warning message, it
32135 includes the header line:
32136
32137 Auto-Submitted: auto-replied
32138
32139
32140 47.7 The Bcc: header line
32141 -------------------------
32142
32143 If Exim is called with the -t option, to take recipient addresses from a
32144 message's header, it removes any Bcc: header line that may exist (after
32145 extracting its addresses). If -t is not present on the command line, any
32146 existing Bcc: is not removed.
32147
32148
32149 47.8 The Date: header line
32150 --------------------------
32151
32152 If a locally-generated or submission-mode message has no Date: header line,
32153 Exim adds one, using the current date and time, unless the
32154 suppress_local_fixups control has been specified.
32155
32156
32157 47.9 The Delivery-date: header line
32158 -----------------------------------
32159
32160 Delivery-date: header lines are not part of the standard RFC 2822 header set.
32161 Exim can be configured to add them to the final delivery of messages. (See the
32162 generic delivery_date_add transport option.) They should not be present in
32163 messages in transit. If the delivery_date_remove configuration option is set
32164 (the default), Exim removes Delivery-date: header lines from incoming messages.
32165
32166
32167 47.10 The Envelope-to: header line
32168 ----------------------------------
32169
32170 Envelope-to: header lines are not part of the standard RFC 2822 header set.
32171 Exim can be configured to add them to the final delivery of messages. (See the
32172 generic envelope_to_add transport option.) They should not be present in
32173 messages in transit. If the envelope_to_remove configuration option is set (the
32174 default), Exim removes Envelope-to: header lines from incoming messages.
32175
32176
32177 47.11 The From: header line
32178 ---------------------------
32179
32180 If a submission-mode message does not contain a From: header line, Exim adds
32181 one if either of the following conditions is true:
32182
32183 * The envelope sender address is not empty (that is, this is not a bounce
32184 message). The added header line copies the envelope sender address.
32185
32186 * The SMTP session is authenticated and $authenticated_id is not empty.
32187
32188 1. If no domain is specified by the submission control, the local part is
32189 $authenticated_id and the domain is $qualify_domain.
32190
32191 2. If a non-empty domain is specified by the submission control, the local
32192 part is $authenticated_id, and the domain is the specified domain.
32193
32194 3. If an empty domain is specified by the submission control,
32195 $authenticated_id is assumed to be the complete address.
32196
32197 A non-empty envelope sender takes precedence.
32198
32199 If a locally-generated incoming message does not contain a From: header line,
32200 and the suppress_local_fixups control is not set, Exim adds one containing the
32201 sender's address. The calling user's login name and full name are used to
32202 construct the address, as described in section 47.18. They are obtained from
32203 the password data by calling getpwuid() (but see the unknown_login
32204 configuration option). The address is qualified with qualify_domain.
32205
32206 For compatibility with Sendmail, if an incoming, non-SMTP message has a From:
32207 header line containing just the unqualified login name of the calling user,
32208 this is replaced by an address containing the user's login name and full name
32209 as described in section 47.18.
32210
32211
32212 47.12 The Message-ID: header line
32213 ---------------------------------
32214
32215 If a locally-generated or submission-mode incoming message does not contain a
32216 Message-ID: or Resent-Message-ID: header line, and the suppress_local_fixups
32217 control is not set, Exim adds a suitable header line to the message. If there
32218 are any Resent-: headers in the message, it creates Resent-Message-ID:. The id
32219 is constructed from Exim's internal message id, preceded by the letter E to
32220 ensure it starts with a letter, and followed by @ and the primary host name.
32221 Additional information can be included in this header line by setting the
32222 message_id_header_text and/or message_id_header_domain options.
32223
32224
32225 47.13 The Received: header line
32226 -------------------------------
32227
32228 A Received: header line is added at the start of every message. The contents
32229 are defined by the received_header_text configuration option, and Exim
32230 automatically adds a semicolon and a timestamp to the configured string.
32231
32232 The Received: header is generated as soon as the message's header lines have
32233 been received. At this stage, the timestamp in the Received: header line is the
32234 time that the message started to be received. This is the value that is seen by
32235 the DATA ACL and by the local_scan() function.
32236
32237 Once a message is accepted, the timestamp in the Received: header line is
32238 changed to the time of acceptance, which is (apart from a small delay while the
32239 -H spool file is written) the earliest time at which delivery could start.
32240
32241
32242 47.14 The References: header line
32243 ---------------------------------
32244
32245 Messages created by the autoreply transport include a References: header line.
32246 This is constructed according to the rules that are described in section 3.64
32247 of RFC 2822 (which states that replies should contain such a header line), and
32248 section 3.14 of RFC 3834 (which states that automatic responses are not
32249 different in this respect). However, because some mail processing software does
32250 not cope well with very long header lines, no more than 12 message IDs are
32251 copied from the References: header line in the incoming message. If there are
32252 more than 12, the first one and then the final 11 are copied, before adding the
32253 message ID of the incoming message.
32254
32255
32256 47.15 The Return-path: header line
32257 ----------------------------------
32258
32259 Return-path: header lines are defined as something an MTA may insert when it
32260 does the final delivery of messages. (See the generic return_path_add transport
32261 option.) Therefore, they should not be present in messages in transit. If the
32262 return_path_remove configuration option is set (the default), Exim removes
32263 Return-path: header lines from incoming messages.
32264
32265
32266 47.16 The Sender: header line
32267 -----------------------------
32268
32269 For a locally-originated message from an untrusted user, Exim may remove an
32270 existing Sender: header line, and it may add a new one. You can modify these
32271 actions by setting the local_sender_retain option true, the local_from_check
32272 option false, or by using the suppress_local_fixups control setting.
32273
32274 When a local message is received from an untrusted user and local_from_check is
32275 true (the default), and the suppress_local_fixups control has not been set, a
32276 check is made to see if the address given in the From: header line is the
32277 correct (local) sender of the message. The address that is expected has the
32278 login name as the local part and the value of qualify_domain as the domain.
32279 Prefixes and suffixes for the local part can be permitted by setting
32280 local_from_prefix and local_from_suffix appropriately. If From: does not
32281 contain the correct sender, a Sender: line is added to the message.
32282
32283 If you set local_from_check false, this checking does not occur. However, the
32284 removal of an existing Sender: line still happens, unless you also set
32285 local_sender_retain to be true. It is not possible to set both of these options
32286 true at the same time.
32287
32288 By default, no processing of Sender: header lines is done for messages received
32289 over TCP/IP or for messages submitted by trusted users. However, when a message
32290 is received over TCP/IP in submission mode, and sender_retain is not specified
32291 on the submission control, the following processing takes place:
32292
32293 First, any existing Sender: lines are removed. Then, if the SMTP session is
32294 authenticated, and $authenticated_id is not empty, a sender address is created
32295 as follows:
32296
32297 * If no domain is specified by the submission control, the local part is
32298 $authenticated_id and the domain is $qualify_domain.
32299
32300 * If a non-empty domain is specified by the submission control, the local
32301 part is $authenticated_id, and the domain is the specified domain.
32302
32303 * If an empty domain is specified by the submission control,
32304 $authenticated_id is assumed to be the complete address.
32305
32306 This address is compared with the address in the From: header line. If they are
32307 different, a Sender: header line containing the created address is added.
32308 Prefixes and suffixes for the local part in From: can be permitted by setting
32309 local_from_prefix and local_from_suffix appropriately.
32310
32311 Note: Whenever a Sender: header line is created, the return path for the
32312 message (the envelope sender address) is changed to be the same address, except
32313 in the case of submission mode when sender_retain is specified.
32314
32315
32316 47.17 Adding and removing header lines in routers and transports
32317 ----------------------------------------------------------------
32318
32319 When a message is delivered, the addition and removal of header lines can be
32320 specified in a system filter, or on any of the routers and transports that
32321 process the message. Section 46.6 contains details about modifying headers in a
32322 system filter. Header lines can also be added in an ACL as a message is
32323 received (see section 43.24).
32324
32325 In contrast to what happens in a system filter, header modifications that are
32326 specified on routers and transports apply only to the particular recipient
32327 addresses that are being processed by those routers and transports. These
32328 changes do not actually take place until a copy of the message is being
32329 transported. Therefore, they do not affect the basic set of header lines, and
32330 they do not affect the values of the variables that refer to header lines.
32331
32332 Note: In particular, this means that any expansions in the configuration of the
32333 transport cannot refer to the modified header lines, because such expansions
32334 all occur before the message is actually transported.
32335
32336 For both routers and transports, the argument of a headers_add option must be
32337 in the form of one or more RFC 2822 header lines, separated by newlines (coded
32338 as "\n"). For example:
32339
32340 headers_add = X-added-header: added by $primary_hostname\n\
32341 X-added-second: another added header line
32342
32343 Exim does not check the syntax of these added header lines.
32344
32345 Multiple headers_add options for a single router or transport can be specified;
32346 the values will append to a single list of header lines. Each header-line is
32347 separately expanded.
32348
32349 The argument of a headers_remove option must consist of a colon-separated list
32350 of header names. This is confusing, because header names themselves are often
32351 terminated by colons. In this case, the colons are the list separators, not
32352 part of the names. For example:
32353
32354 headers_remove = return-receipt-to:acknowledge-to
32355
32356 Multiple headers_remove options for a single router or transport can be
32357 specified; the arguments will append to a single header-names list. Each item
32358 is separately expanded. Note that colons in complex expansions which are used
32359 to form all or part of a headers_remove list will act as list separators.
32360
32361 When headers_add or headers_remove is specified on a router, items are expanded
32362 at routing time, and then associated with all addresses that are accepted by
32363 that router, and also with any new addresses that it generates. If an address
32364 passes through several routers as a result of aliasing or forwarding, the
32365 changes are cumulative.
32366
32367 However, this does not apply to multiple routers that result from the use of
32368 the unseen option. Any header modifications that were specified by the "unseen"
32369 router or its predecessors apply only to the "unseen" delivery.
32370
32371 Addresses that end up with different headers_add or headers_remove settings
32372 cannot be delivered together in a batch, so a transport is always dealing with
32373 a set of addresses that have the same header-processing requirements.
32374
32375 The transport starts by writing the original set of header lines that arrived
32376 with the message, possibly modified by the system filter. As it writes out
32377 these lines, it consults the list of header names that were attached to the
32378 recipient address(es) by headers_remove options in routers, and it also
32379 consults the transport's own headers_remove option. Header lines whose names
32380 are on either of these lists are not written out. If there are multiple
32381 instances of any listed header, they are all skipped.
32382
32383 After the remaining original header lines have been written, new header lines
32384 that were specified by routers' headers_add options are written, in the order
32385 in which they were attached to the address. These are followed by any header
32386 lines specified by the transport's headers_add option.
32387
32388 This way of handling header line modifications in routers and transports has
32389 the following consequences:
32390
32391 * The original set of header lines, possibly modified by the system filter,
32392 remains "visible", in the sense that the $header_xxx variables refer to it,
32393 at all times.
32394
32395 * Header lines that are added by a router's headers_add option are not
32396 accessible by means of the $header_xxx expansion syntax in subsequent
32397 routers or the transport.
32398
32399 * Conversely, header lines that are specified for removal by headers_remove
32400 in a router remain visible to subsequent routers and the transport.
32401
32402 * Headers added to an address by headers_add in a router cannot be removed by
32403 a later router or by a transport.
32404
32405 * An added header can refer to the contents of an original header that is to
32406 be removed, even it has the same name as the added header. For example:
32407
32408 headers_remove = subject
32409 headers_add = Subject: new subject (was: $h_subject:)
32410
32411 Warning: The headers_add and headers_remove options cannot be used for a
32412 redirect router that has the one_time option set.
32413
32414
32415 47.18 Constructed addresses
32416 ---------------------------
32417
32418 When Exim constructs a sender address for a locally-generated message, it uses
32419 the form
32420
32421 <user name> <login@qualify_domain>
32422
32423 For example:
32424
32425 Zaphod Beeblebrox <zaphod@end.univ.example>
32426
32427 The user name is obtained from the -F command line option if set, or otherwise
32428 by looking up the calling user by getpwuid() and extracting the "gecos" field
32429 from the password entry. If the "gecos" field contains an ampersand character,
32430 this is replaced by the login name with the first letter upper cased, as is
32431 conventional in a number of operating systems. See the gecos_name option for a
32432 way to tailor the handling of the "gecos" field. The unknown_username option
32433 can be used to specify user names in cases when there is no password file
32434 entry.
32435
32436 In all cases, the user name is made to conform to RFC 2822 by quoting all or
32437 parts of it if necessary. In addition, if it contains any non-printing
32438 characters, it is encoded as described in RFC 2047, which defines a way of
32439 including non-ASCII characters in header lines. The value of the
32440 headers_charset option specifies the name of the encoding that is used (the
32441 characters are assumed to be in this encoding). The setting of
32442 print_topbitchars controls whether characters with the top bit set (that is,
32443 with codes greater than 127) count as printing characters or not.
32444
32445
32446 47.19 Case of local parts
32447 -------------------------
32448
32449 RFC 2822 states that the case of letters in the local parts of addresses cannot
32450 be assumed to be non-significant. Exim preserves the case of local parts of
32451 addresses, but by default it uses a lower-cased form when it is routing,
32452 because on most Unix systems, usernames are in lower case and case-insensitive
32453 routing is required. However, any particular router can be made to use the
32454 original case for local parts by setting the caseful_local_part generic router
32455 option.
32456
32457 If you must have mixed-case user names on your system, the best way to proceed,
32458 assuming you want case-independent handling of incoming email, is to set up
32459 your first router to convert incoming local parts in your domains to the
32460 correct case by means of a file lookup. For example:
32461
32462 correct_case:
32463 driver = redirect
32464 domains = +local_domains
32465 data = ${lookup{$local_part}cdb\
32466 {/etc/usercased.cdb}{$value}fail}\
32467 @$domain
32468
32469 For this router, the local part is forced to lower case by the default action (
32470 caseful_local_part is not set). The lower-cased local part is used to look up a
32471 new local part in the correct case. If you then set caseful_local_part on any
32472 subsequent routers which process your domains, they will operate on local parts
32473 with the correct case in a case-sensitive manner.
32474
32475
32476 47.20 Dots in local parts
32477 -------------------------
32478
32479 RFC 2822 forbids empty components in local parts. That is, an unquoted local
32480 part may not begin or end with a dot, nor have two consecutive dots in the
32481 middle. However, it seems that many MTAs do not enforce this, so Exim permits
32482 empty components for compatibility.
32483
32484
32485 47.21 Rewriting addresses
32486 -------------------------
32487
32488 Rewriting of sender and recipient addresses, and addresses in headers, can
32489 happen automatically, or as the result of configuration options, as described
32490 in chapter 31. The headers that may be affected by this are Bcc:, Cc:, From:,
32491 Reply-To:, Sender:, and To:.
32492
32493 Automatic rewriting includes qualification, as mentioned above. The other case
32494 in which it can happen is when an incomplete non-local domain is given. The
32495 routing process may cause this to be expanded into the full domain name. For
32496 example, a header such as
32497
32498 To: hare@teaparty
32499
32500 might get rewritten as
32501
32502 To: hare@teaparty.wonderland.fict.example
32503
32504 Rewriting as a result of routing is the one kind of message processing that
32505 does not happen at input time, as it cannot be done until the address has been
32506 routed.
32507
32508 Strictly, one should not do any deliveries of a message until all its addresses
32509 have been routed, in case any of the headers get changed as a result of
32510 routing. However, doing this in practice would hold up many deliveries for
32511 unreasonable amounts of time, just because one address could not immediately be
32512 routed. Exim therefore does not delay other deliveries when routing of one or
32513 more addresses is deferred.
32514
32515
32516
32517 ===============================================================================
32518 48. SMTP PROCESSING
32519
32520 Exim supports a number of different ways of using the SMTP protocol, and its
32521 LMTP variant, which is an interactive protocol for transferring messages into a
32522 closed mail store application. This chapter contains details of how SMTP is
32523 processed. For incoming mail, the following are available:
32524
32525 * SMTP over TCP/IP (Exim daemon or inetd);
32526
32527 * SMTP over the standard input and output (the -bs option);
32528
32529 * Batched SMTP on the standard input (the -bS option).
32530
32531 For mail delivery, the following are available:
32532
32533 * SMTP over TCP/IP (the smtp transport);
32534
32535 * LMTP over TCP/IP (the smtp transport with the protocol option set to
32536 "lmtp");
32537
32538 * LMTP over a pipe to a process running in the local host (the lmtp
32539 transport);
32540
32541 * Batched SMTP to a file or pipe (the appendfile and pipe transports with the
32542 use_bsmtp option set).
32543
32544 Batched SMTP is the name for a process in which batches of messages are stored
32545 in or read from files (or pipes), in a format in which SMTP commands are used
32546 to contain the envelope information.
32547
32548
32549 48.1 Outgoing SMTP and LMTP over TCP/IP
32550 ---------------------------------------
32551
32552 Outgoing SMTP and LMTP over TCP/IP is implemented by the smtp transport. The
32553 protocol option selects which protocol is to be used, but the actual processing
32554 is the same in both cases.
32555
32556 If, in response to its EHLO command, Exim is told that the SIZE parameter is
32557 supported, it adds SIZE=<n> to each subsequent MAIL command. The value of <n>
32558 is the message size plus the value of the size_addition option (default 1024)
32559 to allow for additions to the message such as per-transport header lines, or
32560 changes made in a transport filter. If size_addition is set negative, the use
32561 of SIZE is suppressed.
32562
32563 If the remote server advertises support for PIPELINING, Exim uses the
32564 pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets
32565 required for the transaction.
32566
32567 If the remote server advertises support for the STARTTLS command, and Exim was
32568 built to support TLS encryption, it tries to start a TLS session unless the
32569 server matches hosts_avoid_tls. See chapter 42 for more details. Either a match
32570 in that or hosts_verify_avoid_tls apply when the transport is called for
32571 verification.
32572
32573 If the remote server advertises support for the AUTH command, Exim scans the
32574 authenticators configuration for any suitable client settings, as described in
32575 chapter 33.
32576
32577 Responses from the remote host are supposed to be terminated by CR followed by
32578 LF. However, there are known to be hosts that do not send CR characters, so in
32579 order to be able to interwork with such hosts, Exim treats LF on its own as a
32580 line terminator.
32581
32582 If a message contains a number of different addresses, all those with the same
32583 characteristics (for example, the same envelope sender) that resolve to the
32584 same set of hosts, in the same order, are sent in a single SMTP transaction,
32585 even if they are for different domains, unless there are more than the setting
32586 of the max_rcpts option in the smtp transport allows, in which case they are
32587 split into groups containing no more than max_rcpts addresses each. If
32588 remote_max_parallel is greater than one, such groups may be sent in parallel
32589 sessions. The order of hosts with identical MX values is not significant when
32590 checking whether addresses can be batched in this way.
32591
32592 When the smtp transport suffers a temporary failure that is not
32593 message-related, Exim updates its transport-specific database, which contains
32594 records indexed by host name that remember which messages are waiting for each
32595 particular host. It also updates the retry database with new retry times.
32596
32597 Exim's retry hints are based on host name plus IP address, so if one address of
32598 a multi-homed host is broken, it will soon be skipped most of the time. See the
32599 next section for more detail about error handling.
32600
32601 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
32602 looks in the hints database for the transport to see if there are any queued
32603 messages waiting for the host to which it is connected. If it finds one, it
32604 creates a new Exim process using the -MC option (which can only be used by a
32605 process running as root or the Exim user) and passes the TCP/IP socket to it so
32606 that it can deliver another message using the same socket. The new process does
32607 only those deliveries that are routed to the connected host, and may in turn
32608 pass the socket on to a third process, and so on.
32609
32610 The connection_max_messages option of the smtp transport can be used to limit
32611 the number of messages sent down a single TCP/IP connection.
32612
32613 The second and subsequent messages delivered down an existing connection are
32614 identified in the main log by the addition of an asterisk after the closing
32615 square bracket of the IP address.
32616
32617
32618 48.2 Errors in outgoing SMTP
32619 ----------------------------
32620
32621 Three different kinds of error are recognized for outgoing SMTP: host errors,
32622 message errors, and recipient errors.
32623
32624 Host errors
32625
32626 A host error is not associated with a particular message or with a
32627 particular recipient of a message. The host errors are:
32628
32629 + Connection refused or timed out,
32630
32631 + Any error response code on connection,
32632
32633 + Any error response code to EHLO or HELO,
32634
32635 + Loss of connection at any time, except after ".",
32636
32637 + I/O errors at any time,
32638
32639 + Timeouts during the session, other than in response to MAIL, RCPT or
32640 the "." at the end of the data.
32641
32642 For a host error, a permanent error response on connection, or in response
32643 to EHLO, causes all addresses routed to the host to be failed. Any other
32644 host error causes all addresses to be deferred, and retry data to be
32645 created for the host. It is not tried again, for any message, until its
32646 retry time arrives. If the current set of addresses are not all delivered
32647 in this run (to some alternative host), the message is added to the list of
32648 those waiting for this host, so if it is still undelivered when a
32649 subsequent successful delivery is made to the host, it will be sent down
32650 the same SMTP connection.
32651
32652 Message errors
32653
32654 A message error is associated with a particular message when sent to a
32655 particular host, but not with a particular recipient of the message. The
32656 message errors are:
32657
32658 + Any error response code to MAIL, DATA, or the "." that terminates the
32659 data,
32660
32661 + Timeout after MAIL,
32662
32663 + Timeout or loss of connection after the "." that terminates the data. A
32664 timeout after the DATA command itself is treated as a host error, as is
32665 loss of connection at any other time.
32666
32667 For a message error, a permanent error response (5xx) causes all addresses
32668 to be failed, and a delivery error report to be returned to the sender. A
32669 temporary error response (4xx), or one of the timeouts, causes all
32670 addresses to be deferred. Retry data is not created for the host, but
32671 instead, a retry record for the combination of host plus message id is
32672 created. The message is not added to the list of those waiting for this
32673 host. This ensures that the failing message will not be sent to this host
32674 again until the retry time arrives. However, other messages that are routed
32675 to the host are not affected, so if it is some property of the message that
32676 is causing the error, it will not stop the delivery of other mail.
32677
32678 If the remote host specified support for the SIZE parameter in its response
32679 to EHLO, Exim adds SIZE=nnn to the MAIL command, so an over-large message
32680 will cause a message error because the error arrives as a response to MAIL.
32681
32682 Recipient errors
32683
32684 A recipient error is associated with a particular recipient of a message.
32685 The recipient errors are:
32686
32687 + Any error response to RCPT,
32688
32689 + Timeout after RCPT.
32690
32691 For a recipient error, a permanent error response (5xx) causes the
32692 recipient address to be failed, and a bounce message to be returned to the
32693 sender. A temporary error response (4xx) or a timeout causes the failing
32694 address to be deferred, and routing retry data to be created for it. This
32695 is used to delay processing of the address in subsequent queue runs, until
32696 its routing retry time arrives. This applies to all messages, but because
32697 it operates only in queue runs, one attempt will be made to deliver a new
32698 message to the failing address before the delay starts to operate. This
32699 ensures that, if the failure is really related to the message rather than
32700 the recipient ("message too big for this recipient" is a possible example),
32701 other messages have a chance of getting delivered. If a delivery to the
32702 address does succeed, the retry information gets cleared, so all stuck
32703 messages get tried again, and the retry clock is reset.
32704
32705 The message is not added to the list of those waiting for this host. Use of
32706 the host for other messages is unaffected, and except in the case of a
32707 timeout, other recipients are processed independently, and may be
32708 successfully delivered in the current SMTP session. After a timeout it is
32709 of course impossible to proceed with the session, so all addresses get
32710 deferred. However, those other than the one that failed do not suffer any
32711 subsequent retry delays. Therefore, if one recipient is causing trouble,
32712 the others have a chance of getting through when a subsequent delivery
32713 attempt occurs before the failing recipient's retry time.
32714
32715 In all cases, if there are other hosts (or IP addresses) available for the
32716 current set of addresses (for example, from multiple MX records), they are
32717 tried in this run for any undelivered addresses, subject of course to their own
32718 retry data. In other words, recipient error retry data does not take effect
32719 until the next delivery attempt.
32720
32721 Some hosts have been observed to give temporary error responses to every MAIL
32722 command at certain times ("insufficient space" has been seen). It would be nice
32723 if such circumstances could be recognized, and defer data for the host itself
32724 created, but this is not possible within the current Exim design. What actually
32725 happens is that retry data for every (host, message) combination is created.
32726
32727 The reason that timeouts after MAIL and RCPT are treated specially is that
32728 these can sometimes arise as a result of the remote host's verification
32729 procedures. Exim makes this assumption, and treats them as if a temporary error
32730 response had been received. A timeout after "." is treated specially because it
32731 is known that some broken implementations fail to recognize the end of the
32732 message if the last character of the last line is a binary zero. Thus, it is
32733 helpful to treat this case as a message error.
32734
32735 Timeouts at other times are treated as host errors, assuming a problem with the
32736 host, or the connection to it. If a timeout after MAIL, RCPT, or "." is really
32737 a connection problem, the assumption is that at the next try the timeout is
32738 likely to occur at some other point in the dialogue, causing it then to be
32739 treated as a host error.
32740
32741 There is experimental evidence that some MTAs drop the connection after the
32742 terminating "." if they do not like the contents of the message for some
32743 reason, in contravention of the RFC, which indicates that a 5xx response should
32744 be given. That is why Exim treats this case as a message rather than a host
32745 error, in order not to delay other messages to the same host.
32746
32747
32748 48.3 Incoming SMTP messages over TCP/IP
32749 ---------------------------------------
32750
32751 Incoming SMTP messages can be accepted in one of two ways: by running a
32752 listening daemon, or by using inetd. In the latter case, the entry in /etc/
32753 inetd.conf should be like this:
32754
32755 smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs
32756
32757 Exim distinguishes between this case and the case of a locally running user
32758 agent using the -bs option by checking whether or not the standard input is a
32759 socket. When it is, either the port must be privileged (less than 1024), or the
32760 caller must be root or the Exim user. If any other user passes a socket with an
32761 unprivileged port number, Exim prints a message on the standard error stream
32762 and exits with an error code.
32763
32764 By default, Exim does not make a log entry when a remote host connects or
32765 disconnects (either via the daemon or inetd), unless the disconnection is
32766 unexpected. It can be made to write such log entries by setting the
32767 smtp_connection log selector.
32768
32769 Commands from the remote host are supposed to be terminated by CR followed by
32770 LF. However, there are known to be hosts that do not send CR characters. In
32771 order to be able to interwork with such hosts, Exim treats LF on its own as a
32772 line terminator. Furthermore, because common code is used for receiving
32773 messages from all sources, a CR on its own is also interpreted as a line
32774 terminator. However, the sequence "CR, dot, CR" does not terminate incoming
32775 SMTP data.
32776
32777 One area that sometimes gives rise to problems concerns the EHLO or HELO
32778 commands. Some clients send syntactically invalid versions of these commands,
32779 which Exim rejects by default. (This is nothing to do with verifying the data
32780 that is sent, so helo_verify_hosts is not relevant.) You can tell Exim not to
32781 apply a syntax check by setting helo_accept_junk_hosts to match the broken
32782 hosts that send invalid commands.
32783
32784 The amount of disk space available is checked whenever SIZE is received on a
32785 MAIL command, independently of whether message_size_limit or check_spool_space
32786 is configured, unless smtp_check_spool_space is set false. A temporary error is
32787 given if there is not enough space. If check_spool_space is set, the check is
32788 for that amount of space plus the value given with SIZE, that is, it checks
32789 that the addition of the incoming message will not reduce the space below the
32790 threshold.
32791
32792 When a message is successfully received, Exim includes the local message id in
32793 its response to the final "." that terminates the data. If the remote host logs
32794 this text it can help with tracing what has happened to a message.
32795
32796 The Exim daemon can limit the number of simultaneous incoming connections it is
32797 prepared to handle (see the smtp_accept_max option). It can also limit the
32798 number of simultaneous incoming connections from a single remote host (see the
32799 smtp_accept_max_per_host option). Additional connection attempts are rejected
32800 using the SMTP temporary error code 421.
32801
32802 The Exim daemon does not rely on the SIGCHLD signal to detect when a subprocess
32803 has finished, as this can get lost at busy times. Instead, it looks for
32804 completed subprocesses every time it wakes up. Provided there are other things
32805 happening (new incoming calls, starts of queue runs), completed processes will
32806 be noticed and tidied away. On very quiet systems you may sometimes see a
32807 "defunct" Exim process hanging about. This is not a problem; it will be noticed
32808 when the daemon next wakes up.
32809
32810 When running as a daemon, Exim can reserve some SMTP slots for specific hosts,
32811 and can also be set up to reject SMTP calls from non-reserved hosts at times of
32812 high system load - for details see the smtp_accept_reserve, smtp_load_reserve,
32813 and smtp_reserve_hosts options. The load check applies in both the daemon and
32814 inetd cases.
32815
32816 Exim normally starts a delivery process for each message received, though this
32817 can be varied by means of the -odq command line option and the queue_only,
32818 queue_only_file, and queue_only_load options. The number of simultaneously
32819 running delivery processes started in this way from SMTP input can be limited
32820 by the smtp_accept_queue and smtp_accept_queue_per_connection options. When
32821 either limit is reached, subsequently received messages are just put on the
32822 input queue without starting a delivery process.
32823
32824 The controls that involve counts of incoming SMTP calls (smtp_accept_max,
32825 smtp_accept_queue, smtp_accept_reserve) are not available when Exim is started
32826 up from the inetd daemon, because in that case each connection is handled by an
32827 entirely independent Exim process. Control by load average is, however,
32828 available with inetd.
32829
32830 Exim can be configured to verify addresses in incoming SMTP commands as they
32831 are received. See chapter 43 for details. It can also be configured to rewrite
32832 addresses at this time - before any syntax checking is done. See section 31.9.
32833
32834 Exim can also be configured to limit the rate at which a client host submits
32835 MAIL and RCPT commands in a single SMTP session. See the smtp_ratelimit_hosts
32836 option.
32837
32838
32839 48.4 Unrecognized SMTP commands
32840 -------------------------------
32841
32842 If Exim receives more than smtp_max_unknown_commands unrecognized SMTP commands
32843 during a single SMTP connection, it drops the connection after sending the
32844 error response to the last command. The default value for
32845 smtp_max_unknown_commands is 3. This is a defence against some kinds of abuse
32846 that subvert web servers into making connections to SMTP ports; in these
32847 circumstances, a number of non-SMTP lines are sent first.
32848
32849
32850 48.5 Syntax and protocol errors in SMTP commands
32851 ------------------------------------------------
32852
32853 A syntax error is detected if an SMTP command is recognized, but there is
32854 something syntactically wrong with its data, for example, a malformed email
32855 address in a RCPT command. Protocol errors include invalid command sequencing
32856 such as RCPT before MAIL. If Exim receives more than smtp_max_synprot_errors
32857 such commands during a single SMTP connection, it drops the connection after
32858 sending the error response to the last command. The default value for
32859 smtp_max_synprot_errors is 3. This is a defence against broken clients that
32860 loop sending bad commands (yes, it has been seen).
32861
32862
32863 48.6 Use of non-mail SMTP commands
32864 ----------------------------------
32865
32866 The "non-mail" SMTP commands are those other than MAIL, RCPT, and DATA. Exim
32867 counts such commands, and drops the connection if there are too many of them in
32868 a single SMTP session. This action catches some denial-of-service attempts and
32869 things like repeated failing AUTHs, or a mad client looping sending EHLO. The
32870 global option smtp_accept_max_nonmail defines what "too many" means. Its
32871 default value is 10.
32872
32873 When a new message is expected, one occurrence of RSET is not counted. This
32874 allows a client to send one RSET between messages (this is not necessary, but
32875 some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO,
32876 and one occurrence of STARTTLS between messages. After starting up a TLS
32877 session, another EHLO is expected, and so it too is not counted.
32878
32879 The first occurrence of AUTH in a connection, or immediately following STARTTLS
32880 is also not counted. Otherwise, all commands other than MAIL, RCPT, DATA, and
32881 QUIT are counted.
32882
32883 You can control which hosts are subject to the limit set by
32884 smtp_accept_max_nonmail by setting smtp_accept_max_nonmail_hosts. The default
32885 value is "*", which makes the limit apply to all hosts. This option means that
32886 you can exclude any specific badly-behaved hosts that you have to live with.
32887
32888
32889 48.7 The VRFY and EXPN commands
32890 -------------------------------
32891
32892 When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the
32893 ACL specified by acl_smtp_vrfy or acl_smtp_expn (as appropriate) in order to
32894 decide whether the command should be accepted or not.
32895
32896 When no ACL is defined for VRFY, or if it rejects without setting an explicit
32897 response code, the command is accepted (with a 252 SMTP response code) in order
32898 to support awkward clients that do a VRFY before every RCPT. When VRFY is
32899 accepted, it runs exactly the same code as when Exim is called with the -bv
32900 option, and returns 250/451/550 SMTP response codes.
32901
32902 If no ACL for EXPN is defined, the command is rejected. When EXPN is accepted,
32903 a single-level expansion of the address is done. EXPN is treated as an "address
32904 test" (similar to the -bt option) rather than a verification (the -bv option).
32905 If an unqualified local part is given as the argument to EXPN, it is qualified
32906 with qualify_domain. Rejections of VRFY and EXPN commands are logged on the
32907 main and reject logs, and VRFY verification failures are logged on the main log
32908 for consistency with RCPT failures.
32909
32910
32911 48.8 The ETRN command
32912 ---------------------
32913
32914 RFC 1985 describes an SMTP command called ETRN that is designed to overcome the
32915 security problems of the TURN command (which has fallen into disuse). When Exim
32916 receives an ETRN command on a TCP/IP connection, it runs the ACL specified by
32917 acl_smtp_etrn in order to decide whether the command should be accepted or not.
32918 If no ACL is defined, the command is rejected.
32919
32920 The ETRN command is concerned with "releasing" messages that are awaiting
32921 delivery to certain hosts. As Exim does not organize its message queue by host,
32922 the only form of ETRN that is supported by default is the one where the text
32923 starts with the "#" prefix, in which case the remainder of the text is specific
32924 to the SMTP server. A valid ETRN command causes a run of Exim with the -R
32925 option to happen, with the remainder of the ETRN text as its argument. For
32926 example,
32927
32928 ETRN #brigadoon
32929
32930 runs the command
32931
32932 exim -R brigadoon
32933
32934 which causes a delivery attempt on all messages with undelivered addresses
32935 containing the text "brigadoon". When smtp_etrn_serialize is set (the default),
32936 Exim prevents the simultaneous execution of more than one queue run for the
32937 same argument string as a result of an ETRN command. This stops a misbehaving
32938 client from starting more than one queue runner at once.
32939
32940 Exim implements the serialization by means of a hints database in which a
32941 record is written whenever a process is started by ETRN, and deleted when the
32942 process completes. However, Exim does not keep the SMTP session waiting for the
32943 ETRN process to complete. Once ETRN is accepted, the client is sent a "success"
32944 return code. Obviously there is scope for hints records to get left lying
32945 around if there is a system or program crash. To guard against this, Exim
32946 ignores any records that are more than six hours old.
32947
32948 For more control over what ETRN does, the smtp_etrn_command option can used.
32949 This specifies a command that is run whenever ETRN is received, whatever the
32950 form of its argument. For example:
32951
32952 smtp_etrn_command = /etc/etrn_command $domain \
32953 $sender_host_address
32954
32955 The string is split up into arguments which are independently expanded. The
32956 expansion variable $domain is set to the argument of the ETRN command, and no
32957 syntax checking is done on the contents of this argument. Exim does not wait
32958 for the command to complete, so its status code is not checked. Exim runs under
32959 its own uid and gid when receiving incoming SMTP, so it is not possible for it
32960 to change them before running the command.
32961
32962
32963 48.9 Incoming local SMTP
32964 ------------------------
32965
32966 Some user agents use SMTP to pass messages to their local MTA using the
32967 standard input and output, as opposed to passing the envelope on the command
32968 line and writing the message to the standard input. This is supported by the
32969 -bs option. This form of SMTP is handled in the same way as incoming messages
32970 over TCP/IP (including the use of ACLs), except that the envelope sender given
32971 in a MAIL command is ignored unless the caller is trusted. In an ACL you can
32972 detect this form of SMTP input by testing for an empty host identification. It
32973 is common to have this as the first line in the ACL that runs for RCPT
32974 commands:
32975
32976 accept hosts = :
32977
32978 This accepts SMTP messages from local processes without doing any other tests.
32979
32980
32981 48.10 Outgoing batched SMTP
32982 ---------------------------
32983
32984 Both the appendfile and pipe transports can be used for handling batched SMTP.
32985 Each has an option called use_bsmtp which causes messages to be output in BSMTP
32986 format. No SMTP responses are possible for this form of delivery. All it is
32987 doing is using SMTP commands as a way of transmitting the envelope along with
32988 the message.
32989
32990 The message is written to the file or pipe preceded by the SMTP commands MAIL
32991 and RCPT, and followed by a line containing a single dot. Lines in the message
32992 that start with a dot have an extra dot added. The SMTP command HELO is not
32993 normally used. If it is required, the message_prefix option can be used to
32994 specify it.
32995
32996 Because appendfile and pipe are both local transports, they accept only one
32997 recipient address at a time by default. However, you can arrange for them to
32998 handle several addresses at once by setting the batch_max option. When this is
32999 done for BSMTP, messages may contain multiple RCPT commands. See chapter 25 for
33000 more details.
33001
33002 When one or more addresses are routed to a BSMTP transport by a router that
33003 sets up a host list, the name of the first host on the list is available to the
33004 transport in the variable $host. Here is an example of such a transport and
33005 router:
33006
33007 begin routers
33008 route_append:
33009 driver = manualroute
33010 transport = smtp_appendfile
33011 route_list = domain.example batch.host.example
33012
33013 begin transports
33014 smtp_appendfile:
33015 driver = appendfile
33016 directory = /var/bsmtp/$host
33017 batch_max = 1000
33018 use_bsmtp
33019 user = exim
33020
33021 This causes messages addressed to domain.example to be written in BSMTP format
33022 to /var/bsmtp/batch.host.example, with only a single copy of each message
33023 (unless there are more than 1000 recipients).
33024
33025
33026 48.11 Incoming batched SMTP
33027 ---------------------------
33028
33029 The -bS command line option causes Exim to accept one or more messages by
33030 reading SMTP on the standard input, but to generate no responses. If the caller
33031 is trusted, the senders in the MAIL commands are believed; otherwise the sender
33032 is always the caller of Exim. Unqualified senders and receivers are not
33033 rejected (there seems little point) but instead just get qualified. HELO and
33034 EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act as NOOP; QUIT quits.
33035
33036 Minimal policy checking is done for BSMTP input. Only the non-SMTP ACL is run
33037 in the same way as for non-SMTP local input.
33038
33039 If an error is detected while reading a message, including a missing "." at the
33040 end, Exim gives up immediately. It writes details of the error to the standard
33041 output in a stylized way that the calling program should be able to make some
33042 use of automatically, for example:
33043
33044 554 Unexpected end of file
33045 Transaction started in line 10
33046 Error detected in line 14
33047
33048 It writes a more verbose version, for human consumption, to the standard error
33049 file, for example:
33050
33051 An error was detected while processing a file of BSMTP input.
33052 The error message was:
33053
33054 501 '>' missing at end of address
33055
33056 The SMTP transaction started in line 10.
33057 The error was detected in line 12.
33058 The SMTP command at fault was:
33059
33060 rcpt to:<malformed@in.com.plete
33061
33062 1 previous message was successfully processed.
33063 The rest of the batch was abandoned.
33064
33065 The return code from Exim is zero only if there were no errors. It is 1 if some
33066 messages were accepted before an error was detected, and 2 if no messages were
33067 accepted.
33068
33069
33070
33071 ===============================================================================
33072 49. CUSTOMIZING BOUNCE AND WARNING MESSAGES
33073
33074 When a message fails to be delivered, or remains in the queue for more than a
33075 configured amount of time, Exim sends a message to the original sender, or to
33076 an alternative configured address. The text of these messages is built into the
33077 code of Exim, but it is possible to change it, either by adding a single
33078 string, or by replacing each of the paragraphs by text supplied in a file.
33079
33080 The From: and To: header lines are automatically generated; you can cause a
33081 Reply-To: line to be added by setting the errors_reply_to option. Exim also
33082 adds the line
33083
33084 Auto-Submitted: auto-generated
33085
33086 to all warning and bounce messages,
33087
33088
33089 49.1 Customizing bounce messages
33090 --------------------------------
33091
33092 If bounce_message_text is set, its contents are included in the default message
33093 immediately after "This message was created automatically by mail delivery
33094 software." The string is not expanded. It is not used if bounce_message_file is
33095 set.
33096
33097 When bounce_message_file is set, it must point to a template file for
33098 constructing error messages. The file consists of a series of text items,
33099 separated by lines consisting of exactly four asterisks. If the file cannot be
33100 opened, default text is used and a message is written to the main and panic
33101 logs. If any text item in the file is empty, default text is used for that
33102 item.
33103
33104 Each item of text that is read from the file is expanded, and there are two
33105 expansion variables which can be of use here: $bounce_recipient is set to the
33106 recipient of an error message while it is being created, and
33107 $bounce_return_size_limit contains the value of the return_size_limit option,
33108 rounded to a whole number.
33109
33110 The items must appear in the file in the following order:
33111
33112 * The first item is included in the headers, and should include at least a
33113 Subject: header. Exim does not check the syntax of these headers.
33114
33115 * The second item forms the start of the error message. After it, Exim lists
33116 the failing addresses with their error messages.
33117
33118 * The third item is used to introduce any text from pipe transports that is
33119 to be returned to the sender. It is omitted if there is no such text.
33120
33121 * The fourth, fifth and sixth items will be ignored and may be empty. The
33122 fields exist for back-compatibility
33123
33124 The default state (bounce_message_file unset) is equivalent to the following
33125 file, in which the sixth item is empty. The Subject: and some other lines have
33126 been split in order to fit them on the page:
33127
33128 Subject: Mail delivery failed
33129 ${if eq{$sender_address}{$bounce_recipient}
33130 {: returning message to sender}}
33131 ****
33132 This message was created automatically by mail delivery software.
33133
33134 A message ${if eq{$sender_address}{$bounce_recipient}
33135 {that you sent }{sent by
33136
33137 <$sender_address>
33138
33139 }}could not be delivered to all of its recipients.
33140 This is a permanent error. The following address(es) failed:
33141 ****
33142 The following text was generated during the delivery attempt(s):
33143 ****
33144 ------ This is a copy of the message, including all the headers.
33145 ------
33146 ****
33147 ------ The body of the message is $message_size characters long;
33148 only the first
33149 ------ $bounce_return_size_limit or so are included here.
33150 ****
33151
33152
33153 49.2 Customizing warning messages
33154 ---------------------------------
33155
33156 The option warn_message_file can be pointed at a template file for use when
33157 warnings about message delays are created. In this case there are only three
33158 text sections:
33159
33160 * The first item is included in the headers, and should include at least a
33161 Subject: header. Exim does not check the syntax of these headers.
33162
33163 * The second item forms the start of the warning message. After it, Exim
33164 lists the delayed addresses.
33165
33166 * The third item then ends the message.
33167
33168 The default state is equivalent to the following file, except that some lines
33169 have been split here, in order to fit them on the page:
33170
33171 Subject: Warning: message $message_exim_id delayed
33172 $warn_message_delay
33173 ****
33174 This message was created automatically by mail delivery software.
33175
33176 A message ${if eq{$sender_address}{$warn_message_recipients}
33177 {that you sent }{sent by
33178
33179 <$sender_address>
33180
33181 }}has not been delivered to all of its recipients after
33182 more than $warn_message_delay in the queue on $primary_hostname.
33183
33184 The message identifier is: $message_exim_id
33185 The subject of the message is: $h_subject
33186 The date of the message is: $h_date
33187
33188 The following address(es) have not yet been delivered:
33189 ****
33190 No action is required on your part. Delivery attempts will
33191 continue for some time, and this warning may be repeated at
33192 intervals if the message remains undelivered. Eventually the
33193 mail delivery software will give up, and when that happens,
33194 the message will be returned to you.
33195
33196 However, in the default state the subject and date lines are omitted if no
33197 appropriate headers exist. During the expansion of this file,
33198 $warn_message_delay is set to the delay time in one of the forms "<n> minutes"
33199 or "<n> hours", and $warn_message_recipients contains a list of recipients for
33200 the warning message. There may be more than one if there are multiple addresses
33201 with different errors_to settings on the routers that handled them.
33202
33203
33204
33205 ===============================================================================
33206 50. SOME COMMON CONFIGURATION SETTINGS
33207
33208 This chapter discusses some configuration settings that seem to be fairly
33209 common. More examples and discussion can be found in the Exim book.
33210
33211
33212 50.1 Sending mail to a smart host
33213 ---------------------------------
33214
33215 If you want to send all mail for non-local domains to a "smart host", you
33216 should replace the default dnslookup router with a router which does the
33217 routing explicitly:
33218
33219 send_to_smart_host:
33220 driver = manualroute
33221 route_list = !+local_domains smart.host.name
33222 transport = remote_smtp
33223
33224 You can use the smart host's IP address instead of the name if you wish. If you
33225 are using Exim only to submit messages to a smart host, and not for receiving
33226 incoming messages, you can arrange for it to do the submission synchronously by
33227 setting the mua_wrapper option (see chapter 51).
33228
33229
33230 50.2 Using Exim to handle mailing lists
33231 ---------------------------------------
33232
33233 Exim can be used to run simple mailing lists, but for large and/or complicated
33234 requirements, the use of additional specialized mailing list software such as
33235 Majordomo or Mailman is recommended.
33236
33237 The redirect router can be used to handle mailing lists where each list is
33238 maintained in a separate file, which can therefore be managed by an independent
33239 manager. The domains router option can be used to run these lists in a separate
33240 domain from normal mail. For example:
33241
33242 lists:
33243 driver = redirect
33244 domains = lists.example
33245 file = /usr/lists/$local_part
33246 forbid_pipe
33247 forbid_file
33248 errors_to = $local_part-request@lists.example
33249 no_more
33250
33251 This router is skipped for domains other than lists.example. For addresses in
33252 that domain, it looks for a file that matches the local part. If there is no
33253 such file, the router declines, but because no_more is set, no subsequent
33254 routers are tried, and so the whole delivery fails.
33255
33256 The forbid_pipe and forbid_file options prevent a local part from being
33257 expanded into a filename or a pipe delivery, which is usually inappropriate in
33258 a mailing list.
33259
33260 The errors_to option specifies that any delivery errors caused by addresses
33261 taken from a mailing list are to be sent to the given address rather than the
33262 original sender of the message. However, before acting on this, Exim verifies
33263 the error address, and ignores it if verification fails.
33264
33265 For example, using the configuration above, mail sent to dicts@lists.example is
33266 passed on to those addresses contained in /usr/lists/dicts, with error reports
33267 directed to dicts-request@lists.example, provided that this address can be
33268 verified. There could be a file called /usr/lists/dicts-request containing the
33269 address(es) of this particular list's manager(s), but other approaches, such as
33270 setting up an earlier router (possibly using the local_part_prefix or
33271 local_part_suffix options) to handle addresses of the form owner-xxx or xxx-
33272 request, are also possible.
33273
33274
33275 50.3 Syntax errors in mailing lists
33276 -----------------------------------
33277
33278 If an entry in redirection data contains a syntax error, Exim normally defers
33279 delivery of the original address. That means that a syntax error in a mailing
33280 list holds up all deliveries to the list. This may not be appropriate when a
33281 list is being maintained automatically from data supplied by users, and the
33282 addresses are not rigorously checked.
33283
33284 If the skip_syntax_errors option is set, the redirect router just skips entries
33285 that fail to parse, noting the incident in the log. If in addition
33286 syntax_errors_to is set to a verifiable address, a message is sent to it
33287 whenever a broken address is skipped. It is usually appropriate to set
33288 syntax_errors_to to the same address as errors_to.
33289
33290
33291 50.4 Re-expansion of mailing lists
33292 ----------------------------------
33293
33294 Exim remembers every individual address to which a message has been delivered,
33295 in order to avoid duplication, but it normally stores only the original
33296 recipient addresses with a message. If all the deliveries to a mailing list
33297 cannot be done at the first attempt, the mailing list is re-expanded when the
33298 delivery is next tried. This means that alterations to the list are taken into
33299 account at each delivery attempt, so addresses that have been added to the list
33300 since the message arrived will therefore receive a copy of the message, even
33301 though it pre-dates their subscription.
33302
33303 If this behaviour is felt to be undesirable, the one_time option can be set on
33304 the redirect router. If this is done, any addresses generated by the router
33305 that fail to deliver at the first attempt are added to the message as "top
33306 level" addresses, and the parent address that generated them is marked
33307 "delivered". Thus, expansion of the mailing list does not happen again at the
33308 subsequent delivery attempts. The disadvantage of this is that if any of the
33309 failing addresses are incorrect, correcting them in the file has no effect on
33310 pre-existing messages.
33311
33312 The original top-level address is remembered with each of the generated
33313 addresses, and is output in any log messages. However, any intermediate parent
33314 addresses are not recorded. This makes a difference to the log only if the
33315 all_parents selector is set, but for mailing lists there is normally only one
33316 level of expansion anyway.
33317
33318
33319 50.5 Closed mailing lists
33320 -------------------------
33321
33322 The examples so far have assumed open mailing lists, to which anybody may send
33323 mail. It is also possible to set up closed lists, where mail is accepted from
33324 specified senders only. This is done by making use of the generic senders
33325 option to restrict the router that handles the list.
33326
33327 The following example uses the same file as a list of recipients and as a list
33328 of permitted senders. It requires three routers:
33329
33330 lists_request:
33331 driver = redirect
33332 domains = lists.example
33333 local_part_suffix = -request
33334 file = /usr/lists/$local_part$local_part_suffix
33335 no_more
33336
33337 lists_post:
33338 driver = redirect
33339 domains = lists.example
33340 senders = ${if exists {/usr/lists/$local_part}\
33341 {lsearch;/usr/lists/$local_part}{*}}
33342 file = /usr/lists/$local_part
33343 forbid_pipe
33344 forbid_file
33345 errors_to = $local_part-request@lists.example
33346 no_more
33347
33348 lists_closed:
33349 driver = redirect
33350 domains = lists.example
33351 allow_fail
33352 data = :fail: $local_part@lists.example is a closed mailing list
33353
33354 All three routers have the same domains setting, so for any other domains, they
33355 are all skipped. The first router runs only if the local part ends in -request.
33356 It handles messages to the list manager(s) by means of an open mailing list.
33357
33358 The second router runs only if the senders precondition is satisfied. It checks
33359 for the existence of a list that corresponds to the local part, and then checks
33360 that the sender is on the list by means of a linear search. It is necessary to
33361 check for the existence of the file before trying to search it, because
33362 otherwise Exim thinks there is a configuration error. If the file does not
33363 exist, the expansion of senders is *, which matches all senders. This means
33364 that the router runs, but because there is no list, declines, and no_more
33365 ensures that no further routers are run. The address fails with an "unrouteable
33366 address" error.
33367
33368 The third router runs only if the second router is skipped, which happens when
33369 a mailing list exists, but the sender is not on it. This router forcibly fails
33370 the address, giving a suitable error message.
33371
33372
33373 50.6 Variable Envelope Return Paths (VERP)
33374 ------------------------------------------
33375
33376 Variable Envelope Return Paths - see https://cr.yp.to/proto/verp.txt - are a
33377 way of helping mailing list administrators discover which subscription address
33378 is the cause of a particular delivery failure. The idea is to encode the
33379 original recipient address in the outgoing envelope sender address, so that if
33380 the message is forwarded by another host and then subsequently bounces, the
33381 original recipient can be extracted from the recipient address of the bounce.
33382
33383 Envelope sender addresses can be modified by Exim using two different
33384 facilities: the errors_to option on a router (as shown in previous mailing list
33385 examples), or the return_path option on a transport. The second of these is
33386 effective only if the message is successfully delivered to another host; it is
33387 not used for errors detected on the local host (see the description of
33388 return_path in chapter 24). Here is an example of the use of return_path to
33389 implement VERP on an smtp transport:
33390
33391 verp_smtp:
33392 driver = smtp
33393 max_rcpt = 1
33394 return_path = \
33395 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
33396 {$1-request+$local_part=$domain@your.dom.example}fail}
33397
33398 This has the effect of rewriting the return path (envelope sender) on outgoing
33399 SMTP messages, if the local part of the original return path ends in
33400 "-request", and the domain is your.dom.example. The rewriting inserts the local
33401 part and domain of the recipient into the return path. Suppose, for example,
33402 that a message whose return path has been set to
33403 somelist-request@your.dom.example is sent to subscriber@other.dom.example. In
33404 the transport, the return path is rewritten as
33405
33406 somelist-request+subscriber=other.dom.example@your.dom.example
33407
33408 For this to work, you must tell Exim to send multiple copies of messages that
33409 have more than one recipient, so that each copy has just one recipient. This is
33410 achieved by setting max_rcpt to 1. Without this, a single copy of a message
33411 might be sent to several different recipients in the same domain, in which case
33412 $local_part is not available in the transport, because it is not unique.
33413
33414 Unless your host is doing nothing but mailing list deliveries, you should
33415 probably use a separate transport for the VERP deliveries, so as not to use
33416 extra resources in making one-per-recipient copies for other deliveries. This
33417 can easily be done by expanding the transport option in the router:
33418
33419 dnslookup:
33420 driver = dnslookup
33421 domains = ! +local_domains
33422 transport = \
33423 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
33424 {verp_smtp}{remote_smtp}}
33425 no_more
33426
33427 If you want to change the return path using errors_to in a router instead of
33428 using return_path in the transport, you need to set errors_to on all routers
33429 that handle mailing list addresses. This will ensure that all delivery errors,
33430 including those detected on the local host, are sent to the VERP address.
33431
33432 On a host that does no local deliveries and has no manual routing, only the
33433 dnslookup router needs to be changed. A special transport is not needed for
33434 SMTP deliveries. Every mailing list recipient has its own return path value,
33435 and so Exim must hand them to the transport one at a time. Here is an example
33436 of a dnslookup router that implements VERP:
33437
33438 verp_dnslookup:
33439 driver = dnslookup
33440 domains = ! +local_domains
33441 transport = remote_smtp
33442 errors_to = \
33443 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
33444 {$1-request+$local_part=$domain@your.dom.example}fail}
33445 no_more
33446
33447 Before you start sending out messages with VERPed return paths, you must also
33448 configure Exim to accept the bounce messages that come back to those paths.
33449 Typically this is done by setting a local_part_suffix option for a router, and
33450 using this to route the messages to wherever you want to handle them.
33451
33452 The overhead incurred in using VERP depends very much on the size of the
33453 message, the number of recipient addresses that resolve to the same remote
33454 host, and the speed of the connection over which the message is being sent. If
33455 a lot of addresses resolve to the same host and the connection is slow, sending
33456 a separate copy of the message for each address may take substantially longer
33457 than sending a single copy with many recipients (for which VERP cannot be
33458 used).
33459
33460
33461 50.7 Virtual domains
33462 --------------------
33463
33464 The phrase virtual domain is unfortunately used with two rather different
33465 meanings:
33466
33467 * A domain for which there are no real mailboxes; all valid local parts are
33468 aliases for other email addresses. Common examples are organizational
33469 top-level domains and "vanity" domains.
33470
33471 * One of a number of independent domains that are all handled by the same
33472 host, with mailboxes on that host, but where the mailbox owners do not
33473 necessarily have login accounts on that host.
33474
33475 The first usage is probably more common, and does seem more "virtual" than the
33476 second. This kind of domain can be handled in Exim with a straightforward
33477 aliasing router. One approach is to create a separate alias file for each
33478 virtual domain. Exim can test for the existence of the alias file to determine
33479 whether the domain exists. The dsearch lookup type is useful here, leading to a
33480 router of this form:
33481
33482 virtual:
33483 driver = redirect
33484 domains = dsearch;/etc/mail/virtual
33485 data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}}
33486 no_more
33487
33488 The domains option specifies that the router is to be skipped, unless there is
33489 a file in the /etc/mail/virtual directory whose name is the same as the domain
33490 that is being processed. When the router runs, it looks up the local part in
33491 the file to find a new address (or list of addresses). The no_more setting
33492 ensures that if the lookup fails (leading to data being an empty string), Exim
33493 gives up on the address without trying any subsequent routers.
33494
33495 This one router can handle all the virtual domains because the alias filenames
33496 follow a fixed pattern. Permissions can be arranged so that appropriate people
33497 can edit the different alias files. A successful aliasing operation results in
33498 a new envelope recipient address, which is then routed from scratch.
33499
33500 The other kind of "virtual" domain can also be handled in a straightforward
33501 way. One approach is to create a file for each domain containing a list of
33502 valid local parts, and use it in a router like this:
33503
33504 my_domains:
33505 driver = accept
33506 domains = dsearch;/etc/mail/domains
33507 local_parts = lsearch;/etc/mail/domains/$domain
33508 transport = my_mailboxes
33509
33510 The address is accepted if there is a file for the domain, and the local part
33511 can be found in the file. The domains option is used to check for the file's
33512 existence because domains is tested before the local_parts option (see section
33513 3.12). You cannot use require_files, because that option is tested after
33514 local_parts. The transport is as follows:
33515
33516 my_mailboxes:
33517 driver = appendfile
33518 file = /var/mail/$domain/$local_part
33519 user = mail
33520
33521 This uses a directory of mailboxes for each domain. The user setting is
33522 required, to specify which uid is to be used for writing to the mailboxes.
33523
33524 The configuration shown here is just one example of how you might support this
33525 requirement. There are many other ways this kind of configuration can be set
33526 up, for example, by using a database instead of separate files to hold all the
33527 information about the domains.
33528
33529
33530 50.8 Multiple user mailboxes
33531 ----------------------------
33532
33533 Heavy email users often want to operate with multiple mailboxes, into which
33534 incoming mail is automatically sorted. A popular way of handling this is to
33535 allow users to use multiple sender addresses, so that replies can easily be
33536 identified. Users are permitted to add prefixes or suffixes to their local
33537 parts for this purpose. The wildcard facility of the generic router options
33538 local_part_prefix and local_part_suffix can be used for this. For example,
33539 consider this router:
33540
33541 userforward:
33542 driver = redirect
33543 check_local_user
33544 file = $home/.forward
33545 local_part_suffix = -*
33546 local_part_suffix_optional
33547 allow_filter
33548
33549 It runs a user's .forward file for all local parts of the form username-*.
33550 Within the filter file the user can distinguish different cases by testing the
33551 variable $local_part_suffix. For example:
33552
33553 if $local_part_suffix contains -special then
33554 save /home/$local_part/Mail/special
33555 endif
33556
33557 If the filter file does not exist, or does not deal with such addresses, they
33558 fall through to subsequent routers, and, assuming no subsequent use of the
33559 local_part_suffix option is made, they presumably fail. Thus, users have
33560 control over which suffixes are valid.
33561
33562 Alternatively, a suffix can be used to trigger the use of a different .forward
33563 file - which is the way a similar facility is implemented in another MTA:
33564
33565 userforward:
33566 driver = redirect
33567 check_local_user
33568 file = $home/.forward$local_part_suffix
33569 local_part_suffix = -*
33570 local_part_suffix_optional
33571 allow_filter
33572
33573 If there is no suffix, .forward is used; if the suffix is -special, for
33574 example, .forward-special is used. Once again, if the appropriate file does not
33575 exist, or does not deal with the address, it is passed on to subsequent
33576 routers, which could, if required, look for an unqualified .forward file to use
33577 as a default.
33578
33579
33580 50.9 Simplified vacation processing
33581 -----------------------------------
33582
33583 The traditional way of running the vacation program is for a user to set up a
33584 pipe command in a .forward file (see section 22.6 for syntax details). This is
33585 prone to error by inexperienced users. There are two features of Exim that can
33586 be used to make this process simpler for users:
33587
33588 * A local part prefix such as "vacation-" can be specified on a router which
33589 can cause the message to be delivered directly to the vacation program, or
33590 alternatively can use Exim's autoreply transport. The contents of a user's
33591 .forward file are then much simpler. For example:
33592
33593 spqr, vacation-spqr
33594
33595 * The require_files generic router option can be used to trigger a vacation
33596 delivery by checking for the existence of a certain file in the user's home
33597 directory. The unseen generic option should also be used, to ensure that
33598 the original delivery also proceeds. In this case, all the user has to do
33599 is to create a file called, say, .vacation, containing a vacation message.
33600
33601 Another advantage of both these methods is that they both work even when the
33602 use of arbitrary pipes by users is locked out.
33603
33604
33605 50.10 Taking copies of mail
33606 ---------------------------
33607
33608 Some installations have policies that require archive copies of all messages to
33609 be made. A single copy of each message can easily be taken by an appropriate
33610 command in a system filter, which could, for example, use a different file for
33611 each day's messages.
33612
33613 There is also a shadow transport mechanism that can be used to take copies of
33614 messages that are successfully delivered by local transports, one copy per
33615 delivery. This could be used, inter alia, to implement automatic notification
33616 of delivery by sites that insist on doing such things.
33617
33618
33619 50.11 Intermittently connected hosts
33620 ------------------------------------
33621
33622 It has become quite common (because it is cheaper) for hosts to connect to the
33623 Internet periodically rather than remain connected all the time. The normal
33624 arrangement is that mail for such hosts accumulates on a system that is
33625 permanently connected.
33626
33627 Exim was designed for use on permanently connected hosts, and so it is not
33628 particularly well-suited to use in an intermittently connected environment.
33629 Nevertheless there are some features that can be used.
33630
33631
33632 50.12 Exim on the upstream server host
33633 --------------------------------------
33634
33635 It is tempting to arrange for incoming mail for the intermittently connected
33636 host to remain in Exim's queue until the client connects. However, this
33637 approach does not scale very well. Two different kinds of waiting message are
33638 being mixed up in the same queue - those that cannot be delivered because of
33639 some temporary problem, and those that are waiting for their destination host
33640 to connect. This makes it hard to manage the queue, as well as wasting
33641 resources, because each queue runner scans the entire queue.
33642
33643 A better approach is to separate off those messages that are waiting for an
33644 intermittently connected host. This can be done by delivering these messages
33645 into local files in batch SMTP, "mailstore", or other envelope-preserving
33646 format, from where they are transmitted by other software when their
33647 destination connects. This makes it easy to collect all the mail for one host
33648 in a single directory, and to apply local timeout rules on a per-message basis
33649 if required.
33650
33651 On a very small scale, leaving the mail on Exim's queue can be made to work. If
33652 you are doing this, you should configure Exim with a long retry period for the
33653 intermittent host. For example:
33654
33655 cheshire.wonderland.fict.example * F,5d,24h
33656
33657 This stops a lot of failed delivery attempts from occurring, but Exim remembers
33658 which messages it has queued up for that host. Once the intermittent host comes
33659 online, forcing delivery of one message (either by using the -M or -R options,
33660 or by using the ETRN SMTP command (see section 48.8) causes all the queued up
33661 messages to be delivered, often down a single SMTP connection. While the host
33662 remains connected, any new messages get delivered immediately.
33663
33664 If the connecting hosts do not have fixed IP addresses, that is, if a host is
33665 issued with a different IP address each time it connects, Exim's retry
33666 mechanisms on the holding host get confused, because the IP address is normally
33667 used as part of the key string for holding retry information. This can be
33668 avoided by unsetting retry_include_ip_address on the smtp transport. Since this
33669 has disadvantages for permanently connected hosts, it is best to arrange a
33670 separate transport for the intermittently connected ones.
33671
33672
33673 50.13 Exim on the intermittently connected client host
33674 ------------------------------------------------------
33675
33676 The value of smtp_accept_queue_per_connection should probably be increased, or
33677 even set to zero (that is, disabled) on the intermittently connected host, so
33678 that all incoming messages down a single connection get delivered immediately.
33679
33680 Mail waiting to be sent from an intermittently connected host will probably not
33681 have been routed, because without a connection DNS lookups are not possible.
33682 This means that if a normal queue run is done at connection time, each message
33683 is likely to be sent in a separate SMTP session. This can be avoided by
33684 starting the queue run with a command line option beginning with -qq instead of
33685 -q. In this case, the queue is scanned twice. In the first pass, routing is
33686 done but no deliveries take place. The second pass is a normal queue run; since
33687 all the messages have been previously routed, those destined for the same host
33688 are likely to get sent as multiple deliveries in a single SMTP connection.
33689
33690
33691
33692 ===============================================================================
33693 51. USING EXIM AS A NON-QUEUEING CLIENT
33694
33695 On a personal computer, it is a common requirement for all email to be sent to
33696 a "smart host". There are plenty of MUAs that can be configured to operate that
33697 way, for all the popular operating systems. However, there are some MUAs for
33698 Unix-like systems that cannot be so configured: they submit messages using the
33699 command line interface of /usr/sbin/sendmail. Furthermore, utility programs
33700 such as cron submit messages this way.
33701
33702 If the personal computer runs continuously, there is no problem, because it can
33703 run a conventional MTA that handles delivery to the smart host, and deal with
33704 any delays via its queueing mechanism. However, if the computer does not run
33705 continuously or runs different operating systems at different times, queueing
33706 email is not desirable.
33707
33708 There is therefore a requirement for something that can provide the /usr/sbin/
33709 sendmail interface but deliver messages to a smart host without any queueing or
33710 retrying facilities. Furthermore, the delivery to the smart host should be
33711 synchronous, so that if it fails, the sending MUA is immediately informed. In
33712 other words, we want something that extends an MUA that submits to a local MTA
33713 via the command line so that it behaves like one that submits to a remote smart
33714 host using TCP/SMTP.
33715
33716 There are a number of applications (for example, there is one called ssmtp)
33717 that do this job. However, people have found them to be lacking in various
33718 ways. For instance, you might want to allow aliasing and forwarding to be done
33719 before sending a message to the smart host.
33720
33721 Exim already had the necessary infrastructure for doing this job. Just a few
33722 tweaks were needed to make it behave as required, though it is somewhat of an
33723 overkill to use a fully-featured MTA for this purpose.
33724
33725 There is a Boolean global option called mua_wrapper, defaulting false. Setting
33726 mua_wrapper true causes Exim to run in a special mode where it assumes that it
33727 is being used to "wrap" a command-line MUA in the manner just described. As
33728 well as setting mua_wrapper, you also need to provide a compatible router and
33729 transport configuration. Typically there will be just one router and one
33730 transport, sending everything to a smart host.
33731
33732 When run in MUA wrapping mode, the behaviour of Exim changes in the following
33733 ways:
33734
33735 * A daemon cannot be run, nor will Exim accept incoming messages from inetd.
33736 In other words, the only way to submit messages is via the command line.
33737
33738 * Each message is synchronously delivered as soon as it is received (-odi is
33739 assumed). All queueing options (queue_only, queue_smtp_domains, control in
33740 an ACL, etc.) are quietly ignored. The Exim reception process does not
33741 finish until the delivery attempt is complete. If the delivery is
33742 successful, a zero return code is given.
33743
33744 * Address redirection is permitted, but the final routing for all addresses
33745 must be to the same remote transport, and to the same list of hosts.
33746 Furthermore, the return address (envelope sender) must be the same for all
33747 recipients, as must any added or deleted header lines. In other words, it
33748 must be possible to deliver the message in a single SMTP transaction,
33749 however many recipients there are.
33750
33751 * If these conditions are not met, or if routing any address results in a
33752 failure or defer status, or if Exim is unable to deliver all the recipients
33753 successfully to one of the smart hosts, delivery of the entire message
33754 fails.
33755
33756 * Because no queueing is allowed, all failures are treated as permanent;
33757 there is no distinction between 4xx and 5xx SMTP response codes from the
33758 smart host. Furthermore, because only a single yes/no response can be given
33759 to the caller, it is not possible to deliver to some recipients and not
33760 others. If there is an error (temporary or permanent) for any recipient,
33761 all are failed.
33762
33763 * If more than one smart host is listed, Exim will try another host after a
33764 connection failure or a timeout, in the normal way. However, if this kind
33765 of failure happens for all the hosts, the delivery fails.
33766
33767 * When delivery fails, an error message is written to the standard error
33768 stream (as well as to Exim's log), and Exim exits to the caller with a
33769 return code value 1. The message is expunged from Exim's spool files. No
33770 bounce messages are ever generated.
33771
33772 * No retry data is maintained, and any retry rules are ignored.
33773
33774 * A number of Exim options are overridden: deliver_drop_privilege is forced
33775 true, max_rcpt in the smtp transport is forced to "unlimited",
33776 remote_max_parallel is forced to one, and fallback hosts are ignored.
33777
33778 The overall effect is that Exim makes a single synchronous attempt to deliver
33779 the message, failing if there is any kind of problem. Because no local
33780 deliveries are done and no daemon can be run, Exim does not need root
33781 privilege. It should be possible to run it setuid to exim instead of setuid to
33782 root. See section 55.3 for a general discussion about the advantages and
33783 disadvantages of running without root privilege.
33784
33785
33786
33787 ===============================================================================
33788 52. LOG FILES
33789
33790 Exim writes three different logs, referred to as the main log, the reject log,
33791 and the panic log:
33792
33793 * The main log records the arrival of each message and each delivery in a
33794 single line in each case. The format is as compact as possible, in an
33795 attempt to keep down the size of log files. Two-character flag sequences
33796 make it easy to pick out these lines. A number of other events are recorded
33797 in the main log. Some of them are optional, in which case the log_selector
33798 option controls whether they are included or not. A Perl script called
33799 eximstats, which does simple analysis of main log files, is provided in the
33800 Exim distribution (see section 53.7).
33801
33802 * The reject log records information from messages that are rejected as a
33803 result of a configuration option (that is, for policy reasons). The first
33804 line of each rejection is a copy of the line that is also written to the
33805 main log. Then, if the message's header has been read at the time the log
33806 is written, its contents are written to this log. Only the original header
33807 lines are available; header lines added by ACLs are not logged. You can use
33808 the reject log to check that your policy controls are working correctly; on
33809 a busy host this may be easier than scanning the main log for rejection
33810 messages. You can suppress the writing of the reject log by setting
33811 write_rejectlog false.
33812
33813 * When certain serious errors occur, Exim writes entries to its panic log. If
33814 the error is sufficiently disastrous, Exim bombs out afterwards. Panic log
33815 entries are usually written to the main log as well, but can get lost amid
33816 the mass of other entries. The panic log should be empty under normal
33817 circumstances. It is therefore a good idea to check it (or to have a cron
33818 script check it) regularly, in order to become aware of any problems. When
33819 Exim cannot open its panic log, it tries as a last resort to write to the
33820 system log (syslog). This is opened with LOG_PID+LOG_CONS and the facility
33821 code of LOG_MAIL. The message itself is written at priority LOG_CRIT.
33822
33823 Every log line starts with a timestamp, in the format shown in the following
33824 example. Note that many of the examples shown in this chapter are line-wrapped.
33825 In the log file, this would be all on one line:
33826
33827 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed
33828 by QUIT
33829
33830 By default, the timestamps are in the local timezone. There are two ways of
33831 changing this:
33832
33833 * You can set the timezone option to a different time zone; in particular, if
33834 you set
33835
33836 timezone = UTC
33837
33838 the timestamps will be in UTC (aka GMT).
33839
33840 * If you set log_timezone true, the time zone is added to the timestamp, for
33841 example:
33842
33843 2003-04-25 11:17:07 +0100 Start queue run: pid=12762
33844
33845 Exim does not include its process id in log lines by default, but you can
33846 request that it does so by specifying the "pid" log selector (see section 52.15
33847 ). When this is set, the process id is output, in square brackets, immediately
33848 after the time and date.
33849
33850
33851 52.1 Where the logs are written
33852 -------------------------------
33853
33854 The logs may be written to local files, or to syslog, or both. However, it
33855 should be noted that many syslog implementations use UDP as a transport, and
33856 are therefore unreliable in the sense that messages are not guaranteed to
33857 arrive at the loghost, nor is the ordering of messages necessarily maintained.
33858 It has also been reported that on large log files (tens of megabytes) you may
33859 need to tweak syslog to prevent it syncing the file with each write - on Linux
33860 this has been seen to make syslog take 90% plus of CPU time.
33861
33862 The destination for Exim's logs is configured by setting LOG_FILE_PATH in Local
33863 /Makefile or by setting log_file_path in the runtime configuration. This latter
33864 string is expanded, so it can contain, for example, references to the host
33865 name:
33866
33867 log_file_path = /var/log/$primary_hostname/exim_%slog
33868
33869 It is generally advisable, however, to set the string in Local/Makefile rather
33870 than at runtime, because then the setting is available right from the start of
33871 Exim's execution. Otherwise, if there's something it wants to log before it has
33872 read the configuration file (for example, an error in the configuration file)
33873 it will not use the path you want, and may not be able to log at all.
33874
33875 The value of LOG_FILE_PATH or log_file_path is a colon-separated list,
33876 currently limited to at most two items. This is one option where the facility
33877 for changing a list separator may not be used. The list must always be
33878 colon-separated. If an item in the list is "syslog" then syslog is used;
33879 otherwise the item must either be an absolute path, containing "%s" at the
33880 point where "main", "reject", or "panic" is to be inserted, or be empty,
33881 implying the use of a default path.
33882
33883 When Exim encounters an empty item in the list, it searches the list defined by
33884 LOG_FILE_PATH, and uses the first item it finds that is neither empty nor
33885 "syslog". This means that an empty item in log_file_path can be used to mean
33886 "use the path specified at build time". It no such item exists, log files are
33887 written in the log subdirectory of the spool directory. This is equivalent to
33888 the setting:
33889
33890 log_file_path = $spool_directory/log/%slog
33891
33892 If you do not specify anything at build time or runtime, or if you unset the
33893 option at runtime (i.e. "log_file_path = "), that is where the logs are
33894 written.
33895
33896 A log file path may also contain "%D" or "%M" if datestamped log filenames are
33897 in use - see section 52.3 below.
33898
33899 Here are some examples of possible settings:
33900
33901 LOG_FILE_PATH=syslog syslog only
33902 LOG_FILE_PATH=:syslog syslog and default path
33903 LOG_FILE_PATH=syslog : /usr/log/exim_%s syslog and specified path
33904 LOG_FILE_PATH=/usr/log/exim_%s specified path only
33905
33906 If there are more than two paths in the list, the first is used and a panic
33907 error is logged.
33908
33909
33910 52.2 Logging to local files that are periodically "cycled"
33911 ----------------------------------------------------------
33912
33913 Some operating systems provide centralized and standardized methods for cycling
33914 log files. For those that do not, a utility script called exicyclog is provided
33915 (see section 53.6). This renames and compresses the main and reject logs each
33916 time it is called. The maximum number of old logs to keep can be set. It is
33917 suggested this script is run as a daily cron job.
33918
33919 An Exim delivery process opens the main log when it first needs to write to it,
33920 and it keeps the file open in case subsequent entries are required - for
33921 example, if a number of different deliveries are being done for the same
33922 message. However, remote SMTP deliveries can take a long time, and this means
33923 that the file may be kept open long after it is renamed if exicyclog or
33924 something similar is being used to rename log files on a regular basis. To
33925 ensure that a switch of log files is noticed as soon as possible, Exim calls
33926 stat() on the main log's name before reusing an open file, and if the file does
33927 not exist, or its inode has changed, the old file is closed and Exim tries to
33928 open the main log from scratch. Thus, an old log file may remain open for quite
33929 some time, but no Exim processes should write to it once it has been renamed.
33930
33931
33932 52.3 Datestamped log files
33933 --------------------------
33934
33935 Instead of cycling the main and reject log files by renaming them periodically,
33936 some sites like to use files whose names contain a datestamp, for example,
33937 mainlog-20031225. The datestamp is in the form yyyymmdd or yyyymm. Exim has
33938 support for this way of working. It is enabled by setting the log_file_path
33939 option to a path that includes "%D" or "%M" at the point where the datestamp is
33940 required. For example:
33941
33942 log_file_path = /var/spool/exim/log/%slog-%D
33943 log_file_path = /var/log/exim-%s-%D.log
33944 log_file_path = /var/spool/exim/log/%D-%slog
33945 log_file_path = /var/log/exim/%s.%M
33946
33947 As before, "%s" is replaced by "main" or "reject"; the following are examples
33948 of names generated by the above examples:
33949
33950 /var/spool/exim/log/mainlog-20021225
33951 /var/log/exim-reject-20021225.log
33952 /var/spool/exim/log/20021225-mainlog
33953 /var/log/exim/main.200212
33954
33955 When this form of log file is specified, Exim automatically switches to new
33956 files at midnight. It does not make any attempt to compress old logs; you will
33957 need to write your own script if you require this. You should not run exicyclog
33958 with this form of logging.
33959
33960 The location of the panic log is also determined by log_file_path, but it is
33961 not datestamped, because rotation of the panic log does not make sense. When
33962 generating the name of the panic log, "%D" or "%M" are removed from the string.
33963 In addition, if it immediately follows a slash, a following non-alphanumeric
33964 character is removed; otherwise a preceding non-alphanumeric character is
33965 removed. Thus, the four examples above would give these panic log names:
33966
33967 /var/spool/exim/log/paniclog
33968 /var/log/exim-panic.log
33969 /var/spool/exim/log/paniclog
33970 /var/log/exim/panic
33971
33972
33973 52.4 Logging to syslog
33974 ----------------------
33975
33976 The use of syslog does not change what Exim logs or the format of its messages,
33977 except in one respect. If syslog_timestamp is set false, the timestamps on
33978 Exim's log lines are omitted when these lines are sent to syslog. Apart from
33979 that, the same strings are written to syslog as to log files. The syslog
33980 "facility" is set to LOG_MAIL, and the program name to "exim" by default, but
33981 you can change these by setting the syslog_facility and syslog_processname
33982 options, respectively. If Exim was compiled with SYSLOG_LOG_PID set in Local/
33983 Makefile (this is the default in src/EDITME), then, on systems that permit it
33984 (all except ULTRIX), the LOG_PID flag is set so that the syslog() call adds the
33985 pid as well as the time and host name to each line. The three log streams are
33986 mapped onto syslog priorities as follows:
33987
33988 * mainlog is mapped to LOG_INFO
33989
33990 * rejectlog is mapped to LOG_NOTICE
33991
33992 * paniclog is mapped to LOG_ALERT
33993
33994 Many log lines are written to both mainlog and rejectlog, and some are written
33995 to both mainlog and paniclog, so there will be duplicates if these are routed
33996 by syslog to the same place. You can suppress this duplication by setting
33997 syslog_duplication false.
33998
33999 Exim's log lines can sometimes be very long, and some of its rejectlog entries
34000 contain multiple lines when headers are included. To cope with both these
34001 cases, entries written to syslog are split into separate syslog() calls at each
34002 internal newline, and also after a maximum of 870 data characters. (This allows
34003 for a total syslog line length of 1024, when additions such as timestamps are
34004 added.) If you are running a syslog replacement that can handle lines longer
34005 than the 1024 characters allowed by RFC 3164, you should set
34006
34007 SYSLOG_LONG_LINES=yes
34008
34009 in Local/Makefile before building Exim. That stops Exim from splitting long
34010 lines, but it still splits at internal newlines in reject log entries.
34011
34012 To make it easy to re-assemble split lines later, each component of a split
34013 entry starts with a string of the form [<n>/<m>] or [<n>\<m>] where <n> is the
34014 component number and <m> is the total number of components in the entry. The /
34015 delimiter is used when the line was split because it was too long; if it was
34016 split because of an internal newline, the \ delimiter is used. For example,
34017 supposing the length limit to be 50 instead of 870, the following would be the
34018 result of a typical rejection message to mainlog (LOG_INFO), each line in
34019 addition being preceded by the time, host name, and pid as added by syslog:
34020
34021 [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from
34022 [2/5] [127.0.0.1] (ph10): syntax error in 'From' header
34023 [3/5] when scanning for sender: missing or malformed lo
34024 [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa
34025 [5/5] mple>)
34026
34027 The same error might cause the following lines to be written to "rejectlog"
34028 (LOG_NOTICE):
34029
34030 [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro
34031 [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head
34032 [3/18] er when scanning for sender: missing or malformed
34033 [4/18] local part in "<>" (envelope sender is <ph10@cam
34034 [5\18] .example>)
34035 [6\18] Recipients: ph10@some.domain.cam.example
34036 [7\18] P Received: from [127.0.0.1] (ident=ph10)
34037 [8\18] by xxxxx.cam.example with smtp (Exim 4.00)
34038 [9\18] id 16RdAL-0006pc-00
34039 [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16:
34040 [11\18] 09:43 +0100
34041 [12\18] F From: <>
34042 [13\18] Subject: this is a test header
34043 [18\18] X-something: this is another header
34044 [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp
34045 [16\18] le>
34046 [17\18] B Bcc:
34047 [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100
34048
34049 Log lines that are neither too long nor contain newlines are written to syslog
34050 without modification.
34051
34052 If only syslog is being used, the Exim monitor is unable to provide a log tail
34053 display, unless syslog is routing mainlog to a file on the local host and the
34054 environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor where it
34055 is.
34056
34057
34058 52.5 Log line flags
34059 -------------------
34060
34061 One line is written to the main log for each message received, and for each
34062 successful, unsuccessful, and delayed delivery. These lines can readily be
34063 picked out by the distinctive two-character flags that immediately follow the
34064 timestamp. The flags are:
34065
34066 <= message arrival
34067 (= message fakereject
34068 => normal message delivery
34069 -> additional address in same delivery
34070 >> cutthrough message delivery
34071 *> delivery suppressed by -N
34072 ** delivery failed; address bounced
34073 == delivery deferred; temporary problem
34074
34075
34076 52.6 Logging message reception
34077 ------------------------------
34078
34079 The format of the single-line entry in the main log that is written for every
34080 message received is shown in the basic example below, which is split over
34081 several lines in order to fit it on the page:
34082
34083 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example
34084 H=mailer.fict.example [192.168.123.123] U=exim
34085 P=smtp S=5678 id=<incoming message id>
34086
34087 The address immediately following "<=" is the envelope sender address. A bounce
34088 message is shown with the sender address "<>", and if it is locally generated,
34089 this is followed by an item of the form
34090
34091 R=<message id>
34092
34093 which is a reference to the message that caused the bounce to be sent.
34094
34095 For messages from other hosts, the H and U fields identify the remote host and
34096 record the RFC 1413 identity of the user that sent the message, if one was
34097 received. The number given in square brackets is the IP address of the sending
34098 host. If there is a single, unparenthesized host name in the H field, as above,
34099 it has been verified to correspond to the IP address (see the host_lookup
34100 option). If the name is in parentheses, it was the name quoted by the remote
34101 host in the SMTP HELO or EHLO command, and has not been verified. If
34102 verification yields a different name to that given for HELO or EHLO, the
34103 verified name appears first, followed by the HELO or EHLO name in parentheses.
34104
34105 Misconfigured hosts (and mail forgers) sometimes put an IP address, with or
34106 without brackets, in the HELO or EHLO command, leading to entries in the log
34107 containing text like these examples:
34108
34109 H=(10.21.32.43) [192.168.8.34]
34110 H=([10.21.32.43]) [192.168.8.34]
34111
34112 This can be confusing. Only the final address in square brackets can be relied
34113 on.
34114
34115 For locally generated messages (that is, messages not received over TCP/IP),
34116 the H field is omitted, and the U field contains the login name of the caller
34117 of Exim.
34118
34119 For all messages, the P field specifies the protocol used to receive the
34120 message. This is the value that is stored in $received_protocol. In the case of
34121 incoming SMTP messages, the value indicates whether or not any SMTP extensions
34122 (ESMTP), encryption, or authentication were used. If the SMTP session was
34123 encrypted, there is an additional X field that records the cipher suite that
34124 was used.
34125
34126 The protocol is set to "esmtpsa" or "esmtpa" for messages received from hosts
34127 that have authenticated themselves using the SMTP AUTH command. The first value
34128 is used when the SMTP connection was encrypted ("secure"). In this case there
34129 is an additional item A= followed by the name of the authenticator that was
34130 used. If an authenticated identification was set up by the authenticator's
34131 server_set_id option, this is logged too, separated by a colon from the
34132 authenticator name.
34133
34134 The id field records the existing message id, if present. The size of the
34135 received message is given by the S field. When the message is delivered,
34136 headers may be removed or added, so that the size of delivered copies of the
34137 message may not correspond with this value (and indeed may be different to each
34138 other).
34139
34140 The log_selector option can be used to request the logging of additional data
34141 when a message is received. See section 52.15 below.
34142
34143
34144 52.7 Logging deliveries
34145 -----------------------
34146
34147 The format of the single-line entry in the main log that is written for every
34148 delivery is shown in one of the examples below, for local and remote
34149 deliveries, respectively. Each example has been split into multiple lines in
34150 order to fit it on the page:
34151
34152 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv
34153 <marv@hitch.fict.example> R=localuser T=local_delivery
34154 2002-10-31 09:00:10 16ZCW1-0005MB-00 =>
34155 monk@holistic.fict.example R=dnslookup T=remote_smtp
34156 H=holistic.fict.example [192.168.234.234]
34157
34158 For ordinary local deliveries, the original address is given in angle brackets
34159 after the final delivery address, which might be a pipe or a file. If
34160 intermediate address(es) exist between the original and the final address, the
34161 last of these is given in parentheses after the final address. The R and T
34162 fields record the router and transport that were used to process the address.
34163
34164 If SMTP AUTH was used for the delivery there is an additional item A= followed
34165 by the name of the authenticator that was used. If an authenticated
34166 identification was set up by the authenticator's client_set_id option, this is
34167 logged too, separated by a colon from the authenticator name.
34168
34169 If a shadow transport was run after a successful local delivery, the log line
34170 for the successful delivery has an item added on the end, of the form
34171
34172 ST=<shadow transport name>
34173
34174 If the shadow transport did not succeed, the error message is put in
34175 parentheses afterwards.
34176
34177 When more than one address is included in a single delivery (for example, two
34178 SMTP RCPT commands in one transaction) the second and subsequent addresses are
34179 flagged with "->" instead of "=>". When two or more messages are delivered down
34180 a single SMTP connection, an asterisk follows the IP address in the log lines
34181 for the second and subsequent messages. When two or more messages are delivered
34182 down a single TLS connection, the DNS and some TLS-related information logged
34183 for the first message delivered will not be present in the log lines for the
34184 second and subsequent messages. TLS cipher information is still available.
34185
34186 When delivery is done in cutthrough mode it is flagged with ">>" and the log
34187 line precedes the reception line, since cutthrough waits for a possible
34188 rejection from the destination in case it can reject the sourced item.
34189
34190 The generation of a reply message by a filter file gets logged as a "delivery"
34191 to the addressee, preceded by ">".
34192
34193 The log_selector option can be used to request the logging of additional data
34194 when a message is delivered. See section 52.15 below.
34195
34196
34197 52.8 Discarded deliveries
34198 -------------------------
34199
34200 When a message is discarded as a result of the command "seen finish" being
34201 obeyed in a filter file which generates no deliveries, a log entry of the form
34202
34203 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded
34204 <low.club@bridge.example> R=userforward
34205
34206 is written, to record why no deliveries are logged. When a message is discarded
34207 because it is aliased to ":blackhole:" the log line is like this:
34208
34209 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole:
34210 <hole@nowhere.example> R=blackhole_router
34211
34212
34213 52.9 Deferred deliveries
34214 ------------------------
34215
34216 When a delivery is deferred, a line of the following form is logged:
34217
34218 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example
34219 R=dnslookup T=smtp defer (146): Connection refused
34220
34221 In the case of remote deliveries, the error is the one that was given for the
34222 last IP address that was tried. Details of individual SMTP failures are also
34223 written to the log, so the above line would be preceded by something like
34224
34225 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to
34226 mail1.endrest.example [192.168.239.239]: Connection refused
34227
34228 When a deferred address is skipped because its retry time has not been reached,
34229 a message is written to the log, but this can be suppressed by setting an
34230 appropriate value in log_selector.
34231
34232
34233 52.10 Delivery failures
34234 -----------------------
34235
34236 If a delivery fails because an address cannot be routed, a line of the
34237 following form is logged:
34238
34239 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example
34240 <jim@trek99.example>: unknown mail domain
34241
34242 If a delivery fails at transport time, the router and transport are shown, and
34243 the response from the remote host is included, as in this example:
34244
34245 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example
34246 R=dnslookup T=remote_smtp: SMTP error from remote mailer
34247 after pipelined RCPT TO:<ace400@pb.example>: host
34248 pbmail3.py.example [192.168.63.111]: 553 5.3.0
34249 <ace400@pb.example>...Addressee unknown
34250
34251 The word "pipelined" indicates that the SMTP PIPELINING extension was being
34252 used. See hosts_avoid_esmtp in the smtp transport for a way of disabling
34253 PIPELINING. The log lines for all forms of delivery failure are flagged with
34254 "**".
34255
34256
34257 52.11 Fake deliveries
34258 ---------------------
34259
34260 If a delivery does not actually take place because the -N option has been used
34261 to suppress it, a normal delivery line is written to the log, except that "=>"
34262 is replaced by "*>".
34263
34264
34265 52.12 Completion
34266 ----------------
34267
34268 A line of the form
34269
34270 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed
34271
34272 is written to the main log when a message is about to be removed from the spool
34273 at the end of its processing.
34274
34275
34276 52.13 Summary of Fields in Log Lines
34277 ------------------------------------
34278
34279 A summary of the field identifiers that are used in log lines is shown in the
34280 following table:
34281
34282 A authenticator name (and optional id and sender)
34283 C SMTP confirmation on delivery
34284 command list for "no mail in SMTP session"
34285 CV certificate verification status
34286 D duration of "no mail in SMTP session"
34287 DKIM domain verified in incoming message
34288 DN distinguished name from peer certificate
34289 DS DNSSEC secured lookups
34290 DT on => lines: time taken for a delivery
34291 F sender address (on delivery lines)
34292 H host name and IP address
34293 I local interface used
34294 id message id for incoming message
34295 K CHUNKING extension used
34296 L on <= and => lines: PIPELINING extension used
34297 M8S 8BITMIME status for incoming message
34298 P on <= lines: protocol used
34299 on => and ** lines: return path
34300 PRDR PRDR extension used
34301 PRX on <= and => lines: proxy address
34302 Q alternate queue name
34303 QT on => lines: time spent on queue so far
34304 on "Completed" lines: time spent on queue
34305 R on <= lines: reference for local bounce
34306 on => >> ** and == lines: router name
34307 RT on <= lines: time taken for reception
34308 S size of message in bytes
34309 SNI server name indication from TLS client hello
34310 ST shadow transport name
34311 T on <= lines: message subject (topic)
34312 TFO connection took advantage of TCP Fast Open
34313 on => ** and == lines: transport name
34314 U local user or RFC 1413 identity
34315 X TLS cipher suite
34316
34317
34318 52.14 Other log entries
34319 -----------------------
34320
34321 Various other types of log entry are written from time to time. Most should be
34322 self-explanatory. Among the more common are:
34323
34324 * retry time not reached An address previously suffered a temporary error
34325 during routing or local delivery, and the time to retry has not yet
34326 arrived. This message is not written to an individual message log file
34327 unless it happens during the first delivery attempt.
34328
34329 * retry time not reached for any host An address previously suffered
34330 temporary errors during remote delivery, and the retry time has not yet
34331 arrived for any of the hosts to which it is routed.
34332
34333 * spool file locked An attempt to deliver a message cannot proceed because
34334 some other Exim process is already working on the message. This can be
34335 quite common if queue running processes are started at frequent intervals.
34336 The exiwhat utility script can be used to find out what Exim processes are
34337 doing.
34338
34339 * error ignored There are several circumstances that give rise to this
34340 message:
34341
34342 1. Exim failed to deliver a bounce message whose age was greater than
34343 ignore_bounce_errors_after. The bounce was discarded.
34344
34345 2. A filter file set up a delivery using the "noerror" option, and the
34346 delivery failed. The delivery was discarded.
34347
34348 3. A delivery set up by a router configured with
34349
34350 errors_to = <>
34351
34352 failed. The delivery was discarded.
34353
34354 * DKIM: d= Verbose results of a DKIM verification attempt, if enabled for
34355 logging and the message has a DKIM signature header.
34356
34357
34358 52.15 Reducing or increasing what is logged
34359 -------------------------------------------
34360
34361 By setting the log_selector global option, you can disable some of Exim's
34362 default logging, or you can request additional logging. The value of
34363 log_selector is made up of names preceded by plus or minus characters. For
34364 example:
34365
34366 log_selector = +arguments -retry_defer
34367
34368 The list of optional log items is in the following table, with the default
34369 selection marked by asterisks:
34370
34371 8bitmime received 8BITMIME status
34372 *acl_warn_skipped skipped warn statement in ACL
34373 address_rewrite address rewriting
34374 all_parents all parents in => lines
34375 arguments command line arguments
34376 *connection_reject connection rejections
34377 *delay_delivery immediate delivery delayed
34378 deliver_time time taken to perform delivery
34379 delivery_size add S=nnn to => lines
34380 *dkim DKIM verified domain on <= lines
34381 dkim_verbose separate full DKIM verification result line, per signature
34382 *dnslist_defer defers of DNS list (aka RBL) lookups
34383 dnssec DNSSEC secured lookups
34384 *etrn ETRN commands
34385 *host_lookup_failed as it says
34386 ident_timeout timeout for ident connection
34387 incoming_interface local interface on <= and => lines
34388 incoming_port remote port on <= lines
34389 *lost_incoming_connection as it says (includes timeouts)
34390 millisec millisecond timestamps and RT,QT,DT,D times
34391 outgoing_interface local interface on => lines
34392 outgoing_port add remote port to => lines
34393 *queue_run start and end queue runs
34394 queue_time time on queue for one recipient
34395 queue_time_overall time on queue for whole message
34396 pid Exim process id
34397 pipelining PIPELINING use, on <= and => lines
34398 proxy proxy address on <= and => lines
34399 receive_time time taken to receive message
34400 received_recipients recipients on <= lines
34401 received_sender sender on <= lines
34402 *rejected_header header contents on reject log
34403 *retry_defer "retry time not reached"
34404 return_path_on_delivery put return path on => and ** lines
34405 sender_on_delivery add sender to => lines
34406 *sender_verify_fail sender verification failures
34407 *size_reject rejection because too big
34408 *skip_delivery delivery skipped in a queue run
34409 *smtp_confirmation SMTP confirmation on => lines
34410 smtp_connection incoming SMTP connections
34411 smtp_incomplete_transaction incomplete SMTP transactions
34412 smtp_mailauth AUTH argument to MAIL commands
34413 smtp_no_mail session with no MAIL commands
34414 smtp_protocol_error SMTP protocol errors
34415 smtp_syntax_error SMTP syntax errors
34416 subject contents of Subject: on <= lines
34417 *tls_certificate_verified certificate verification status
34418 *tls_cipher TLS cipher suite on <= and => lines
34419 tls_peerdn TLS peer DN on <= and => lines
34420 tls_sni TLS SNI on <= lines
34421 unknown_in_list DNS lookup failed in list match
34422
34423 all all of the above
34424
34425 See also the slow_lookup_log main configuration option, section 14.4
34426
34427 More details on each of these items follows:
34428
34429 * 8bitmime: This causes Exim to log any 8BITMIME status of received messages,
34430 which may help in tracking down interoperability issues with ancient MTAs
34431 that are not 8bit clean. This is added to the "<=" line, tagged with "M8S="
34432 and a value of "0", "7" or "8", corresponding to "not given", "7BIT" and
34433 "8BITMIME" respectively.
34434
34435 * acl_warn_skipped: When an ACL warn statement is skipped because one of its
34436 conditions cannot be evaluated, a log line to this effect is written if
34437 this log selector is set.
34438
34439 * address_rewrite: This applies both to global rewrites and per-transport
34440 rewrites, but not to rewrites in filters run as an unprivileged user
34441 (because such users cannot access the log).
34442
34443 * all_parents: Normally only the original and final addresses are logged on
34444 delivery lines; with this selector, intermediate parents are given in
34445 parentheses between them.
34446
34447 * arguments: This causes Exim to write the arguments with which it was called
34448 to the main log, preceded by the current working directory. This is a
34449 debugging feature, added to make it easier to find out how certain MUAs
34450 call /usr/sbin/sendmail. The logging does not happen if Exim has given up
34451 root privilege because it was called with the -C or -D options. Arguments
34452 that are empty or that contain white space are quoted. Non-printing
34453 characters are shown as escape sequences. This facility cannot log
34454 unrecognized arguments, because the arguments are checked before the
34455 configuration file is read. The only way to log such cases is to interpose
34456 a script such as util/logargs.sh between the caller and Exim.
34457
34458 * connection_reject: A log entry is written whenever an incoming SMTP
34459 connection is rejected, for whatever reason.
34460
34461 * delay_delivery: A log entry is written whenever a delivery process is not
34462 started for an incoming message because the load is too high or too many
34463 messages were received on one connection. Logging does not occur if no
34464 delivery process is started because queue_only is set or -odq was used.
34465
34466 * deliver_time: For each delivery, the amount of real time it has taken to
34467 perform the actual delivery is logged as DT=<time>, for example, "DT=1s".
34468 If millisecond logging is enabled, short times will be shown with greater
34469 precision, eg. "DT=0.304s".
34470
34471 * delivery_size: For each delivery, the size of message delivered is added to
34472 the "=>" line, tagged with S=.
34473
34474 * dkim: For message acceptance log lines, when an DKIM signature in the
34475 header verifies successfully a tag of DKIM is added, with one of the
34476 verified domains.
34477
34478 * dkim_verbose: A log entry is written for each attempted DKIM verification.
34479
34480 * dnslist_defer: A log entry is written if an attempt to look up a host in a
34481 DNS black list suffers a temporary error.
34482
34483 * dnssec: For message acceptance and (attempted) delivery log lines, when dns
34484 lookups gave secure results a tag of DS is added. For acceptance this
34485 covers the reverse and forward lookups for host name verification. It does
34486 not cover helo-name verification. For delivery this covers the SRV, MX, A
34487 and/or AAAA lookups.
34488
34489 * etrn: Every valid ETRN command that is received is logged, before the ACL
34490 is run to determine whether or not it is actually accepted. An invalid ETRN
34491 command, or one received within a message transaction is not logged by this
34492 selector (see smtp_syntax_error and smtp_protocol_error).
34493
34494 * host_lookup_failed: When a lookup of a host's IP addresses fails to find
34495 any addresses, or when a lookup of an IP address fails to find a host name,
34496 a log line is written. This logging does not apply to direct DNS lookups
34497 when routing email addresses, but it does apply to "byname" lookups.
34498
34499 * ident_timeout: A log line is written whenever an attempt to connect to a
34500 client's ident port times out.
34501
34502 * incoming_interface: The interface on which a message was received is added
34503 to the "<=" line as an IP address in square brackets, tagged by I= and
34504 followed by a colon and the port number. The local interface and port are
34505 also added to other SMTP log lines, for example, "SMTP connection from", to
34506 rejection lines, and (despite the name) to outgoing "=>" and "->" lines.
34507 The latter can be disabled by turning off the outgoing_interface option.
34508
34509 * proxy: The internal (closest to the system running Exim) IP address of the
34510 proxy, tagged by PRX=, on the "<=" line for a message accepted on a proxied
34511 connection or the "=>" line for a message delivered on a proxied
34512 connection. See 58.1 for more information.
34513
34514 * incoming_port: The remote port number from which a message was received is
34515 added to log entries and Received: header lines, following the IP address
34516 in square brackets, and separated from it by a colon. This is implemented
34517 by changing the value that is put in the $sender_fullhost and
34518 $sender_rcvhost variables. Recording the remote port number has become more
34519 important with the widening use of NAT (see RFC 2505).
34520
34521 * lost_incoming_connection: A log line is written when an incoming SMTP
34522 connection is unexpectedly dropped.
34523
34524 * millisec: Timestamps have a period and three decimal places of finer
34525 granularity appended to the seconds value.
34526
34527 * outgoing_interface: If incoming_interface is turned on, then the interface
34528 on which a message was sent is added to delivery lines as an I= tag
34529 followed by IP address in square brackets. You can disable this by turning
34530 off the outgoing_interface option.
34531
34532 * outgoing_port: The remote port number is added to delivery log lines (those
34533 containing => tags) following the IP address. The local port is also added
34534 if incoming_interface and outgoing_interface are both enabled. This option
34535 is not included in the default setting, because for most ordinary
34536 configurations, the remote port number is always 25 (the SMTP port), and
34537 the local port is a random ephemeral port.
34538
34539 * pid: The current process id is added to every log line, in square brackets,
34540 immediately after the time and date.
34541
34542 * pipelining: A field is added to delivery and accept log lines when the
34543 ESMTP PIPELINING extension was used. The field is a single "L".
34544
34545 On accept lines, where PIPELINING was offered but not used by the client,
34546 the field has a minus appended.
34547
34548 * queue_run: The start and end of every queue run are logged.
34549
34550 * queue_time: The amount of time the message has been in the queue on the
34551 local host is logged as QT=<time> on delivery ("=>") lines, for example,
34552 "QT=3m45s". The clock starts when Exim starts to receive the message, so it
34553 includes reception time as well as the delivery time for the current
34554 address. This means that it may be longer than the difference between the
34555 arrival and delivery log line times, because the arrival log line is not
34556 written until the message has been successfully received. If millisecond
34557 logging is enabled, short times will be shown with greater precision, eg.
34558 "QT=1.578s".
34559
34560 * queue_time_overall: The amount of time the message has been in the queue on
34561 the local host is logged as QT=<time> on "Completed" lines, for example,
34562 "QT=3m45s". The clock starts when Exim starts to receive the message, so it
34563 includes reception time as well as the total delivery time.
34564
34565 * receive_time: For each message, the amount of real time it has taken to
34566 perform the reception is logged as RT=<time>, for example, "RT=1s". If
34567 millisecond logging is enabled, short times will be shown with greater
34568 precision, eg. "RT=0.204s".
34569
34570 * received_recipients: The recipients of a message are listed in the main log
34571 as soon as the message is received. The list appears at the end of the log
34572 line that is written when a message is received, preceded by the word
34573 "for". The addresses are listed after they have been qualified, but before
34574 any rewriting has taken place. Recipients that were discarded by an ACL for
34575 MAIL or RCPT do not appear in the list.
34576
34577 * received_sender: The unrewritten original sender of a message is added to
34578 the end of the log line that records the message's arrival, after the word
34579 "from" (before the recipients if received_recipients is also set).
34580
34581 * rejected_header: If a message's header has been received at the time a
34582 rejection is written to the reject log, the complete header is added to the
34583 log. Header logging can be turned off individually for messages that are
34584 rejected by the local_scan() function (see section 45.2).
34585
34586 * retry_defer: A log line is written if a delivery is deferred because a
34587 retry time has not yet been reached. However, this "retry time not reached"
34588 message is always omitted from individual message logs after the first
34589 delivery attempt.
34590
34591 * return_path_on_delivery: The return path that is being transmitted with the
34592 message is included in delivery and bounce lines, using the tag P=. This is
34593 omitted if no delivery actually happens, for example, if routing fails, or
34594 if delivery is to /dev/null or to ":blackhole:".
34595
34596 * sender_on_delivery: The message's sender address is added to every delivery
34597 and bounce line, tagged by F= (for "from"). This is the original sender
34598 that was received with the message; it is not necessarily the same as the
34599 outgoing return path.
34600
34601 * sender_verify_fail: If this selector is unset, the separate log line that
34602 gives details of a sender verification failure is not written. Log lines
34603 for the rejection of SMTP commands contain just "sender verify failed", so
34604 some detail is lost.
34605
34606 * size_reject: A log line is written whenever a message is rejected because
34607 it is too big.
34608
34609 * skip_delivery: A log line is written whenever a message is skipped during a
34610 queue run because it is frozen or because another process is already
34611 delivering it. The message that is written is "spool file is locked".
34612
34613 * smtp_confirmation: The response to the final "." in the SMTP or LMTP
34614 dialogue for outgoing messages is added to delivery log lines in the form
34615 "C="<text>. A number of MTAs (including Exim) return an identifying string
34616 in this response.
34617
34618 * smtp_connection: A log line is written whenever an incoming SMTP connection
34619 is established or closed, unless the connection is from a host that matches
34620 hosts_connection_nolog. (In contrast, lost_incoming_connection applies only
34621 when the closure is unexpected.) This applies to connections from local
34622 processes that use -bs as well as to TCP/IP connections. If a connection is
34623 dropped in the middle of a message, a log line is always written, whether
34624 or not this selector is set, but otherwise nothing is written at the start
34625 and end of connections unless this selector is enabled.
34626
34627 For TCP/IP connections to an Exim daemon, the current number of connections
34628 is included in the log message for each new connection, but note that the
34629 count is reset if the daemon is restarted. Also, because connections are
34630 closed (and the closure is logged) in subprocesses, the count may not
34631 include connections that have been closed but whose termination the daemon
34632 has not yet noticed. Thus, while it is possible to match up the opening and
34633 closing of connections in the log, the value of the logged counts may not
34634 be entirely accurate.
34635
34636 * smtp_incomplete_transaction: When a mail transaction is aborted by RSET,
34637 QUIT, loss of connection, or otherwise, the incident is logged, and the
34638 message sender plus any accepted recipients are included in the log line.
34639 This can provide evidence of dictionary attacks.
34640
34641 * smtp_no_mail: A line is written to the main log whenever an accepted SMTP
34642 connection terminates without having issued a MAIL command. This includes
34643 both the case when the connection is dropped, and the case when QUIT is
34644 used. It does not include cases where the connection is rejected right at
34645 the start (by an ACL, or because there are too many connections, or
34646 whatever). These cases already have their own log lines.
34647
34648 The log line that is written contains the identity of the client in the
34649 usual way, followed by D= and a time, which records the duration of the
34650 connection. If the connection was authenticated, this fact is logged
34651 exactly as it is for an incoming message, with an A= item. If the
34652 connection was encrypted, CV=, DN=, and X= items may appear as they do for
34653 an incoming message, controlled by the same logging options.
34654
34655 Finally, if any SMTP commands were issued during the connection, a C= item
34656 is added to the line, listing the commands that were used. For example,
34657
34658 C=EHLO,QUIT
34659
34660 shows that the client issued QUIT straight after EHLO. If there were fewer
34661 than 20 commands, they are all listed. If there were more than 20 commands,
34662 the last 20 are listed, preceded by "...". However, with the default
34663 setting of 10 for smtp_accept_max_nonmail, the connection will in any case
34664 have been aborted before 20 non-mail commands are processed.
34665
34666 * smtp_mailauth: A third subfield with the authenticated sender,
34667 colon-separated, is appended to the A= item for a message arrival or
34668 delivery log line, if an AUTH argument to the SMTP MAIL command (see 33.2)
34669 was accepted or used.
34670
34671 * smtp_protocol_error: A log line is written for every SMTP protocol error
34672 encountered. Exim does not have perfect detection of all protocol errors
34673 because of transmission delays and the use of pipelining. If PIPELINING has
34674 been advertised to a client, an Exim server assumes that the client will
34675 use it, and therefore it does not count "expected" errors (for example,
34676 RCPT received after rejecting MAIL) as protocol errors.
34677
34678 * smtp_syntax_error: A log line is written for every SMTP syntax error
34679 encountered. An unrecognized command is treated as a syntax error. For an
34680 external connection, the host identity is given; for an internal connection
34681 using -bs the sender identification (normally the calling user) is given.
34682
34683 * subject: The subject of the message is added to the arrival log line,
34684 preceded by "T=" (T for "topic", since S is already used for "size"). Any
34685 MIME "words" in the subject are decoded. The print_topbitchars option
34686 specifies whether characters with values greater than 127 should be logged
34687 unchanged, or whether they should be rendered as escape sequences.
34688
34689 * tls_certificate_verified: An extra item is added to <= and => log lines
34690 when TLS is in use. The item is "CV=yes" if the peer's certificate was
34691 verified using a CA trust anchor, "CA=dane" if using a DNS trust anchor,
34692 and "CV=no" if not.
34693
34694 * tls_cipher: When a message is sent or received over an encrypted
34695 connection, the cipher suite used is added to the log line, preceded by X=.
34696
34697 * tls_peerdn: When a message is sent or received over an encrypted
34698 connection, and a certificate is supplied by the remote host, the peer DN
34699 is added to the log line, preceded by DN=.
34700
34701 * tls_sni: When a message is received over an encrypted connection, and the
34702 remote host provided the Server Name Indication extension, the SNI is added
34703 to the log line, preceded by SNI=.
34704
34705 * unknown_in_list: This setting causes a log entry to be written when the
34706 result of a list match is failure because a DNS lookup failed.
34707
34708
34709 52.16 Message log
34710 -----------------
34711
34712 In addition to the general log files, Exim writes a log file for each message
34713 that it handles. The names of these per-message logs are the message ids, and
34714 they are kept in the msglog sub-directory of the spool directory. Each message
34715 log contains copies of the log lines that apply to the message. This makes it
34716 easier to inspect the status of an individual message without having to search
34717 the main log. A message log is deleted when processing of the message is
34718 complete, unless preserve_message_logs is set, but this should be used only
34719 with great care because they can fill up your disk very quickly.
34720
34721 On a heavily loaded system, it may be desirable to disable the use of
34722 per-message logs, in order to reduce disk I/O. This can be done by setting the
34723 message_logs option false.
34724
34725
34726
34727 ===============================================================================
34728 53. EXIM UTILITIES
34729
34730 A number of utility scripts and programs are supplied with Exim and are
34731 described in this chapter. There is also the Exim Monitor, which is covered in
34732 the next chapter. The utilities described here are:
34733
34734 53.1 exiwhat list what Exim processes are doing
34735 53.2 exiqgrep grep the queue
34736 53.3 exiqsumm summarize the queue
34737 53.4 exigrep search the main log
34738 53.5 exipick select messages on various criteria
34739 53.6 exicyclog cycle (rotate) log files
34740 53.7 eximstats extract statistics from the log
34741 53.8 exim_checkaccess check address acceptance from given IP
34742 53.9 exim_dbmbuild build a DBM file
34743 53.10 exinext extract retry information
34744 53.11 exim_dumpdb dump a hints database
34745 53.11 exim_tidydb clean up a hints database
34746 53.11 exim_fixdb patch a hints database
34747 53.15 exim_lock lock a mailbox file
34748
34749 Another utility that might be of use to sites with many MTAs is Tom Kistner's
34750 exilog. It provides log visualizations across multiple Exim servers. See https:
34751 //duncanthrax.net/exilog/ for details.
34752
34753
34754 53.1 Finding out what Exim processes are doing (exiwhat)
34755 --------------------------------------------------------
34756
34757 On operating systems that can restart a system call after receiving a signal
34758 (most modern OS), an Exim process responds to the SIGUSR1 signal by writing a
34759 line describing what it is doing to the file exim-process.info in the Exim
34760 spool directory. The exiwhat script sends the signal to all Exim processes it
34761 can find, having first emptied the file. It then waits for one second to allow
34762 the Exim processes to react before displaying the results. In order to run
34763 exiwhat successfully you have to have sufficient privilege to send the signal
34764 to the Exim processes, so it is normally run as root.
34765
34766 Warning: This is not an efficient process. It is intended for occasional use by
34767 system administrators. It is not sensible, for example, to set up a script that
34768 sends SIGUSR1 signals to Exim processes at short intervals.
34769
34770 Unfortunately, the ps command that exiwhat uses to find Exim processes varies
34771 in different operating systems. Not only are different options used, but the
34772 format of the output is different. For this reason, there are some system
34773 configuration options that configure exactly how exiwhat works. If it doesn't
34774 seem to be working for you, check the following compile-time options:
34775
34776 EXIWHAT_PS_CMD the command for running ps
34777 EXIWHAT_PS_ARG the argument for ps
34778 EXIWHAT_EGREP_ARG the argument for egrep to select from ps output
34779 EXIWHAT_KILL_ARG the argument for the kill command
34780
34781 An example of typical output from exiwhat is
34782
34783 164 daemon: -q1h, listening on port 25
34784 10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
34785 10492 delivering 0tAycK-0002ij-00 to mail.ref.example
34786 [10.19.42.42] (editor@ref.example)
34787 10592 handling incoming call from [192.168.243.242]
34788 10628 accepting a local non-SMTP message
34789
34790 The first number in the output line is the process number. The third line has
34791 been split here, in order to fit it on the page.
34792
34793
34794 53.2 Selective queue listing (exiqgrep)
34795 ---------------------------------------
34796
34797 This utility is a Perl script contributed by Matt Hubbard. It runs
34798
34799 exim -bpu
34800
34801 or (in case -a switch is specified)
34802
34803 exim -bp
34804
34805 The -C option is used to specify an alternate exim.conf which might contain
34806 alternate exim configuration the queue management might be using.
34807
34808 to obtain a queue listing, and then greps the output to select messages that
34809 match given criteria. The following selection options are available:
34810
34811 -f <regex>
34812
34813 Match the sender address using a case-insensitive search. The field that is
34814 tested is enclosed in angle brackets, so you can test for bounce messages
34815 with
34816
34817 exiqgrep -f '^<>$'
34818
34819 -r <regex>
34820
34821 Match a recipient address using a case-insensitive search. The field that
34822 is tested is not enclosed in angle brackets.
34823
34824 -s <regex>
34825
34826 Match against the size field.
34827
34828 -y <seconds>
34829
34830 Match messages that are younger than the given time.
34831
34832 -o <seconds>
34833
34834 Match messages that are older than the given time.
34835
34836 -z
34837
34838 Match only frozen messages.
34839
34840 -x
34841
34842 Match only non-frozen messages.
34843
34844 The following options control the format of the output:
34845
34846 -c
34847
34848 Display only the count of matching messages.
34849
34850 -l
34851
34852 Long format - display the full message information as output by Exim. This
34853 is the default.
34854
34855 -i
34856
34857 Display message ids only.
34858
34859 -b
34860
34861 Brief format - one line per message.
34862
34863 -R
34864
34865 Display messages in reverse order.
34866
34867 -a
34868
34869 Include delivered recipients in queue listing.
34870
34871 There is one more option, -h, which outputs a list of options.
34872
34873
34874 53.3 Summarizing the queue (exiqsumm)
34875 -------------------------------------
34876
34877 The exiqsumm utility is a Perl script which reads the output of "exim -bp" and
34878 produces a summary of the messages in the queue. Thus, you use it by running a
34879 command such as
34880
34881 exim -bp | exiqsumm
34882
34883 The output consists of one line for each domain that has messages waiting for
34884 it, as in the following example:
34885
34886 3 2322 74m 66m msn.com.example
34887
34888 Each line lists the number of pending deliveries for a domain, their total
34889 volume, and the length of time that the oldest and the newest messages have
34890 been waiting. Note that the number of pending deliveries is greater than the
34891 number of messages when messages have more than one recipient.
34892
34893 A summary line is output at the end. By default the output is sorted on the
34894 domain name, but exiqsumm has the options -a and -c, which cause the output to
34895 be sorted by oldest message and by count of messages, respectively. There are
34896 also three options that split the messages for each domain into two or more
34897 subcounts: -b separates bounce messages, -f separates frozen messages, and -s
34898 separates messages according to their sender.
34899
34900 The output of exim -bp contains the original addresses in the message, so this
34901 also applies to the output from exiqsumm. No domains from addresses generated
34902 by aliasing or forwarding are included (unless the one_time option of the
34903 redirect router has been used to convert them into "top level" addresses).
34904
34905
34906 53.4 Extracting specific information from the log (exigrep)
34907 -----------------------------------------------------------
34908
34909 The exigrep utility is a Perl script that searches one or more main log files
34910 for entries that match a given pattern. When it finds a match, it extracts all
34911 the log entries for the relevant message, not just those that match the
34912 pattern. Thus, exigrep can extract complete log entries for a given message, or
34913 all mail for a given user, or for a given host, for example. The input files
34914 can be in Exim log format or syslog format. If a matching log line is not
34915 associated with a specific message, it is included in exigrep's output without
34916 any additional lines. The usage is:
34917
34918 exigrep [-t<n>] [-I] [-l] [-M] [-v] <pattern> [<log file>] ...
34919
34920 If no log filenames are given on the command line, the standard input is read.
34921
34922 The -t argument specifies a number of seconds. It adds an additional condition
34923 for message selection. Messages that are complete are shown only if they spent
34924 more than <n> seconds in the queue.
34925
34926 By default, exigrep does case-insensitive matching. The -I option makes it
34927 case-sensitive. This may give a performance improvement when searching large
34928 log files. Without -I, the Perl pattern matches use Perl's "/i" option; with -I
34929 they do not. In both cases it is possible to change the case sensitivity within
34930 the pattern by using "(?i)" or "(?-i)".
34931
34932 The -l option means "literal", that is, treat all characters in the pattern as
34933 standing for themselves. Otherwise the pattern must be a Perl regular
34934 expression.
34935
34936 The -v option inverts the matching condition. That is, a line is selected if it
34937 does not match the pattern.
34938
34939 The -M options means "related messages". exigrep will show messages that are
34940 generated as a result/response to a message that exigrep matched normally.
34941
34942 Example of -M: user_a sends a message to user_b, which generates a bounce back
34943 to user_b. If exigrep is used to search for "user_a", only the first message
34944 will be displayed. But if exigrep is used to search for "user_b", the first and
34945 the second (bounce) message will be displayed. Using -M with exigrep when
34946 searching for "user_a" will show both messages since the bounce is "related" to
34947 or a "result" of the first message that was found by the search term.
34948
34949 If the location of a zcat command is known from the definition of ZCAT_COMMAND
34950 in Local/Makefile, exigrep automatically passes any file whose name ends in
34951 COMPRESS_SUFFIX through zcat as it searches it. If the ZCAT_COMMAND is not
34952 executable, exigrep tries to use autodetection of some well known compression
34953 extensions.
34954
34955
34956 53.5 Selecting messages by various criteria (exipick)
34957 -----------------------------------------------------
34958
34959 John Jetmore's exipick utility is included in the Exim distribution. It lists
34960 messages from the queue according to a variety of criteria. For details of
34961 exipick's facilities, run exipick with the --help option.
34962
34963
34964 53.6 Cycling log files (exicyclog)
34965 ----------------------------------
34966
34967 The exicyclog script can be used to cycle (rotate) mainlog and rejectlog files.
34968 This is not necessary if only syslog is being used, or if you are using log
34969 files with datestamps in their names (see section 52.3). Some operating systems
34970 have their own standard mechanisms for log cycling, and these can be used
34971 instead of exicyclog if preferred. There are two command line options for
34972 exicyclog:
34973
34974 * -k <count> specifies the number of log files to keep, overriding the
34975 default that is set when Exim is built. The default default is 10.
34976
34977 * -l <path> specifies the log file path, in the same format as Exim's
34978 log_file_path option (for example, "/var/log/exim_%slog"), again overriding
34979 the script's default, which is to find the setting from Exim's
34980 configuration.
34981
34982 Each time exicyclog is run the filenames get "shuffled down" by one. If the
34983 main log filename is mainlog (the default) then when exicyclog is run mainlog
34984 becomes mainlog.01, the previous mainlog.01 becomes mainlog.02 and so on, up to
34985 the limit that is set in the script or by the -k option. Log files whose
34986 numbers exceed the limit are discarded. Reject logs are handled similarly.
34987
34988 If the limit is greater than 99, the script uses 3-digit numbers such as
34989 mainlog.001, mainlog.002, etc. If you change from a number less than 99 to one
34990 that is greater, or vice versa, you will have to fix the names of any existing
34991 log files.
34992
34993 If no mainlog file exists, the script does nothing. Files that "drop off" the
34994 end are deleted. All files with numbers greater than 01 are compressed, using a
34995 compression command which is configured by the COMPRESS_COMMAND setting in
34996 Local/Makefile. It is usual to run exicyclog daily from a root crontab entry of
34997 the form
34998
34999 1 0 * * * su exim -c /usr/exim/bin/exicyclog
35000
35001 assuming you have used the name "exim" for the Exim user. You can run exicyclog
35002 as root if you wish, but there is no need.
35003
35004
35005 53.7 Mail statistics (eximstats)
35006 --------------------------------
35007
35008 A Perl script called eximstats is provided for extracting statistical
35009 information from log files. The output is either plain text, or HTML.
35010
35011 The eximstats script has been hacked about quite a bit over time. The latest
35012 version is the result of some extensive revision by Steve Campbell. A lot of
35013 information is given by default, but there are options for suppressing various
35014 parts of it. Following any options, the arguments to the script are a list of
35015 files, which should be main log files. For example:
35016
35017 eximstats -nr /var/spool/exim/log/mainlog.01
35018
35019 By default, eximstats extracts information about the number and volume of
35020 messages received from or delivered to various hosts. The information is sorted
35021 both by message count and by volume, and the top fifty hosts in each category
35022 are listed on the standard output. Similar information, based on email
35023 addresses or domains instead of hosts can be requested by means of various
35024 options. For messages delivered and received locally, similar statistics are
35025 also produced per user.
35026
35027 The output also includes total counts and statistics about delivery errors, and
35028 histograms showing the number of messages received and deliveries made in each
35029 hour of the day. A delivery with more than one address in its envelope (for
35030 example, an SMTP transaction with more than one RCPT command) is counted as a
35031 single delivery by eximstats.
35032
35033 Though normally more deliveries than receipts are reported (as messages may
35034 have multiple recipients), it is possible for eximstats to report more messages
35035 received than delivered, even though the queue is empty at the start and end of
35036 the period in question. If an incoming message contains no valid recipients, no
35037 deliveries are recorded for it. A bounce message is handled as an entirely
35038 separate message.
35039
35040 eximstats always outputs a grand total summary giving the volume and number of
35041 messages received and deliveries made, and the number of hosts involved in each
35042 case. It also outputs the number of messages that were delayed (that is, not
35043 completely delivered at the first attempt), and the number that had at least
35044 one address that failed.
35045
35046 The remainder of the output is in sections that can be independently disabled
35047 or modified by various options. It consists of a summary of deliveries by
35048 transport, histograms of messages received and delivered per time interval
35049 (default per hour), information about the time messages spent in the queue, a
35050 list of relayed messages, lists of the top fifty sending hosts, local senders,
35051 destination hosts, and destination local users by count and by volume, and a
35052 list of delivery errors that occurred.
35053
35054 The relay information lists messages that were actually relayed, that is, they
35055 came from a remote host and were directly delivered to some other remote host,
35056 without being processed (for example, for aliasing or forwarding) locally.
35057
35058 There are quite a few options for eximstats to control exactly what it outputs.
35059 These are documented in the Perl script itself, and can be extracted by running
35060 the command perldoc on the script. For example:
35061
35062 perldoc /usr/exim/bin/eximstats
35063
35064
35065 53.8 Checking access policy (exim_checkaccess)
35066 ----------------------------------------------
35067
35068 The -bh command line argument allows you to run a fake SMTP session with
35069 debugging output, in order to check what Exim is doing when it is applying
35070 policy controls to incoming SMTP mail. However, not everybody is sufficiently
35071 familiar with the SMTP protocol to be able to make full use of -bh, and
35072 sometimes you just want to answer the question "Does this address have access?"
35073 without bothering with any further details.
35074
35075 The exim_checkaccess utility is a "packaged" version of -bh. It takes two
35076 arguments, an IP address and an email address:
35077
35078 exim_checkaccess 10.9.8.7 A.User@a.domain.example
35079
35080 The utility runs a call to Exim with the -bh option, to test whether the given
35081 email address would be accepted in a RCPT command in a TCP/IP connection from
35082 the host with the given IP address. The output of the utility is either the
35083 word "accepted", or the SMTP error response, for example:
35084
35085 Rejected:
35086 550 Relay not permitted
35087
35088 When running this test, the utility uses "<>" as the envelope sender address
35089 for the MAIL command, but you can change this by providing additional options.
35090 These are passed directly to the Exim command. For example, to specify that the
35091 test is to be run with the sender address himself@there.example you can use:
35092
35093 exim_checkaccess 10.9.8.7 A.User@a.domain.example \
35094 -f himself@there.example
35095
35096 Note that these additional Exim command line items must be given after the two
35097 mandatory arguments.
35098
35099 Because the exim_checkaccess uses -bh, it does not perform callouts while
35100 running its checks. You can run checks that include callouts by using -bhc, but
35101 this is not yet available in a "packaged" form.
35102
35103
35104 53.9 Making DBM files (exim_dbmbuild)
35105 -------------------------------------
35106
35107 The exim_dbmbuild program reads an input file containing keys and data in the
35108 format used by the lsearch lookup (see section 9.3). It writes a DBM file using
35109 the lower-cased alias names as keys and the remainder of the information as
35110 data. The lower-casing can be prevented by calling the program with the -nolc
35111 option.
35112
35113 A terminating zero is included as part of the key string. This is expected by
35114 the dbm lookup type. However, if the option -nozero is given, exim_dbmbuild
35115 creates files without terminating zeroes in either the key strings or the data
35116 strings. The dbmnz lookup type can be used with such files.
35117
35118 The program requires two arguments: the name of the input file (which can be a
35119 single hyphen to indicate the standard input), and the name of the output file.
35120 It creates the output under a temporary name, and then renames it if all went
35121 well.
35122
35123 If the native DB interface is in use (USE_DB is set in a compile-time
35124 configuration file - this is common in free versions of Unix) the two filenames
35125 must be different, because in this mode the Berkeley DB functions create a
35126 single output file using exactly the name given. For example,
35127
35128 exim_dbmbuild /etc/aliases /etc/aliases.db
35129
35130 reads the system alias file and creates a DBM version of it in /etc/aliases.db.
35131
35132 In systems that use the ndbm routines (mostly proprietary versions of Unix),
35133 two files are used, with the suffixes .dir and .pag. In this environment, the
35134 suffixes are added to the second argument of exim_dbmbuild, so it can be the
35135 same as the first. This is also the case when the Berkeley functions are used
35136 in compatibility mode (though this is not recommended), because in that case it
35137 adds a .db suffix to the filename.
35138
35139 If a duplicate key is encountered, the program outputs a warning, and when it
35140 finishes, its return code is 1 rather than zero, unless the -noduperr option is
35141 used. By default, only the first of a set of duplicates is used - this makes it
35142 compatible with lsearch lookups. There is an option -lastdup which causes it to
35143 use the data for the last duplicate instead. There is also an option -nowarn,
35144 which stops it listing duplicate keys to stderr. For other errors, where it
35145 doesn't actually make a new file, the return code is 2.
35146
35147
35148 53.10 Finding individual retry times (exinext)
35149 ----------------------------------------------
35150
35151 A utility called exinext (mostly a Perl script) provides the ability to fish
35152 specific information out of the retry database. Given a mail domain (or a
35153 complete address), it looks up the hosts for that domain, and outputs any retry
35154 information for the hosts or for the domain. At present, the retry information
35155 is obtained by running exim_dumpdb (see below) and post-processing the output.
35156 For example:
35157
35158 $ exinext piglet@milne.fict.example
35159 kanga.milne.example:192.168.8.1 error 146: Connection refused
35160 first failed: 21-Feb-1996 14:57:34
35161 last tried: 21-Feb-1996 14:57:34
35162 next try at: 21-Feb-1996 15:02:34
35163 roo.milne.example:192.168.8.3 error 146: Connection refused
35164 first failed: 20-Jan-1996 13:12:08
35165 last tried: 21-Feb-1996 11:42:03
35166 next try at: 21-Feb-1996 19:42:03
35167 past final cutoff time
35168
35169 You can also give exinext a local part, without a domain, and it will give any
35170 retry information for that local part in your default domain. A message id can
35171 be used to obtain retry information pertaining to a specific message. This
35172 exists only when an attempt to deliver a message to a remote host suffers a
35173 message-specific error (see section 48.2). exinext is not particularly
35174 efficient, but then it is not expected to be run very often.
35175
35176 The exinext utility calls Exim to find out information such as the location of
35177 the spool directory. The utility has -C and -D options, which are passed on to
35178 the exim commands. The first specifies an alternate Exim configuration file,
35179 and the second sets macros for use within the configuration file. These
35180 features are mainly to help in testing, but might also be useful in
35181 environments where more than one configuration file is in use.
35182
35183
35184 53.11 Hints database maintenance
35185 --------------------------------
35186
35187 Three utility programs are provided for maintaining the DBM files that Exim
35188 uses to contain its delivery hint information. Each program requires two
35189 arguments. The first specifies the name of Exim's spool directory, and the
35190 second is the name of the database it is to operate on. These are as follows:
35191
35192 * retry: the database of retry information
35193
35194 * wait-<transport name>: databases of information about messages waiting for
35195 remote hosts
35196
35197 * callout: the callout cache
35198
35199 * ratelimit: the data for implementing the ratelimit ACL condition
35200
35201 * misc: other hints data
35202
35203 The misc database is used for
35204
35205 * Serializing ETRN runs (when smtp_etrn_serialize is set)
35206
35207 * Serializing delivery to a specific host (when serialize_hosts is set in an
35208 smtp transport)
35209
35210 * Limiting the concurrency of specific transports (when max_parallel is set
35211 in a transport)
35212
35213
35214 53.12 exim_dumpdb
35215 -----------------
35216
35217 The entire contents of a database are written to the standard output by the
35218 exim_dumpdb program, which has no options or arguments other than the spool and
35219 database names. For example, to dump the retry database:
35220
35221 exim_dumpdb /var/spool/exim retry
35222
35223 Two lines of output are produced for each entry:
35224
35225 T:mail.ref.example:192.168.242.242 146 77 Connection refused
35226 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 *
35227
35228 The first item on the first line is the key of the record. It starts with one
35229 of the letters R, or T, depending on whether it refers to a routing or
35230 transport retry. For a local delivery, the next part is the local address; for
35231 a remote delivery it is the name of the remote host, followed by its failing IP
35232 address (unless retry_include_ip_address is set false on the smtp transport).
35233 If the remote port is not the standard one (port 25), it is added to the IP
35234 address. Then there follows an error code, an additional error code, and a
35235 textual description of the error.
35236
35237 The three times on the second line are the time of first failure, the time of
35238 the last delivery attempt, and the computed time for the next attempt. The line
35239 ends with an asterisk if the cutoff time for the last retry rule has been
35240 exceeded.
35241
35242 Each output line from exim_dumpdb for the wait-xxx databases consists of a host
35243 name followed by a list of ids for messages that are or were waiting to be
35244 delivered to that host. If there are a very large number for any one host,
35245 continuation records, with a sequence number added to the host name, may be
35246 seen. The data in these records is often out of date, because a message may be
35247 routed to several alternative hosts, and Exim makes no effort to keep
35248 cross-references.
35249
35250
35251 53.13 exim_tidydb
35252 -----------------
35253
35254 The exim_tidydb utility program is used to tidy up the contents of a hints
35255 database. If run with no options, it removes all records that are more than 30
35256 days old. The age is calculated from the date and time that the record was last
35257 updated. Note that, in the case of the retry database, it is not the time since
35258 the first delivery failure. Information about a host that has been down for
35259 more than 30 days will remain in the database, provided that the record is
35260 updated sufficiently often.
35261
35262 The cutoff date can be altered by means of the -t option, which must be
35263 followed by a time. For example, to remove all records older than a week from
35264 the retry database:
35265
35266 exim_tidydb -t 7d /var/spool/exim retry
35267
35268 Both the wait-xxx and retry databases contain items that involve message ids.
35269 In the former these appear as data in records keyed by host - they were
35270 messages that were waiting for that host - and in the latter they are the keys
35271 for retry information for messages that have suffered certain types of error.
35272 When exim_tidydb is run, a check is made to ensure that message ids in database
35273 records are those of messages that are still on the queue. Message ids for
35274 messages that no longer exist are removed from wait-xxx records, and if this
35275 leaves any records empty, they are deleted. For the retry database, records
35276 whose keys are non-existent message ids are removed. The exim_tidydb utility
35277 outputs comments on the standard output whenever it removes information from
35278 the database.
35279
35280 Certain records are automatically removed by Exim when they are no longer
35281 needed, but others are not. For example, if all the MX hosts for a domain are
35282 down, a retry record is created for each one. If the primary MX host comes back
35283 first, its record is removed when Exim successfully delivers to it, but the
35284 records for the others remain because Exim has not tried to use those hosts.
35285
35286 It is important, therefore, to run exim_tidydb periodically on all the hints
35287 databases. You should do this at a quiet time of day, because it requires a
35288 database to be locked (and therefore inaccessible to Exim) while it does its
35289 work. Removing records from a DBM file does not normally make the file smaller,
35290 but all the common DBM libraries are able to re-use the space that is released.
35291 After an initial phase of increasing in size, the databases normally reach a
35292 point at which they no longer get any bigger, as long as they are regularly
35293 tidied.
35294
35295 Warning: If you never run exim_tidydb, the space used by the hints databases is
35296 likely to keep on increasing.
35297
35298
35299 53.14 exim_fixdb
35300 ----------------
35301
35302 The exim_fixdb program is a utility for interactively modifying databases. Its
35303 main use is for testing Exim, but it might also be occasionally useful for
35304 getting round problems in a live system. It has no options, and its interface
35305 is somewhat crude. On entry, it prompts for input with a right angle-bracket. A
35306 key of a database record can then be entered, and the data for that record is
35307 displayed.
35308
35309 If "d" is typed at the next prompt, the entire record is deleted. For all
35310 except the retry database, that is the only operation that can be carried out.
35311 For the retry database, each field is output preceded by a number, and data for
35312 individual fields can be changed by typing the field number followed by new
35313 data, for example:
35314
35315 > 4 951102:1000
35316
35317 resets the time of the next delivery attempt. Time values are given as a
35318 sequence of digit pairs for year, month, day, hour, and minute. Colons can be
35319 used as optional separators.
35320
35321
35322 53.15 Mailbox maintenance (exim_lock)
35323 -------------------------------------
35324
35325 The exim_lock utility locks a mailbox file using the same algorithm as Exim.
35326 For a discussion of locking issues, see section 26.3. Exim_lock can be used to
35327 prevent any modification of a mailbox by Exim or a user agent while
35328 investigating a problem. The utility requires the name of the file as its first
35329 argument. If the locking is successful, the second argument is run as a command
35330 (using C's system() function); if there is no second argument, the value of the
35331 SHELL environment variable is used; if this is unset or empty, /bin/sh is run.
35332 When the command finishes, the mailbox is unlocked and the utility ends. The
35333 following options are available:
35334
35335 -fcntl
35336
35337 Use fcntl() locking on the open mailbox.
35338
35339 -flock
35340
35341 Use flock() locking on the open mailbox, provided the operating system
35342 supports it.
35343
35344 -interval
35345
35346 This must be followed by a number, which is a number of seconds; it sets
35347 the interval to sleep between retries (default 3).
35348
35349 -lockfile
35350
35351 Create a lock file before opening the mailbox.
35352
35353 -mbx
35354
35355 Lock the mailbox using MBX rules.
35356
35357 -q
35358
35359 Suppress verification output.
35360
35361 -retries
35362
35363 This must be followed by a number; it sets the number of times to try to
35364 get the lock (default 10).
35365
35366 -restore_time
35367
35368 This option causes exim_lock to restore the modified and read times to the
35369 locked file before exiting. This allows you to access a locked mailbox (for
35370 example, to take a backup copy) without disturbing the times that the user
35371 subsequently sees.
35372
35373 -timeout
35374
35375 This must be followed by a number, which is a number of seconds; it sets a
35376 timeout to be used with a blocking fcntl() lock. If it is not set (the
35377 default), a non-blocking call is used.
35378
35379 -v
35380
35381 Generate verbose output.
35382
35383 If none of -fcntl, -flock, -lockfile or -mbx are given, the default is to
35384 create a lock file and also to use fcntl() locking on the mailbox, which is the
35385 same as Exim's default. The use of -flock or -fcntl requires that the file be
35386 writeable; the use of -lockfile requires that the directory containing the file
35387 be writeable. Locking by lock file does not last forever; Exim assumes that a
35388 lock file is expired if it is more than 30 minutes old.
35389
35390 The -mbx option can be used with either or both of -fcntl or -flock. It assumes
35391 -fcntl by default. MBX locking causes a shared lock to be taken out on the open
35392 mailbox, and an exclusive lock on the file /tmp/.n.m where n and m are the
35393 device number and inode number of the mailbox file. When the locking is
35394 released, if an exclusive lock can be obtained for the mailbox, the file in /
35395 tmp is deleted.
35396
35397 The default output contains verification of the locking that takes place. The
35398 -v option causes some additional information to be given. The -q option
35399 suppresses all output except error messages.
35400
35401 A command such as
35402
35403 exim_lock /var/spool/mail/spqr
35404
35405 runs an interactive shell while the file is locked, whereas
35406
35407 exim_lock -q /var/spool/mail/spqr <<End
35408 <some commands>
35409 End
35410
35411 runs a specific non-interactive sequence of commands while the file is locked,
35412 suppressing all verification output. A single command can be run by a command
35413 such as
35414
35415 exim_lock -q /var/spool/mail/spqr \
35416 "cp /var/spool/mail/spqr /some/where"
35417
35418 Note that if a command is supplied, it must be entirely contained within the
35419 second argument - hence the quotes.
35420
35421
35422
35423 ===============================================================================
35424 54. THE EXIM MONITOR
35425
35426 The Exim monitor is an application which displays in an X window information
35427 about the state of Exim's queue and what Exim is doing. An admin user can
35428 perform certain operations on messages from this GUI interface; however all
35429 such facilities are also available from the command line, and indeed, the
35430 monitor itself makes use of the command line to perform any actions requested.
35431
35432
35433 54.1 Running the monitor
35434 ------------------------
35435
35436 The monitor is started by running the script called eximon. This is a shell
35437 script that sets up a number of environment variables, and then runs the binary
35438 called eximon.bin. The default appearance of the monitor window can be changed
35439 by editing the Local/eximon.conf file created by editing exim_monitor/EDITME.
35440 Comments in that file describe what the various parameters are for.
35441
35442 The parameters that get built into the eximon script can be overridden for a
35443 particular invocation by setting up environment variables of the same names,
35444 preceded by "EXIMON_". For example, a shell command such as
35445
35446 EXIMON_LOG_DEPTH=400 eximon
35447
35448 (in a Bourne-compatible shell) runs eximon with an overriding setting of the
35449 LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it
35450 overrides the Exim log file configuration. This makes it possible to have
35451 eximon tailing log data that is written to syslog, provided that MAIL.INFO
35452 syslog messages are routed to a file on the local host.
35453
35454 X resources can be used to change the appearance of the window in the normal
35455 way. For example, a resource setting of the form
35456
35457 Eximon*background: gray94
35458
35459 changes the colour of the background to light grey rather than white. The
35460 stripcharts are drawn with both the data lines and the reference lines in
35461 black. This means that the reference lines are not visible when on top of the
35462 data. However, their colour can be changed by setting a resource called
35463 "highlight" (an odd name, but that's what the Athena stripchart widget uses).
35464 For example, if your X server is running Unix, you could set up lighter
35465 reference lines in the stripcharts by obeying
35466
35467 xrdb -merge <<End
35468 Eximon*highlight: gray
35469 End
35470
35471 In order to see the contents of messages in the queue, and to operate on them,
35472 eximon must either be run as root or by an admin user.
35473
35474 The command-line parameters of eximon are passed to eximon.bin and may contain
35475 X11 resource parameters interpreted by the X11 library. In addition, if the
35476 first parameter starts with the string "gdb" then it is removed and the binary
35477 is invoked under gdb (the parameter is used as the gdb command-name, so
35478 versioned variants of gdb can be invoked).
35479
35480 The monitor's window is divided into three parts. The first contains one or
35481 more stripcharts and two action buttons, the second contains a "tail" of the
35482 main log file, and the third is a display of the queue of messages awaiting
35483 delivery, with two more action buttons. The following sections describe these
35484 different parts of the display.
35485
35486
35487 54.2 The stripcharts
35488 --------------------
35489
35490 The first stripchart is always a count of messages in the queue. Its name can
35491 be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file.
35492 The remaining stripcharts are defined in the configuration script by regular
35493 expression matches on log file entries, making it possible to display, for
35494 example, counts of messages delivered to certain hosts or using certain
35495 transports. The supplied defaults display counts of received and delivered
35496 messages, and of local and SMTP deliveries. The default period between
35497 stripchart updates is one minute; this can be adjusted by a parameter in the
35498 Local/eximon.conf file.
35499
35500 The stripchart displays rescale themselves automatically as the value they are
35501 displaying changes. There are always 10 horizontal lines in each chart; the
35502 title string indicates the value of each division when it is greater than one.
35503 For example, "x2" means that each division represents a value of 2.
35504
35505 It is also possible to have a stripchart which shows the percentage fullness of
35506 a particular disk partition, which is useful when local deliveries are confined
35507 to a single partition.
35508
35509 This relies on the availability of the statvfs() function or equivalent in the
35510 operating system. Most, but not all versions of Unix that support Exim have
35511 this. For this particular stripchart, the top of the chart always represents
35512 100%, and the scale is given as "x10%". This chart is configured by setting
35513 SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the Local/eximon.conf
35514 file.
35515
35516
35517 54.3 Main action buttons
35518 ------------------------
35519
35520 Below the stripcharts there is an action button for quitting the monitor. Next
35521 to this is another button marked "Size". They are placed here so that shrinking
35522 the window to its default minimum size leaves just the queue count stripchart
35523 and these two buttons visible. Pressing the "Size" button causes the window to
35524 expand to its maximum size, unless it is already at the maximum, in which case
35525 it is reduced to its minimum.
35526
35527 When expanding to the maximum, if the window cannot be fully seen where it
35528 currently is, it is moved back to where it was the last time it was at full
35529 size. When it is expanding from its minimum size, the old position is
35530 remembered, and next time it is reduced to the minimum it is moved back there.
35531
35532 The idea is that you can keep a reduced window just showing one or two
35533 stripcharts at a convenient place on your screen, easily expand it to show the
35534 full window when required, and just as easily put it back to what it was. The
35535 idea is copied from what the twm window manager does for its f.fullzoom action.
35536 The minimum size of the window can be changed by setting the MIN_HEIGHT and
35537 MIN_WIDTH values in Local/eximon.conf.
35538
35539 Normally, the monitor starts up with the window at its full size, but it can be
35540 built so that it starts up with the window at its smallest size, by setting
35541 START_SMALL=yes in Local/eximon.conf.
35542
35543
35544 54.4 The log display
35545 --------------------
35546
35547 The second section of the window is an area in which a display of the tail of
35548 the main log is maintained. To save space on the screen, the timestamp on each
35549 log line is shortened by removing the date and, if log_timezone is set, the
35550 timezone. The log tail is not available when the only destination for logging
35551 data is syslog, unless the syslog lines are routed to a local file whose name
35552 is passed to eximon via the EXIMON_LOG_FILE_PATH environment variable.
35553
35554 The log sub-window has a scroll bar at its lefthand side which can be used to
35555 move back to look at earlier text, and the up and down arrow keys also have a
35556 scrolling effect. The amount of log that is kept depends on the setting of
35557 LOG_BUFFER in Local/eximon.conf, which specifies the amount of memory to use.
35558 When this is full, the earlier 50% of data is discarded - this is much more
35559 efficient than throwing it away line by line. The sub-window also has a
35560 horizontal scroll bar for accessing the ends of long log lines. This is the
35561 only means of horizontal scrolling; the right and left arrow keys are not
35562 available. Text can be cut from this part of the window using the mouse in the
35563 normal way. The size of this subwindow is controlled by parameters in the
35564 configuration file Local/eximon.conf.
35565
35566 Searches of the text in the log window can be carried out by means of the ^R
35567 and ^S keystrokes, which default to a reverse and a forward search,
35568 respectively. The search covers only the text that is displayed in the window.
35569 It cannot go further back up the log.
35570
35571 The point from which the search starts is indicated by a caret marker. This is
35572 normally at the end of the text in the window, but can be positioned explicitly
35573 by pointing and clicking with the left mouse button, and is moved automatically
35574 by a successful search. If new text arrives in the window when it is scrolled
35575 back, the caret remains where it is, but if the window is not scrolled back,
35576 the caret is moved to the end of the new text.
35577
35578 Pressing ^R or ^S pops up a window into which the search text can be typed.
35579 There are buttons for selecting forward or reverse searching, for carrying out
35580 the search, and for cancelling. If the "Search" button is pressed, the search
35581 happens and the window remains so that further searches can be done. If the
35582 "Return" key is pressed, a single search is done and the window is closed. If ^
35583 C is typed the search is cancelled.
35584
35585 The searching facility is implemented using the facilities of the Athena text
35586 widget. By default this pops up a window containing both "search" and "replace"
35587 options. In order to suppress the unwanted "replace" portion for eximon, a
35588 modified version of the TextPop widget is distributed with Exim. However, the
35589 linkers in BSDI and HP-UX seem unable to handle an externally provided version
35590 of TextPop when the remaining parts of the text widget come from the standard
35591 libraries. The compile-time option EXIMON_TEXTPOP can be unset to cut out the
35592 modified TextPop, making it possible to build Eximon on these systems, at the
35593 expense of having unwanted items in the search popup window.
35594
35595
35596 54.5 The queue display
35597 ----------------------
35598
35599 The bottom section of the monitor window contains a list of all messages that
35600 are in the queue, which includes those currently being received or delivered,
35601 as well as those awaiting delivery. The size of this subwindow is controlled by
35602 parameters in the configuration file Local/eximon.conf, and the frequency at
35603 which it is updated is controlled by another parameter in the same file - the
35604 default is 5 minutes, since queue scans can be quite expensive. However, there
35605 is an "Update" action button just above the display which can be used to force
35606 an update of the queue display at any time.
35607
35608 When a host is down for some time, a lot of pending mail can build up for it,
35609 and this can make it hard to deal with other messages in the queue. To help
35610 with this situation there is a button next to "Update" called "Hide". If
35611 pressed, a dialogue box called "Hide addresses ending with" is put up. If you
35612 type anything in here and press "Return", the text is added to a chain of such
35613 texts, and if every undelivered address in a message matches at least one of
35614 the texts, the message is not displayed.
35615
35616 If there is an address that does not match any of the texts, all the addresses
35617 are displayed as normal. The matching happens on the ends of addresses so, for
35618 example, cam.ac.uk specifies all addresses in Cambridge, while
35619 xxx@foo.com.example specifies just one specific address. When any hiding has
35620 been set up, a button called "Unhide" is displayed. If pressed, it cancels all
35621 hiding. Also, to ensure that hidden messages do not get forgotten, a hide
35622 request is automatically cancelled after one hour.
35623
35624 While the dialogue box is displayed, you can't press any buttons or do anything
35625 else to the monitor window. For this reason, if you want to cut text from the
35626 queue display to use in the dialogue box, you have to do the cutting before
35627 pressing the "Hide" button.
35628
35629 The queue display contains, for each unhidden queued message, the length of
35630 time it has been in the queue, the size of the message, the message id, the
35631 message sender, and the first undelivered recipient, all on one line. If it is
35632 a bounce message, the sender is shown as "<>". If there is more than one
35633 recipient to which the message has not yet been delivered, subsequent ones are
35634 listed on additional lines, up to a maximum configured number, following which
35635 an ellipsis is displayed. Recipients that have already received the message are
35636 not shown.
35637
35638 If a message is frozen, an asterisk is displayed at the left-hand side.
35639
35640 The queue display has a vertical scroll bar, and can also be scrolled by means
35641 of the arrow keys. Text can be cut from it using the mouse in the normal way.
35642 The text searching facilities, as described above for the log window, are also
35643 available, but the caret is always moved to the end of the text when the queue
35644 display is updated.
35645
35646
35647 54.6 The queue menu
35648 -------------------
35649
35650 If the shift key is held down and the left button is clicked when the mouse
35651 pointer is over the text for any message, an action menu pops up, and the first
35652 line of the queue display for the message is highlighted. This does not affect
35653 any selected text.
35654
35655 If you want to use some other event for popping up the menu, you can set the
35656 MENU_EVENT parameter in Local/eximon.conf to change the default, or set
35657 EXIMON_MENU_EVENT in the environment before starting the monitor. The value set
35658 in this parameter is a standard X event description. For example, to run eximon
35659 using ctrl rather than shift you could use
35660
35661 EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
35662
35663 The title of the menu is the message id, and it contains entries which act as
35664 follows:
35665
35666 * message log: The contents of the message log for the message are displayed
35667 in a new text window.
35668
35669 * headers: Information from the spool file that contains the envelope
35670 information and headers is displayed in a new text window. See chapter 56
35671 for a description of the format of spool files.
35672
35673 * body: The contents of the spool file containing the body of the message are
35674 displayed in a new text window. There is a default limit of 20,000 bytes to
35675 the amount of data displayed. This can be changed by setting the BODY_MAX
35676 option at compile time, or the EXIMON_BODY_MAX option at runtime.
35677
35678 * deliver message: A call to Exim is made using the -M option to request
35679 delivery of the message. This causes an automatic thaw if the message is
35680 frozen. The -v option is also set, and the output from Exim is displayed in
35681 a new text window. The delivery is run in a separate process, to avoid
35682 holding up the monitor while the delivery proceeds.
35683
35684 * freeze message: A call to Exim is made using the -Mf option to request that
35685 the message be frozen.
35686
35687 * thaw message: A call to Exim is made using the -Mt option to request that
35688 the message be thawed.
35689
35690 * give up on msg: A call to Exim is made using the -Mg option to request that
35691 Exim gives up trying to deliver the message. A bounce message is generated
35692 for any remaining undelivered addresses.
35693
35694 * remove message: A call to Exim is made using the -Mrm option to request
35695 that the message be deleted from the system without generating a bounce
35696 message.
35697
35698 * add recipient: A dialog box is displayed into which a recipient address can
35699 be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
35700 is set in Local/eximon.conf, the address is qualified with that domain.
35701 Otherwise it must be entered as a fully qualified address. Pressing RETURN
35702 causes a call to Exim to be made using the -Mar option to request that an
35703 additional recipient be added to the message, unless the entry box is
35704 empty, in which case no action is taken.
35705
35706 * mark delivered: A dialog box is displayed into which a recipient address
35707 can be typed. If the address is not qualified and the QUALIFY_DOMAIN
35708 parameter is set in Local/eximon.conf, the address is qualified with that
35709 domain. Otherwise it must be entered as a fully qualified address. Pressing
35710 RETURN causes a call to Exim to be made using the -Mmd option to mark the
35711 given recipient address as already delivered, unless the entry box is
35712 empty, in which case no action is taken.
35713
35714 * mark all delivered: A call to Exim is made using the -Mmad option to mark
35715 all recipient addresses as already delivered.
35716
35717 * edit sender: A dialog box is displayed initialized with the current
35718 sender's address. Pressing RETURN causes a call to Exim to be made using
35719 the -Mes option to replace the sender address, unless the entry box is
35720 empty, in which case no action is taken. If you want to set an empty sender
35721 (as in bounce messages), you must specify it as "<>". Otherwise, if the
35722 address is not qualified and the QUALIFY_DOMAIN parameter is set in Local/
35723 eximon.conf, the address is qualified with that domain.
35724
35725 When a delivery is forced, a window showing the -v output is displayed. In
35726 other cases when a call to Exim is made, if there is any output from Exim (in
35727 particular, if the command fails) a window containing the command and the
35728 output is displayed. Otherwise, the results of the action are normally apparent
35729 from the log and queue displays. However, if you set ACTION_OUTPUT=yes in Local
35730 /eximon.conf, a window showing the Exim command is always opened, even if no
35731 output is generated.
35732
35733 The queue display is automatically updated for actions such as freezing and
35734 thawing, unless ACTION_QUEUE_UPDATE=no has been set in Local/eximon.conf. In
35735 this case the "Update" button has to be used to force an update of the display
35736 after one of these actions.
35737
35738 In any text window that is displayed as result of a menu action, the normal
35739 cut-and-paste facility is available, and searching can be carried out using ^R
35740 and ^S, as described above for the log tail window.
35741
35742
35743
35744 ===============================================================================
35745 55. SECURITY CONSIDERATIONS
35746
35747 This chapter discusses a number of issues concerned with security, some of
35748 which are also covered in other parts of this manual.
35749
35750 For reasons that this author does not understand, some people have promoted
35751 Exim as a "particularly secure" mailer. Perhaps it is because of the existence
35752 of this chapter in the documentation. However, the intent of the chapter is
35753 simply to describe the way Exim works in relation to certain security concerns,
35754 not to make any specific claims about the effectiveness of its security as
35755 compared with other MTAs.
35756
35757 What follows is a description of the way Exim is supposed to be. Best efforts
35758 have been made to try to ensure that the code agrees with the theory, but an
35759 absence of bugs can never be guaranteed. Any that are reported will get fixed
35760 as soon as possible.
35761
35762
35763 55.1 Building a more "hardened" Exim
35764 ------------------------------------
35765
35766 There are a number of build-time options that can be set in Local/Makefile to
35767 create Exim binaries that are "harder" to attack, in particular by a rogue Exim
35768 administrator who does not have the root password, or by someone who has
35769 penetrated the Exim (but not the root) account. These options are as follows:
35770
35771 * ALT_CONFIG_PREFIX can be set to a string that is required to match the
35772 start of any filenames used with the -C option. When it is set, these
35773 filenames are also not allowed to contain the sequence "/../". (However, if
35774 the value of the -C option is identical to the value of CONFIGURE_FILE in
35775 Local/Makefile, Exim ignores -C and proceeds as usual.) There is no default
35776 setting for ALT_CONFIG_PREFIX.
35777
35778 If the permitted configuration files are confined to a directory to which
35779 only root has access, this guards against someone who has broken into the
35780 Exim account from running a privileged Exim with an arbitrary configuration
35781 file, and using it to break into other accounts.
35782
35783 * If a non-trusted configuration file (i.e. not the default configuration
35784 file or one which is trusted by virtue of being listed in the
35785 TRUSTED_CONFIG_LIST file) is specified with -C, or if macros are given with
35786 -D (but see the next item), then root privilege is retained only if the
35787 caller of Exim is root. This locks out the possibility of testing a
35788 configuration using -C right through message reception and delivery, even
35789 if the caller is root. The reception works, but by that time, Exim is
35790 running as the Exim user, so when it re-execs to regain privilege for the
35791 delivery, the use of -C causes privilege to be lost. However, root can test
35792 reception and delivery using two separate commands.
35793
35794 * The WHITELIST_D_MACROS build option declares some macros to be safe to
35795 override with -D if the real uid is one of root, the Exim run-time user or
35796 the CONFIGURE_OWNER, if defined. The potential impact of this option is
35797 limited by requiring the run-time value supplied to -D to match a regex
35798 that errs on the restrictive side. Requiring build-time selection of safe
35799 macros is onerous but this option is intended solely as a transition
35800 mechanism to permit previously-working configurations to continue to work
35801 after release 4.73.
35802
35803 * If DISABLE_D_OPTION is defined, the use of the -D command line option is
35804 disabled.
35805
35806 * FIXED_NEVER_USERS can be set to a colon-separated list of users that are
35807 never to be used for any deliveries. This is like the never_users runtime
35808 option, but it cannot be overridden; the runtime option adds additional
35809 users to the list. The default setting is "root"; this prevents a non-root
35810 user who is permitted to modify the runtime file from using Exim as a way
35811 to get root.
35812
35813
35814 55.2 Root privilege
35815 -------------------
35816
35817 The Exim binary is normally setuid to root, which means that it gains root
35818 privilege (runs as root) when it starts execution. In some special cases (for
35819 example, when the daemon is not in use and there are no local deliveries), it
35820 may be possible to run Exim setuid to some user other than root. This is
35821 discussed in the next section. However, in most installations, root privilege
35822 is required for two things:
35823
35824 * To set up a socket connected to the standard SMTP port (25) when
35825 initialising the listening daemon. If Exim is run from inetd, this
35826 privileged action is not required.
35827
35828 * To be able to change uid and gid in order to read users' .forward files and
35829 perform local deliveries as the receiving user or as specified in the
35830 configuration.
35831
35832 It is not necessary to be root to do any of the other things Exim does, such as
35833 receiving messages and delivering them externally over SMTP, and it is
35834 obviously more secure if Exim does not run as root except when necessary. For
35835 this reason, a user and group for Exim to use must be defined in Local/Makefile
35836 . These are known as "the Exim user" and "the Exim group". Their values can be
35837 changed by the runtime configuration, though this is not recommended. Often a
35838 user called exim is used, but some sites use mail or another user name
35839 altogether.
35840
35841 Exim uses setuid() whenever it gives up root privilege. This is a permanent
35842 abdication; the process cannot regain root afterwards. Prior to release 4.00,
35843 seteuid() was used in some circumstances, but this is no longer the case.
35844
35845 After a new Exim process has interpreted its command line options, it changes
35846 uid and gid in the following cases:
35847
35848 * If the -C option is used to specify an alternate configuration file, or if
35849 the -D option is used to define macro values for the configuration, and the
35850 calling process is not running as root, the uid and gid are changed to
35851 those of the calling process. However, if DISABLE_D_OPTION is defined in
35852 Local/Makefile, the -D option may not be used at all. If WHITELIST_D_MACROS
35853 is defined in Local/Makefile, then some macro values can be supplied if the
35854 calling process is running as root, the Exim run-time user or
35855 CONFIGURE_OWNER, if defined.
35856
35857 * If the expansion test option (-be) or one of the filter testing options (
35858 -bf or -bF) are used, the uid and gid are changed to those of the calling
35859 process.
35860
35861 * If the process is not a daemon process or a queue runner process or a
35862 delivery process or a process for testing address routing (started with -bt
35863 ), the uid and gid are changed to the Exim user and group. This means that
35864 Exim always runs under its own uid and gid when receiving messages. This
35865 also applies when testing address verification (the -bv option) and testing
35866 incoming message policy controls (the -bh option).
35867
35868 * For a daemon, queue runner, delivery, or address testing process, the uid
35869 remains as root at this stage, but the gid is changed to the Exim group.
35870
35871 The processes that initially retain root privilege behave as follows:
35872
35873 * A daemon process changes the gid to the Exim group and the uid to the Exim
35874 user after setting up one or more listening sockets. The initgroups()
35875 function is called, so that if the Exim user is in any additional groups,
35876 they will be used during message reception.
35877
35878 * A queue runner process retains root privilege throughout its execution. Its
35879 job is to fork a controlled sequence of delivery processes.
35880
35881 * A delivery process retains root privilege throughout most of its execution,
35882 but any actual deliveries (that is, the transports themselves) are run in
35883 subprocesses which always change to a non-root uid and gid. For local
35884 deliveries this is typically the uid and gid of the owner of the mailbox;
35885 for remote deliveries, the Exim uid and gid are used. Once all the delivery
35886 subprocesses have been run, a delivery process changes to the Exim uid and
35887 gid while doing post-delivery tidying up such as updating the retry
35888 database and generating bounce and warning messages.
35889
35890 While the recipient addresses in a message are being routed, the delivery
35891 process runs as root. However, if a user's filter file has to be processed,
35892 this is done in a subprocess that runs under the individual user's uid and
35893 gid. A system filter is run as root unless system_filter_user is set.
35894
35895 * A process that is testing addresses (the -bt option) runs as root so that
35896 the routing is done in the same environment as a message delivery.
35897
35898
35899 55.3 Running Exim without privilege
35900 -----------------------------------
35901
35902 Some installations like to run Exim in an unprivileged state for more of its
35903 operation, for added security. Support for this mode of operation is provided
35904 by the global option deliver_drop_privilege. When this is set, the uid and gid
35905 are changed to the Exim user and group at the start of a delivery process (and
35906 also queue runner and address testing processes). This means that address
35907 routing is no longer run as root, and the deliveries themselves cannot change
35908 to any other uid.
35909
35910 Leaving the binary setuid to root, but setting deliver_drop_privilege means
35911 that the daemon can still be started in the usual way, and it can respond
35912 correctly to SIGHUP because the re-invocation regains root privilege.
35913
35914 An alternative approach is to make Exim setuid to the Exim user and also setgid
35915 to the Exim group. If you do this, the daemon must be started from a root
35916 process. (Calling Exim from a root process makes it behave in the way it does
35917 when it is setuid root.) However, the daemon cannot restart itself after a
35918 SIGHUP signal because it cannot regain privilege.
35919
35920 It is still useful to set deliver_drop_privilege in this case, because it stops
35921 Exim from trying to re-invoke itself to do a delivery after a message has been
35922 received. Such a re-invocation is a waste of resources because it has no
35923 effect.
35924
35925 If restarting the daemon is not an issue (for example, if mua_wrapper is set,
35926 or inetd is being used instead of a daemon), having the binary setuid to the
35927 Exim user seems a clean approach, but there is one complication:
35928
35929 In this style of operation, Exim is running with the real uid and gid set to
35930 those of the calling process, and the effective uid/gid set to Exim's values.
35931 Ideally, any association with the calling process' uid/gid should be dropped,
35932 that is, the real uid/gid should be reset to the effective values so as to
35933 discard any privileges that the caller may have. While some operating systems
35934 have a function that permits this action for a non-root effective uid, quite a
35935 number of them do not. Because of this lack of standardization, Exim does not
35936 address this problem at this time.
35937
35938 For this reason, the recommended approach for "mostly unprivileged" running is
35939 to keep the Exim binary setuid to root, and to set deliver_drop_privilege. This
35940 also has the advantage of allowing a daemon to be used in the most
35941 straightforward way.
35942
35943 If you configure Exim not to run delivery processes as root, there are a number
35944 of restrictions on what you can do:
35945
35946 * You can deliver only as the Exim user/group. You should explicitly use the
35947 user and group options to override routers or local transports that
35948 normally deliver as the recipient. This makes sure that configurations that
35949 work in this mode function the same way in normal mode. Any implicit or
35950 explicit specification of another user causes an error.
35951
35952 * Use of .forward files is severely restricted, such that it is usually not
35953 worthwhile to include them in the configuration.
35954
35955 * Users who wish to use .forward would have to make their home directory and
35956 the file itself accessible to the Exim user. Pipe and append-to-file
35957 entries, and their equivalents in Exim filters, cannot be used. While they
35958 could be enabled in the Exim user's name, that would be insecure and not
35959 very useful.
35960
35961 * Unless the local user mailboxes are all owned by the Exim user (possible in
35962 some POP3 or IMAP-only environments):
35963
35964 1. They must be owned by the Exim group and be writeable by that group.
35965 This implies you must set mode in the appendfile configuration, as well
35966 as the mode of the mailbox files themselves.
35967
35968 2. You must set no_check_owner, since most or all of the files will not be
35969 owned by the Exim user.
35970
35971 3. You must set file_must_exist, because Exim cannot set the owner
35972 correctly on a newly created mailbox when unprivileged. This also
35973 implies that new mailboxes need to be created manually.
35974
35975 These restrictions severely restrict what can be done in local deliveries.
35976 However, there are no restrictions on remote deliveries. If you are running a
35977 gateway host that does no local deliveries, setting deliver_drop_privilege
35978 gives more security at essentially no cost.
35979
35980 If you are using the mua_wrapper facility (see chapter 51),
35981 deliver_drop_privilege is forced to be true.
35982
35983
35984 55.4 Delivering to local files
35985 ------------------------------
35986
35987 Full details of the checks applied by appendfile before it writes to a file are
35988 given in chapter 26.
35989
35990
35991 55.5 Running local commands
35992 ---------------------------
35993
35994 There are a number of ways in which an administrator can configure Exim to run
35995 commands based upon received, untrustworthy, data. Further, in some
35996 configurations a user who can control a .forward file can also arrange to run
35997 commands. Configuration to check includes, but is not limited to:
35998
35999 * Use of use_shell in the pipe transport: various forms of shell command
36000 injection may be possible with this option present. It is dangerous and
36001 should be used only with considerable caution. Consider constraints which
36002 whitelist allowed characters in a variable which is to be used in a pipe
36003 transport that has use_shell enabled.
36004
36005 * A number of options such as forbid_filter_run, forbid_filter_perl,
36006 forbid_filter_dlfunc and so forth which restrict facilities available to
36007 .forward files in a redirect router. If Exim is running on a central mail
36008 hub to which ordinary users do not have shell access, but home directories
36009 are NFS mounted (for instance) then administrators should review the list
36010 of these forbid options available, and should bear in mind that the options
36011 that may need forbidding can change as new features are added between
36012 releases.
36013
36014 * The ${run...} expansion item does not use a shell by default, but
36015 administrators can configure use of /bin/sh as part of the command. Such
36016 invocations should be viewed with prejudicial suspicion.
36017
36018 * Administrators who use embedded Perl are advised to explore how Perl's
36019 taint checking might apply to their usage.
36020
36021 * Use of ${expand...} is somewhat analogous to shell's eval builtin and
36022 administrators are well advised to view its use with suspicion, in case
36023 (for instance) it allows a local-part to contain embedded Exim directives.
36024
36025 * Use of ${match_local_part...} and friends becomes more dangerous if Exim
36026 was built with EXPAND_LISTMATCH_RHS defined: the second string in each can
36027 reference arbitrary lists and files, rather than just being a list of
36028 opaque strings. The EXPAND_LISTMATCH_RHS option was added and set false by
36029 default because of real-world security vulnerabilities caused by its use
36030 with untrustworthy data injected in, for SQL injection attacks. Consider
36031 the use of the inlisti expansion condition instead.
36032
36033
36034 55.6 Trust in configuration data
36035 --------------------------------
36036
36037 If configuration data for Exim can come from untrustworthy sources, there are
36038 some issues to be aware of:
36039
36040 * Use of ${expand...} may provide a path for shell injection attacks.
36041
36042 * Letting untrusted data provide a regular expression is unwise.
36043
36044 * Using ${match...} to apply a fixed regular expression against untrusted
36045 data may result in pathological behaviour within PCRE. Be aware of what
36046 "backtracking" means and consider options for being more strict with a
36047 regular expression. Avenues to explore include limiting what can match
36048 (avoiding "." when "[a-z0-9]" or other character class will do), use of
36049 atomic grouping and possessive quantifiers or just not using regular
36050 expressions against untrusted data.
36051
36052 * It can be important to correctly use ${quote:...}, ${quote_local_part:...}
36053 and ${quote_<lookup-type>:...} expansion items to ensure that data is
36054 correctly constructed.
36055
36056 * Some lookups might return multiple results, even though normal usage is
36057 only expected to yield one result.
36058
36059
36060 55.7 IPv4 source routing
36061 ------------------------
36062
36063 Many operating systems suppress IP source-routed packets in the kernel, but
36064 some cannot be made to do this, so Exim does its own check. It logs incoming
36065 IPv4 source-routed TCP calls, and then drops them. Things are all different in
36066 IPv6. No special checking is currently done.
36067
36068
36069 55.8 The VRFY, EXPN, and ETRN commands in SMTP
36070 ----------------------------------------------
36071
36072 Support for these SMTP commands is disabled by default. If required, they can
36073 be enabled by defining suitable ACLs.
36074
36075
36076 55.9 Privileged users
36077 ---------------------
36078
36079 Exim recognizes two sets of users with special privileges. Trusted users are
36080 able to submit new messages to Exim locally, but supply their own sender
36081 addresses and information about a sending host. For other users submitting
36082 local messages, Exim sets up the sender address from the uid, and doesn't
36083 permit a remote host to be specified.
36084
36085 However, an untrusted user is permitted to use the -f command line option in
36086 the special form -f <> to indicate that a delivery failure for the message
36087 should not cause an error report. This affects the message's envelope, but it
36088 does not affect the Sender: header. Untrusted users may also be permitted to
36089 use specific forms of address with the -f option by setting the
36090 untrusted_set_sender option.
36091
36092 Trusted users are used to run processes that receive mail messages from some
36093 other mail domain and pass them on to Exim for delivery either locally, or over
36094 the Internet. Exim trusts a caller that is running as root, as the Exim user,
36095 as any user listed in the trusted_users configuration option, or under any
36096 group listed in the trusted_groups option.
36097
36098 Admin users are permitted to do things to the messages on Exim's queue. They
36099 can freeze or thaw messages, cause them to be returned to their senders, remove
36100 them entirely, or modify them in various ways. In addition, admin users can run
36101 the Exim monitor and see all the information it is capable of providing, which
36102 includes the contents of files on the spool.
36103
36104 By default, the use of the -M and -q options to cause Exim to attempt delivery
36105 of messages on its queue is restricted to admin users. This restriction can be
36106 relaxed by setting the no_prod_requires_admin option. Similarly, the use of -bp
36107 (and its variants) to list the contents of the queue is also restricted to
36108 admin users. This restriction can be relaxed by setting
36109 no_queue_list_requires_admin.
36110
36111 Exim recognizes an admin user if the calling process is running as root or as
36112 the Exim user or if any of the groups associated with the calling process is
36113 the Exim group. It is not necessary actually to be running under the Exim
36114 group. However, if admin users who are not root or the Exim user are to access
36115 the contents of files on the spool via the Exim monitor (which runs
36116 unprivileged), Exim must be built to allow group read access to its spool
36117 files.
36118
36119 By default, regular users are trusted to perform basic testing and
36120 introspection commands, as themselves. This setting can be tightened by setting
36121 the commandline_checks_require_admin option. This affects most of the checking
36122 options, such as -be and anything else -b*.
36123
36124
36125 55.10 Spool files
36126 -----------------
36127
36128 Exim's spool directory and everything it contains is owned by the Exim user and
36129 set to the Exim group. The mode for spool files is defined in the Local/
36130 Makefile configuration file, and defaults to 0640. This means that any user who
36131 is a member of the Exim group can access these files.
36132
36133
36134 55.11 Use of argv[0]
36135 --------------------
36136
36137 Exim examines the last component of argv[0], and if it matches one of a set of
36138 specific strings, Exim assumes certain options. For example, calling Exim with
36139 the last component of argv[0] set to "rsmtp" is exactly equivalent to calling
36140 it with the option -bS. There are no security implications in this.
36141
36142
36143 55.12 Use of %f formatting
36144 --------------------------
36145
36146 The only use made of "%f" by Exim is in formatting load average values. These
36147 are actually stored in integer variables as 1000 times the load average.
36148 Consequently, their range is limited and so therefore is the length of the
36149 converted output.
36150
36151
36152 55.13 Embedded Exim path
36153 ------------------------
36154
36155 Exim uses its own path name, which is embedded in the code, only when it needs
36156 to re-exec in order to regain root privilege. Therefore, it is not root when it
36157 does so. If some bug allowed the path to get overwritten, it would lead to an
36158 arbitrary program's being run as exim, not as root.
36159
36160
36161 55.14 Dynamic module directory
36162 ------------------------------
36163
36164 Any dynamically loadable modules must be installed into the directory defined
36165 in "LOOKUP_MODULE_DIR" in Local/Makefile for Exim to permit loading it.
36166
36167
36168 55.15 Use of sprintf()
36169 ----------------------
36170
36171 A large number of occurrences of "sprintf" in the code are actually calls to
36172 string_sprintf(), a function that returns the result in malloc'd store. The
36173 intermediate formatting is done into a large fixed buffer by a function that
36174 runs through the format string itself, and checks the length of each conversion
36175 before performing it, thus preventing buffer overruns.
36176
36177 The remaining uses of sprintf() happen in controlled circumstances where the
36178 output buffer is known to be sufficiently long to contain the converted string.
36179
36180
36181 55.16 Use of debug_printf() and log_write()
36182 -------------------------------------------
36183
36184 Arbitrary strings are passed to both these functions, but they do their
36185 formatting by calling the function string_vformat(), which runs through the
36186 format string itself, and checks the length of each conversion.
36187
36188
36189 55.17 Use of strcat() and strcpy()
36190 ----------------------------------
36191
36192 These are used only in cases where the output buffer is known to be large
36193 enough to hold the result.
36194
36195
36196
36197 ===============================================================================
36198 56. FORMAT OF SPOOL FILES
36199
36200 A message on Exim's queue consists of two files, whose names are the message id
36201 followed by -D and -H, respectively. The data portion of the message is kept in
36202 the -D file on its own. The message's envelope, status, and headers are all
36203 kept in the -H file, whose format is described in this chapter. Each of these
36204 two files contains the final component of its own name as its first line. This
36205 is insurance against disk crashes where the directory is lost but the files
36206 themselves are recoverable.
36207
36208 The file formats may be changed, or new formats added, at any release. Spool
36209 files are not intended as an interface to other programs and should not be used
36210 as such.
36211
36212 Some people are tempted into editing -D files in order to modify messages. You
36213 need to be extremely careful if you do this; it is not recommended and you are
36214 on your own if you do it. Here are some of the pitfalls:
36215
36216 * You must ensure that Exim does not try to deliver the message while you are
36217 fiddling with it. The safest way is to take out a write lock on the -D
36218 file, which is what Exim itself does, using fcntl(). If you update the file
36219 in place, the lock will be retained. If you write a new file and rename it,
36220 the lock will be lost at the instant of rename.
36221
36222 * If you change the number of lines in the file, the value of $body_linecount
36223 , which is stored in the -H file, will be incorrect and can cause
36224 incomplete transmission of messages or undeliverable messages.
36225
36226 * If the message is in MIME format, you must take care not to break it.
36227
36228 * If the message is cryptographically signed, any change will invalidate the
36229 signature.
36230
36231 All in all, modifying -D files is fraught with danger.
36232
36233 Files whose names end with -J may also be seen in the input directory (or its
36234 subdirectories when split_spool_directory is set). These are journal files,
36235 used to record addresses to which the message has been delivered during the
36236 course of a delivery attempt. If there are still undelivered recipients at the
36237 end, the -H file is updated, and the -J file is deleted. If, however, there is
36238 some kind of crash (for example, a power outage) before this happens, the -J
36239 file remains in existence. When Exim next processes the message, it notices the
36240 -J file and uses it to update the -H file before starting the next delivery
36241 attempt.
36242
36243 Files whose names end with -K or .eml may also be seen in the spool. These are
36244 temporaries used for DKIM or malware processing, when that is used. They should
36245 be tidied up by normal operations; any old ones are probably relics of crashes
36246 and can be removed.
36247
36248
36249 56.1 Format of the -H file
36250 --------------------------
36251
36252 The second line of the -H file contains the login name for the uid of the
36253 process that called Exim to read the message, followed by the numerical uid and
36254 gid. For a locally generated message, this is normally the user who sent the
36255 message. For a message received over TCP/IP via the daemon, it is normally the
36256 Exim user.
36257
36258 The third line of the file contains the address of the message's sender as
36259 transmitted in the envelope, contained in angle brackets. The sender address is
36260 empty for bounce messages. For incoming SMTP mail, the sender address is given
36261 in the MAIL command. For locally generated mail, the sender address is created
36262 by Exim from the login name of the current user and the configured
36263 qualify_domain. However, this can be overridden by the -f option or a leading
36264 "From " line if the caller is trusted, or if the supplied address is "<>" or an
36265 address that matches untrusted_set_senders.
36266
36267 The fourth line contains two numbers. The first is the time that the message
36268 was received, in the conventional Unix form - the number of seconds since the
36269 start of the epoch. The second number is a count of the number of messages
36270 warning of delayed delivery that have been sent to the sender.
36271
36272 There follow a number of lines starting with a hyphen. These can appear in any
36273 order, and are omitted when not relevant:
36274
36275 -acl <number> <length>
36276
36277 This item is obsolete, and is not generated from Exim release 4.61 onwards;
36278 -aclc and -aclm are used instead. However, -acl is still recognized, to
36279 provide backward compatibility. In the old format, a line of this form is
36280 present for every ACL variable that is not empty. The number identifies the
36281 variable; the acl_cx variables are numbered 0-9 and the acl_mx variables
36282 are numbered 10-19. The length is the length of the data string for the
36283 variable. The string itself starts at the beginning of the next line, and
36284 is followed by a newline character. It may contain internal newlines.
36285
36286 -aclc <rest-of-name> <length>
36287
36288 A line of this form is present for every ACL connection variable that is
36289 defined. Note that there is a space between -aclc and the rest of the name.
36290 The length is the length of the data string for the variable. The string
36291 itself starts at the beginning of the next line, and is followed by a
36292 newline character. It may contain internal newlines.
36293
36294 -aclm <rest-of-name> <length>
36295
36296 A line of this form is present for every ACL message variable that is
36297 defined. Note that there is a space between -aclm and the rest of the name.
36298 The length is the length of the data string for the variable. The string
36299 itself starts at the beginning of the next line, and is followed by a
36300 newline character. It may contain internal newlines.
36301
36302 -active_hostname <hostname>
36303
36304 This is present if, when the message was received over SMTP, the value of
36305 $smtp_active_hostname was different to the value of $primary_hostname.
36306
36307 -allow_unqualified_recipient
36308
36309 This is present if unqualified recipient addresses are permitted in header
36310 lines (to stop such addresses from being qualified if rewriting occurs at
36311 transport time). Local messages that were input using -bnq and remote
36312 messages from hosts that match recipient_unqualified_hosts set this flag.
36313
36314 -allow_unqualified_sender
36315
36316 This is present if unqualified sender addresses are permitted in header
36317 lines (to stop such addresses from being qualified if rewriting occurs at
36318 transport time). Local messages that were input using -bnq and remote
36319 messages from hosts that match sender_unqualified_hosts set this flag.
36320
36321 -auth_id <text>
36322
36323 The id information for a message received on an authenticated SMTP
36324 connection - the value of the $authenticated_id variable.
36325
36326 -auth_sender <address>
36327
36328 The address of an authenticated sender - the value of the
36329 $authenticated_sender variable.
36330
36331 -body_linecount <number>
36332
36333 This records the number of lines in the body of the message, and is present
36334 unless -spool_file_wireformat is.
36335
36336 -body_zerocount <number>
36337
36338 This records the number of binary zero bytes in the body of the message,
36339 and is present if the number is greater than zero.
36340
36341 -deliver_firsttime
36342
36343 This is written when a new message is first added to the spool. When the
36344 spool file is updated after a deferral, it is omitted.
36345
36346 -frozen <time>
36347
36348 The message is frozen, and the freezing happened at <time>.
36349
36350 -helo_name <text>
36351
36352 This records the host name as specified by a remote host in a HELO or EHLO
36353 command.
36354
36355 -host_address <address>.<port>
36356
36357 This records the IP address of the host from which the message was received
36358 and the remote port number that was used. It is omitted for locally
36359 generated messages.
36360
36361 -host_auth <text>
36362
36363 If the message was received on an authenticated SMTP connection, this
36364 records the name of the authenticator - the value of the
36365 $sender_host_authenticated variable.
36366
36367 -host_lookup_failed
36368
36369 This is present if an attempt to look up the sending host's name from its
36370 IP address failed. It corresponds to the $host_lookup_failed variable.
36371
36372 -host_name <text>
36373
36374 This records the name of the remote host from which the message was
36375 received, if the host name was looked up from the IP address when the
36376 message was being received. It is not present if no reverse lookup was
36377 done.
36378
36379 -ident <text>
36380
36381 For locally submitted messages, this records the login of the originating
36382 user, unless it was a trusted user and the -oMt option was used to specify
36383 an ident value. For messages received over TCP/IP, this records the ident
36384 string supplied by the remote host, if any.
36385
36386 -interface_address <address>.<port>
36387
36388 This records the IP address of the local interface and the port number
36389 through which a message was received from a remote host. It is omitted for
36390 locally generated messages.
36391
36392 -local
36393
36394 The message is from a local sender.
36395
36396 -localerror
36397
36398 The message is a locally-generated bounce message.
36399
36400 -local_scan <string>
36401
36402 This records the data string that was returned by the local_scan() function
36403 when the message was received - the value of the $local_scan_data variable.
36404 It is omitted if no data was returned.
36405
36406 -manual_thaw
36407
36408 The message was frozen but has been thawed manually, that is, by an
36409 explicit Exim command rather than via the auto-thaw process.
36410
36411 -N
36412
36413 A testing delivery process was started using the -N option to suppress any
36414 actual deliveries, but delivery was deferred. At any further delivery
36415 attempts, -N is assumed.
36416
36417 -received_protocol
36418
36419 This records the value of the $received_protocol variable, which contains
36420 the name of the protocol by which the message was received.
36421
36422 -sender_set_untrusted
36423
36424 The envelope sender of this message was set by an untrusted local caller
36425 (used to ensure that the caller is displayed in queue listings).
36426
36427 -spam_score_int <number>
36428
36429 If a message was scanned by SpamAssassin, this is present. It records the
36430 value of $spam_score_int.
36431
36432 -spool_file_wireformat
36433
36434 The -D file for this message is in wire-format (for ESMTP CHUNKING) rather
36435 than Unix-format. The line-ending is CRLF rather than newline. There is
36436 still, however, no leading-dot-stuffing.
36437
36438 -tls_certificate_verified
36439
36440 A TLS certificate was received from the client that sent this message, and
36441 the certificate was verified by the server.
36442
36443 -tls_cipher <cipher name>
36444
36445 When the message was received over an encrypted connection, this records
36446 the name of the cipher suite that was used.
36447
36448 -tls_peerdn <peer DN>
36449
36450 When the message was received over an encrypted connection, and a
36451 certificate was received from the client, this records the Distinguished
36452 Name from that certificate.
36453
36454 Following the options there is a list of those addresses to which the message
36455 is not to be delivered. This set of addresses is initialized from the command
36456 line when the -t option is used and extract_addresses_remove_arguments is set;
36457 otherwise it starts out empty. Whenever a successful delivery is made, the
36458 address is added to this set. The addresses are kept internally as a balanced
36459 binary tree, and it is a representation of that tree which is written to the
36460 spool file. If an address is expanded via an alias or forward file, the
36461 original address is added to the tree when deliveries to all its child
36462 addresses are complete.
36463
36464 If the tree is empty, there is a single line in the spool file containing just
36465 the text "XX". Otherwise, each line consists of two letters, which are either Y
36466 or N, followed by an address. The address is the value for the node of the
36467 tree, and the letters indicate whether the node has a left branch and/or a
36468 right branch attached to it, respectively. If branches exist, they immediately
36469 follow. Here is an example of a three-node tree:
36470
36471 YY darcy@austen.fict.example
36472 NN alice@wonderland.fict.example
36473 NN editor@thesaurus.ref.example
36474
36475 After the non-recipients tree, there is a list of the message's recipients.
36476 This is a simple list, preceded by a count. It includes all the original
36477 recipients of the message, including those to whom the message has already been
36478 delivered. In the simplest case, the list contains one address per line. For
36479 example:
36480
36481 4
36482 editor@thesaurus.ref.example
36483 darcy@austen.fict.example
36484 rdo@foundation
36485 alice@wonderland.fict.example
36486
36487 However, when a child address has been added to the top-level addresses as a
36488 result of the use of the one_time option on a redirect router, each line is of
36489 the following form:
36490
36491 <top-level address> <errors_to address> <length>,<parent number>#<flag bits>
36492
36493 The 01 flag bit indicates the presence of the three other fields that follow
36494 the top-level address. Other bits may be used in future to support additional
36495 fields. The <parent number> is the offset in the recipients list of the
36496 original parent of the "one time" address. The first two fields are the
36497 envelope sender that is associated with this address and its length. If the
36498 length is zero, there is no special envelope sender (there are then two space
36499 characters in the line). A non-empty field can arise from a redirect router
36500 that has an errors_to setting.
36501
36502 A blank line separates the envelope and status information from the headers
36503 which follow. A header may occupy several lines of the file, and to save effort
36504 when reading it in, each header is preceded by a number and an identifying
36505 character. The number is the number of characters in the header, including any
36506 embedded newlines and the terminating newline. The character is one of the
36507 following:
36508
36509 <blank> header in which Exim has no special interest
36510 "B" Bcc: header
36511 "C" Cc: header
36512 "F" From: header
36513 "I" Message-id: header
36514 "P" Received: header - P for "postmark"
36515 "R" Reply-To: header
36516 "S" Sender: header
36517 "T" To: header
36518 "*" replaced or deleted header
36519
36520 Deleted or replaced (rewritten) headers remain in the spool file for debugging
36521 purposes. They are not transmitted when the message is delivered. Here is a
36522 typical set of headers:
36523
36524 111P Received: by hobbit.fict.example with local (Exim 4.00)
36525 id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100
36526 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example>
36527 038* X-rewrote-sender: bb@hobbit.fict.example
36528 042* From: Bilbo Baggins <bb@hobbit.fict.example>
36529 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example>
36530 099* To: alice@wonderland.fict.example, rdo@foundation,
36531 darcy@austen.fict.example, editor@thesaurus.ref.example
36532 104T To: alice@wonderland.fict.example, rdo@foundation.example,
36533 darcy@austen.fict.example, editor@thesaurus.ref.example
36534 038 Date: Fri, 11 May 2001 10:28:59 +0100
36535
36536 The asterisked headers indicate that the envelope sender, From: header, and To:
36537 header have been rewritten, the last one because routing expanded the
36538 unqualified domain foundation.
36539
36540
36541 56.2 Format of the -D file
36542 --------------------------
36543
36544 The data file is traditionally in Unix-standard format: lines are ended with an
36545 ASCII newline character. However, when the spool_wireformat main option is used
36546 some -D files can have an alternate format. This is flagged by a
36547 -spool_file_wireformat line in the corresponding -H file. The -D file lines
36548 (not including the first name-component line) are suitable for direct copying
36549 to the wire when transmitting using the ESMTP CHUNKING option, meaning lower
36550 processing overhead. Lines are terminated with an ASCII CRLF pair. There is no
36551 dot-stuffing (and no dot-termination).
36552
36553
36554
36555 ===============================================================================
36556 57. DKIM AND SPF
36557
36558
36559 57.1 DKIM (DomainKeys Identified Mail)
36560 --------------------------------------
36561
36562 DKIM is a mechanism by which messages sent by some entity can be provably
36563 linked to a domain which that entity controls. It permits reputation to be
36564 tracked on a per-domain basis, rather than merely upon source IP address. DKIM
36565 is documented in RFC 6376.
36566
36567 As DKIM relies on the message being unchanged in transit, messages handled by a
36568 mailing-list (which traditionally adds to the message) will not match any
36569 original DKIM signature.
36570
36571 DKIM support is compiled into Exim by default if TLS support is present. It can
36572 be disabled by setting DISABLE_DKIM=yes in Local/Makefile.
36573
36574 Exim's DKIM implementation allows for
36575
36576 1. Signing outgoing messages: This function is implemented in the SMTP
36577 transport. It can co-exist with all other Exim features (including
36578 transport filters) except cutthrough delivery.
36579
36580 2. Verifying signatures in incoming messages: This is implemented by an
36581 additional ACL (acl_smtp_dkim), which can be called several times per
36582 message, with different signature contexts.
36583
36584 In typical Exim style, the verification implementation does not include any
36585 default "policy". Instead it enables you to build your own policy using Exim's
36586 standard controls.
36587
36588 Please note that verification of DKIM signatures in incoming mail is turned on
36589 by default for logging (in the <= line) purposes.
36590
36591 Additional log detail can be enabled using the dkim_verbose log_selector. When
36592 set, for each signature in incoming email, exim will log a line displaying the
36593 most important signature details, and the signature status. Here is an example
36594 (with line-breaks added for clarity):
36595
36596 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
36597 d=facebookmail.com s=q1-2009b
36598 c=relaxed/relaxed a=rsa-sha1
36599 i=@facebookmail.com t=1252484542 [verification succeeded]
36600
36601 You might want to turn off DKIM verification processing entirely for internal
36602 or relay mail sources. To do that, set the dkim_disable_verify ACL control
36603 modifier. This should typically be done in the RCPT ACL, at points where you
36604 accept mail from relay sources (internal hosts or authenticated senders).
36605
36606
36607 57.2 Signing outgoing messages
36608 ------------------------------
36609
36610 For signing to be usable you must have published a DKIM record in DNS. Note
36611 that RFC 8301 says:
36612
36613 rsa-sha1 MUST NOT be used for signing or verifying.
36614
36615 Signers MUST use RSA keys of at least 1024 bits for all keys.
36616 Signers SHOULD use RSA keys of at least 2048 bits.
36617
36618 Note also that the key content (the 'p=' field) in the DNS record is different
36619 between RSA and EC keys; for the former it is the base64 of the ASN.1 for the
36620 RSA public key (equivalent to the private-key .pem with the header/trailer
36621 stripped) but for EC keys it is the base64 of the pure key; no ASN.1 wrapping.
36622
36623 Signing is enabled by setting private options on the SMTP transport. These
36624 options take (expandable) strings as arguments.
36625
36626 +-------------------------------------------------+
36627 |dkim_domain|Use: smtp|Type: string|Default: list*|
36628 +-------------------------------------------------+
36629
36630 The domain(s) you want to sign with. After expansion, this can be a list. Each
36631 element in turn is put into the $dkim_domain expansion variable while expanding
36632 the remaining signing options. If it is empty after expansion, DKIM signing is
36633 not done, and no error will result even if dkim_strict is set.
36634
36635 +---------------------------------------------------+
36636 |dkim_selector|Use: smtp|Type: string|Default: list*|
36637 +---------------------------------------------------+
36638
36639 This sets the key selector string. After expansion, which can use $dkim_domain,
36640 this can be a list. Each element in turn is put in the expansion variable
36641 $dkim_selector which may be used in the dkim_private_key option along with
36642 $dkim_domain. If the option is empty after expansion, DKIM signing is not done
36643 for this domain, and no error will result even if dkim_strict is set.
36644
36645 +-------------------------------------------------------+
36646 |dkim_private_key|Use: smtp|Type: string*|Default: unset|
36647 +-------------------------------------------------------+
36648
36649 This sets the private key to use. You can use the $dkim_domain and
36650 $dkim_selector expansion variables to determine the private key to use. The
36651 result can either
36652
36653 * be a valid RSA private key in ASCII armor (.pem file), including line
36654 breaks
36655
36656 * with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, be a valid Ed25519 private key
36657 (same format as above)
36658
36659 * start with a slash, in which case it is treated as a file that contains the
36660 private key
36661
36662 * be "0", "false" or the empty string, in which case the message will not be
36663 signed. This case will not result in an error, even if dkim_strict is set.
36664
36665 To generate keys under OpenSSL:
36666
36667 openssl genrsa -out dkim_rsa.private 2048
36668 openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM
36669
36670 Take the base-64 lines from the output of the second command, concatenated, for
36671 the DNS TXT record. See section 3.6 of RFC6376 for the record specification.
36672
36673 Under GnuTLS:
36674
36675 certtool --generate-privkey --rsa --bits=2048 --password='' -8 --outfile=dkim_rsa.private
36676 certtool --load-privkey=dkim_rsa.private --pubkey-info
36677
36678 Note that RFC 8301 says:
36679
36680 Signers MUST use RSA keys of at least 1024 bits for all keys.
36681 Signers SHOULD use RSA keys of at least 2048 bits.
36682
36683 Support for EC keys is being developed under https://datatracker.ietf.org/doc/
36684 draft-ietf-dcrup-dkim-crypto/. They are considerably smaller than RSA keys for
36685 equivalent protection. As they are a recent development, users should consider
36686 dual-signing (by setting a list of selectors, and an expansion for this option)
36687 for some transition period. The "_CRYPTO_SIGN_ED25519" macro will be defined if
36688 support is present for EC keys.
36689
36690 OpenSSL 1.1.1 and GnuTLS 3.6.0 can create Ed25519 private keys:
36691
36692 openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
36693 certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private
36694
36695 To produce the required public key value for a DNS record:
36696
36697 openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
36698 certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64
36699
36700 Note that the format of Ed25519 keys in DNS has not yet been decided; this
36701 release supports both of the leading candidates at this time, a future release
36702 will probably drop support for whichever proposal loses.
36703
36704 +-------------------------------------------------+
36705 |dkim_hash|Use: smtp|Type: string*|Default: sha256|
36706 +-------------------------------------------------+
36707
36708 Can be set to any one of the supported hash methods, which are:
36709
36710 * "sha1" - should not be used, is old and insecure
36711
36712 * "sha256" - the default
36713
36714 * "sha512" - possibly more secure but less well supported
36715
36716 Note that RFC 8301 says:
36717
36718 rsa-sha1 MUST NOT be used for signing or verifying.
36719
36720 +----------------------------------------------------+
36721 |dkim_identity|Use: smtp|Type: string*|Default: unset|
36722 +----------------------------------------------------+
36723
36724 If set after expansion, the value is used to set an "i=" tag in the signing
36725 header. The DKIM standards restrict the permissible syntax of this optional tag
36726 to a mail address, with possibly-empty local part, an @, and a domain identical
36727 to or subdomain of the "d=" tag value. Note that Exim does not check the value.
36728
36729 +-------------------------------------------------+
36730 |dkim_canon|Use: smtp|Type: string*|Default: unset|
36731 +-------------------------------------------------+
36732
36733 This option sets the canonicalization method used when signing a message. The
36734 DKIM RFC currently supports two methods: "simple" and "relaxed". The option
36735 defaults to "relaxed" when unset. Note: the current implementation only
36736 supports signing with the same canonicalization method for both headers and
36737 body.
36738
36739 +--------------------------------------------------+
36740 |dkim_strict|Use: smtp|Type: string*|Default: unset|
36741 +--------------------------------------------------+
36742
36743 This option defines how Exim behaves when signing a message that should be
36744 signed fails for some reason. When the expansion evaluates to either "1" or
36745 "true", Exim will defer. Otherwise Exim will send the message unsigned. You can
36746 use the $dkim_domain and $dkim_selector expansion variables here.
36747
36748 +------------------------------------------------------------+
36749 |dkim_sign_headers|Use: smtp|Type: string*|Default: see below|
36750 +------------------------------------------------------------+
36751
36752 If set, this option must expand to a colon-separated list of header names.
36753 Headers with these names, or the absence or such a header, will be included in
36754 the message signature. When unspecified, the header names listed in RFC4871
36755 will be used, whether or not each header is present in the message. The default
36756 list is available for the expansion in the macro "_DKIM_SIGN_HEADERS".
36757
36758 If a name is repeated, multiple headers by that name (or the absence thereof)
36759 will be signed. The textually later headers in the headers part of the message
36760 are signed first, if there are multiples.
36761
36762 A name can be prefixed with either an '=' or a '+' character. If an '=' prefix
36763 is used, all headers that are present with this name will be signed. If a '+'
36764 prefix if used, all headers that are present with this name will be signed, and
36765 one signature added for a missing header with the name will be appended.
36766
36767 +-------------------------------------------------------+
36768 |dkim_timestamps|Use: smtp|Type: integer*|Default: unset|
36769 +-------------------------------------------------------+
36770
36771 This option controls the inclusion of timestamp information in the signature.
36772 If not set, no such information will be included. Otherwise, must be an
36773 unsigned number giving an offset in seconds from the current time for the
36774 expiry tag (eg. 1209600 for two weeks); both creation (t=) and expiry (x=) tags
36775 will be included.
36776
36777 RFC 6376 lists these tags as RECOMMENDED.
36778
36779
36780 57.3 Verifying DKIM signatures in incoming mail
36781 -----------------------------------------------
36782
36783 Verification of DKIM signatures in SMTP incoming email is done for all messages
36784 for which an ACL control dkim_disable_verify has not been set. Performing
36785 verification sets up information used by the $authresults expansion item.
36786
36787 The acl_smtp_dkim ACL, which can examine and modify them. By default, this ACL
36788 is called once for each syntactically(!) correct signature in the incoming
36789 message. A missing ACL definition defaults to accept. If any ACL call does not
36790 accept, the message is not accepted. If a cutthrough delivery was in progress
36791 for the message, that is summarily dropped (having wasted the transmission
36792 effort).
36793
36794 To evaluate the verification result in the ACL a large number of expansion
36795 variables containing the signature status and its details are set up during the
36796 runtime of the ACL.
36797
36798 Calling the ACL only for existing signatures is not sufficient to build more
36799 advanced policies. For that reason, the global option dkim_verify_signers, and
36800 a global expansion variable $dkim_signers exist.
36801
36802 The global option dkim_verify_signers can be set to a colon-separated list of
36803 DKIM domains or identities for which the ACL acl_smtp_dkim is called. It is
36804 expanded when the message has been received. At this point, the expansion
36805 variable $dkim_signers already contains a colon-separated list of signer
36806 domains and identities for the message. When dkim_verify_signers is not
36807 specified in the main configuration, it defaults as:
36808
36809 dkim_verify_signers = $dkim_signers
36810
36811 This leads to the default behaviour of calling acl_smtp_dkim for each DKIM
36812 signature in the message. Current DKIM verifiers may want to explicitly call
36813 the ACL for known domains or identities. This would be achieved as follows:
36814
36815 dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
36816
36817 This would result in acl_smtp_dkim always being called for "paypal.com" and
36818 "ebay.com", plus all domains and identities that have signatures in the
36819 message. You can also be more creative in constructing your policy. For
36820 example:
36821
36822 dkim_verify_signers = $sender_address_domain:$dkim_signers
36823
36824 If a domain or identity is listed several times in the (expanded) value of
36825 dkim_verify_signers, the ACL is only called once for that domain or identity.
36826
36827 If multiple signatures match a domain (or identity), the ACL is called once for
36828 each matching signature.
36829
36830 Inside the acl_smtp_dkim, the following expansion variables are available (from
36831 most to least important):
36832
36833 $dkim_cur_signer
36834
36835 The signer that is being evaluated in this ACL run. This can be a domain or
36836 an identity. This is one of the list items from the expanded main option
36837 dkim_verify_signers (see above).
36838
36839 $dkim_verify_status
36840
36841 Within the DKIM ACL, a string describing the general status of the
36842 signature. One of
36843
36844 + none: There is no signature in the message for the current domain or
36845 identity (as reflected by $dkim_cur_signer).
36846
36847 + invalid: The signature could not be verified due to a processing error.
36848 More detail is available in $dkim_verify_reason.
36849
36850 + fail: Verification of the signature failed. More detail is available in
36851 $dkim_verify_reason.
36852
36853 + pass: The signature passed verification. It is valid.
36854
36855 This variable can be overwritten using an ACL 'set' modifier. This might,
36856 for instance, be done to enforce a policy restriction on hash-method or
36857 key-size:
36858
36859 warn condition = ${if eq {$dkim_verify_status}{pass}}
36860 condition = ${if eq {${length_3:$dkim_algo}}{rsa}}
36861 condition = ${if or {{eq {$dkim_algo}{rsa-sha1}} \
36862 {< {$dkim_key_length}{1024}}}}
36863 logwrite = NOTE: forcing DKIM verify fail (was pass)
36864 set dkim_verify_status = fail
36865 set dkim_verify_reason = hash too weak or key too short
36866
36867 So long as a DKIM ACL is defined (it need do no more than accept), after
36868 all the DKIM ACL runs have completed, the value becomes a colon-separated
36869 list of the values after each run. This is maintained for the mime, prdr
36870 and data ACLs.
36871
36872 $dkim_verify_reason
36873
36874 A string giving a little bit more detail when $dkim_verify_status is either
36875 "fail" or "invalid". One of
36876
36877 + pubkey_unavailable (when $dkim_verify_status="invalid"): The public key
36878 for the domain could not be retrieved. This may be a temporary problem.
36879
36880 + pubkey_syntax (when $dkim_verify_status="invalid"): The public key
36881 record for the domain is syntactically invalid.
36882
36883 + bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated
36884 body hash does not match the one specified in the signature header.
36885 This means that the message body was modified in transit.
36886
36887 + signature_incorrect (when $dkim_verify_status="fail"): The signature
36888 could not be verified. This may mean that headers were modified,
36889 re-written or otherwise changed in a way which is incompatible with
36890 DKIM verification. It may of course also mean that the signature is
36891 forged.
36892
36893 This variable can be overwritten, with any value, using an ACL 'set'
36894 modifier.
36895
36896 $dkim_domain
36897
36898 The signing domain. IMPORTANT: This variable is only populated if there is
36899 an actual signature in the message for the current domain or identity (as
36900 reflected by $dkim_cur_signer).
36901
36902 $dkim_identity
36903
36904 The signing identity, if present. IMPORTANT: This variable is only
36905 populated if there is an actual signature in the message for the current
36906 domain or identity (as reflected by $dkim_cur_signer).
36907
36908 $dkim_selector
36909
36910 The key record selector string.
36911
36912 $dkim_algo
36913
36914 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. If running under
36915 GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, may also be 'ed25519-sha256'. The
36916 "_CRYPTO_SIGN_ED25519" macro will be defined if support is present for EC
36917 keys.
36918
36919 Note that RFC 8301 says:
36920
36921 rsa-sha1 MUST NOT be used for signing or verifying.
36922
36923 DKIM signatures identified as having been signed with historic
36924 algorithms (currently, rsa-sha1) have permanently failed evaluation
36925
36926 To enforce this you must have a DKIM ACL which checks this variable and
36927 overwrites the $dkim_verify_status variable as discussed above.
36928
36929 $dkim_canon_body
36930
36931 The body canonicalization method. One of 'relaxed' or 'simple'.
36932
36933 $dkim_canon_headers
36934
36935 The header canonicalization method. One of 'relaxed' or 'simple'.
36936
36937 $dkim_copiedheaders
36938
36939 A transcript of headers and their values which are included in the
36940 signature (copied from the 'z=' tag of the signature). Note that RFC6376
36941 requires that verification fail if the From: header is not included in the
36942 signature. Exim does not enforce this; sites wishing strict enforcement
36943 should code the check explicitly.
36944
36945 $dkim_bodylength
36946
36947 The number of signed body bytes. If zero ("0"), the body is unsigned. If no
36948 limit was set by the signer, "9999999999999" is returned. This makes sure
36949 that this variable always expands to an integer value.
36950
36951 Note: The presence of the signature tag specifying a signing body length is
36952 one possible route to spoofing of valid DKIM signatures. A paranoid
36953 implementation might wish to regard signature where this variable shows
36954 less than the "no limit" return as being invalid.
36955
36956 $dkim_created
36957
36958 UNIX timestamp reflecting the date and time when the signature was created.
36959 When this was not specified by the signer, "0" is returned.
36960
36961 $dkim_expires
36962
36963 UNIX timestamp reflecting the date and time when the signer wants the
36964 signature to be treated as "expired". When this was not specified by the
36965 signer, "9999999999999" is returned. This makes it possible to do useful
36966 integer size comparisons against this value. Note that Exim does not check
36967 this value.
36968
36969 $dkim_headernames
36970
36971 A colon-separated list of names of headers included in the signature.
36972
36973 $dkim_key_testing
36974
36975 "1" if the key record has the "testing" flag set, "0" if not.
36976
36977 $dkim_key_nosubdomains
36978
36979 "1" if the key record forbids subdomaining, "0" otherwise.
36980
36981 $dkim_key_srvtype
36982
36983 Service type (tag s=) from the key record. Defaults to "*" if not specified
36984 in the key record.
36985
36986 $dkim_key_granularity
36987
36988 Key granularity (tag g=) from the key record. Defaults to "*" if not
36989 specified in the key record.
36990
36991 $dkim_key_notes
36992
36993 Notes from the key record (tag n=).
36994
36995 $dkim_key_length
36996
36997 Number of bits in the key.
36998
36999 Note that RFC 8301 says:
37000
37001 Verifiers MUST NOT consider signatures using RSA keys of
37002 less than 1024 bits as valid signatures.
37003
37004 To enforce this you must have a DKIM ACL which checks this variable and
37005 overwrites the $dkim_verify_status variable as discussed above. As EC keys
37006 are much smaller, the check should only do this for RSA keys.
37007
37008 In addition, two ACL conditions are provided:
37009
37010 dkim_signers
37011
37012 ACL condition that checks a colon-separated list of domains or identities
37013 for a match against the domain or identity that the ACL is currently
37014 verifying (reflected by $dkim_cur_signer). This is typically used to
37015 restrict an ACL verb to a group of domains or identities. For example:
37016
37017 # Warn when Mail purportedly from GMail has no gmail signature
37018 warn log_message = GMail sender without gmail.com DKIM signature
37019 sender_domains = gmail.com
37020 dkim_signers = gmail.com
37021 dkim_status = none
37022
37023 Note that the above does not check for a total lack of DKIM signing; for
37024 that check for empty $h_DKIM-Signature: in the data ACL.
37025
37026 dkim_status
37027
37028 ACL condition that checks a colon-separated list of possible DKIM
37029 verification results against the actual result of verification. This is
37030 typically used to restrict an ACL verb to a list of verification outcomes,
37031 for example:
37032
37033 deny message = Mail from Paypal with invalid/missing signature
37034 sender_domains = paypal.com:paypal.de
37035 dkim_signers = paypal.com:paypal.de
37036 dkim_status = none:invalid:fail
37037
37038 The possible status keywords are: 'none','invalid','fail' and 'pass'.
37039 Please see the documentation of the $dkim_verify_status expansion variable
37040 above for more information of what they mean.
37041
37042
37043 57.4 SPF (Sender Policy Framework)
37044 ----------------------------------
37045
37046 SPF is a mechanism whereby a domain may assert which IP addresses may transmit
37047 messages with its domain in the envelope from, documented by RFC 7208. For more
37048 information on SPF see http://www.openspf.org.
37049
37050 Messages sent by a system not authorised will fail checking of such assertions.
37051 This includes retransmissions done by traditional forwarders.
37052
37053 SPF verification support is built into Exim if SUPPORT_SPF=yes is set in Local/
37054 Makefile. The support uses the libspf2 library https://www.libspf2.org/. There
37055 is no Exim involvement in the transmission of messages; publishing certain DNS
37056 records is all that is required.
37057
37058 For verification, an ACL condition and an expansion lookup are provided.
37059 Performing verification sets up information used by the $authresults expansion
37060 item.
37061
37062 The ACL condition "spf" can be used at or after the MAIL ACL. It takes as an
37063 argument a list of strings giving the outcome of the SPF check, and will
37064 succeed for any matching outcome. Valid strings are:
37065
37066 pass
37067
37068 The SPF check passed, the sending host is positively verified by SPF.
37069
37070 fail
37071
37072 The SPF check failed, the sending host is NOT allowed to send mail for the
37073 domain in the envelope-from address.
37074
37075 softfail
37076
37077 The SPF check failed, but the queried domain can't absolutely confirm that
37078 this is a forgery.
37079
37080 none
37081
37082 The queried domain does not publish SPF records.
37083
37084 neutral
37085
37086 The SPF check returned a "neutral" state. This means the queried domain has
37087 published a SPF record, but wants to allow outside servers to send mail
37088 under its domain as well. This should be treated like "none".
37089
37090 permerror
37091
37092 This indicates a syntax error in the SPF record of the queried domain. You
37093 may deny messages when this occurs.
37094
37095 temperror
37096
37097 This indicates a temporary error during all processing, including Exim's
37098 SPF processing. You may defer messages when this occurs.
37099
37100 You can prefix each string with an exclamation mark to invert its meaning, for
37101 example "!fail" will match all results but "fail". The string list is evaluated
37102 left-to-right, in a short-circuit fashion.
37103
37104 Example:
37105
37106 deny spf = fail
37107 message = $sender_host_address is not allowed to send mail from \
37108 ${if def:sender_address_domain \
37109 {$sender_address_domain}{$sender_helo_name}}. \
37110 Please see http://www.openspf.org/Why?scope=\
37111 ${if def:sender_address_domain {mfrom}{helo}};\
37112 identity=${if def:sender_address_domain \
37113 {$sender_address}{$sender_helo_name}};\
37114 ip=$sender_host_address
37115
37116 When the spf condition has run, it sets up several expansion variables:
37117
37118 $spf_header_comment
37119
37120 This contains a human-readable string describing the outcome of the SPF
37121 check. You can add it to a custom header or use it for logging purposes.
37122
37123 $spf_received
37124
37125 This contains a complete Received-SPF: header that can be added to the
37126 message. Please note that according to the SPF draft, this header must be
37127 added at the top of the header list. Please see section 10 on how you can
37128 do this.
37129
37130 Note: in case of "Best-guess" (see below), the convention is to put this
37131 string in a header called X-SPF-Guess: instead.
37132
37133 $spf_result
37134
37135 This contains the outcome of the SPF check in string form, one of pass,
37136 fail, softfail, none, neutral, permerror or temperror.
37137
37138 $spf_result_guessed
37139
37140 This boolean is true only if a best-guess operation was used and required
37141 in order to obtain a result.
37142
37143 $spf_smtp_comment
37144
37145 This contains a string that can be used in a SMTP response to the calling
37146 party. Useful for "fail".
37147
37148 In addition to SPF, you can also perform checks for so-called "Best-guess".
37149 Strictly speaking, "Best-guess" is not standard SPF, but it is supported by the
37150 same framework that enables SPF capability. Refer to http://www.openspf.org/FAQ
37151 /Best_guess_record for a description of what it means.
37152
37153 To access this feature, simply use the spf_guess condition in place of the spf
37154 one. For example:
37155
37156 deny spf_guess = fail
37157 message = $sender_host_address doesn't look trustworthy to me
37158
37159 In case you decide to reject messages based on this check, you should note that
37160 although it uses the same framework, "Best-guess" is not SPF, and therefore you
37161 should not mention SPF at all in your reject message.
37162
37163 When the spf_guess condition has run, it sets up the same expansion variables
37164 as when spf condition is run, described above.
37165
37166 Additionally, since Best-guess is not standardized, you may redefine what
37167 "Best-guess" means to you by redefining the main configuration spf_guess
37168 option. For example, the following:
37169
37170 spf_guess = v=spf1 a/16 mx/16 ptr ?all
37171
37172 would relax host matching rules to a broader network range.
37173
37174 A lookup expansion is also available. It takes an email address as the key and
37175 an IP address as the database:
37176
37177 ${lookup {username@domain} spf {ip.ip.ip.ip}}
37178
37179 The lookup will return the same result strings as can appear in $spf_result
37180 (pass,fail,softfail,neutral,none,err_perm,err_temp). Currently, only IPv4
37181 addresses are supported.
37182
37183
37184
37185 ===============================================================================
37186 58. PROXIES
37187
37188 A proxy is an intermediate system through which communication is passed.
37189 Proxies may provide a security, availability or load-distribution function.
37190
37191
37192 58.1 Inbound proxies
37193 --------------------
37194
37195 Exim has support for receiving inbound SMTP connections via a proxy that uses
37196 "Proxy Protocol" to speak to it. To include this support, include
37197 "SUPPORT_PROXY=yes" in Local/Makefile.
37198
37199 It was built on the HAProxy specification, found at https://www.haproxy.org/
37200 download/1.8/doc/proxy-protocol.txt.
37201
37202 The purpose of this facility is so that an application load balancer, such as
37203 HAProxy, can sit in front of several Exim servers to distribute load. Exim uses
37204 the local protocol communication with the proxy to obtain the remote SMTP
37205 system IP address and port information. There is no logging if a host passes or
37206 fails Proxy Protocol negotiation, but it can easily be determined and recorded
37207 in an ACL (example is below).
37208
37209 Use of a proxy is enabled by setting the hosts_proxy main configuration option
37210 to a hostlist; connections from these hosts will use Proxy Protocol. Exim
37211 supports both version 1 and version 2 of the Proxy Protocol and automatically
37212 determines which version is in use.
37213
37214 The Proxy Protocol header is the first data received on a TCP connection and is
37215 inserted before any TLS-on-connect handshake from the client; Exim negotiates
37216 TLS between Exim-as-server and the remote client, not between Exim and the
37217 proxy server.
37218
37219 The following expansion variables are usable ("internal" and "external" here
37220 refer to the interfaces of the proxy):
37221
37222 proxy_external_address
37223 IP of host being proxied or IP of remote interface of proxy
37224 proxy_external_port
37225 Port of host being proxied or Port on remote interface of proxy
37226 proxy_local_address
37227 IP of proxy server inbound or IP of local interface of proxy
37228 proxy_local_port
37229 Port of proxy server inbound or Port on local interface of proxy
37230 proxy_session boolean: SMTP connection via proxy
37231
37232 If $proxy_session is set but $proxy_external_address is empty there was a
37233 protocol error.
37234
37235 Since the real connections are all coming from the proxy, and the per host
37236 connection tracking is done before Proxy Protocol is evaluated,
37237 smtp_accept_max_per_host must be set high enough to handle all of the parallel
37238 volume you expect per inbound proxy. With the option set so high, you lose the
37239 ability to protect your server from many connections from one IP. In order to
37240 prevent your server from overload, you need to add a per connection ratelimit
37241 to your connect ACL. A possible solution is:
37242
37243 # Set max number of connections per host
37244 LIMIT = 5
37245 # Or do some kind of IP lookup in a flat file or database
37246 # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}}
37247
37248 defer message = Too many connections from this IP right now
37249 ratelimit = LIMIT / 5s / per_conn / strict
37250
37251
37252 58.2 Outbound proxies
37253 ---------------------
37254
37255 Exim has support for sending outbound SMTP via a proxy using a protocol called
37256 SOCKS5 (defined by RFC1928). The support can be optionally included by defining
37257 SUPPORT_SOCKS=yes in Local/Makefile.
37258
37259 Use of a proxy is enabled by setting the socks_proxy option on an smtp
37260 transport. The option value is expanded and should then be a list
37261 (colon-separated by default) of proxy specifiers. Each proxy specifier is a
37262 list (space-separated by default) where the initial element is an IP address
37263 and any subsequent elements are options.
37264
37265 Options are a string <name>=<value>. The list of options is in the following
37266 table:
37267
37268 auth authentication method
37269 name authentication username
37270 pass authentication password
37271 port tcp port
37272 tmo connection timeout
37273 pri priority
37274 weight selection bias
37275
37276 More details on each of these options follows:
37277
37278 * auth: Either "none" (default) or "name". Using "name" selects username/
37279 password authentication per RFC 1929 for access to the proxy. Default is
37280 "none".
37281
37282 * name: sets the username for the "name" authentication method. Default is
37283 empty.
37284
37285 * pass: sets the password for the "name" authentication method. Default is
37286 empty.
37287
37288 * port: the TCP port number to use for the connection to the proxy. Default
37289 is 1080.
37290
37291 * tmo: sets a connection timeout in seconds for this proxy. Default is 5.
37292
37293 * pri: specifies a priority for the proxy within the list, higher values
37294 being tried first. The default priority is 1.
37295
37296 * weight: specifies a selection bias. Within a priority set servers are
37297 queried in a random fashion, weighted by this value. The default value for
37298 selection bias is 1.
37299
37300 Proxies from the list are tried according to their priority and weight settings
37301 until one responds. The timeout for the overall connection applies to the set
37302 of proxied attempts.
37303
37304
37305 58.3 Logging
37306 ------------
37307
37308 To log the (local) IP of a proxy in the incoming or delivery logline, add
37309 "+proxy" to the log_selector option. This will add a component tagged with "PRX
37310 =" to the line.
37311
37312
37313
37314 ===============================================================================
37315 59. INTERNATIONALISATION
37316
37317 Exim has support for Internationalised mail names. To include this it must be
37318 built with SUPPORT_I18N and the libidn library. Standards supported are RFCs
37319 2060, 5890, 6530 and 6533.
37320
37321 If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not
37322 instead of it) then IDNA2008 is supported; this adds an extra library
37323 requirement, upon libidn2.
37324
37325
37326 59.1 MTA operations
37327 -------------------
37328
37329 The main configuration option smtputf8_advertise_hosts specifies a host list.
37330 If this matches the sending host and accept_8bitmime is true (the default) then
37331 the ESMTP option SMTPUTF8 will be advertised.
37332
37333 If the sender specifies the SMTPUTF8 option on a MAIL command international
37334 handling for the message is enabled and the expansion variable
37335 $message_smtputf8 will have value TRUE.
37336
37337 The option allow_utf8_domains is set to true for this message. All DNS lookups
37338 are converted to a-label form whatever the setting of allow_utf8_domains when
37339 Exim is built with SUPPORT_I18N.
37340
37341 Both localparts and domain are maintained as the original UTF-8 form
37342 internally; any comparison or regular-expression use will require appropriate
37343 care. Filenames created, eg. by the appendfile transport, will have UTF-8
37344 names.
37345
37346 HELO names sent by the smtp transport will have any UTF-8 components expanded
37347 to a-label form, and any certificate name checks will be done using the a-label
37348 form of the name.
37349
37350 Log lines and Received-by: header lines will acquire a "utf8" prefix on the
37351 protocol element, eg. utf8esmtp.
37352
37353 The following expansion operators can be used:
37354
37355 ${utf8_domain_to_alabel:str}
37356 ${utf8_domain_from_alabel:str}
37357 ${utf8_localpart_to_alabel:str}
37358 ${utf8_localpart_from_alabel:str}
37359
37360 The RCPT ACL may use the following modifier:
37361
37362 control = utf8_downconvert
37363 control = utf8_downconvert/<value>
37364
37365 This sets a flag requiring that addresses are converted to a-label form before
37366 smtp delivery, for use in a Message Submission Agent context. If a value is
37367 appended it may be:
37368
37369 1 (default) mandatory downconversion
37370 0 no downconversion
37371 -1 if SMTPUTF8 not supported by destination host
37372
37373 If mua_wrapper is set, the utf8_downconvert control is initially set to -1.
37374
37375 The smtp transport has an option utf8_downconvert. If set it must expand to one
37376 of the three values described above, and it overrides any previously set value.
37377
37378 There is no explicit support for VRFY and EXPN. Configurations supporting these
37379 should inspect $smtp_command_argument for an SMTPUTF8 argument.
37380
37381 There is no support for LMTP on Unix sockets. Using the "lmtp" protocol option
37382 on an smtp transport, for LMTP over TCP, should work as expected.
37383
37384 There is no support for DSN unitext handling, and no provision for converting
37385 logging from or to UTF-8.
37386
37387
37388 59.2 MDA operations
37389 -------------------
37390
37391 To aid in constructing names suitable for IMAP folders the following expansion
37392 operator can be used:
37393
37394 ${imapfolder {<string>} {<sep>} {<specials>}}
37395
37396 The string is converted from the charset specified by the "headers charset"
37397 command (in a filter file) or headers_charset main configuration option
37398 (otherwise), to the modified UTF-7 encoding specified by RFC 2060, with the
37399 following exception: All occurrences of <sep> (which has to be a single
37400 character) are replaced with periods ("."), and all periods and slashes that
37401 are not <sep> and are not in the <specials> string are BASE64 encoded.
37402
37403 The third argument can be omitted, defaulting to an empty string. The second
37404 argument can be omitted, defaulting to "/".
37405
37406 This is the encoding used by Courier for Maildir names on disk, and followed by
37407 many other IMAP servers.
37408
37409 Examples:
37410
37411 ${imapfolder {Foo/Bar}} yields Foo.Bar
37412 ${imapfolder {Foo/Bar}{.}{/}} yields Foo&AC8-Bar
37413 ${imapfolder {R?ksm?rg?s}} yields R&AOQ-ksm&APY-rg&AOU-s
37414
37415 Note that the source charset setting is vital, and also that characters must be
37416 representable in UTF-16.
37417
37418
37419
37420 ===============================================================================
37421 60. EVENTS
37422
37423 The events mechanism in Exim can be used to intercept processing at a number of
37424 points. It was originally invented to give a way to do customised logging
37425 actions (for example, to a database) but can also be used to modify some
37426 processing actions.
37427
37428 Most installations will never need to use Events. The support can be left out
37429 of a build by defining DISABLE_EVENT=yes in Local/Makefile.
37430
37431 There are two major classes of events: main and transport. The main
37432 configuration option event_action controls reception events; a transport option
37433 event_action controls delivery events.
37434
37435 Both options are a string which is expanded when the event fires. An example
37436 might look like:
37437
37438 event_action = ${if eq {msg:delivery}{$event_name} \
37439 {${lookup pgsql {SELECT * FROM record_Delivery( \
37440 '${quote_pgsql:$sender_address_domain}',\
37441 '${quote_pgsql:${lc:$sender_address_local_part}}', \
37442 '${quote_pgsql:$domain}', \
37443 '${quote_pgsql:${lc:$local_part}}', \
37444 '${quote_pgsql:$host_address}', \
37445 '${quote_pgsql:${lc:$host}}', \
37446 '${quote_pgsql:$message_exim_id}')}} \
37447 } {}}
37448
37449 Events have names which correspond to the point in process at which they fire.
37450 The name is placed in the variable $event_name and the event action expansion
37451 must check this, as it will be called for every possible event type.
37452
37453 The current list of events is:
37454
37455 dane:fail after transport per connection
37456 msg:complete after main per message
37457 msg:delivery after transport per recipient
37458 msg:rcpt:host:defer after transport per recipient per host
37459 msg:rcpt:defer after transport per recipient
37460 msg:host:defer after transport per attempt
37461 msg:fail:delivery after transport per recipient
37462 msg:fail:internal after main per recipient
37463 tcp:connect before transport per connection
37464 tcp:close after transport per connection
37465 tls:cert before both per certificate in verification chain
37466 smtp:connect after transport per connection
37467
37468 New event types may be added in future.
37469
37470 The event name is a colon-separated list, defining the type of event in a tree
37471 of possibilities. It may be used as a list or just matched on as a whole. There
37472 will be no spaces in the name.
37473
37474 The second column in the table above describes whether the event fires before
37475 or after the action is associates with. Those which fire before can be used to
37476 affect that action (more on this below).
37477
37478 The third column in the table above says what section of the configuration
37479 should define the event action.
37480
37481 An additional variable, $event_data, is filled with information varying with
37482 the event type:
37483
37484 dane:fail failure reason
37485 msg:delivery smtp confirmation message
37486 msg:fail:internal failure reason
37487 msg:fail:delivery smtp error message
37488 msg:rcpt:host:defer error string
37489 msg:rcpt:defer error string
37490 msg:host:defer error string
37491 tls:cert verification chain depth
37492 smtp:connect smtp banner
37493
37494 The :defer events populate one extra variable: $event_defer_errno.
37495
37496 For complex operations an ACL expansion can be used in event_action however due
37497 to the multiple contexts that Exim operates in during the course of its
37498 processing:
37499
37500 * variables set in transport events will not be visible outside that
37501 transport call
37502
37503 * acl_m variables in a server context are lost on a new connection, and after
37504 smtp helo/ehlo/mail/starttls/rset commands
37505
37506 Using an ACL expansion with the logwrite modifier can be a useful way of
37507 writing to the main log.
37508
37509 The expansion of the event_action option should normally return an empty
37510 string. Should it return anything else the following will be forced:
37511
37512 tcp:connect do not connect
37513 tls:cert refuse verification
37514 smtp:connect close connection
37515
37516 All other message types ignore the result string, and no other use is made of
37517 it.
37518
37519 For a tcp:connect event, if the connection is being made to a proxy then the
37520 address and port variables will be that of the proxy and not the target system.
37521
37522 For tls:cert events, if GnuTLS is in use this will trigger only per chain
37523 element received on the connection. For OpenSSL it will trigger for every chain
37524 element including those loaded locally.
37525
37526
37527
37528 ===============================================================================
37529 61. ADDING NEW DRIVERS OR LOOKUP TYPES
37530
37531 The following actions have to be taken in order to add a new router, transport,
37532 authenticator, or lookup type to Exim:
37533
37534 1. Choose a name for the driver or lookup type that does not conflict with any
37535 existing name; I will use "newdriver" in what follows.
37536
37537 2. Add to src/EDITME the line:
37538
37539 <type>_NEWDRIVER=yes
37540
37541 where <type> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the code is not to
37542 be included in the binary by default, comment this line out. You should
37543 also add any relevant comments about the driver or lookup type.
37544
37545 3. Add to src/config.h.defaults the line:
37546
37547 #define <type>_NEWDRIVER
37548
37549 4. Edit src/drtables.c, adding conditional code to pull in the private header
37550 and create a table entry as is done for all the other drivers and lookup
37551 types.
37552
37553 5. Edit scripts/lookups-Makefile if this is a new lookup; there is a for-loop
37554 near the bottom, ranging the "name_mod" variable over a list of all
37555 lookups. Add your "NEWDRIVER" to that list. As long as the dynamic module
37556 would be named newdriver.so, you can use the simple form that most lookups
37557 have.
37558
37559 6. Edit Makefile in the appropriate sub-directory (src/routers, src/transports
37560 , src/auths, or src/lookups); add a line for the new driver or lookup type
37561 and add it to the definition of OBJ.
37562
37563 7. Edit OS/Makefile-Base adding a .o file for the predefined-macros, to the
37564 definition of OBJ_MACRO. Add a set of line to do the compile also.
37565
37566 8. Create newdriver.h and newdriver.c in the appropriate sub-directory of src.
37567
37568 9. Edit scripts/MakeLinks and add commands to link the .h and .c files as for
37569 other drivers and lookups.
37570
37571 Then all you need to do is write the code! A good way to start is to make a
37572 proforma by copying an existing module of the same type, globally changing all
37573 occurrences of the name, and cutting out most of the code. Note that any
37574 options you create must be listed in alphabetical order, because the tables are
37575 searched using a binary chop procedure.
37576
37577 There is a README file in each of the sub-directories of src describing the
37578 interface that is expected.
37579