1 Specification of the Exim Mail Transfer Agent
5 Copyright (c) 2014 University of Cambridge
7 Revision 4.84.2 02 Mar 2016 EM
9 -------------------------------------------------------------------------------
15 1.1. Exim documentation
16 1.2. FTP and web sites
20 1.6. Where to find the Exim distribution
22 1.8. Run time configuration
23 1.9. Calling interface
27 3. How Exim receives and delivers mail
29 3.1. Overall philosophy
32 3.4. Message identification
34 3.6. Handling an incoming message
35 3.7. Life of a message
36 3.8. Processing an address for delivery
37 3.9. Processing an address for verification
38 3.10. Running an individual router
39 3.11. Duplicate addresses
40 3.12. Router preconditions
41 3.13. Delivery in detail
43 3.15. Temporary delivery failure
44 3.16. Permanent delivery failure
45 3.17. Failures to deliver bounce messages
47 4. Building and installing Exim
50 4.2. Multiple machine architectures and operating systems
53 4.5. Pre-building configuration
54 4.6. Support for iconv()
55 4.7. Including TLS/SSL encryption support
56 4.8. Use of tcpwrappers
57 4.9. Including support for IPv6
58 4.10. Dynamically loaded lookup module support
59 4.11. The building process
60 4.12. Output from "make"
61 4.13. Overriding build-time options for Exim
62 4.14. OS-specific header files
63 4.15. Overriding build-time options for the monitor
64 4.16. Installing Exim binaries and scripts
65 4.17. Installing info documentation
66 4.18. Setting up the spool directory
68 4.20. Replacing another MTA with Exim
70 4.22. Stopping the Exim daemon on Solaris
72 5. The Exim command line
74 5.1. Setting options by program name
75 5.2. Trusted and admin users
76 5.3. Command line options
78 6. The Exim run time configuration file
80 6.1. Using a different configuration file
81 6.2. Configuration file format
82 6.3. File inclusions in the configuration file
83 6.4. Macros in the configuration file
84 6.5. Macro substitution
85 6.6. Redefining macros
86 6.7. Overriding macro values
87 6.8. Example of macro usage
88 6.9. Conditional skips in the configuration file
89 6.10. Common option syntax
92 6.13. Octal integer values
93 6.14. Fixed point numbers
96 6.17. Expanded strings
97 6.18. User and group names
98 6.19. List construction
99 6.20. Changing list separators
100 6.21. Empty items in lists
101 6.22. Format of driver configurations
103 7. The default configuration file
105 7.1. Main configuration settings
106 7.2. ACL configuration
107 7.3. Router configuration
108 7.4. Transport configuration
109 7.5. Default retry rule
110 7.6. Rewriting configuration
111 7.7. Authenticators configuration
113 8. Regular expressions
114 9. File and database lookups
116 9.1. Examples of different lookup syntax
118 9.3. Single-key lookup types
119 9.4. Query-style lookup types
120 9.5. Temporary errors in lookups
121 9.6. Default values in single-key lookups
122 9.7. Partial matching in single-key lookups
124 9.9. Quoting lookup data
125 9.10. More about dnsdb
126 9.11. Pseudo dnsdb record types
127 9.12. Multiple dnsdb lookups
128 9.13. More about LDAP
129 9.14. Format of LDAP queries
131 9.16. LDAP connections
132 9.17. LDAP authentication and control information
133 9.18. Format of data returned by LDAP
134 9.19. More about NIS+
136 9.21. More about MySQL, PostgreSQL, Oracle, and InterBase
137 9.22. Specifying the server in the query
138 9.23. Special MySQL features
139 9.24. Special PostgreSQL features
140 9.25. More about SQLite
142 10. Domain, host, address, and local part lists
144 10.1. Expansion of lists
145 10.2. Negated items in lists
146 10.3. File names in lists
147 10.4. An lsearch file is not an out-of-line list
149 10.6. Named lists compared with macros
150 10.7. Named list caching
153 10.10. Special host list patterns
154 10.11. Host list patterns that match by IP address
155 10.12. Host list patterns for single-key lookups by host address
156 10.13. Host list patterns that match by host name
157 10.14. Behaviour when an IP address or name cannot be found
158 10.15. Mixing wildcarded host names and addresses in host lists
159 10.16. Temporary DNS errors when looking up host information
160 10.17. Host list patterns for single-key lookups by host name
161 10.18. Host list patterns for query-style lookups
163 10.20. Case of letters in address lists
164 10.21. Local part lists
166 11. String expansions
168 11.1. Literal text in expanded strings
169 11.2. Character escape sequences in expanded strings
170 11.3. Testing string expansions
171 11.4. Forced expansion failure
172 11.5. Expansion items
173 11.6. Expansion operators
174 11.7. Expansion conditions
175 11.8. Combining expansion conditions
176 11.9. Expansion variables
180 12.1. Setting up so Perl can be used
181 12.2. Calling Perl subroutines
182 12.3. Calling Exim functions from Perl
183 12.4. Use of standard output and error by Perl
185 13. Starting the daemon and the use of network interfaces
187 13.1. Starting a listening daemon
188 13.2. Special IP listening addresses
189 13.3. Overriding local_interfaces and daemon_smtp_ports
190 13.4. Support for the obsolete SSMTP (or SMTPS) protocol
191 13.5. IPv6 address scopes
193 13.7. Examples of starting a listening daemon
194 13.8. Recognizing the local host
195 13.9. Delivering to a remote host
197 14. Main configuration
200 14.2. Exim parameters
201 14.3. Privilege controls
203 14.5. Frozen messages
206 14.8. Embedded Perl Startup
208 14.10. Resource control
209 14.11. Policy controls
212 14.14. Local user handling
213 14.15. All incoming messages (SMTP and non-SMTP)
214 14.16. Non-SMTP incoming messages
215 14.17. Incoming SMTP messages
216 14.18. SMTP extensions
217 14.19. Processing messages
219 14.21. Routing and delivery
220 14.22. Bounce and warning messages
221 14.23. Alphabetical list of main options
223 15. Generic options for routers
224 16. The accept router
225 17. The dnslookup router
227 17.1. Problems with DNS lookups
228 17.2. Declining addresses by dnslookup
229 17.3. Private options for dnslookup
230 17.4. Effect of qualify_single and search_parents
232 18. The ipliteral router
233 19. The iplookup router
234 20. The manualroute router
236 20.1. Private options for manualroute
237 20.2. Routing rules in route_list
238 20.3. Routing rules in route_data
239 20.4. Format of the list of hosts
240 20.5. Format of one host item
241 20.6. How the list of hosts is used
242 20.7. How the options are used
243 20.8. Manualroute examples
245 21. The queryprogram router
246 22. The redirect router
248 22.1. Redirection data
249 22.2. Forward files and address verification
250 22.3. Interpreting redirection data
251 22.4. Items in a non-filter redirection list
252 22.5. Redirecting to a local mailbox
253 22.6. Special items in redirection lists
254 22.7. Duplicate addresses
255 22.8. Repeated redirection expansion
256 22.9. Errors in redirection lists
257 22.10. Private options for the redirect router
259 23. Environment for running local transports
261 23.1. Concurrent deliveries
263 23.3. Current and home directories
264 23.4. Expansion variables derived from the address
266 24. Generic options for transports
267 25. Address batching in local transports
268 26. The appendfile transport
270 26.1. The file and directory options
271 26.2. Private options for appendfile
272 26.3. Operational details for appending
273 26.4. Operational details for delivery to a new file
274 26.5. Maildir delivery
275 26.6. Using tags to record message sizes
276 26.7. Using a maildirsize file
277 26.8. Mailstore delivery
278 26.9. Non-special new file delivery
280 27. The autoreply transport
282 27.1. Private options for autoreply
284 28. The lmtp transport
285 29. The pipe transport
287 29.1. Concurrent delivery
288 29.2. Returned status and data
289 29.3. How the command is run
290 29.4. Environment variables
291 29.5. Private options for pipe
292 29.6. Using an external local delivery agent
294 30. The smtp transport
296 30.1. Multiple messages on a single connection
297 30.2. Use of the $host and $host_address variables
298 30.3. Use of $tls_cipher and $tls_peerdn
299 30.4. Private options for smtp
300 30.5. How the limits for the number of hosts to try are used
302 31. Address rewriting
304 31.1. Explicitly configured address rewriting
305 31.2. When does rewriting happen?
306 31.3. Testing the rewriting rules that apply on input
307 31.4. Rewriting rules
308 31.5. Rewriting patterns
309 31.6. Rewriting replacements
310 31.7. Rewriting flags
311 31.8. Flags specifying which headers and envelope addresses to rewrite
312 31.9. The SMTP-time rewriting flag
313 31.10. Flags controlling the rewriting process
314 31.11. Rewriting examples
316 32. Retry configuration
318 32.1. Changing retry rules
319 32.2. Format of retry rules
320 32.3. Choosing which retry rule to use for address errors
321 32.4. Choosing which retry rule to use for host and message errors
322 32.5. Retry rules for specific errors
323 32.6. Retry rules for specified senders
324 32.7. Retry parameters
325 32.8. Retry rule examples
326 32.9. Timeout of retry data
327 32.10. Long-term failures
328 32.11. Deliveries that work intermittently
330 33. SMTP authentication
332 33.1. Generic options for authenticators
333 33.2. The AUTH parameter on MAIL commands
334 33.3. Authentication on an Exim server
335 33.4. Testing server authentication
336 33.5. Authentication by an Exim client
338 34. The plaintext authenticator
340 34.1. Plaintext options
341 34.2. Using plaintext in a server
342 34.3. The PLAIN authentication mechanism
343 34.4. The LOGIN authentication mechanism
344 34.5. Support for different kinds of authentication
345 34.6. Using plaintext in a client
347 35. The cram_md5 authenticator
349 35.1. Using cram_md5 as a server
350 35.2. Using cram_md5 as a client
352 36. The cyrus_sasl authenticator
354 36.1. Using cyrus_sasl as a server
356 37. The dovecot authenticator
357 38. The gsasl authenticator
359 38.1. gsasl auth variables
361 39. The heimdal_gssapi authenticator
363 39.1. heimdal_gssapi auth variables
365 40. The spa authenticator
367 40.1. Using spa as a server
368 40.2. Using spa as a client
370 41. Encrypted SMTP connections using TLS/SSL
372 41.1. Support for the legacy "ssmtp" (aka "smtps") protocol
373 41.2. OpenSSL vs GnuTLS
374 41.3. GnuTLS parameter computation
375 41.4. Requiring specific ciphers in OpenSSL
376 41.5. Requiring specific ciphers or other parameters in GnuTLS
377 41.6. Configuring an Exim server to use TLS
378 41.7. Requesting and verifying client certificates
379 41.8. Revoked certificates
380 41.9. Configuring an Exim client to use TLS
381 41.10. Use of TLS Server Name Indication
382 41.11. Multiple messages on the same encrypted TCP/IP connection
383 41.12. Certificates and all that
384 41.13. Certificate chains
385 41.14. Self-signed certificates
387 42. Access control lists
390 42.2. Specifying when ACLs are used
391 42.3. The non-SMTP ACLs
392 42.4. The SMTP connect ACL
393 42.5. The EHLO/HELO ACL
395 42.7. The SMTP DKIM ACL
396 42.8. The SMTP MIME ACL
397 42.9. The SMTP PRDR ACL
399 42.11. The not-QUIT ACL
400 42.12. Finding an ACL to use
401 42.13. ACL return codes
402 42.14. Unset ACL options
403 42.15. Data for message ACLs
404 42.16. Data for non-message ACLs
405 42.17. Format of an ACL
408 42.20. Condition and modifier processing
410 42.22. Use of the control modifier
411 42.23. Summary of message fixup control
412 42.24. Adding header lines in ACLs
413 42.25. Removing header lines in ACLs
414 42.26. ACL conditions
415 42.27. Using DNS lists
416 42.28. Specifying the IP address for a DNS list lookup
417 42.29. DNS lists keyed on domain names
418 42.30. Multiple explicit keys for a DNS list
419 42.31. Data returned by DNS lists
420 42.32. Variables set from DNS lists
421 42.33. Additional matching conditions for DNS lists
422 42.34. Negated DNS matching conditions
423 42.35. Handling multiple DNS records from a DNS list
424 42.36. Detailed information from merged DNS lists
425 42.37. DNS lists and IPv6
426 42.38. Rate limiting incoming messages
427 42.39. Ratelimit options for what is being measured
428 42.40. Ratelimit update modes
429 42.41. Ratelimit options for handling fast clients
430 42.42. Limiting the rate of different events
431 42.43. Using rate limiting
432 42.44. Address verification
433 42.45. Callout verification
434 42.46. Additional parameters for callouts
435 42.47. Callout caching
436 42.48. Sender address verification reporting
437 42.49. Redirection while verifying
438 42.50. Client SMTP authorization (CSA)
439 42.51. Bounce address tag validation
440 42.52. Using an ACL to control relaying
441 42.53. Checking a relay configuration
443 43. Content scanning at ACL time
445 43.1. Scanning for viruses
446 43.2. Scanning with SpamAssassin
447 43.3. Calling SpamAssassin from an Exim ACL
448 43.4. Scanning MIME parts
449 43.5. Scanning with regular expressions
450 43.6. The demime condition
452 44. Adding a local scan function to Exim
454 44.1. Building Exim to use a local scan function
455 44.2. API for local_scan()
456 44.3. Configuration options for local_scan()
457 44.4. Available Exim variables
458 44.5. Structure of header lines
459 44.6. Structure of recipient items
460 44.7. Available Exim functions
461 44.8. More about Exim's memory handling
463 45. System-wide message filtering
465 45.1. Specifying a system filter
466 45.2. Testing a system filter
467 45.3. Contents of a system filter
468 45.4. Additional variable for system filters
469 45.5. Defer, freeze, and fail commands for system filters
470 45.6. Adding and removing headers in a system filter
471 45.7. Setting an errors address in a system filter
472 45.8. Per-address filtering
474 46. Message processing
476 46.1. Submission mode for non-local messages
478 46.3. Unqualified addresses
479 46.4. The UUCP From line
480 46.5. Resent- header lines
481 46.6. The Auto-Submitted: header line
482 46.7. The Bcc: header line
483 46.8. The Date: header line
484 46.9. The Delivery-date: header line
485 46.10. The Envelope-to: header line
486 46.11. The From: header line
487 46.12. The Message-ID: header line
488 46.13. The Received: header line
489 46.14. The References: header line
490 46.15. The Return-path: header line
491 46.16. The Sender: header line
492 46.17. Adding and removing header lines in routers and transports
493 46.18. Constructed addresses
494 46.19. Case of local parts
495 46.20. Dots in local parts
496 46.21. Rewriting addresses
500 47.1. Outgoing SMTP and LMTP over TCP/IP
501 47.2. Errors in outgoing SMTP
502 47.3. Incoming SMTP messages over TCP/IP
503 47.4. Unrecognized SMTP commands
504 47.5. Syntax and protocol errors in SMTP commands
505 47.6. Use of non-mail SMTP commands
506 47.7. The VRFY and EXPN commands
507 47.8. The ETRN command
508 47.9. Incoming local SMTP
509 47.10. Outgoing batched SMTP
510 47.11. Incoming batched SMTP
512 48. Customizing bounce and warning messages
514 48.1. Customizing bounce messages
515 48.2. Customizing warning messages
517 49. Some common configuration settings
519 49.1. Sending mail to a smart host
520 49.2. Using Exim to handle mailing lists
521 49.3. Syntax errors in mailing lists
522 49.4. Re-expansion of mailing lists
523 49.5. Closed mailing lists
524 49.6. Variable Envelope Return Paths (VERP)
525 49.7. Virtual domains
526 49.8. Multiple user mailboxes
527 49.9. Simplified vacation processing
528 49.10. Taking copies of mail
529 49.11. Intermittently connected hosts
530 49.12. Exim on the upstream server host
531 49.13. Exim on the intermittently connected client host
533 50. Using Exim as a non-queueing client
536 51.1. Where the logs are written
537 51.2. Logging to local files that are periodically "cycled"
538 51.3. Datestamped log files
539 51.4. Logging to syslog
541 51.6. Logging message reception
542 51.7. Logging deliveries
543 51.8. Discarded deliveries
544 51.9. Deferred deliveries
545 51.10. Delivery failures
546 51.11. Fake deliveries
548 51.13. Summary of Fields in Log Lines
549 51.14. Other log entries
550 51.15. Reducing or increasing what is logged
555 52.1. Finding out what Exim processes are doing (exiwhat)
556 52.2. Selective queue listing (exiqgrep)
557 52.3. Summarizing the queue (exiqsumm)
558 52.4. Extracting specific information from the log (exigrep)
559 52.5. Selecting messages by various criteria (exipick)
560 52.6. Cycling log files (exicyclog)
561 52.7. Mail statistics (eximstats)
562 52.8. Checking access policy (exim_checkaccess)
563 52.9. Making DBM files (exim_dbmbuild)
564 52.10. Finding individual retry times (exinext)
565 52.11. Hints database maintenance
569 52.15. Mailbox maintenance (exim_lock)
573 53.1. Running the monitor
574 53.2. The stripcharts
575 53.3. Main action buttons
576 53.4. The log display
577 53.5. The queue display
580 54. Security considerations
582 54.1. Building a more "hardened" Exim
584 54.3. Running Exim without privilege
585 54.4. Delivering to local files
586 54.5. Running local commands
587 54.6. Trust in configuration data
588 54.7. IPv4 source routing
589 54.8. The VRFY, EXPN, and ETRN commands in SMTP
590 54.9. Privileged users
592 54.11. Use of argv[0]
593 54.12. Use of %f formatting
594 54.13. Embedded Exim path
595 54.14. Dynamic module directory
596 54.15. Use of sprintf()
597 54.16. Use of debug_printf() and log_write()
598 54.17. Use of strcat() and strcpy()
600 55. Format of spool files
602 55.1. Format of the -H file
604 56. Support for DKIM (DomainKeys Identified Mail)
606 56.1. Signing outgoing messages
607 56.2. Verifying DKIM signatures in incoming mail
609 57. Adding new drivers or lookup types
613 ===============================================================================
616 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
617 Unix-like operating systems. It was designed on the assumption that it would be
618 run on hosts that are permanently connected to the Internet. However, it can be
619 used on intermittently connected hosts with suitable configuration adjustments.
621 Configuration files currently exist for the following operating systems: AIX,
622 BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/
623 Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
624 OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
625 Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware.
626 Some of these operating systems are no longer current and cannot easily be
627 tested, so the configuration files may no longer work in practice.
629 There are also configuration files for compiling Exim in the Cygwin environment
630 that can be installed on systems running Windows. However, this document does
631 not contain any information about running Exim in the Cygwin environment.
633 The terms and conditions for the use and distribution of Exim are contained in
634 the file NOTICE. Exim is distributed under the terms of the GNU General Public
635 Licence, a copy of which may be found in the file LICENCE.
637 The use, supply or promotion of Exim for the purpose of sending bulk,
638 unsolicited electronic mail is incompatible with the basic aims of the program,
639 which revolve around the free provision of a service that enhances the quality
640 of personal communications. The author of Exim regards indiscriminate
641 mass-mailing as an antisocial, irresponsible abuse of the Internet.
643 Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
644 experience of running and working on the Smail 3 code, I could never have
645 contemplated starting to write a new MTA. Many of the ideas and user interfaces
646 were originally taken from Smail 3, though the actual code of Exim is entirely
647 new, and has developed far beyond the initial concept.
649 Many people, both in Cambridge and around the world, have contributed to the
650 development and the testing of Exim, and to porting it to various operating
651 systems. I am grateful to them all. The distribution now contains a file called
652 ACKNOWLEDGMENTS, in which I have started recording the names of contributors.
655 1.1 Exim documentation
656 ----------------------
658 This edition of the Exim specification applies to version 4.84.2 of Exim.
659 Substantive changes from the 4.83 edition are marked in some renditions of the
660 document; this paragraph is so marked if the rendition is capable of showing a
663 This document is very much a reference manual; it is not a tutorial. The reader
664 is expected to have some familiarity with the SMTP mail transfer protocol and
665 with general Unix system administration. Although there are some discussions
666 and examples in places, the information is mostly organized in a way that makes
667 it easy to look up, rather than in a natural order for sequential reading.
668 Furthermore, the manual aims to cover every aspect of Exim in detail, including
669 a number of rarely-used, special-purpose features that are unlikely to be of
672 An "easier" discussion of Exim which provides more in-depth explanatory,
673 introductory, and tutorial material can be found in a book entitled The Exim
674 SMTP Mail Server (second edition, 2007), published by UIT Cambridge (http://
675 www.uit.co.uk/exim-book/).
677 This book also contains a chapter that gives a general introduction to SMTP and
678 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
679 with the latest release of Exim. (Note that the earlier book about Exim,
680 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
682 If you are using a Debian distribution of Exim, you will find information about
683 Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian.
684 The command man update-exim.conf is another source of Debian-specific
687 As the program develops, there may be features in newer versions that have not
688 yet made it into this document, which is updated only when the most significant
689 digit of the fractional part of the version number changes. Specifications of
690 new features that are not yet in this manual are placed in the file doc/
691 NewStuff in the Exim distribution.
693 Some features may be classified as "experimental". These may change
694 incompatibly while they are developing, or even be withdrawn. For this reason,
695 they are not documented in this manual. Information about experimental features
696 can be found in the file doc/experimental.txt.
698 All changes to the program (whether new features, bug fixes, or other kinds of
699 change) are noted briefly in the file called doc/ChangeLog.
701 This specification itself is available as an ASCII file in doc/spec.txt so that
702 it can easily be searched with a text editor. Other files in the doc directory
705 OptionLists.txt list of all options in alphabetical order
706 dbm.discuss.txt discussion about DBM libraries
707 exim.8 a man page of Exim's command line options
708 experimental.txt documentation of experimental features
709 filter.txt specification of the filter language
710 Exim3.upgrade upgrade notes from release 2 to release 3
711 Exim4.upgrade upgrade notes from release 3 to release 4
713 The main specification and the specification of the filtering language are also
714 available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6
715 below tells you how to get hold of these.
718 1.2 FTP and web sites
719 ---------------------
721 The primary site for Exim source distributions is currently the University of
722 Cambridge's FTP site, whose contents are described in Where to find the Exim
723 distribution below. In addition, there is a web site and an FTP site at
724 exim.org. These are now also hosted at the University of Cambridge. The
725 exim.org site was previously hosted for a number of years by Energis Squared,
726 formerly Planet Online Ltd, whose support I gratefully acknowledge.
728 As well as Exim distribution tar files, the Exim web site contains a number of
729 differently formatted versions of the documentation. A recent addition to the
730 online information is the Exim wiki (http://wiki.exim.org), which contains what
731 used to be a separate FAQ, as well as various other examples, tips, and
732 know-how that have been contributed by Exim users.
734 An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report
735 bugs, and also to add items to the wish list. Please search first to check that
736 you are not duplicating a previous entry.
742 The following Exim mailing lists exist:
744 exim-announce@exim.org Moderated, low volume announcements list
745 exim-users@exim.org General discussion list
746 exim-dev@exim.org Discussion of bugs, enhancements, etc.
747 exim-cvs@exim.org Automated commit messages from the VCS
749 You can subscribe to these lists, change your existing subscriptions, and view
750 or search the archives via the mailing lists link on the Exim home page. If you
751 are using a Debian distribution of Exim, you may wish to subscribe to the
752 Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this
755 http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users
757 Please ask Debian-specific questions on this list and not on the general Exim
764 Training courses in Cambridge (UK) used to be run annually by the author of
765 Exim, before he retired. At the time of writing, there are no plans to run
766 further Exim courses in Cambridge. However, if that changes, relevant
767 information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/.
773 Reports of obvious bugs can be emailed to bugs@exim.org or reported via the
774 Bugzilla (http://bugs.exim.org). However, if you are unsure whether some
775 behaviour is a bug or not, the best thing to do is to post a message to the
776 exim-dev mailing list and have it discussed.
779 1.6 Where to find the Exim distribution
780 ---------------------------------------
782 The master ftp site for the Exim distribution is
784 ftp://ftp.csx.cam.ac.uk/pub/software/email/exim
788 ftp://ftp.exim.org/pub/exim
790 The file references that follow are relative to the exim directories at these
791 sites. There are now quite a number of independent mirror sites around the
792 world. Those that I know about are listed in the file called Mirrors.
794 Within the exim directory there are subdirectories called exim3 (for previous
795 Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing
796 for testing versions. In the exim4 subdirectory, the current release can always
797 be found in files called
802 where n.nn is the highest such version number in the directory. The two files
803 contain identical data; the only difference is the type of compression. The
804 .bz2 file is usually a lot smaller than the .gz file.
806 The distributions will be PGP signed by an individual key of the Release
807 Coordinator. This key will have a uid containing an email address in the
808 exim.org domain and will have signatures from other people, including other
809 Exim maintainers. We expect that the key will be in the "strong set" of PGP
810 keys. There should be a trust path to that key from Nigel Metheringham's PGP
811 key, a version of which can be found in the release directory in the file
812 nigel-pubkey.asc. All keys used will be available in public keyserver pools,
813 such as pool.sks-keyservers.net.
815 At time of last update, releases were being made by Phil Pennock and signed
816 with key 0x403043153903637F, although that key is expected to be replaced in
817 2013. A trust path from Nigel's key to Phil's can be observed at https://
818 www.security.spodhuis.org/exim-trustpath.
820 Releases have also been authorized to be performed by Todd Lyons who signs with
821 key 0xC4F4F94804D29EBA. A direct trust path exists between previous RE Phil
822 Pennock and Todd Lyons through a common associate.
824 The signatures for the tar bundles are in:
827 exim-n.nn.tar.bz2.asc
829 For each released version, the log of changes is made separately available in a
830 separate file in the directory ChangeLogs so that it is possible to find out
831 what has changed without having to download the entire distribution.
833 The main distribution contains ASCII versions of this specification and other
834 documentation; other formats of the documents are available in separate files
835 inside the exim4 directory of the FTP site:
837 exim-html-n.nn.tar.gz
839 exim-postscript-n.nn.tar.gz
840 exim-texinfo-n.nn.tar.gz
842 These tar files contain only the doc directory, not the complete distribution,
843 and are also available in .bz2 as well as .gz forms.
849 * Exim is designed for use as an Internet MTA, and therefore handles
850 addresses in RFC 2822 domain format only. It cannot handle UUCP "bang
851 paths", though simple two-component bang paths can be converted by a
852 straightforward rewriting configuration. This restriction does not prevent
853 Exim from being interfaced to UUCP as a transport mechanism, provided that
854 domain addresses are used.
856 * Exim insists that every address it handles has a domain attached. For
857 incoming local messages, domainless addresses are automatically qualified
858 with a configured domain value. Configuration options specify from which
859 remote systems unqualified addresses are acceptable. These are then
860 qualified on arrival.
862 * The only external transport mechanisms that are currently implemented are
863 SMTP and LMTP over a TCP/IP network (including support for IPv6). However,
864 a pipe transport is available, and there are facilities for writing
865 messages to files and pipes, optionally in batched SMTP format; these
866 facilities can be used to send messages to other transport mechanisms such
867 as UUCP, provided they can handle domain-style addresses. Batched SMTP
868 input is also catered for.
870 * Exim is not designed for storing mail for dial-in hosts. When the volumes
871 of such mail are large, it is better to get the messages "delivered" into
872 files (that is, off Exim's queue) and subsequently passed on to the dial-in
873 hosts by other means.
875 * Although Exim does have basic facilities for scanning incoming messages,
876 these are not comprehensive enough to do full virus or spam scanning. Such
877 operations are best carried out using additional specialized software
878 packages. If you compile Exim with the content-scanning extension,
879 straightforward interfaces to a number of common scanners are provided.
882 1.8 Run time configuration
883 --------------------------
885 Exim's run time configuration is held in a single text file that is divided
886 into a number of sections. The entries in this file consist of keywords and
887 values, in the style of Smail 3 configuration files. A default configuration
888 file which is suitable for simple online installations is provided in the
889 distribution, and is described in chapter 7 below.
892 1.9 Calling interface
893 ---------------------
895 Like many MTAs, Exim has adopted the Sendmail command line interface so that it
896 can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when
897 sending mail, but you do not need to know anything about Sendmail in order to
898 run Exim. For actions other than sending messages, Sendmail-compatible options
899 also exist, but those that produce output (for example, -bp, which lists the
900 messages on the queue) do so in Exim's own format. There are also some
901 additional options that are compatible with Smail 3, and some further options
902 that are new to Exim. Chapter 5 documents all Exim's command line options. This
903 information is automatically made into the man page that forms part of the Exim
906 Control of messages on the queue can be done via certain privileged command
907 line options. There is also an optional monitor program called eximon, which
908 displays current information in an X window, and which contains a menu
909 interface to Exim's command line administration options.
915 The body of a message is the actual data that the sender wants to transmit. It
916 is the last part of a message, and is separated from the header (see below) by
919 When a message cannot be delivered, it is normally returned to the sender in a
920 delivery failure message or a "non-delivery report" (NDR). The term bounce is
921 commonly used for this action, and the error reports are often called bounce
922 messages. This is a convenient shorthand for "delivery failure error report".
923 Such messages have an empty sender address in the message's envelope (see
924 below) to ensure that they cannot themselves give rise to further bounce
927 The term default appears frequently in this manual. It is used to qualify a
928 value which is used in the absence of any setting in the configuration. It may
929 also qualify an action which is taken unless a configuration setting specifies
932 The term defer is used when the delivery of a message to a specific destination
933 cannot immediately take place for some reason (a remote host may be down, or a
934 user's local mailbox may be full). Such deliveries are deferred until a later
937 The word domain is sometimes used to mean all but the first component of a
938 host's name. It is not used in that sense here, where it normally refers to the
939 part of an email address following the @ sign.
941 A message in transit has an associated envelope, as well as a header and a
942 body. The envelope contains a sender address (to which bounce messages should
943 be delivered), and any number of recipient addresses. References to the sender
944 or the recipients of a message usually mean the addresses in the envelope. An
945 MTA uses these addresses for delivery, and for returning bounce messages, not
946 the addresses that appear in the header lines.
948 The header of a message is the first part of a message's text, consisting of a
949 number of lines, each of which has a name such as From:, To:, Subject:, etc.
950 Long header lines can be split over several text lines by indenting the
951 continuations. The header is separated from the body by a blank line.
953 The term local part, which is taken from RFC 2822, is used to refer to that
954 part of an email address that precedes the @ sign. The part that follows the @
955 sign is called the domain or mail domain.
957 The terms local delivery and remote delivery are used to distinguish delivery
958 to a file or a pipe on the local host from delivery by SMTP over TCP/IP to
959 another host. As far as Exim is concerned, all hosts other than the host it is
960 running on are remote.
962 Return path is another name that is used for the sender address in a message's
965 The term queue is used to refer to the set of messages awaiting delivery,
966 because this term is in widespread use in the context of MTAs. However, in
967 Exim's case the reality is more like a pool than a queue, because there is
968 normally no ordering of waiting messages.
970 The term queue runner is used to describe a process that scans the queue and
971 attempts to deliver those messages whose retry times have come. This term is
972 used by other MTAs, and also relates to the command runq, but in Exim the
973 waiting messages are normally processed in an unpredictable order.
975 The term spool directory is used for a directory in which Exim keeps the
976 messages on its queue - that is, those that it is in the process of delivering.
977 This should not be confused with the directory in which local mailboxes are
978 stored, which is called a "spool directory" by some people. In the Exim
979 documentation, "spool" is always used in the first sense.
983 ===============================================================================
986 A number of pieces of external code are included in the Exim distribution.
988 * Regular expressions are supported in the main Exim program and in the Exim
989 monitor using the freely-distributable PCRE library, copyright (c)
990 University of Cambridge. The source to PCRE is no longer shipped with Exim,
991 so you will need to use the version of PCRE shipped with your system, or
992 obtain and install the full version of the library from ftp://
993 ftp.csx.cam.ac.uk/pub/software/programming/pcre.
995 * Support for the cdb (Constant DataBase) lookup method is provided by code
996 contributed by Nigel Metheringham of (at the time he contributed it) Planet
997 Online Ltd. The implementation is completely contained within the code of
998 Exim. It does not link against an external cdb library. The code contains
999 the following statements:
1001 Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
1003 This program is free software; you can redistribute it and/or modify it
1004 under the terms of the GNU General Public License as published by the
1005 Free Software Foundation; either version 2 of the License, or (at your
1006 option) any later version. This code implements Dan Bernstein's
1007 Constant DataBase (cdb) spec. Information, the spec and sample code for
1008 cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This
1009 implementation borrows some code from Dan Bernstein's implementation
1010 (which has no license restrictions applied to it).
1012 * Client support for Microsoft's Secure Password Authentication is provided
1013 by code contributed by Marc Prud'hommeaux. Server support was contributed
1014 by Tom Kistner. This includes code taken from the Samba project, which is
1015 released under the Gnu GPL.
1017 * Support for calling the Cyrus pwcheck and saslauthd daemons is provided by
1018 code taken from the Cyrus-SASL library and adapted by Alexander S.
1019 Sabourenkov. The permission notice appears below, in accordance with the
1020 conditions expressed therein.
1022 Copyright (c) 2001 Carnegie Mellon University. All rights reserved.
1024 Redistribution and use in source and binary forms, with or without
1025 modification, are permitted provided that the following conditions are
1028 1. Redistributions of source code must retain the above copyright
1029 notice, this list of conditions and the following disclaimer.
1031 2. Redistributions in binary form must reproduce the above copyright
1032 notice, this list of conditions and the following disclaimer in the
1033 documentation and/or other materials provided with the
1036 3. The name "Carnegie Mellon University" must not be used to endorse
1037 or promote products derived from this software without prior
1038 written permission. For permission or any other legal details,
1041 Office of Technology Transfer
1042 Carnegie Mellon University
1044 Pittsburgh, PA 15213-3890
1045 (412) 268-4387, fax: (412) 268-7395
1046 tech-transfer@andrew.cmu.edu
1048 4. Redistributions of any form whatsoever must retain the following
1051 "This product includes software developed by Computing Services at
1052 Carnegie Mellon University (http://www.cmu.edu/computing/."
1054 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
1055 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1056 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
1057 FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
1058 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
1059 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
1060 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
1063 * The Exim Monitor program, which is an X-Window application, includes
1064 modified versions of the Athena StripChart and TextPop widgets. This code
1065 is copyright by DEC and MIT, and their permission notice appears below, in
1066 accordance with the conditions expressed therein.
1068 Copyright 1987, 1988 by Digital Equipment Corporation, Maynard,
1069 Massachusetts, and the Massachusetts Institute of Technology,
1070 Cambridge, Massachusetts.
1074 Permission to use, copy, modify, and distribute this software and its
1075 documentation for any purpose and without fee is hereby granted,
1076 provided that the above copyright notice appear in all copies and that
1077 both that copyright notice and this permission notice appear in
1078 supporting documentation, and that the names of Digital or MIT not be
1079 used in advertising or publicity pertaining to distribution of the
1080 software without specific, written prior permission.
1082 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
1083 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
1084 EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
1085 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
1086 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1087 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1088 PERFORMANCE OF THIS SOFTWARE.
1090 * The DMARC implementation uses the OpenDMARC library which is Copyrighted by
1091 The Trusted Domain Project. Portions of Exim source which use OpenDMARC
1092 derived code are indicated in the respective source files. The full
1093 OpenDMARC license is provided in the LICENSE.opendmarc file contained in
1094 the distributed source code.
1096 * Many people have contributed code fragments, some large, some small, that
1097 were not covered by any specific licence requirements. It is assumed that
1098 the contributors are happy to see their code incorporated into Exim under
1103 ===============================================================================
1104 3. HOW EXIM RECEIVES AND DELIVERS MAIL
1107 3.1 Overall philosophy
1108 ----------------------
1110 Exim is designed to work efficiently on systems that are permanently connected
1111 to the Internet and are handling a general mix of mail. In such circumstances,
1112 most messages can be delivered immediately. Consequently, Exim does not
1113 maintain independent queues of messages for specific domains or hosts, though
1114 it does try to send several messages in a single SMTP connection after a host
1115 has been down, and it also maintains per-host retry information.
1121 Policy controls are now an important feature of MTAs that are connected to the
1122 Internet. Perhaps their most important job is to stop MTAs being abused as
1123 "open relays" by misguided individuals who send out vast amounts of unsolicited
1124 junk, and want to disguise its source. Exim provides flexible facilities for
1125 specifying policy controls on incoming mail:
1127 * Exim 4 (unlike previous versions of Exim) implements policy controls on
1128 incoming mail by means of Access Control Lists (ACLs). Each list is a
1129 series of statements that may either grant or deny access. ACLs can be used
1130 at several places in the SMTP dialogue while receiving a message from a
1131 remote host. However, the most common places are after each RCPT command,
1132 and at the very end of the message. The sysadmin can specify conditions for
1133 accepting or rejecting individual recipients or the entire message,
1134 respectively, at these two points (see chapter 42). Denial of access
1135 results in an SMTP error code.
1137 * An ACL is also available for locally generated, non-SMTP messages. In this
1138 case, the only available actions are to accept or deny the entire message.
1140 * When Exim is compiled with the content-scanning extension, facilities are
1141 provided in the ACL mechanism for passing the message to external virus and
1142 /or spam scanning software. The result of such a scan is passed back to the
1143 ACL, which can then use it to decide what to do with the message.
1145 * When a message has been received, either from a remote host or from the
1146 local host, but before the final acknowledgment has been sent, a locally
1147 supplied C function called local_scan() can be run to inspect the message
1148 and decide whether to accept it or not (see chapter 44). If the message is
1149 accepted, the list of recipients can be modified by the function.
1151 * Using the local_scan() mechanism is another way of calling external scanner
1152 software. The SA-Exim add-on package works this way. It does not require
1153 Exim to be compiled with the content-scanning extension.
1155 * After a message has been accepted, a further checking mechanism is
1156 available in the form of the system filter (see chapter 45). This runs at
1157 the start of every delivery process.
1163 In a conventional Exim configuration, users are able to run private filters by
1164 setting up appropriate .forward files in their home directories. See chapter 22
1165 (about the redirect router) for the configuration needed to support this, and
1166 the separate document entitled Exim's interfaces to mail filtering for user
1167 details. Two different kinds of filtering are available:
1169 * Sieve filters are written in the standard filtering language that is
1170 defined by RFC 3028.
1172 * Exim filters are written in a syntax that is unique to Exim, but which is
1173 more powerful than Sieve, which it pre-dates.
1175 User filters are run as part of the routing process, described below.
1178 3.4 Message identification
1179 --------------------------
1181 Every message handled by Exim is given a message id which is sixteen characters
1182 long. It is divided into three parts, separated by hyphens, for example
1183 "16VDhn-0001bo-D3". Each part is a sequence of letters and digits, normally
1184 encoding numbers in base 62. However, in the Darwin operating system (Mac OS X)
1185 and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of
1186 lower case letters) is used instead, because the message id is used to
1187 construct file names, and the names of files in those systems are not always
1190 The detail of the contents of the message id have changed as Exim has evolved.
1191 Earlier versions relied on the operating system not re-using a process id (pid)
1192 within one second. On modern operating systems, this assumption can no longer
1193 be made, so the algorithm had to be changed. To retain backward compatibility,
1194 the format of the message id was retained, which is why the following rules are
1197 * The first six characters of the message id are the time at which the
1198 message started to be received, to a granularity of one second. That is,
1199 this field contains the number of seconds since the start of the epoch (the
1200 normal Unix way of representing the date and time of day).
1202 * After the first hyphen, the next six characters are the id of the process
1203 that received the message.
1205 * There are two different possibilities for the final two characters:
1207 1. If localhost_number is not set, this value is the fractional part of
1208 the time of reception, normally in units of 1/2000 of a second, but for
1209 systems that must use base 36 instead of base 62 (because of
1210 case-insensitive file systems), the units are 1/1000 of a second.
1212 2. If localhost_number is set, it is multiplied by 200 (100) and added to
1213 the fractional part of the time, which in this case is in units of 1/
1214 200 (1/100) of a second.
1216 After a message has been received, Exim waits for the clock to tick at the
1217 appropriate resolution before proceeding, so that if another message is
1218 received by the same process, or by another process with the same (re-used)
1219 pid, it is guaranteed that the time will be different. In most cases, the clock
1220 will already have ticked while the message was being received.
1226 The only way Exim can receive mail from another host is using SMTP over TCP/IP,
1227 in which case the sender and recipient addresses are transferred using SMTP
1228 commands. However, from a locally running process (such as a user's MUA), there
1229 are several possibilities:
1231 * If the process runs Exim with the -bm option, the message is read
1232 non-interactively (usually via a pipe), with the recipients taken from the
1233 command line, or from the body of the message if -t is also used.
1235 * If the process runs Exim with the -bS option, the message is also read
1236 non-interactively, but in this case the recipients are listed at the start
1237 of the message in a series of SMTP RCPT commands, terminated by a DATA
1238 command. This is so-called "batch SMTP" format, but it isn't really SMTP.
1239 The SMTP commands are just another way of passing envelope addresses in a
1240 non-interactive submission.
1242 * If the process runs Exim with the -bs option, the message is read
1243 interactively, using the SMTP protocol. A two-way pipe is normally used for
1244 passing data between the local process and the Exim process. This is "real"
1245 SMTP and is handled in the same way as SMTP over TCP/IP. For example, the
1246 ACLs for SMTP commands are used for this form of submission.
1248 * A local process may also make a TCP/IP call to the host's loopback address
1249 (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
1250 does not treat the loopback address specially. It treats all such
1251 connections in the same way as connections from other hosts.
1253 In the three cases that do not involve TCP/IP, the sender address is
1254 constructed from the login name of the user that called Exim and a default
1255 qualification domain (which can be set by the qualify_domain configuration
1256 option). For local or batch SMTP, a sender address that is passed using the
1257 SMTP MAIL command is ignored. However, the system administrator may allow
1258 certain users ("trusted users") to specify a different sender address
1259 unconditionally, or all users to specify certain forms of different sender
1260 address. The -f option or the SMTP MAIL command is used to specify these
1261 different addresses. See section 5.2 for details of trusted users, and the
1262 untrusted_set_sender option for a way of allowing untrusted users to change
1265 Messages received by either of the non-interactive mechanisms are subject to
1266 checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
1267 (either over TCP/IP, or interacting with a local process) can be checked by a
1268 number of ACLs that operate at different times during the SMTP session. Either
1269 individual recipients, or the entire message, can be rejected if local policy
1270 requirements are not met. The local_scan() function (see chapter 44) is run for
1271 all incoming messages.
1273 Exim can be configured not to start a delivery process when a message is
1274 received; this can be unconditional, or depend on the number of incoming SMTP
1275 connections or the system load. In these situations, new messages wait on the
1276 queue until a queue runner process picks them up. However, in standard
1277 configurations under normal conditions, delivery is started as soon as a
1278 message is received.
1281 3.6 Handling an incoming message
1282 --------------------------------
1284 When Exim accepts a message, it writes two files in its spool directory. The
1285 first contains the envelope information, the current status of the message, and
1286 the header lines, and the second contains the body of the message. The names of
1287 the two spool files consist of the message id, followed by "-H" for the file
1288 containing the envelope and header, and "-D" for the data file.
1290 By default all these message files are held in a single directory called input
1291 inside the general Exim spool directory. Some operating systems do not perform
1292 very well if the number of files in a directory gets large; to improve
1293 performance in such cases, the split_spool_directory option can be used. This
1294 causes Exim to split up the input files into 62 sub-directories whose names are
1295 single letters or digits. When this is done, the queue is processed one
1296 sub-directory at a time instead of all at once, which can improve overall
1297 performance even when there are not enough files in each directory to affect
1298 file system performance.
1300 The envelope information consists of the address of the message's sender and
1301 the addresses of the recipients. This information is entirely separate from any
1302 addresses contained in the header lines. The status of the message includes a
1303 list of recipients who have already received the message. The format of the
1304 first spool file is described in chapter 55.
1306 Address rewriting that is specified in the rewrite section of the configuration
1307 (see chapter 31) is done once and for all on incoming addresses, both in the
1308 header lines and the envelope, at the time the message is accepted. If during
1309 the course of delivery additional addresses are generated (for example, via
1310 aliasing), these new addresses are rewritten as soon as they are generated. At
1311 the time a message is actually delivered (transported) further rewriting can
1312 take place; because this is a transport option, it can be different for
1313 different forms of delivery. It is also possible to specify the addition or
1314 removal of certain header lines at the time the message is delivered (see
1315 chapters 15 and 24).
1318 3.7 Life of a message
1319 ---------------------
1321 A message remains in the spool directory until it is completely delivered to
1322 its recipients or to an error address, or until it is deleted by an
1323 administrator or by the user who originally created it. In cases when delivery
1324 cannot proceed - for example, when a message can neither be delivered to its
1325 recipients nor returned to its sender, the message is marked "frozen" on the
1326 spool, and no more deliveries are attempted.
1328 An administrator can "thaw" such messages when the problem has been corrected,
1329 and can also freeze individual messages by hand if necessary. In addition, an
1330 administrator can force a delivery error, causing a bounce message to be sent.
1332 There are options called ignore_bounce_errors_after and timeout_frozen_after,
1333 which discard frozen messages after a certain time. The first applies only to
1334 frozen bounces, the second to any frozen messages.
1336 While Exim is working on a message, it writes information about each delivery
1337 attempt to its main log file. This includes successful, unsuccessful, and
1338 delayed deliveries for each recipient (see chapter 51). The log lines are also
1339 written to a separate message log file for each message. These logs are solely
1340 for the benefit of the administrator, and are normally deleted along with the
1341 spool files when processing of a message is complete. The use of individual
1342 message logs can be disabled by setting no_message_logs; this might give an
1343 improvement in performance on very busy systems.
1345 All the information Exim itself needs to set up a delivery is kept in the first
1346 spool file, along with the header lines. When a successful delivery occurs, the
1347 address is immediately written at the end of a journal file, whose name is the
1348 message id followed by "-J". At the end of a delivery run, if there are some
1349 addresses left to be tried again later, the first spool file (the "-H" file) is
1350 updated to indicate which these are, and the journal file is then deleted.
1351 Updating the spool file is done by writing a new file and renaming it, to
1352 minimize the possibility of data loss.
1354 Should the system or the program crash after a successful delivery but before
1355 the spool file has been updated, the journal is left lying around. The next
1356 time Exim attempts to deliver the message, it reads the journal file and
1357 updates the spool file before proceeding. This minimizes the chances of double
1358 deliveries caused by crashes.
1361 3.8 Processing an address for delivery
1362 --------------------------------------
1364 The main delivery processing elements of Exim are called routers and transports
1365 , and collectively these are known as drivers. Code for a number of them is
1366 provided in the source distribution, and compile-time options specify which
1367 ones are included in the binary. Run time options specify which ones are
1368 actually used for delivering messages.
1370 Each driver that is specified in the run time configuration is an instance of
1371 that particular driver type. Multiple instances are allowed; for example, you
1372 can set up several different smtp transports, each with different option values
1373 that might specify different ports or different timeouts. Each instance has its
1374 own identifying name. In what follows we will normally use the instance name
1375 when discussing one particular instance (that is, one specific configuration of
1376 the driver), and the generic driver name when discussing the driver's features
1379 A router is a driver that operates on an address, either determining how its
1380 delivery should happen, by assigning it to a specific transport, or converting
1381 the address into one or more new addresses (for example, via an alias file). A
1382 router may also explicitly choose to fail an address, causing it to be bounced.
1384 A transport is a driver that transmits a copy of the message from Exim's spool
1385 to some destination. There are two kinds of transport: for a local transport,
1386 the destination is a file or a pipe on the local host, whereas for a remote
1387 transport the destination is some other host. A message is passed to a specific
1388 transport as a result of successful routing. If a message has several
1389 recipients, it may be passed to a number of different transports.
1391 An address is processed by passing it to each configured router instance in
1392 turn, subject to certain preconditions, until a router accepts the address or
1393 specifies that it should be bounced. We will describe this process in more
1394 detail shortly. First, as a simple example, we consider how each recipient
1395 address in a message is processed in a small configuration of three routers.
1397 To make this a more concrete example, it is described in terms of some actual
1398 routers, but remember, this is only an example. You can configure Exim's
1399 routers in many different ways, and there may be any number of routers in a
1402 The first router that is specified in a configuration is often one that handles
1403 addresses in domains that are not recognized specially by the local host. These
1404 are typically addresses for arbitrary domains on the Internet. A precondition
1405 is set up which looks for the special domains known to the host (for example,
1406 its own domain name), and the router is run for addresses that do not match.
1407 Typically, this is a router that looks up domains in the DNS in order to find
1408 the hosts to which this address routes. If it succeeds, the address is assigned
1409 to a suitable SMTP transport; if it does not succeed, the router is configured
1410 to fail the address.
1412 The second router is reached only when the domain is recognized as one that
1413 "belongs" to the local host. This router does redirection - also known as
1414 aliasing and forwarding. When it generates one or more new addresses from the
1415 original, each of them is routed independently from the start. Otherwise, the
1416 router may cause an address to fail, or it may simply decline to handle the
1417 address, in which case the address is passed to the next router.
1419 The final router in many configurations is one that checks to see if the
1420 address belongs to a local mailbox. The precondition may involve a check to see
1421 if the local part is the name of a login account, or it may look up the local
1422 part in a file or a database. If its preconditions are not met, or if the
1423 router declines, we have reached the end of the routers. When this happens, the
1427 3.9 Processing an address for verification
1428 ------------------------------------------
1430 As well as being used to decide how to deliver to an address, Exim's routers
1431 are also used for address verification. Verification can be requested as one of
1432 the checks to be performed in an ACL for incoming messages, on both sender and
1433 recipient addresses, and it can be tested using the -bv and -bvs command line
1436 When an address is being verified, the routers are run in "verify mode". This
1437 does not affect the way the routers work, but it is a state that can be
1438 detected. By this means, a router can be skipped or made to behave differently
1439 when verifying. A common example is a configuration in which the first router
1440 sends all messages to a message-scanning program, unless they have been
1441 previously scanned. Thus, the first router accepts all addresses without any
1442 checking, making it useless for verifying. Normally, the no_verify option would
1443 be set for such a router, causing it to be skipped in verify mode.
1446 3.10 Running an individual router
1447 ---------------------------------
1449 As explained in the example above, a number of preconditions are checked before
1450 running a router. If any are not met, the router is skipped, and the address is
1451 passed to the next router. When all the preconditions on a router are met, the
1452 router is run. What happens next depends on the outcome, which is one of the
1455 * accept: The router accepts the address, and either assigns it to a
1456 transport, or generates one or more "child" addresses. Processing the
1457 original address ceases, unless the unseen option is set on the router.
1458 This option can be used to set up multiple deliveries with different
1459 routing (for example, for keeping archive copies of messages). When unseen
1460 is set, the address is passed to the next router. Normally, however, an
1461 accept return marks the end of routing.
1463 Any child addresses generated by the router are processed independently,
1464 starting with the first router by default. It is possible to change this by
1465 setting the redirect_router option to specify which router to start at for
1466 child addresses. Unlike pass_router (see below) the router specified by
1467 redirect_router may be anywhere in the router configuration.
1469 * pass: The router recognizes the address, but cannot handle it itself. It
1470 requests that the address be passed to another router. By default the
1471 address is passed to the next router, but this can be changed by setting
1472 the pass_router option. However, (unlike redirect_router) the named router
1473 must be below the current router (to avoid loops).
1475 * decline: The router declines to accept the address because it does not
1476 recognize it at all. By default, the address is passed to the next router,
1477 but this can be prevented by setting the no_more option. When no_more is
1478 set, all the remaining routers are skipped. In effect, no_more converts
1481 * fail: The router determines that the address should fail, and queues it for
1482 the generation of a bounce message. There is no further processing of the
1483 original address unless unseen is set on the router.
1485 * defer: The router cannot handle the address at the present time. (A
1486 database may be offline, or a DNS lookup may have timed out.) No further
1487 processing of the address happens in this delivery attempt. It is tried
1488 again next time the message is considered for delivery.
1490 * error: There is some error in the router (for example, a syntax error in
1491 its configuration). The action is as for defer.
1493 If an address reaches the end of the routers without having been accepted by
1494 any of them, it is bounced as unrouteable. The default error message in this
1495 situation is "unrouteable address", but you can set your own message by making
1496 use of the cannot_route_message option. This can be set for any router; the
1497 value from the last router that "saw" the address is used.
1499 Sometimes while routing you want to fail a delivery when some conditions are
1500 met but others are not, instead of passing the address on for further routing.
1501 You can do this by having a second router that explicitly fails the delivery
1502 when the relevant conditions are met. The redirect router has a "fail" facility
1506 3.11 Duplicate addresses
1507 ------------------------
1509 Once routing is complete, Exim scans the addresses that are assigned to local
1510 and remote transports, and discards any duplicates that it finds. During this
1511 check, local parts are treated as case-sensitive. This happens only when
1512 actually delivering a message; when testing routers with -bt, all the routed
1513 addresses are shown.
1516 3.12 Router preconditions
1517 -------------------------
1519 The preconditions that are tested for each router are listed below, in the
1520 order in which they are tested. The individual configuration options are
1521 described in more detail in chapter 15.
1523 * The local_part_prefix and local_part_suffix options can specify that the
1524 local parts handled by the router may or must have certain prefixes and/or
1525 suffixes. If a mandatory affix (prefix or suffix) is not present, the
1526 router is skipped. These conditions are tested first. When an affix is
1527 present, it is removed from the local part before further processing,
1528 including the evaluation of any other conditions.
1530 * Routers can be designated for use only when not verifying an address, that
1531 is, only when routing it for delivery (or testing its delivery routing). If
1532 the verify option is set false, the router is skipped when Exim is
1533 verifying an address. Setting the verify option actually sets two options,
1534 verify_sender and verify_recipient, which independently control the use of
1535 the router for sender and recipient verification. You can set these options
1536 directly if you want a router to be used for only one type of verification.
1537 Note that cutthrough delivery is classed as a recipient verification for
1540 * If the address_test option is set false, the router is skipped when Exim is
1541 run with the -bt option to test an address routing. This can be helpful
1542 when the first router sends all new messages to a scanner of some sort; it
1543 makes it possible to use -bt to test subsequent delivery routing without
1544 having to simulate the effect of the scanner.
1546 * Routers can be designated for use only when verifying an address, as
1547 opposed to routing it for delivery. The verify_only option controls this.
1548 Again, cutthrough delivery counts as a verification.
1550 * Individual routers can be explicitly skipped when running the routers to
1551 check an address given in the SMTP EXPN command (see the expn option).
1553 * If the domains option is set, the domain of the address must be in the set
1554 of domains that it defines.
1556 * If the local_parts option is set, the local part of the address must be in
1557 the set of local parts that it defines. If local_part_prefix or
1558 local_part_suffix is in use, the prefix or suffix is removed from the local
1559 part before this check. If you want to do precondition tests on local parts
1560 that include affixes, you can do so by using a condition option (see below)
1561 that uses the variables $local_part, $local_part_prefix, and
1562 $local_part_suffix as necessary.
1564 * If the check_local_user option is set, the local part must be the name of
1565 an account on the local host. If this check succeeds, the uid and gid of
1566 the local user are placed in $local_user_uid and $local_user_gid and the
1567 user's home directory is placed in $home; these values can be used in the
1568 remaining preconditions.
1570 * If the router_home_directory option is set, it is expanded at this point,
1571 because it overrides the value of $home. If this expansion were left till
1572 later, the value of $home as set by check_local_user would be used in
1573 subsequent tests. Having two different values of $home in the same router
1574 could lead to confusion.
1576 * If the senders option is set, the envelope sender address must be in the
1577 set of addresses that it defines.
1579 * If the require_files option is set, the existence or non-existence of
1580 specified files is tested.
1582 * If the condition option is set, it is evaluated and tested. This option
1583 uses an expanded string to allow you to set up your own custom
1584 preconditions. Expanded strings are described in chapter 11.
1586 Note that require_files comes near the end of the list, so you cannot use it to
1587 check for the existence of a file in which to lookup up a domain, local part,
1588 or sender. However, as these options are all expanded, you can use the exists
1589 expansion condition to make such tests within each condition. The require_files
1590 option is intended for checking files that the router may be going to use
1591 internally, or which are needed by a specific transport (for example,
1595 3.13 Delivery in detail
1596 -----------------------
1598 When a message is to be delivered, the sequence of events is as follows:
1600 * If a system-wide filter file is specified, the message is passed to it. The
1601 filter may add recipients to the message, replace the recipients, discard
1602 the message, cause a new message to be generated, or cause the message
1603 delivery to fail. The format of the system filter file is the same as for
1604 Exim user filter files, described in the separate document entitled Exim's
1605 interfaces to mail filtering. (Note: Sieve cannot be used for system filter
1608 Some additional features are available in system filters - see chapter 45
1609 for details. Note that a message is passed to the system filter only once
1610 per delivery attempt, however many recipients it has. However, if there are
1611 several delivery attempts because one or more addresses could not be
1612 immediately delivered, the system filter is run each time. The filter
1613 condition first_delivery can be used to detect the first run of the system
1616 * Each recipient address is offered to each configured router in turn,
1617 subject to its preconditions, until one is able to handle it. If no router
1618 can handle the address, that is, if they all decline, the address is
1619 failed. Because routers can be targeted at particular domains, several
1620 locally handled domains can be processed entirely independently of each
1623 * A router that accepts an address may assign it to a local or a remote
1624 transport. However, the transport is not run at this time. Instead, the
1625 address is placed on a list for the particular transport, which will be run
1626 later. Alternatively, the router may generate one or more new addresses
1627 (typically from alias, forward, or filter files). New addresses are fed
1628 back into this process from the top, but in order to avoid loops, a router
1629 ignores any address which has an identically-named ancestor that was
1630 processed by itself.
1632 * When all the routing has been done, addresses that have been successfully
1633 handled are passed to their assigned transports. When local transports are
1634 doing real local deliveries, they handle only one address at a time, but if
1635 a local transport is being used as a pseudo-remote transport (for example,
1636 to collect batched SMTP messages for transmission by some other means)
1637 multiple addresses can be handled. Remote transports can always handle more
1638 than one address at a time, but can be configured not to do so, or to
1639 restrict multiple addresses to the same domain.
1641 * Each local delivery to a file or a pipe runs in a separate process under a
1642 non-privileged uid, and these deliveries are run one at a time. Remote
1643 deliveries also run in separate processes, normally under a uid that is
1644 private to Exim ("the Exim user"), but in this case, several remote
1645 deliveries can be run in parallel. The maximum number of simultaneous
1646 remote deliveries for any one message is set by the remote_max_parallel
1647 option. The order in which deliveries are done is not defined, except that
1648 all local deliveries happen before any remote deliveries.
1650 * When it encounters a local delivery during a queue run, Exim checks its
1651 retry database to see if there has been a previous temporary delivery
1652 failure for the address before running the local transport. If there was a
1653 previous failure, Exim does not attempt a new delivery until the retry time
1654 for the address is reached. However, this happens only for delivery
1655 attempts that are part of a queue run. Local deliveries are always
1656 attempted when delivery immediately follows message reception, even if
1657 retry times are set for them. This makes for better behaviour if one
1658 particular message is causing problems (for example, causing quota
1659 overflow, or provoking an error in a filter file).
1661 * Remote transports do their own retry handling, since an address may be
1662 deliverable to one of a number of hosts, each of which may have a different
1663 retry time. If there have been previous temporary failures and no host has
1664 reached its retry time, no delivery is attempted, whether in a queue run or
1665 not. See chapter 32 for details of retry strategies.
1667 * If there were any permanent errors, a bounce message is returned to an
1668 appropriate address (the sender in the common case), with details of the
1669 error for each failing address. Exim can be configured to send copies of
1670 bounce messages to other addresses.
1672 * If one or more addresses suffered a temporary failure, the message is left
1673 on the queue, to be tried again later. Delivery of these addresses is said
1676 * When all the recipient addresses have either been delivered or bounced,
1677 handling of the message is complete. The spool files and message log are
1678 deleted, though the message log can optionally be preserved if required.
1681 3.14 Retry mechanism
1682 --------------------
1684 Exim's mechanism for retrying messages that fail to get delivered at the first
1685 attempt is the queue runner process. You must either run an Exim daemon that
1686 uses the -q option with a time interval to start queue runners at regular
1687 intervals, or use some other means (such as cron) to start them. If you do not
1688 arrange for queue runners to be run, messages that fail temporarily at the
1689 first attempt will remain on your queue for ever. A queue runner process works
1690 its way through the queue, one message at a time, trying each delivery that has
1691 passed its retry time. You can run several queue runners at once.
1693 Exim uses a set of configured rules to determine when next to retry the failing
1694 address (see chapter 32). These rules also specify when Exim should give up
1695 trying to deliver to the address, at which point it generates a bounce message.
1696 If no retry rules are set for a particular host, address, and error
1697 combination, no retries are attempted, and temporary errors are treated as
1701 3.15 Temporary delivery failure
1702 -------------------------------
1704 There are many reasons why a message may not be immediately deliverable to a
1705 particular address. Failure to connect to a remote machine (because it, or the
1706 connection to it, is down) is one of the most common. Temporary failures may be
1707 detected during routing as well as during the transport stage of delivery.
1708 Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
1709 is on a file system where the user is over quota. Exim can be configured to
1710 impose its own quotas on local mailboxes; where system quotas are set they will
1713 If a host is unreachable for a period of time, a number of messages may be
1714 waiting for it by the time it recovers, and sending them in a single SMTP
1715 connection is clearly beneficial. Whenever a delivery to a remote host is
1716 deferred, Exim makes a note in its hints database, and whenever a successful
1717 SMTP delivery has happened, it looks to see if any other messages are waiting
1718 for the same host. If any are found, they are sent over the same SMTP
1719 connection, subject to a configuration limit as to the maximum number in any
1723 3.16 Permanent delivery failure
1724 -------------------------------
1726 When a message cannot be delivered to some or all of its intended recipients, a
1727 bounce message is generated. Temporary delivery failures turn into permanent
1728 errors when their timeout expires. All the addresses that fail in a given
1729 delivery attempt are listed in a single message. If the original message has
1730 many recipients, it is possible for some addresses to fail in one delivery
1731 attempt and others to fail subsequently, giving rise to more than one bounce
1732 message. The wording of bounce messages can be customized by the administrator.
1733 See chapter 48 for details.
1735 Bounce messages contain an X-Failed-Recipients: header line that lists the
1736 failed addresses, for the benefit of programs that try to analyse such messages
1739 A bounce message is normally sent to the sender of the original message, as
1740 obtained from the message's envelope. For incoming SMTP messages, this is the
1741 address given in the MAIL command. However, when an address is expanded via a
1742 forward or alias file, an alternative address can be specified for delivery
1743 failures of the generated addresses. For a mailing list expansion (see section
1744 49.2) it is common to direct bounce messages to the manager of the list.
1747 3.17 Failures to deliver bounce messages
1748 ----------------------------------------
1750 If a bounce message (either locally generated or received from a remote host)
1751 itself suffers a permanent delivery failure, the message is left on the queue,
1752 but it is frozen, awaiting the attention of an administrator. There are options
1753 that can be used to make Exim discard such failed messages, or to keep them for
1754 only a short time (see timeout_frozen_after and ignore_bounce_errors_after).
1758 ===============================================================================
1759 4. BUILDING AND INSTALLING EXIM
1765 Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
1766 creates a directory with the name of the current release (for example,
1767 exim-4.84.2) into which the following files are placed:
1769 ACKNOWLEDGMENTS contains some acknowledgments
1770 CHANGES contains a reference to where changes are documented
1771 LICENCE the GNU General Public Licence
1772 Makefile top-level make file
1773 NOTICE conditions for the use of Exim
1774 README list of files, directories and simple build instructions
1776 Other files whose names begin with README may also be present. The following
1777 subdirectories are created:
1779 Local an empty directory for local configuration files
1780 OS OS-specific files
1781 doc documentation files
1782 exim_monitor source files for the Exim monitor
1783 scripts scripts used in the build process
1784 src remaining source files
1785 util independent utilities
1787 The main utility programs are contained in the src directory, and are built
1788 with the Exim binary. The util directory contains a few optional scripts that
1789 may be useful to some sites.
1792 4.2 Multiple machine architectures and operating systems
1793 --------------------------------------------------------
1795 The building process for Exim is arranged to make it easy to build binaries for
1796 a number of different architectures and operating systems from the same set of
1797 source files. Compilation does not take place in the src directory. Instead, a
1798 build directory is created for each architecture and operating system. Symbolic
1799 links to the sources are installed in this directory, which is where the actual
1800 building takes place. In most cases, Exim can discover the machine architecture
1801 and operating system for itself, but the defaults can be overridden if
1808 Exim no longer has an embedded PCRE library as the vast majority of modern
1809 systems include PCRE as a system library, although you may need to install the
1810 PCRE or PCRE development package for your operating system. If your system has
1811 a normal PCRE installation the Exim build process will need no further
1812 configuration. If the library or the headers are in an unusual location you
1813 will need to either set the PCRE_LIBS and INCLUDE directives appropriately, or
1814 set PCRE_CONFIG=yes to use the installed pcre-config command. If your operating
1815 system has no PCRE support then you will need to obtain and build the current
1816 PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More
1817 information on PCRE is available at http://www.pcre.org/.
1823 Even if you do not use any DBM files in your configuration, Exim still needs a
1824 DBM library in order to operate, because it uses indexed files for its hints
1825 databases. Unfortunately, there are a number of DBM libraries in existence, and
1826 different operating systems often have different ones installed.
1828 If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
1829 Linux distribution, the DBM configuration should happen automatically, and you
1830 may be able to ignore this section. Otherwise, you may have to learn more than
1831 you would like about DBM libraries from what follows.
1833 Licensed versions of Unix normally contain a library of DBM functions operating
1834 via the ndbm interface, and this is what Exim expects by default. Free versions
1835 of Unix seem to vary in what they contain as standard. In particular, some
1836 early versions of Linux have no default DBM library, and different distributors
1837 have chosen to bundle different libraries with their packaged versions.
1838 However, the more recent releases seem to have standardized on the Berkeley DB
1841 Different DBM libraries have different conventions for naming the files they
1842 use. When a program opens a file called dbmfile, there are several
1845 1. A traditional ndbm implementation, such as that supplied as part of
1846 Solaris, operates on two files called dbmfile.dir and dbmfile.pag.
1848 2. The GNU library, gdbm, operates on a single file. If used via its ndbm
1849 compatibility interface it makes two different hard links to it with names
1850 dbmfile.dir and dbmfile.pag, but if used via its native interface, the file
1851 name is used unmodified.
1853 3. The Berkeley DB package, if called via its ndbm compatibility interface,
1854 operates on a single file called dbmfile.db, but otherwise looks to the
1855 programmer exactly the same as the traditional ndbm implementation.
1857 4. If the Berkeley package is used in its native mode, it operates on a single
1858 file called dbmfile; the programmer's interface is somewhat different to
1859 the traditional ndbm interface.
1861 5. To complicate things further, there are several very different versions of
1862 the Berkeley DB package. Version 1.85 was stable for a very long time,
1863 releases 2.x and 3.x were current for a while, but the latest versions are
1864 now numbered 4.x. Maintenance of some of the earlier releases has ceased.
1865 All versions of Berkeley DB can be obtained from http://www.sleepycat.com/.
1867 6. Yet another DBM library, called tdb, is available from http://
1868 download.sourceforge.net/tdb. It has its own interface, and also operates
1871 Exim and its utilities can be compiled to use any of these interfaces. In order
1872 to use any version of the Berkeley DB package in native mode, you must set
1873 USE_DB in an appropriate configuration file (typically Local/Makefile). For
1878 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is
1879 diagnosed if you set more than one of these.
1881 At the lowest level, the build-time configuration sets none of these options,
1882 thereby assuming an interface of type (1). However, some operating system
1883 configuration files (for example, those for the BSD operating systems and
1884 Linux) assume type (4) by setting USE_DB as their default, and the
1885 configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile
1886 , however, overrides these system defaults.
1888 As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to
1889 set DBMLIB, to cause inclusion of the appropriate library, as in one of these
1895 Settings like that will work if the DBM library is installed in the standard
1896 place. Sometimes it is not, and the library's header file may also not be in
1897 the default path. You may need to set INCLUDE to specify where the header file
1898 is, and to specify the path to the library more fully in DBMLIB, as in this
1901 INCLUDE=-I/usr/local/include/db-4.1
1902 DBMLIB=/usr/local/lib/db-4.1/libdb.a
1904 There is further detailed discussion about the various DBM libraries in the
1905 file doc/dbm.discuss.txt in the Exim distribution.
1908 4.5 Pre-building configuration
1909 ------------------------------
1911 Before building Exim, a local configuration file that specifies options
1912 independent of any operating system has to be created with the name Local/
1913 Makefile. A template for this file is supplied as the file src/EDITME, and it
1914 contains full descriptions of all the option settings therein. These
1915 descriptions are therefore not repeated here. If you are building Exim for the
1916 first time, the simplest thing to do is to copy src/EDITME to Local/Makefile,
1917 then read it and edit it appropriately.
1919 There are three settings that you must supply, because Exim will not build
1920 without them. They are the location of the run time configuration file
1921 (CONFIGURE_FILE), the directory in which Exim binaries will be installed
1922 (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe
1923 EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a
1924 colon-separated list of file names; Exim uses the first of them that exists.
1926 There are a few other parameters that can be specified either at build time or
1927 at run time, to enable the same binary to be used on a number of different
1928 machines. However, if the locations of Exim's spool directory and log file
1929 directory (if not within the spool directory) are fixed, it is recommended that
1930 you specify them in Local/Makefile instead of at run time, so that errors
1931 detected early in Exim's execution (such as a malformed configuration file) can
1934 Exim's interfaces for calling virus and spam scanning software directly from
1935 access control lists are not compiled by default. If you want to include these
1936 facilities, you need to set
1938 WITH_CONTENT_SCAN=yes
1940 in your Local/Makefile. For details of the facilities themselves, see chapter
1943 If you are going to build the Exim monitor, a similar configuration process is
1944 required. The file exim_monitor/EDITME must be edited appropriately for your
1945 installation and saved under the name Local/eximon.conf. If you are happy with
1946 the default settings described in exim_monitor/EDITME, Local/eximon.conf can be
1947 empty, but it must exist.
1949 This is all the configuration that is needed in straightforward cases for known
1950 operating systems. However, the building process is set up so that it is easy
1951 to override options that are set by default or by operating-system-specific
1952 configuration files, for example to change the name of the C compiler, which
1953 defaults to gcc. See section 4.13 below for details of how to do this.
1956 4.6 Support for iconv()
1957 -----------------------
1959 The contents of header lines in messages may be encoded according to the rules
1960 described RFC 2047. This makes it possible to transmit characters that are not
1961 in the ASCII character set, and to label them as being in a particular
1962 character set. When Exim is inspecting header lines by means of the $h_
1963 mechanism, it decodes them, and translates them into a specified character set
1964 (default ISO-8859-1). The translation is possible only if the operating system
1965 supports the iconv() function.
1967 However, some of the operating systems that supply iconv() do not support very
1968 many conversions. The GNU libiconv library (available from http://www.gnu.org/
1969 software/libiconv/) can be installed on such systems to remedy this deficiency,
1970 as well as on systems that do not supply iconv() at all. After installing
1971 libiconv, you should add
1975 to your Local/Makefile and rebuild Exim.
1978 4.7 Including TLS/SSL encryption support
1979 ----------------------------------------
1981 Exim can be built to support encrypted SMTP connections, using the STARTTLS
1982 command as per RFC 2487. It can also support legacy clients that expect to
1983 start a TLS session immediately on connection to a non-standard port (see the
1984 tls_on_connect_ports runtime option and the -tls-on-connect command line
1987 If you want to build Exim with TLS support, you must first install either the
1988 OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
1991 If OpenSSL is installed, you should set
1994 TLS_LIBS=-lssl -lcrypto
1996 in Local/Makefile. You may also need to specify the locations of the OpenSSL
1997 library and include files. For example:
2000 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
2001 TLS_INCLUDE=-I/usr/local/openssl/include/
2003 If you have pkg-config available, then instead you can just use:
2006 USE_OPENSSL_PC=openssl
2008 If GnuTLS is installed, you should set
2012 TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
2014 in Local/Makefile, and again you may need to specify the locations of the
2015 library and include files. For example:
2019 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
2020 TLS_INCLUDE=-I/usr/gnu/include
2022 If you have pkg-config available, then instead you can just use:
2026 USE_GNUTLS_PC=gnutls
2028 You do not need to set TLS_INCLUDE if the relevant directory is already
2029 specified in INCLUDE. Details of how to configure Exim to make use of TLS are
2030 given in chapter 41.
2033 4.8 Use of tcpwrappers
2034 ----------------------
2036 Exim can be linked with the tcpwrappers library in order to check incoming SMTP
2037 calls using the tcpwrappers control files. This may be a convenient alternative
2038 to Exim's own checking facilities for installations that are already making use
2039 of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS
2040 in Local/Makefile, arrange for the file tcpd.h to be available at compile time,
2041 and also ensure that the library libwrap.a is available at link time, typically
2042 by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed
2043 in /usr/local, you might have
2045 USE_TCP_WRAPPERS=yes
2046 CFLAGS=-O -I/usr/local/include
2047 EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
2049 in Local/Makefile. The daemon name to use in the tcpwrappers control files is
2050 "exim". For example, the line
2052 exim : LOCAL 192.168.1. .friendly.domain.example
2054 in your /etc/hosts.allow file allows connections from the local host, from the
2055 subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other
2056 connections are denied. The daemon name used by tcpwrappers can be changed at
2057 build time by setting TCP_WRAPPERS_DAEMON_NAME in Local/Makefile, or by setting
2058 tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers
2059 documentation for further details.
2062 4.9 Including support for IPv6
2063 ------------------------------
2065 Exim contains code for use on systems that have IPv6 support. Setting
2066 "HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may
2067 also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6
2068 support is not fully integrated into the normal include and library files.
2070 Two different types of DNS record for handling IPv6 addresses have been
2071 defined. AAAA records (analogous to A records for IPv4) are in use, and are
2072 currently seen as the mainstream. Another record type called A6 was proposed as
2073 better than AAAA because it had more flexibility. However, it was felt to be
2074 over-complex, and its status was reduced to "experimental". It is not known if
2075 anyone is actually using A6 records. Exim has support for A6 records, but this
2076 is included only if you set "SUPPORT_A6=YES" in Local/Makefile. The support has
2077 not been tested for some time.
2080 4.10 Dynamically loaded lookup module support
2081 ---------------------------------------------
2083 On some platforms, Exim supports not compiling all lookup types directly into
2084 the main binary, instead putting some into external modules which can be loaded
2085 on demand. This permits packagers to build Exim with support for lookups with
2086 extensive library dependencies without requiring all users to install all of
2087 those dependencies. Most, but not all, lookup types can be built this way.
2089 Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be
2090 installed; Exim will only load modules from that directory, as a security
2091 measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your
2092 OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting
2093 "EXTRALIBS" may also be necessary, see src/EDITME for details.
2095 Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"<
2096 lookup_type> flags to have the value "2" instead of "yes". For example, this
2097 will build in lsearch but load sqlite and mysql support on demand:
2104 4.11 The building process
2105 -------------------------
2107 Once Local/Makefile (and Local/eximon.conf, if required) have been created, run
2108 make at the top level. It determines the architecture and operating system
2109 types, and creates a build directory if one does not exist. For example, on a
2110 Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created.
2111 Symbolic links to relevant source files are installed in the build directory.
2113 Warning: The -j (parallel) flag must not be used with make; the building
2114 process fails if it is set.
2116 If this is the first time make has been run, it calls a script that builds a
2117 make file inside the build directory, using the configuration files from the
2118 Local directory. The new make file is then passed to another instance of make.
2119 This does the real work, building a number of utility scripts, and then
2120 compiling and linking the binaries for the Exim monitor (if configured), a
2121 number of utility programs, and finally Exim itself. The command "make
2122 makefile" can be used to force a rebuild of the make file in the build
2123 directory, should this ever be necessary.
2125 If you have problems building Exim, check for any comments there may be in the
2126 README file concerning your operating system, and also take a look at the FAQ,
2127 where some common problems are covered.
2130 4.12 Output from "make"
2131 -----------------------
2133 The output produced by the make process for compile lines is often very
2134 unreadable, because these lines can be very long. For this reason, the normal
2135 output is suppressed by default, and instead output similar to that which
2136 appears when compiling the 2.6 Linux kernel is generated: just a short line for
2137 each module that is being compiled or linked. However, it is still possible to
2138 get the full output, by calling make like this:
2142 The value of FULLECHO defaults to "@", the flag character that suppresses
2143 command reflection in make. When you ask for the full output, it is given in
2144 addition to the short output.
2147 4.13 Overriding build-time options for Exim
2148 -------------------------------------------
2150 The main make file that is created at the beginning of the building process
2151 consists of the concatenation of a number of files which set configuration
2152 values, followed by a fixed set of make instructions. If a value is set more
2153 than once, the last setting overrides any previous ones. This provides a
2154 convenient way of overriding defaults. The files that are concatenated are, in
2158 OS/Makefile-<ostype>
2160 Local/Makefile-<ostype>
2161 Local/Makefile-<archtype>
2162 Local/Makefile-<ostype>-<archtype>
2165 where <ostype> is the operating system type and <archtype> is the architecture
2166 type. Local/Makefile is required to exist, and the building process fails if it
2167 is absent. The other three Local files are optional, and are often not needed.
2169 The values used for <ostype> and <archtype> are obtained from scripts called
2170 scripts/os-type and scripts/arch-type respectively. If either of the
2171 environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are
2172 used, thereby providing a means of forcing particular settings. Otherwise, the
2173 scripts try to get values from the uname command. If this fails, the shell
2174 variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations
2175 are then applied, to produce the standard names that Exim expects. You can run
2176 these scripts directly from the shell in order to find out what values are
2177 being used on your system.
2179 OS/Makefile-Default contains comments about the variables that are set therein.
2180 Some (but not all) are mentioned below. If there is something that needs
2181 changing, review the contents of this file and the contents of the make file
2182 for your operating system (OS/Makefile-<ostype>) to see what the default values
2185 If you need to change any of the values that are set in OS/Makefile-Default or
2186 in OS/Makefile-<ostype>, or to add any new definitions, you do not need to
2187 change the original files. Instead, you should make the changes by putting the
2188 new values in an appropriate Local file. For example, when building Exim in
2189 many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1)
2190 operating system, it is necessary to specify that the C compiler is called cc
2191 rather than gcc. Also, the compiler must be called with the option -std1, to
2192 make it recognize some of the features of Standard C that Exim uses. (Most
2193 other compilers recognize Standard C by default.) To do this, you should create
2194 a file called Local/Makefile-OSF1 containing the lines
2199 If you are compiling for just one operating system, it may be easier to put
2200 these lines directly into Local/Makefile.
2202 Keeping all your local configuration settings separate from the distributed
2203 files makes it easy to transfer them to new versions of Exim simply by copying
2204 the contents of the Local directory.
2206 Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
2207 lookup, but not all systems have these components installed, so the default is
2208 not to include the relevant code in the binary. All the different kinds of file
2209 and database lookup that Exim supports are implemented as separate code modules
2210 which are included only if the relevant compile-time options are set. In the
2211 case of LDAP, NIS, and NIS+, the settings for Local/Makefile are:
2217 and similar settings apply to the other lookup types. They are all listed in
2218 src/EDITME. In many cases the relevant include files and interface libraries
2219 need to be installed before compiling Exim. However, there are some optional
2220 lookup types (such as cdb) for which the code is entirely contained within
2221 Exim, and no external include files or libraries are required. When a lookup
2222 type is not included in the binary, attempts to configure Exim to use it cause
2223 run time configuration errors.
2225 Many systems now use a tool called pkg-config to encapsulate information about
2226 how to compile against a library; Exim has some initial support for being able
2227 to use pkg-config for lookups and authenticators. For any given makefile
2228 variable which starts "LOOKUP_" or "AUTH_", you can add a new variable with the
2229 "_PC" suffix in the name and assign as the value the name of the package to be
2230 queried. The results of querying via the pkg-config command will be added to
2231 the appropriate Makefile variables with "+=" directives, so your version of
2232 make will need to support that syntax. For instance:
2235 LOOKUP_SQLITE_PC=sqlite3
2237 AUTH_GSASL_PC=libgsasl
2238 AUTH_HEIMDAL_GSSAPI=yes
2239 AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
2241 Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines
2242 to be called during string expansion. To enable this facility,
2246 must be defined in Local/Makefile. Details of this facility are given in
2249 The location of the X11 libraries is something that varies a lot between
2250 operating systems, and there may be different versions of X11 to cope with.
2251 Exim itself makes no use of X11, but if you are compiling the Exim monitor, the
2252 X11 libraries must be available. The following three variables are set in OS/
2256 XINCLUDE=-I$(X11)/include
2257 XLFLAGS=-L$(X11)/lib
2259 These are overridden in some of the operating-system configuration files. For
2260 example, in OS/Makefile-SunOS5 there is
2263 XINCLUDE=-I$(X11)/include
2264 XLFLAGS=-L$(X11)/lib -R$(X11)/lib
2266 If you need to override the default setting for your operating system, place a
2267 definition of all three of these variables into your Local/Makefile-<ostype>
2270 If you need to add any extra libraries to the link steps, these can be put in a
2271 variable called EXTRALIBS, which appears in all the link commands, but by
2272 default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command
2273 for linking the main Exim binary, and not for any associated utilities.
2275 There is also DBMLIB, which appears in the link commands for binaries that use
2276 DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which
2277 appears only in the link step for the Exim monitor binary, and which can be
2278 used, for example, to include additional X11 libraries.
2280 The make file copes with rebuilding Exim correctly if any of the configuration
2281 files are edited. However, if an optional configuration file is deleted, it is
2282 necessary to touch the associated non-optional file (that is, Local/Makefile or
2283 Local/eximon.conf) before rebuilding.
2286 4.14 OS-specific header files
2287 -----------------------------
2289 The OS directory contains a number of files with names of the form os.h-
2290 <ostype>. These are system-specific C header files that should not normally
2291 need to be changed. There is a list of macro settings that are recognized in
2292 the file OS/os.configuring, which should be consulted if you are porting Exim
2293 to a new operating system.
2296 4.15 Overriding build-time options for the monitor
2297 --------------------------------------------------
2299 A similar process is used for overriding things when building the Exim monitor,
2300 where the files that are involved are
2302 OS/eximon.conf-Default
2303 OS/eximon.conf-<ostype>
2305 Local/eximon.conf-<ostype>
2306 Local/eximon.conf-<archtype>
2307 Local/eximon.conf-<ostype>-<archtype>
2309 As with Exim itself, the final three files need not exist, and in this case the
2310 OS/eximon.conf-<ostype> file is also optional. The default values in OS/
2311 eximon.conf-Default can be overridden dynamically by setting environment
2312 variables of the same name, preceded by EXIMON_. For example, setting
2313 EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run
2317 4.16 Installing Exim binaries and scripts
2318 -----------------------------------------
2320 The command "make install" runs the exim_install script with no arguments. The
2321 script copies binaries and utility scripts into the directory whose name is
2322 specified by the BIN_DIRECTORY setting in Local/Makefile. The install script
2323 copies files only if they are newer than the files they are going to replace.
2324 The Exim binary is required to be owned by root and have the setuid bit set,
2325 for normal configurations. Therefore, you must run "make install" as root so
2326 that it can set up the Exim binary in this way. However, in some special
2327 situations (for example, if a host is doing no local deliveries) it may be
2328 possible to run Exim without making the binary setuid root (see chapter 54 for
2331 Exim's run time configuration file is named by the CONFIGURE_FILE setting in
2332 Local/Makefile. If this names a single file, and the file does not exist, the
2333 default configuration file src/configure.default is copied there by the
2334 installation script. If a run time configuration file already exists, it is
2335 left alone. If CONFIGURE_FILE is a colon-separated list, naming several
2336 alternative files, no default is installed.
2338 One change is made to the default configuration file when it is installed: the
2339 default configuration contains a router that references a system aliases file.
2340 The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in
2341 Local/Makefile (/etc/aliases by default). If the system aliases file does not
2342 exist, the installation script creates it, and outputs a comment to the user.
2344 The created file contains no aliases, but it does contain comments about the
2345 aliases a site should normally have. Mail aliases have traditionally been kept
2346 in /etc/aliases. However, some operating systems are now using /etc/mail/
2347 aliases. You should check if yours is one of these, and change Exim's
2348 configuration if necessary.
2350 The default configuration uses the local host's name as the only local domain,
2351 and is set up to do local deliveries into the shared directory /var/mail,
2352 running as the local user. System aliases and .forward files in users' home
2353 directories are supported, but no NIS or NIS+ support is configured. Domains
2354 other than the name of the local host are routed using the DNS, with delivery
2357 It is possible to install Exim for special purposes (such as building a binary
2358 distribution) in a private part of the file system. You can do this by a
2361 make DESTDIR=/some/directory/ install
2363 This has the effect of pre-pending the specified directory to all the file
2364 paths, except the name of the system aliases file that appears in the default
2365 configuration. (If a default alias file is created, its name is modified.) For
2366 backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is
2369 Running make install does not copy the Exim 4 conversion script convert4r4. You
2370 will probably run this only once if you are upgrading from Exim 3. None of the
2371 documentation files in the doc directory are copied, except for the info files
2372 when you have set INFO_DIRECTORY, as described in section 4.17 below.
2374 For the utility programs, old versions are renamed by adding the suffix .O to
2375 their names. The Exim binary itself, however, is handled differently. It is
2376 installed under a name that includes the version number and the compile number,
2377 for example exim-4.84.2-1. The script then arranges for a symbolic link called
2378 exim to point to the binary. If you are updating a previous version of Exim,
2379 the script takes care to ensure that the name exim is never absent from the
2380 directory (as seen by other processes).
2382 If you want to see what the make install will do before running it for real,
2383 you can pass the -n option to the installation script by this command:
2385 make INSTALL_ARG=-n install
2387 The contents of the variable INSTALL_ARG are passed to the installation script.
2388 You do not need to be root to run this test. Alternatively, you can run the
2389 installation script directly, but this must be from within the build directory.
2390 For example, from the top-level Exim directory you could use this command:
2392 (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
2394 There are two other options that can be supplied to the installation script.
2396 * -no_chown bypasses the call to change the owner of the installed binary to
2397 root, and the call to make it a setuid binary.
2399 * -no_symlink bypasses the setting up of the symbolic link exim to the
2402 INSTALL_ARG can be used to pass these options to the script. For example:
2404 make INSTALL_ARG=-no_symlink install
2406 The installation script can also be given arguments specifying which files are
2407 to be copied. For example, to install just the Exim binary, and nothing else,
2408 without creating the symbolic link, you could use:
2410 make INSTALL_ARG='-no_symlink exim' install
2413 4.17 Installing info documentation
2414 ----------------------------------
2416 Not all systems use the GNU info system for documentation, and for this reason,
2417 the Texinfo source of Exim's documentation is not included in the main
2418 distribution. Instead it is available separately from the ftp site (see section
2421 If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of
2422 the documentation is found in the source tree, running "make install"
2423 automatically builds the info files and installs them.
2426 4.18 Setting up the spool directory
2427 -----------------------------------
2429 When it starts up, Exim tries to create its spool directory if it does not
2430 exist. The Exim uid and gid are used for the owner and group of the spool
2431 directory. Sub-directories are automatically created in the spool directory as
2438 Having installed Exim, you can check that the run time configuration file is
2439 syntactically valid by running the following command, which assumes that the
2440 Exim binary directory is within your PATH environment variable:
2444 If there are any errors in the configuration file, Exim outputs error messages.
2445 Otherwise it outputs the version number and build date, the DBM library that is
2446 being used, and information about which drivers and other optional code modules
2447 are included in the binary. Some simple routing tests can be done by using the
2448 address testing option. For example,
2450 exim -bt <local username>
2452 should verify that it recognizes a local mailbox, and
2454 exim -bt <remote address>
2456 a remote one. Then try getting it to deliver mail, both locally and remotely.
2457 This can be done by passing messages directly to Exim, without going through a
2458 user agent. For example:
2460 exim -v postmaster@your.domain.example
2461 From: user@your.domain.example
2462 To: postmaster@your.domain.example
2463 Subject: Testing Exim
2465 This is a test message.
2468 The -v option causes Exim to output some verification of what it is doing. In
2469 this case you should see copies of three log lines, one for the message's
2470 arrival, one for its delivery, and one containing "Completed".
2472 If you encounter problems, look at Exim's log files (mainlog and paniclog) to
2473 see if there is any relevant information there. Another source of information
2474 is running Exim with debugging turned on, by specifying the -d option. If a
2475 message is stuck on Exim's spool, you can force a delivery with debugging
2476 turned on by a command of the form
2478 exim -d -M <exim-message-id>
2480 You must be root or an "admin user" in order to do this. The -d option produces
2481 rather a lot of output, but you can cut this down to specific areas. For
2482 example, if you use -d-all+route only the debugging information relevant to
2483 routing is included. (See the -d option in chapter 5 for more details.)
2485 One specific problem that has shown up on some sites is the inability to do
2486 local deliveries into a shared mailbox directory, because it does not have the
2487 "sticky bit" set on it. By default, Exim tries to create a lock file before
2488 writing to a mailbox file, and if it cannot create the lock file, the delivery
2489 is deferred. You can get round this either by setting the "sticky bit" on the
2490 directory, or by setting a specific group for local deliveries and allowing
2491 that group to create files in the directory (see the comments above the
2492 local_delivery transport in the default configuration file). Another approach
2493 is to configure Exim not to use lock files, but just to rely on fcntl() locking
2494 instead. However, you should do this only if all user agents also use fcntl()
2495 locking. For further discussion of locking issues, see chapter 26.
2497 One thing that cannot be tested on a system that is already running an MTA is
2498 the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX
2499 option can be used to run an Exim daemon that listens on some other port, or
2500 inetd can be used to do this. The -bh option and the exim_checkaccess utility
2501 can be used to check out policy controls on incoming SMTP mail.
2503 Testing a new version on a system that is already running Exim can most easily
2504 be done by building a binary with a different CONFIGURE_FILE setting. From
2505 within the run time configuration, all other file and directory names that Exim
2506 uses can be altered, in order to keep it entirely clear of the production
2510 4.20 Replacing another MTA with Exim
2511 ------------------------------------
2513 Building and installing Exim for the first time does not of itself put it in
2514 general use. The name by which the system's MTA is called by mail user agents
2515 is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating
2516 system), and it is necessary to make this name point to the exim binary in
2517 order to get the user agents to pass messages to Exim. This is normally done by
2518 renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a
2519 symbolic link to the exim binary. It is a good idea to remove any setuid
2520 privilege and executable status from the old MTA. It is then necessary to stop
2521 and restart the mailer daemon, if one is running.
2523 Some operating systems have introduced alternative ways of switching MTAs. For
2524 example, if you are running FreeBSD, you need to edit the file /etc/mail/
2525 mailer.conf instead of setting up a symbolic link as just described. A typical
2526 example of the contents of this file for running Exim is as follows:
2528 sendmail /usr/exim/bin/exim
2529 send-mail /usr/exim/bin/exim
2530 mailq /usr/exim/bin/exim -bp
2531 newaliases /usr/bin/true
2533 Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your
2534 Exim installation is "live". Check it by sending a message from your favourite
2537 You should consider what to tell your users about the change of MTA. Exim may
2538 have different capabilities to what was previously running, and there are
2539 various operational differences such as the text of messages produced by
2540 command line options and in bounce messages. If you allow your users to make
2541 use of Exim's filtering capabilities, you should make the document entitled
2542 Exim's interface to mail filtering available to them.
2548 If you are already running Exim on your host, building and installing a new
2549 version automatically makes it available to MUAs, or any other programs that
2550 call the MTA directly. However, if you are running an Exim daemon, you do need
2551 to send it a HUP signal, to make it re-execute itself, and thereby pick up the
2552 new binary. You do not need to stop processing mail in order to install a new
2553 version of Exim. The install script does not modify an existing runtime
2557 4.22 Stopping the Exim daemon on Solaris
2558 ----------------------------------------
2560 The standard command for stopping the mailer daemon on Solaris is
2562 /etc/init.d/sendmail stop
2564 If /usr/lib/sendmail has been turned into a symbolic link, this script fails to
2565 stop Exim because it uses the command ps -e and greps the output for the text
2566 "sendmail"; this is not present because the actual program name (that is,
2567 "exim") is given by the ps command with these options. A solution is to replace
2568 the line that finds the process id with something like
2570 pid=`cat /var/spool/exim/exim-daemon.pid`
2572 to obtain the daemon's pid directly from the file that Exim saves it in.
2574 Note, however, that stopping the daemon does not "stop Exim". Messages can
2575 still be received from local processes, and if automatic delivery is configured
2576 (the normal case), deliveries will still occur.
2580 ===============================================================================
2581 5. THE EXIM COMMAND LINE
2583 Exim's command line takes the standard Unix form of a sequence of options, each
2584 starting with a hyphen character, followed by a number of arguments. The
2585 options are compatible with the main options of Sendmail, and there are also
2586 some additional options, some of which are compatible with Smail 3. Certain
2587 combinations of options do not make sense, and provoke an error if used. The
2588 form of the arguments depends on which options are set.
2591 5.1 Setting options by program name
2592 -----------------------------------
2594 If Exim is called under the name mailq, it behaves as if the option -bp were
2595 present before any other options. The -bp option requests a listing of the
2596 contents of the mail queue on the standard output. This feature is for
2597 compatibility with some systems that contain a command of that name in one of
2598 the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/
2601 If Exim is called under the name rsmtp it behaves as if the option -bS were
2602 present before any other options, for compatibility with Smail. The -bS option
2603 is used for reading in a number of messages in batched SMTP format.
2605 If Exim is called under the name rmail it behaves as if the -i and -oee options
2606 were present before any other options, for compatibility with Smail. The name
2607 rmail is used as an interface by some UUCP systems.
2609 If Exim is called under the name runq it behaves as if the option -q were
2610 present before any other options, for compatibility with Smail. The -q option
2611 causes a single queue runner process to be started.
2613 If Exim is called under the name newaliases it behaves as if the option -bi
2614 were present before any other options, for compatibility with Sendmail. This
2615 option is used for rebuilding Sendmail's alias file. Exim does not have the
2616 concept of a single alias file, but can be configured to run a given command if
2617 called with the -bi option.
2620 5.2 Trusted and admin users
2621 ---------------------------
2623 Some Exim options are available only to trusted users and others are available
2624 only to admin users. In the description below, the phrases "Exim user" and
2625 "Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in
2626 Local/Makefile or set by the exim_user and exim_group options. These do not
2627 necessarily have to use the name "exim".
2629 * The trusted users are root, the Exim user, any user listed in the
2630 trusted_users configuration option, and any user whose current group or any
2631 supplementary group is one of those listed in the trusted_groups
2632 configuration option. Note that the Exim group is not automatically
2635 Trusted users are always permitted to use the -f option or a leading
2636 "From " line to specify the envelope sender of a message that is passed to
2637 Exim through the local interface (see the -bm and -f options below). See
2638 the untrusted_set_sender option for a way of permitting non-trusted users
2639 to set envelope senders.
2641 For a trusted user, there is never any check on the contents of the From:
2642 header line, and a Sender: line is never added. Furthermore, any existing
2643 Sender: line in incoming local (non-TCP/IP) messages is not removed.
2645 Trusted users may also specify a host name, host address, interface
2646 address, protocol name, ident value, and authentication data when
2647 submitting a message locally. Thus, they are able to insert messages into
2648 Exim's queue locally that have the characteristics of messages received
2649 from a remote host. Untrusted users may in some circumstances use -f, but
2650 can never set the other values that are available to trusted users.
2652 * The admin users are root, the Exim user, and any user that is a member of
2653 the Exim group or of any group listed in the admin_groups configuration
2654 option. The current group does not have to be one of these groups.
2656 Admin users are permitted to list the queue, and to carry out certain
2657 operations on messages, for example, to force delivery failures. It is also
2658 necessary to be an admin user in order to see the full information provided
2659 by the Exim monitor, and full debugging output.
2661 By default, the use of the -M, -q, -R, and -S options to cause Exim to
2662 attempt delivery of messages on its queue is restricted to admin users.
2663 However, this restriction can be relaxed by setting the prod_requires_admin
2664 option false (that is, specifying no_prod_requires_admin).
2666 Similarly, the use of the -bp option to list all the messages in the queue
2667 is restricted to admin users unless queue_list_requires_admin is set false.
2669 Warning: If you configure your system so that admin users are able to edit
2670 Exim's configuration file, you are giving those users an easy way of getting
2671 root. There is further discussion of this issue at the start of chapter 6.
2674 5.3 Command line options
2675 ------------------------
2677 Exim's command line options are described in alphabetical order below. If none
2678 of the options that specifies a specific action (such as starting the daemon or
2679 a queue runner, or testing an address, or receiving a message in a specific
2680 format, or listing the queue) are present, and there is at least one argument
2681 on the command line, -bm (accept a local message on the standard input, with
2682 the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a
2683 brief message about itself and exits.
2687 This is a pseudo-option whose only purpose is to terminate the options and
2688 therefore to cause subsequent command line items to be treated as arguments
2689 rather than options, even if they begin with hyphens.
2693 This option causes Exim to output a few sentences stating what it is. The
2694 same output is generated if the Exim binary is called with no options and
2699 This option is an alias for -bV and causes version information to be
2704 These options are used by Sendmail for selecting configuration files and
2705 are ignored by Exim.
2709 This is a Sendmail option for selecting 7 or 8 bit processing. Exim is
2710 8-bit clean; it ignores this option.
2714 This option runs Exim as a daemon, awaiting incoming SMTP connections.
2715 Usually the -bd option is combined with the -q<time> option, to specify
2716 that the daemon should also initiate periodic queue runs.
2718 The -bd option can be used only by an admin user. If either of the -d
2719 (debugging) or -v (verifying) options are set, the daemon does not
2720 disconnect from the controlling terminal. When running this way, it can be
2721 stopped by pressing ctrl-C.
2723 By default, Exim listens for incoming connections to the standard SMTP port
2724 on all the host's running interfaces. However, it is possible to listen on
2725 other ports, on multiple ports, and only on specific interfaces. Chapter 13
2726 contains a description of the options that control this.
2728 When a listening daemon is started without the use of -oX (that is, without
2729 overriding the normal configuration), it writes its process id to a file
2730 called exim-daemon.pid in Exim's spool directory. This location can be
2731 overridden by setting PID_FILE_PATH in Local/Makefile. The file is written
2732 while Exim is still running as root.
2734 When -oX is used on the command line to start a listening daemon, the
2735 process id is not written to the normal pid file path. However, -oP can be
2736 used to specify a path on the command line if a pid file is required.
2738 The SIGHUP signal can be used to cause the daemon to re-execute itself.
2739 This should be done whenever Exim's configuration file, or any file that is
2740 incorporated into it by means of the .include facility, is changed, and
2741 also whenever a new version of Exim is installed. It is not necessary to do
2742 this when other files that are referenced from the configuration (for
2743 example, alias files) are changed, because these are reread each time they
2748 This option has the same effect as -bd except that it never disconnects
2749 from the controlling terminal, even when no debugging is specified.
2753 Run Exim in expansion testing mode. Exim discards its root privilege, to
2754 prevent ordinary users from using this mode to read otherwise inaccessible
2755 files. If no arguments are given, Exim runs interactively, prompting for
2756 lines of data. Otherwise, it processes each argument in turn.
2758 If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load
2759 the libreadline library dynamically whenever the -be option is used without
2760 command line arguments. If successful, it uses the readline() function,
2761 which provides extensive line-editing facilities, for reading the test
2762 data. A line history is supported.
2764 Long expansion expressions can be split over several lines by using
2765 backslash continuations. As in Exim's run time configuration, white space
2766 at the start of continuation lines is ignored. Each argument or data line
2767 is passed through the string expansion mechanism, and the result is output.
2768 Variable values from the configuration file (for example, $qualify_domain)
2769 are available, but no message-specific values (such as $sender_domain) are
2770 set, because no message is being processed (but see -bem and -Mset).
2772 Note: If you use this mechanism to test lookups, and you change the data
2773 files or databases you are using, you must exit and restart Exim before
2774 trying the same lookup again. Otherwise, because each Exim process caches
2775 the results of lookups, you will just get the same result as before.
2779 This option operates like -be except that it must be followed by the name
2780 of a file. For example:
2782 exim -bem /tmp/testmessage
2784 The file is read as a message (as if receiving a locally-submitted non-SMTP
2785 message) before any of the test expansions are done. Thus, message-specific
2786 variables such as $message_size and $header_from: are available. However,
2787 no Received: header is added to the message. If the -t option is set,
2788 recipients are read from the headers in the normal way, and are shown in
2789 the $recipients variable. Note that recipients cannot be given on the
2790 command line, because further arguments are taken as strings to expand
2795 This option is the same as -bf except that it assumes that the filter being
2796 tested is a system filter. The additional commands that are available only
2797 in system filters are recognized.
2801 This option runs Exim in user filter testing mode; the file is the filter
2802 file to be tested, and a test message must be supplied on the standard
2803 input. If there are no message-dependent tests in the filter, an empty file
2806 If you want to test a system filter file, use -bF instead of -bf. You can
2807 use both -bF and -bf on the same command, in order to test a system filter
2808 and a user filter in the same run. For example:
2810 exim -bF /system/filter -bf /user/filter </test/message
2812 This is helpful when the system filter adds header lines or sets filter
2813 variables that are used by the user filter.
2815 If the test filter file does not begin with one of the special lines
2820 it is taken to be a normal .forward file, and is tested for validity under
2821 that interpretation. See sections 22.4 to 22.6 for a description of the
2822 possible contents of non-filter redirection lists.
2824 The result of an Exim command that uses -bf, provided no errors are
2825 detected, is a list of the actions that Exim would try to take if presented
2826 with the message for real. More details of filter testing are given in the
2827 separate document entitled Exim's interfaces to mail filtering.
2829 When testing a filter file, the envelope sender can be set by the -f
2830 option, or by a "From " line at the start of the test message. Various
2831 parameters that would normally be taken from the envelope recipient address
2832 of the message can be set by means of additional command line options (see
2833 the next four options).
2837 This sets the domain of the recipient address when a filter file is being
2838 tested by means of the -bf option. The default is the value of
2843 This sets the local part of the recipient address when a filter file is
2844 being tested by means of the -bf option. The default is the username of the
2845 process that calls Exim. A local part should be specified with any prefix
2846 or suffix stripped, because that is how it appears to the filter when a
2847 message is actually being delivered.
2851 This sets the prefix of the local part of the recipient address when a
2852 filter file is being tested by means of the -bf option. The default is an
2857 This sets the suffix of the local part of the recipient address when a
2858 filter file is being tested by means of the -bf option. The default is an
2863 This option runs a fake SMTP session as if from the given IP address, using
2864 the standard input and output. The IP address may include a port number at
2865 the end, after a full stop. For example:
2867 exim -bh 10.9.8.7.1234
2868 exim -bh fe80::a00:20ff:fe86:a061.5678
2870 When an IPv6 address is given, it is converted into canonical form. In the
2871 case of the second example above, the value of $sender_host_address after
2872 conversion to the canonical form is
2873 "fe80:0000:0000:0a00:20ff:fe86:a061.5678".
2875 Comments as to what is going on are written to the standard error file.
2876 These include lines beginning with "LOG" for anything that would have been
2877 logged. This facility is provided for testing configuration options for
2878 incoming messages, to make sure they implement the required policy. For
2879 example, you can test your relay controls using -bh.
2881 Warning 1: You can test features of the configuration that rely on ident
2882 (RFC 1413) information by using the -oMt option. However, Exim cannot
2883 actually perform an ident callout when testing using -bh because there is
2884 no incoming SMTP connection.
2886 Warning 2: Address verification callouts (see section 42.45) are also
2887 skipped when testing using -bh. If you want these callouts to occur, use
2890 Messages supplied during the testing session are discarded, and nothing is
2891 written to any of the real log files. There may be pauses when DNS (and
2892 other) lookups are taking place, and of course these may time out. The -oMi
2893 option can be used to specify a specific IP interface and port if this is
2894 important, and -oMaa and -oMai can be used to set parameters as if the SMTP
2895 session were authenticated.
2897 The exim_checkaccess utility is a "packaged" version of -bh whose output
2898 just states whether a given recipient address from a given host is
2899 acceptable or not. See section 52.8.
2901 Features such as authentication and encryption, where the client input is
2902 not plain text, cannot easily be tested with -bh. Instead, you should use a
2903 specialized SMTP test program such as swaks.
2907 This option operates in the same way as -bh, except that address
2908 verification callouts are performed if required. This includes consulting
2909 and updating the callout cache database.
2913 Sendmail interprets the -bi option as a request to rebuild its alias file.
2914 Exim does not have the concept of a single alias file, and so it cannot
2915 mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi
2916 option tend to appear in various scripts such as NIS make files, so the
2917 option must be recognized.
2919 If -bi is encountered, the command specified by the bi_command
2920 configuration option is run, under the uid and gid of the caller of Exim.
2921 If the -oA option is used, its value is passed to the command as an
2922 argument. The command set by bi_command may not contain arguments. The
2923 command can use the exim_dbmbuild utility, or some other means, to rebuild
2924 alias files if this is required. If the bi_command option is not set,
2925 calling Exim with -bi is a no-op.
2929 We shall provide various options starting "-bI:" for querying Exim for
2930 information. The output of many of these will be intended for machine
2931 consumption. This one is not. The -bI:help option asks Exim for a synopsis
2932 of supported options beginning "-bI:". Use of any of these options shall
2933 cause Exim to exit after producing the requested output.
2937 This option causes Exim to emit an alphabetically sorted list of all
2938 recognised DSCP names.
2942 This option causes Exim to emit an alphabetically sorted list of all
2943 supported Sieve protocol extensions on stdout, one per line. This is
2944 anticipated to be useful for ManageSieve (RFC 5804) implementations, in
2945 providing that protocol's "SIEVE" capability response line. As the precise
2946 list may depend upon compile-time build options, which this option will
2947 adapt to, this is the only way to guarantee a correct response.
2951 This option runs an Exim receiving process that accepts an incoming,
2952 locally-generated message on the standard input. The recipients are given
2953 as the command arguments (except when -t is also present - see below). Each
2954 argument can be a comma-separated list of RFC 2822 addresses. This is the
2955 default option for selecting the overall action of an Exim call; it is
2956 assumed if no other conflicting option is present.
2958 If any addresses in the message are unqualified (have no domain), they are
2959 qualified by the values of the qualify_domain or qualify_recipient options,
2960 as appropriate. The -bnq option (see below) provides a way of suppressing
2961 this for special cases.
2963 Policy checks on the contents of local messages can be enforced by means of
2964 the non-SMTP ACL. See chapter 42 for details.
2966 The return code is zero if the message is successfully accepted. Otherwise,
2967 the action is controlled by the -oex option setting - see below.
2969 The format of the message must be as defined in RFC 2822, except that, for
2970 compatibility with Sendmail and Smail, a line in one of the forms
2972 From sender Fri Jan 5 12:55 GMT 1997
2973 From sender Fri, 5 Jan 97 12:55:01
2975 (with the weekday optional, and possibly with additional text after the
2976 date) is permitted to appear at the start of the message. There appears to
2977 be no authoritative specification of the format of this line. Exim
2978 recognizes it by matching against the regular expression defined by the
2979 uucp_from_pattern option, which can be changed if necessary.
2981 The specified sender is treated as if it were given as the argument to the
2982 -f option, but if a -f option is also present, its argument is used in
2983 preference to the address taken from the message. The caller of Exim must
2984 be a trusted user for the sender of a message to be set in this way.
2986 -bmalware <filename>
2988 This debugging option causes Exim to scan the given file, using the malware
2989 scanning framework. The option of av_scanner influences this option, so if
2990 av_scanner's value is dependent upon an expansion then the expansion should
2991 have defaults which apply to this invocation. ACLs are not invoked, so if
2992 av_scanner references an ACL variable then that variable will never be
2993 populated and -bmalware will fail.
2995 Exim will have changed working directory before resolving the filename, so
2996 using fully qualified pathnames is advisable. Exim will be running as the
2997 Exim user when it tries to open the file, rather than as the invoking user.
2998 This option requires admin privileges.
3000 The -bmalware option will not be extended to be more generally useful,
3001 there are better tools for file-scanning. This option exists to help
3002 administrators verify their Exim and AV scanner configuration.
3006 By default, Exim automatically qualifies unqualified addresses (those
3007 without domains) that appear in messages that are submitted locally (that
3008 is, not over TCP/IP). This qualification applies both to addresses in
3009 envelopes, and addresses in header lines. Sender addresses are qualified
3010 using qualify_domain, and recipient addresses using qualify_recipient
3011 (which defaults to the value of qualify_domain).
3013 Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is
3014 being used to re-submit messages that originally came from remote hosts
3015 after content scanning, you probably do not want to qualify unqualified
3016 addresses in header lines. (Such lines will be present only if you have not
3017 enabled a header syntax check in the appropriate ACL.)
3019 The -bnq option suppresses all qualification of unqualified addresses in
3020 messages that originate on the local host. When this is used, unqualified
3021 addresses in the envelope provoke errors (causing message rejection) and
3022 unqualified addresses in header lines are left alone.
3026 If this option is given with no arguments, it causes the values of all
3027 Exim's main configuration options to be written to the standard output. The
3028 values of one or more specific options can be requested by giving their
3029 names as arguments, for example:
3031 exim -bP qualify_domain hold_domains
3033 However, any option setting that is preceded by the word "hide" in the
3034 configuration file is not shown in full, except to an admin user. For other
3035 users, the output is as in this example:
3037 mysql_servers = <value not displayable>
3039 If configure_file is given as an argument, the name of the run time
3040 configuration file is output. If a list of configuration files was
3041 supplied, the value that is output here is the name of the file that was
3044 If the -n flag is given, then for most modes of -bP operation the name will
3047 If log_file_path or pid_file_path are given, the names of the directories
3048 where log files and daemon pid files are written are output, respectively.
3049 If these values are unset, log files are written in a sub-directory of the
3050 spool directory called log, and the pid file is written directly into the
3053 If -bP is followed by a name preceded by "+", for example,
3055 exim -bP +local_domains
3057 it searches for a matching named list of any type (domain, host, address,
3058 or local part) and outputs what it finds.
3060 If one of the words router, transport, or authenticator is given, followed
3061 by the name of an appropriate driver instance, the option settings for that
3062 driver are output. For example:
3064 exim -bP transport local_delivery
3066 The generic driver options are output first, followed by the driver's
3067 private options. A list of the names of drivers of a particular type can be
3068 obtained by using one of the words router_list, transport_list, or
3069 authenticator_list, and a complete list of all drivers with their option
3070 settings can be obtained by using routers, transports, or authenticators.
3072 If environment is given as an argument, the set of environment variables is
3073 output, line by line. Using the -n flag supresses the value of the
3076 If invoked by an admin user, then macro, macro_list and macros are
3077 available, similarly to the drivers. Because macros are sometimes used for
3078 storing passwords, this option is restricted. The output format is one item
3083 This option requests a listing of the contents of the mail queue on the
3084 standard output. If the -bp option is followed by a list of message ids,
3085 just those messages are listed. By default, this option can be used only by
3086 an admin user. However, the queue_list_requires_admin option can be set
3087 false to allow any user to see the queue.
3089 Each message on the queue is displayed as in the following example:
3091 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
3092 red.king@looking-glass.fict.example
3095 The first line contains the length of time the message has been on the
3096 queue (in this case 25 minutes), the size of the message (2.9K), the unique
3097 local identifier for the message, and the message sender, as contained in
3098 the envelope. For bounce messages, the sender address is empty, and appears
3099 as "<>". If the message was submitted locally by an untrusted user who
3100 overrode the default sender address, the user's login name is shown in
3101 parentheses before the sender address.
3103 If the message is frozen (attempts to deliver it are suspended) then the
3104 text "*** frozen ***" is displayed at the end of this line.
3106 The recipients of the message (taken from the envelope, not the headers)
3107 are displayed on subsequent lines. Those addresses to which the message has
3108 already been delivered are marked with the letter D. If an original address
3109 gets expanded into several addresses via an alias or forward file, the
3110 original is displayed with a D only when deliveries for all of its child
3111 addresses are complete.
3115 This option operates like -bp, but in addition it shows delivered addresses
3116 that were generated from the original top level address(es) in each message
3117 by alias or forwarding operations. These addresses are flagged with "+D"
3118 instead of just "D".
3122 This option counts the number of messages on the queue, and writes the
3123 total to the standard output. It is restricted to admin users, unless
3124 queue_list_requires_admin is set false.
3128 This option operates like -bp, but the output is not sorted into
3129 chronological order of message arrival. This can speed it up when there are
3130 lots of messages on the queue, and is particularly useful if the output is
3131 going to be post-processed in a way that doesn't need the sorting.
3135 This option is a combination of -bpr and -bpa.
3139 This option is a combination of -bpr and -bpu.
3143 This option operates like -bp but shows only undelivered top-level
3144 addresses for each message displayed. Addresses generated by aliasing or
3145 forwarding are not shown, unless the message was deferred after processing
3146 by a router with the one_time option set.
3150 This option is for testing retry rules, and it must be followed by up to
3151 three arguments. It causes Exim to look for a retry rule that matches the
3152 values and to write it to the standard output. For example:
3154 exim -brt bach.comp.mus.example
3155 Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
3157 See chapter 32 for a description of Exim's retry rules. The first argument,
3158 which is required, can be a complete address in the form local_part@domain,
3159 or it can be just a domain name. If the second argument contains a dot, it
3160 is interpreted as an optional second domain name; if no retry rule is found
3161 for the first argument, the second is tried. This ties in with Exim's
3162 behaviour when looking for retry rules for remote hosts - if no rule is
3163 found that matches the host, one that matches the mail domain is sought.
3164 Finally, an argument that is the name of a specific delivery error, as used
3165 in setting up retry rules, can be given. For example:
3167 exim -brt haydn.comp.mus.example quota_3d
3168 Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m
3172 This option is for testing address rewriting rules, and it must be followed
3173 by a single argument, consisting of either a local part without a domain,
3174 or a complete address with a fully qualified domain. Exim outputs how this
3175 address would be rewritten for each possible place it might appear. See
3176 chapter 31 for further details.
3180 This option is used for batched SMTP input, which is an alternative
3181 interface for non-interactive local message submission. A number of
3182 messages can be submitted in a single run. However, despite its name, this
3183 is not really SMTP input. Exim reads each message's envelope from SMTP
3184 commands on the standard input, but generates no responses. If the caller
3185 is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL
3186 commands are believed; otherwise the sender is always the caller of Exim.
3188 The message itself is read from the standard input, in SMTP format (leading
3189 dots doubled), terminated by a line containing just a single dot. An error
3190 is provoked if the terminating dot is missing. A further message may then
3193 As for other local message submissions, the contents of incoming batch SMTP
3194 messages can be checked using the non-SMTP ACL (see chapter 42).
3195 Unqualified addresses are automatically qualified using qualify_domain and
3196 qualify_recipient, as appropriate, unless the -bnq option is used.
3198 Some other SMTP commands are recognized in the input. HELO and EHLO act as
3199 RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest
3200 of the standard input.
3202 If any error is encountered, reports are written to the standard output and
3203 error streams, and Exim gives up immediately. The return code is 0 if no
3204 error was detected; it is 1 if one or more messages were accepted before
3205 the error was detected; otherwise it is 2.
3207 More details of input using batched SMTP are given in section 47.11.
3211 This option causes Exim to accept one or more messages by reading SMTP
3212 commands on the standard input, and producing SMTP replies on the standard
3213 output. SMTP policy controls, as defined in ACLs (see chapter 42) are
3214 applied. Some user agents use this interface as a way of passing
3215 locally-generated messages to the MTA.
3217 In this usage, if the caller of Exim is trusted, or untrusted_set_sender is
3218 set, the senders of messages are taken from the SMTP MAIL commands.
3219 Otherwise the content of these commands is ignored and the sender is set up
3220 as the calling user. Unqualified addresses are automatically qualified
3221 using qualify_domain and qualify_recipient, as appropriate, unless the -bnq
3224 The -bs option is also used to run Exim from inetd, as an alternative to
3225 using a listening daemon. Exim can distinguish the two cases by checking
3226 whether the standard input is a TCP/IP socket. When Exim is called from
3227 inetd, the source of the mail is assumed to be remote, and the comments
3228 above concerning senders and qualification do not apply. In this situation,
3229 Exim behaves in exactly the same way as it does when receiving a message
3230 via the listening daemon.
3234 This option runs Exim in address testing mode, in which each argument is
3235 taken as a recipient address to be tested for deliverability. The results
3236 are written to the standard output. If a test fails, and the caller is not
3237 an admin user, no details of the failure are output, because these might
3238 contain sensitive information such as usernames and passwords for database
3241 If no arguments are given, Exim runs in an interactive manner, prompting
3242 with a right angle bracket for addresses to be tested.
3244 Unlike the -be test option, you cannot arrange for Exim to use the readline
3245 () function, because it is running as root and there are security issues.
3247 Each address is handled as if it were the recipient address of a message
3248 (compare the -bv option). It is passed to the routers and the result is
3249 written to the standard output. However, any router that has
3250 no_address_test set is bypassed. This can make -bt easier to use for
3251 genuine routing tests if your first router passes everything to a scanner
3254 The return code is 2 if any address failed outright; it is 1 if no address
3255 failed outright but at least one could not be resolved for some reason.
3256 Return code 0 is given only when all addresses succeed.
3258 Note: When actually delivering a message, Exim removes duplicate recipient
3259 addresses after routing is complete, so that only one delivery takes place.
3260 This does not happen when testing with -bt; the full results of routing are
3263 Warning: -bt can only do relatively simple testing. If any of the routers
3264 in the configuration makes any tests on the sender address of a message,
3265 you can use the -f option to set an appropriate sender when running -bt
3266 tests. Without it, the sender is assumed to be the calling user at the
3267 default qualifying domain. However, if you have set up (for example)
3268 routers whose behaviour depends on the contents of an incoming message, you
3269 cannot test those conditions using -bt. The -N option provides a possible
3270 way of doing such tests.
3274 This option causes Exim to write the current version number, compilation
3275 number, and compilation date of the exim binary to the standard output. It
3276 also lists the DBM library that is being used, the optional modules (such
3277 as specific lookup types), the drivers that are included in the binary, and
3278 the name of the run time configuration file that is in use.
3280 As part of its operation, -bV causes Exim to read and syntax check its
3281 configuration file. However, this is a static check only. It cannot check
3282 values that are to be expanded. For example, although a misspelt ACL verb
3283 is detected, an error in the verb's arguments is not. You cannot rely on
3284 -bV alone to discover (for example) all the typos in the configuration;
3285 some realistic testing is needed. The -bh and -N options provide more
3286 dynamic testing facilities.
3290 This option runs Exim in address verification mode, in which each argument
3291 is taken as a recipient address to be verified by the routers. (This does
3292 not involve any verification callouts). During normal operation,
3293 verification happens mostly as a consequence processing a verify condition
3294 in an ACL (see chapter 42). If you want to test an entire ACL, possibly
3295 including callouts, see the -bh and -bhc options.
3297 If verification fails, and the caller is not an admin user, no details of
3298 the failure are output, because these might contain sensitive information
3299 such as usernames and passwords for database lookups.
3301 If no arguments are given, Exim runs in an interactive manner, prompting
3302 with a right angle bracket for addresses to be verified.
3304 Unlike the -be test option, you cannot arrange for Exim to use the readline
3305 () function, because it is running as exim and there are security issues.
3307 Verification differs from address testing (the -bt option) in that routers
3308 that have no_verify set are skipped, and if the address is accepted by a
3309 router that has fail_verify set, verification fails. The address is
3310 verified as a recipient if -bv is used; to test verification for a sender
3311 address, -bvs should be used.
3313 If the -v option is not set, the output consists of a single line for each
3314 address, stating whether it was verified or not, and giving a reason in the
3315 latter case. Without -v, generating more than one address by redirection
3316 causes verification to end successfully, without considering the generated
3317 addresses. However, if just one address is generated, processing continues,
3318 and the generated address must verify successfully for the overall
3319 verification to succeed.
3321 When -v is set, more details are given of how the address has been handled,
3322 and in the case of address redirection, all the generated addresses are
3323 also considered. Verification may succeed for some and fail for others.
3325 The return code is 2 if any address failed outright; it is 1 if no address
3326 failed outright but at least one could not be resolved for some reason.
3327 Return code 0 is given only when all addresses succeed.
3329 If any of the routers in the configuration makes any tests on the sender
3330 address of a message, you should use the -f option to set an appropriate
3331 sender when running -bv tests. Without it, the sender is assumed to be the
3332 calling user at the default qualifying domain.
3336 This option acts like -bv, but verifies the address as a sender rather than
3337 a recipient address. This affects any rewriting and qualification that
3342 This option runs Exim as a daemon, awaiting incoming SMTP connections,
3343 similarly to the -bd option. All port specifications on the command-line
3344 and in the configuration file are ignored. Queue-running may not be
3347 In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
3348 listening for connections. This permits the system to start up and have
3349 inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
3350 each port only when the first connection is received.
3352 If the option is given as -bw<time> then the time is a timeout, after which
3353 the daemon will exit, which should cause inetd to listen once more.
3357 This option causes Exim to find the run time configuration file from the
3358 given list instead of from the list specified by the CONFIGURE_FILE
3359 compile-time setting. Usually, the list will consist of just a single file
3360 name, but it can be a colon-separated list of names. In this case, the
3361 first file that exists is used. Failure to open an existing file stops Exim
3362 from proceeding any further along the list, and an error is generated.
3364 The file names need to be absolute names.
3366 When this option is used by a caller other than root, and the list is
3367 different from the compiled-in list, Exim gives up its root privilege
3368 immediately, and runs with the real and effective uid and gid set to those
3369 of the caller. However, if a TRUSTED_CONFIG_LIST file is defined in Local/
3370 Makefile, that file contains a list of full pathnames, one per line, for
3371 configuration files which are trusted. Root privilege is retained for any
3372 configuration file so listed, as long as the caller is the Exim user (or
3373 the user specified in the CONFIGURE_OWNER option, if any), and as long as
3374 the configuration file is not writeable by inappropriate users or groups.
3376 Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
3377 configuration using -C right through message reception and delivery, even
3378 if the caller is root. The reception works, but by that time, Exim is
3379 running as the Exim user, so when it re-executes to regain privilege for
3380 the delivery, the use of -C causes privilege to be lost. However, root can
3381 test reception and delivery using two separate commands (one to put a
3382 message on the queue, using -odq, and another to do the delivery, using -M
3385 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix
3386 string with which any file named in a -C command line option must start. In
3387 addition, the file name must not contain the sequence "/../". However, if
3388 the value of the -C option is identical to the value of CONFIGURE_FILE in
3389 Local/Makefile, Exim ignores -C and proceeds as usual. There is no default
3390 setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used
3393 ALT_CONFIG_PREFIX can be used to confine alternative configuration files to
3394 a directory to which only root has access. This prevents someone who has
3395 broken into the Exim account from running a privileged Exim with an
3396 arbitrary configuration file.
3398 The -C facility is useful for ensuring that configuration files are
3399 syntactically correct, but cannot be used for test deliveries, unless the
3400 caller is privileged, or unless it is an exotic configuration that does not
3401 require privilege. No check is made on the owner or group of the files
3402 specified by this option.
3406 This option can be used to override macro definitions in the configuration
3407 file (see section 6.4). However, like -C, if it is used by an unprivileged
3408 caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION
3409 is defined in Local/Makefile, the use of -D is completely disabled, and its
3410 use causes an immediate error exit.
3412 If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a
3413 colon-separated list of macros which are considered safe and, if -D only
3414 supplies macros from this list, and the values are acceptable, then Exim
3415 will not give up root privilege if the caller is root, the Exim run-time
3416 user, or the CONFIGURE_OWNER, if set. This is a transition mechanism and is
3417 expected to be removed in the future. Acceptable values for the macros
3418 satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
3420 The entire option (including equals sign if present) must all be within one
3421 command line item. -D can be used to set the value of a macro to the empty
3422 string, in which case the equals sign is optional. These two commands are
3428 To include spaces in a macro definition item, quotes must be used. If you
3429 use quotes, spaces are permitted around the macro name and the equals sign.
3432 exim '-D ABC = something' ...
3434 -D may be repeated up to 10 times on a command line.
3438 This option causes debugging information to be written to the standard
3439 error stream. It is restricted to admin users because debugging output may
3440 show database queries that contain password information. Also, the details
3441 of users' filter files should be protected. If a non-admin user uses -d,
3442 Exim writes an error message to the standard error stream and exits with a
3443 non-zero return code.
3445 When -d is used, -v is assumed. If -d is given on its own, a lot of
3446 standard debugging data is output. This can be reduced, or increased to
3447 include some more rarely needed information, by directly following -d with
3448 a string made up of names preceded by plus or minus characters. These add
3449 or remove sets of debugging data, respectively. For example, -d+filter adds
3450 filter debugging, whereas -d-all+filter selects only filter debugging. Note
3451 that no spaces are allowed in the debug setting. The available debugging
3454 acl ACL interpretation
3456 deliver general delivery logic
3457 dns DNS lookups (see also resolver)
3458 dnsbl DNS black list (aka RBL) code
3459 exec arguments for execv() calls
3460 expand detailed debugging for string expansions
3461 filter filter handling
3462 hints_lookup hints data lookups
3463 host_lookup all types of name-to-IP address handling
3465 interface lists of local interfaces
3466 lists matching things in lists
3467 load system load checks
3468 local_scan can be used by local_scan() (see chapter 44)
3469 lookup general lookup code and all lookups
3470 memory memory handling
3471 pid add pid to debug output lines
3472 process_info setting info for the process log
3473 queue_run queue runs
3474 receive general message reception logic
3475 resolver turn on the DNS resolver's debugging output
3476 retry retry handling
3477 rewrite address rewriting
3478 route address routing
3479 timestamp add timestamp to debug output lines
3481 transport transports
3482 uid changes of uid/gid and looking up uid/gid
3483 verify address verification logic
3484 all almost all of the above (see below), and also -v
3486 The "all" option excludes "memory" when used as "+all", but includes it for
3487 "-all". The reason for this is that "+all" is something that people tend to
3488 use when generating debug output for Exim maintainers. If "+memory" is
3489 included, an awful lot of output that is very rarely of interest is
3490 generated, so it now has to be explicitly requested. However, "-all" does
3491 turn everything off.
3493 The "resolver" option produces output only if the DNS resolver was compiled
3494 with DEBUG enabled. This is not the case in some operating systems. Also,
3495 unfortunately, debugging output from the DNS resolver is written to stdout
3498 The default (-d with no argument) omits "expand", "filter", "interface",
3499 "load", "memory", "pid", "resolver", and "timestamp". However, the "pid"
3500 selector is forced when debugging is turned on for a daemon, which then
3501 passes it on to any re-executed Exims. Exim also automatically adds the pid
3502 to debug lines when several remote deliveries are run in parallel.
3504 The "timestamp" selector causes the current time to be inserted at the
3505 start of all debug output lines. This can be useful when trying to track
3506 down delays in processing.
3508 If the debug_print option is set in any driver, it produces output whenever
3509 any debugging is selected, or if -v is used.
3513 This option behaves exactly like -d except when used on a command that
3514 starts a daemon process. In that case, debugging is turned off for the
3515 subprocesses that the daemon creates. Thus, it is useful for monitoring the
3516 behaviour of the daemon without creating as much output as full debugging
3521 This is an obsolete option that is now a no-op. It used to affect the way
3522 Exim handled CR and LF characters in incoming messages. What happens now is
3523 described in section 46.2.
3527 This option specifies that an incoming message is a locally-generated
3528 delivery failure report. It is used internally by Exim when handling
3529 delivery failures and is not intended for external use. Its only effect is
3530 to stop Exim generating certain messages to the postmaster, as otherwise
3531 message cascades could occur in some situations. As part of the same
3532 option, a message id may follow the characters -E. If it does, the log
3533 entry for the receipt of the new message contains the id, following "R=",
3534 as a cross-reference.
3538 There are a number of Sendmail options starting with -oe which seem to be
3539 called by various programs without the leading o in the option. For
3540 example, the vacation program uses -eq. Exim treats all options of the form
3541 -ex as synonymous with the corresponding -oex options.
3545 This option sets the sender's full name for use when a locally-generated
3546 message is being accepted. In the absence of this option, the user's gecos
3547 entry from the password data is used. As users are generally permitted to
3548 alter their gecos entries, no security considerations are involved. White
3549 space between -F and the <string> is optional.
3553 This option sets the address of the envelope sender of a locally-generated
3554 message (also known as the return path). The option can normally be used
3555 only by a trusted user, but untrusted_set_sender can be set to allow
3556 untrusted users to use it.
3558 Processes running as root or the Exim user are always trusted. Other
3559 trusted users are defined by the trusted_users or trusted_groups options.
3560 In the absence of -f, or if the caller is not trusted, the sender of a
3561 local message is set to the caller's login name at the default qualify
3564 There is one exception to the restriction on the use of -f: an empty sender
3565 can be specified by any user, trusted or not, to create a message that can
3566 never provoke a bounce. An empty sender can be specified either as an empty
3567 string, or as a pair of angle brackets with nothing between them, as in
3568 these examples of shell commands:
3570 exim -f '<>' user@domain
3571 exim -f "" user@domain
3573 In addition, the use of -f is not restricted when testing a filter file
3574 with -bf or when testing or verifying addresses using the -bt or -bv
3577 Allowing untrusted users to change the sender address does not of itself
3578 make it possible to send anonymous mail. Exim still checks that the From:
3579 header refers to the local user, and if it does not, it adds a Sender:
3580 header, though this can be overridden by setting no_local_from_check.
3582 White space between -f and the <address> is optional (that is, they can be
3583 given as two arguments or one combined argument). The sender of a
3584 locally-generated message can also be set (when permitted) by an initial
3585 "From " line in the message - see the description of -bm above - but if -f
3586 is also present, it overrides "From ".
3590 This option is equivalent to an ACL applying:
3592 control = suppress_local_fixups
3594 for every message received. Note that Sendmail will complain about such bad
3595 formatting, where Exim silently just does not fix it up. This may change in
3598 As this affects audit information, the caller must be a trusted user to use
3603 This option is accepted for compatibility with Sendmail, but has no effect.
3604 (In Sendmail it overrides the "hop count" obtained by counting Received:
3609 This option, which has the same effect as -oi, specifies that a dot on a
3610 line by itself should not terminate an incoming, non-SMTP message. I can
3611 find no documentation for this option in Solaris 2.4 Sendmail, but the
3612 mailx command in Solaris 2.4 uses it. See also -ti.
3616 This option is equivalent to setting syslog_processname in the config file
3617 and setting log_file_path to "syslog". Its use is restricted to
3618 administrators. The configuration file has to be read and parsed, to
3619 determine access rights, before this is set and takes effect, so early
3620 configuration file errors will not honour this flag.
3622 The tag should not be longer than 32 characters.
3624 -M <message id> <message id> ...
3626 This option requests Exim to run a delivery attempt on each message in
3627 turn. If any of the messages are frozen, they are automatically thawed
3628 before the delivery attempt. The settings of queue_domains,
3629 queue_smtp_domains, and hold_domains are ignored.
3631 Retry hints for any of the addresses are overridden - Exim tries to deliver
3632 even if the normal retry time has not yet been reached. This option
3633 requires the caller to be an admin user. However, there is an option called
3634 prod_requires_admin which can be set false to relax this restriction (and
3635 also the same requirement for the -q, -R, and -S options).
3637 The deliveries happen synchronously, that is, the original Exim process
3638 does not terminate until all the delivery attempts have finished. No output
3639 is produced unless there is a serious error. If you want to see what is
3640 happening, use the -v option as well, or inspect Exim's main log.
3642 -Mar <message id> <address> <address> ...
3644 This option requests Exim to add the addresses to the list of recipients of
3645 the message ("ar" for "add recipients"). The first argument must be a
3646 message id, and the remaining ones must be email addresses. However, if the
3647 message is active (in the middle of a delivery attempt), it is not altered.
3648 This option can be used only by an admin user.
3650 -MC <transport> <hostname> <sequence number> <message id>
3652 This option is not intended for use by external callers. It is used
3653 internally by Exim to invoke another instance of itself to deliver a
3654 waiting message using an existing SMTP connection, which is passed as the
3655 standard input. Details are given in chapter 47. This must be the final
3656 option, and the caller must be root or the Exim user in order to use it.
3660 This option is not intended for use by external callers. It is used
3661 internally by Exim in conjunction with the -MC option. It signifies that
3662 the connection to the remote host has been authenticated.
3666 This option is not intended for use by external callers. It is used
3667 internally by Exim in conjunction with the -MC option. It signifies that
3668 the server to which Exim is connected supports pipelining.
3670 -MCQ <process id> <pipe fd>
3672 This option is not intended for use by external callers. It is used
3673 internally by Exim in conjunction with the -MC option when the original
3674 delivery was started by a queue runner. It passes on the process id of the
3675 queue runner, together with the file descriptor number of an open pipe.
3676 Closure of the pipe signals the final completion of the sequence of
3677 processes that are passing messages through the same SMTP connection.
3681 This option is not intended for use by external callers. It is used
3682 internally by Exim in conjunction with the -MC option, and passes on the
3683 fact that the SMTP SIZE option should be used on messages delivered down
3684 the existing connection.
3688 This option is not intended for use by external callers. It is used
3689 internally by Exim in conjunction with the -MC option, and passes on the
3690 fact that the host to which Exim is connected supports TLS encryption.
3692 -Mc <message id> <message id> ...
3694 This option requests Exim to run a delivery attempt on each message in
3695 turn, but unlike the -M option, it does check for retry hints, and respects
3696 any that are found. This option is not very useful to external callers. It
3697 is provided mainly for internal use by Exim when it needs to re-invoke
3698 itself in order to regain root privilege for a delivery (see chapter 54).
3699 However, -Mc can be useful when testing, in order to run a delivery that
3700 respects retry times and other options such as hold_domains that are
3701 overridden when -M is used. Such a delivery does not count as a queue run.
3702 If you want to run a specific delivery as if in a queue run, you should use
3703 -q with a message id argument. A distinction between queue run deliveries
3704 and other deliveries is made in one or two places.
3706 -Mes <message id> <address>
3708 This option requests Exim to change the sender address in the message to
3709 the given address, which must be a fully qualified address or "<>" ("es"
3710 for "edit sender"). There must be exactly two arguments. The first argument
3711 must be a message id, and the second one an email address. However, if the
3712 message is active (in the middle of a delivery attempt), its status is not
3713 altered. This option can be used only by an admin user.
3715 -Mf <message id> <message id> ...
3717 This option requests Exim to mark each listed message as "frozen". This
3718 prevents any delivery attempts taking place until the message is "thawed",
3719 either manually or as a result of the auto_thaw configuration option.
3720 However, if any of the messages are active (in the middle of a delivery
3721 attempt), their status is not altered. This option can be used only by an
3724 -Mg <message id> <message id> ...
3726 This option requests Exim to give up trying to deliver the listed messages,
3727 including any that are frozen. However, if any of the messages are active,
3728 their status is not altered. For non-bounce messages, a delivery error
3729 message is sent to the sender, containing the text "cancelled by
3730 administrator". Bounce messages are just discarded. This option can be used
3731 only by an admin user.
3733 -Mmad <message id> <message id> ...
3735 This option requests Exim to mark all the recipient addresses in the
3736 messages as already delivered ("mad" for "mark all delivered"). However, if
3737 any message is active (in the middle of a delivery attempt), its status is
3738 not altered. This option can be used only by an admin user.
3740 -Mmd <message id> <address> <address> ...
3742 This option requests Exim to mark the given addresses as already delivered
3743 ("md" for "mark delivered"). The first argument must be a message id, and
3744 the remaining ones must be email addresses. These are matched to recipient
3745 addresses in the message in a case-sensitive manner. If the message is
3746 active (in the middle of a delivery attempt), its status is not altered.
3747 This option can be used only by an admin user.
3749 -Mrm <message id> <message id> ...
3751 This option requests Exim to remove the given messages from the queue. No
3752 bounce messages are sent; each message is simply forgotten. However, if any
3753 of the messages are active, their status is not altered. This option can be
3754 used only by an admin user or by the user who originally caused the message
3755 to be placed on the queue.
3759 This option is useful only in conjunction with -be (that is, when testing
3760 string expansions). Exim loads the given message from its spool before
3761 doing the test expansions, thus setting message-specific variables such as
3762 $message_size and the header variables. The $recipients variable is made
3763 available. This feature is provided to make it easier to test expansions
3764 that make use of these variables. However, this option can be used only by
3765 an admin user. See also -bem.
3767 -Mt <message id> <message id> ...
3769 This option requests Exim to "thaw" any of the listed messages that are
3770 "frozen", so that delivery attempts can resume. However, if any of the
3771 messages are active, their status is not altered. This option can be used
3772 only by an admin user.
3776 This option causes the contents of the message body (-D) spool file to be
3777 written to the standard output. This option can be used only by an admin
3782 This option causes a copy of the complete message (header lines plus body)
3783 to be written to the standard output in RFC 2822 format. This option can be
3784 used only by an admin user.
3788 This option causes the contents of the message headers (-H) spool file to
3789 be written to the standard output. This option can be used only by an admin
3794 This option causes the contents of the message log spool file to be written
3795 to the standard output. This option can be used only by an admin user.
3799 This is apparently a synonym for -om that is accepted by Sendmail, so Exim
3800 treats it that way too.
3804 This is a debugging option that inhibits delivery of a message at the
3805 transport level. It implies -v. Exim goes through many of the motions of
3806 delivery - it just doesn't actually transport the message, but instead
3807 behaves as if it had successfully done so. However, it does not make any
3808 updates to the retry database, and the log entries for deliveries are
3809 flagged with "*>" rather than "=>".
3811 Because -N discards any message to which it applies, only root or the Exim
3812 user are allowed to use it with -bd, -q, -R or -M. In other words, an
3813 ordinary user can use it only when supplying an incoming message to which
3814 it will apply. Although transportation never fails when -N is set, an
3815 address may be deferred because of a configuration problem on a transport,
3816 or a routing problem. Once -N has been used for a delivery attempt, it
3817 sticks to the message, and applies to any subsequent delivery attempts that
3818 may happen for that message.
3822 This option is interpreted by Sendmail to mean "no aliasing". For normal
3823 modes of operation, it is ignored by Exim. When combined with -bP it
3824 suppresses the name of an option from being output.
3828 This option is interpreted by Sendmail to mean "set option". It is ignored
3833 This option is used by Sendmail in conjunction with -bi to specify an
3834 alternative alias file name. Exim handles -bi differently; see the
3839 This is a debugging option which limits the maximum number of messages that
3840 can be delivered down one SMTP connection, overriding the value set in any
3841 smtp transport. If <n> is omitted, the limit is set to 1.
3845 This option applies to all modes in which Exim accepts incoming messages,
3846 including the listening daemon. It requests "background" delivery of such
3847 messages, which means that the accepting process automatically starts a
3848 delivery process for each message received, but does not wait for the
3849 delivery processes to finish.
3851 When all the messages have been received, the reception process exits,
3852 leaving the delivery processes to finish in their own time. The standard
3853 output and error streams are closed at the start of each delivery process.
3854 This is the default action if none of the -od options are present.
3856 If one of the queueing options in the configuration file (queue_only or
3857 queue_only_file, for example) is in effect, -odb overrides it if
3858 queue_only_override is set true, which is the default setting. If
3859 queue_only_override is set false, -odb has no effect.
3863 This option requests "foreground" (synchronous) delivery when Exim has
3864 accepted a locally-generated message. (For the daemon it is exactly the
3865 same as -odb.) A delivery process is automatically started to deliver the
3866 message, and Exim waits for it to complete before proceeding.
3868 The original Exim reception process does not finish until the delivery
3869 process for the final message has ended. The standard error stream is left
3870 open during deliveries.
3872 However, like -odb, this option has no effect if queue_only_override is
3873 false and one of the queueing options in the configuration file is in
3876 If there is a temporary delivery error during foreground delivery, the
3877 message is left on the queue for later delivery, and the original reception
3878 process exits. See chapter 50 for a way of setting up a restricted
3879 configuration that never queues messages.
3883 This option is synonymous with -odf. It is provided for compatibility with
3888 This option applies to all modes in which Exim accepts incoming messages,
3889 including the listening daemon. It specifies that the accepting process
3890 should not automatically start a delivery process for each message
3891 received. Messages are placed on the queue, and remain there until a
3892 subsequent queue runner process encounters them. There are several
3893 configuration options (such as queue_only) that can be used to queue
3894 incoming messages under certain conditions. This option overrides all of
3895 them and also -odqs. It always forces queueing.
3899 This option is a hybrid between -odb/-odi and -odq. However, like -odb and
3900 -odi, this option has no effect if queue_only_override is false and one of
3901 the queueing options in the configuration file is in effect.
3903 When -odqs does operate, a delivery process is started for each incoming
3904 message, in the background by default, but in the foreground if -odi is
3905 also present. The recipient addresses are routed, and local deliveries are
3906 done in the normal way. However, if any SMTP deliveries are required, they
3907 are not done at this time, so the message remains on the queue until a
3908 subsequent queue runner process encounters it. Because routing was done,
3909 Exim knows which messages are waiting for which hosts, and so a number of
3910 messages for the same host can be sent in a single SMTP connection. The
3911 queue_smtp_domains configuration option has the same effect for specific
3912 domains. See also the -qq option.
3916 If an error is detected while a non-SMTP message is being received (for
3917 example, a malformed address), the error is reported to the sender in a
3920 Provided this error message is successfully sent, the Exim receiving
3921 process exits with a return code of zero. If not, the return code is 2 if
3922 the problem is that the original message has no recipients, or 1 for any
3923 other error. This is the default -oex option if Exim is called as rmail.
3927 This is the same as -oee, except that Exim always exits with a non-zero
3928 return code, whether or not the error message was successfully sent. This
3929 is the default -oex option, unless Exim is called as rmail.
3933 If an error is detected while a non-SMTP message is being received, the
3934 error is reported by writing a message to the standard error file (stderr).
3935 The return code is 1 for all errors.
3939 This option is supported for compatibility with Sendmail, but has the same
3944 This option is supported for compatibility with Sendmail, but has the same
3949 This option, which has the same effect as -i, specifies that a dot on a
3950 line by itself should not terminate an incoming, non-SMTP message.
3951 Otherwise, a single dot does terminate, though Exim does no special
3952 processing for other lines that start with a dot. This option is set by
3953 default if Exim is called as rmail. See also -ti.
3957 This option is treated as synonymous with -oi.
3961 A number of options starting with -oM can be used to set values associated
3962 with remote hosts on locally-submitted messages (that is, messages not
3963 received over TCP/IP). These options can be used by any caller in
3964 conjunction with the -bh, -be, -bf, -bF, -bt, or -bv testing options. In
3965 other circumstances, they are ignored unless the caller is trusted.
3967 The -oMa option sets the sender host address. This may include a port
3968 number at the end, after a full stop (period). For example:
3970 exim -bs -oMa 10.9.8.7.1234
3972 An alternative syntax is to enclose the IP address in square brackets,
3973 followed by a colon and the port number:
3975 exim -bs -oMa [10.9.8.7]:1234
3977 The IP address is placed in the $sender_host_address variable, and the
3978 port, if present, in $sender_host_port. If both -oMa and -bh are present on
3979 the command line, the sender host IP address is taken from whichever one is
3984 See -oMa above for general remarks about the -oM options. The -oMaa option
3985 sets the value of $sender_host_authenticated (the authenticator name). See
3986 chapter 33 for a discussion of SMTP authentication. This option can be used
3987 with -bh and -bs to set up an authenticated SMTP session without actually
3988 using the SMTP AUTH command.
3992 See -oMa above for general remarks about the -oM options. The -oMai option
3993 sets the value of $authenticated_id (the id that was authenticated). This
3994 overrides the default value (the caller's login id, except with -bh, where
3995 there is no default) for messages from local sources. See chapter 33 for a
3996 discussion of authenticated ids.
4000 See -oMa above for general remarks about the -oM options. The -oMas option
4001 sets the authenticated sender value in $authenticated_sender. It overrides
4002 the sender address that is created from the caller's login id for messages
4003 from local sources, except when -bh is used, when there is no default. For
4004 both -bh and -bs, an authenticated sender that is specified on a MAIL
4005 command overrides this value. See chapter 33 for a discussion of
4006 authenticated senders.
4008 -oMi <interface address>
4010 See -oMa above for general remarks about the -oM options. The -oMi option
4011 sets the IP interface address value. A port number may be included, using
4012 the same syntax as for -oMa. The interface address is placed in
4013 $received_ip_address and the port number, if present, in $received_port.
4015 -oMm <message reference>
4017 See -oMa above for general remarks about the -oM options. The -oMm option
4018 sets the message reference, e.g. message-id, and is logged during delivery.
4019 This is useful when some kind of audit trail is required to tie messages
4020 together. The format of the message reference is checked and will abort if
4021 the format is invalid. The option will only be accepted if exim is running
4022 in trusted mode, not as any regular user.
4024 The best example of a message reference is when Exim sends a bounce
4025 message. The message reference is the message-id of the original message
4026 for which Exim is sending the bounce.
4028 -oMr <protocol name>
4030 See -oMa above for general remarks about the -oM options. The -oMr option
4031 sets the received protocol value that is stored in $received_protocol.
4032 However, it does not apply (and is ignored) when -bh or -bs is used. For
4033 -bh, the protocol is forced to one of the standard SMTP protocol names (see
4034 the description of $received_protocol in section 11.9). For -bs, the
4035 protocol is always "local-" followed by one of those same names. For -bS
4036 (batched SMTP) however, the protocol can be set by -oMr.
4040 See -oMa above for general remarks about the -oM options. The -oMs option
4041 sets the sender host name in $sender_host_name. When this option is
4042 present, Exim does not attempt to look up a host name from an IP address;
4043 it uses the name it is given.
4047 See -oMa above for general remarks about the -oM options. The -oMt option
4048 sets the sender ident value in $sender_ident. The default setting for local
4049 callers is the login id of the calling process, except when -bh is used,
4050 when there is no default.
4054 In Sendmail, this option means "me too", indicating that the sender of a
4055 message should receive a copy of the message if the sender appears in an
4056 alias expansion. Exim always does this, so the option does nothing.
4060 This option is ignored. In Sendmail it specifies "old style headers",
4061 whatever that means.
4065 This option is useful only in conjunction with -bd or -q with a time value.
4066 The option specifies the file to which the process id of the daemon is
4067 written. When -oX is used with -bd, or when -q with a time is used without
4068 -bd, this is the only way of causing Exim to write a pid file, because in
4069 those cases, the normal pid file is not used.
4073 This option sets a timeout value for incoming non-SMTP messages. If it is
4074 not set, Exim will wait forever for the standard input. The value can also
4075 be set by the receive_timeout option. The format used for specifying times
4076 is described in section 6.15.
4080 This option sets a timeout value for incoming SMTP messages. The timeout
4081 applies to each SMTP command and block of data. The value can also be set
4082 by the smtp_receive_timeout option; it defaults to 5 minutes. The format
4083 used for specifying times is described in section 6.15.
4087 This option has exactly the same effect as -v.
4089 -oX <number or string>
4091 This option is relevant only when the -bd (start listening daemon) option
4092 is also given. It controls which ports and interfaces the daemon uses.
4093 Details of the syntax, and how it interacts with configuration file
4094 options, are given in chapter 13. When -oX is used to start a daemon, no
4095 pid file is written unless -oP is also present to specify a pid file name.
4099 This option applies when an embedded Perl interpreter is linked with Exim
4100 (see chapter 12). It overrides the setting of the perl_at_start option,
4101 forcing the starting of the interpreter to be delayed until it is needed.
4105 This option applies when an embedded Perl interpreter is linked with Exim
4106 (see chapter 12). It overrides the setting of the perl_at_start option,
4107 forcing the starting of the interpreter to occur as soon as Exim is
4112 For compatibility with Sendmail, this option is equivalent to
4114 -oMr <rval> -oMs <sval>
4116 It sets the incoming protocol and host name (for trusted callers). The host
4117 name and its colon can be omitted when only the protocol is to be set. Note
4118 the Exim already has two private options, -pd and -ps, that refer to
4119 embedded Perl. It is therefore impossible to set a protocol value of "d" or
4120 "s" using this option (but that does not seem a real limitation).
4124 This option is normally restricted to admin users. However, there is a
4125 configuration option called prod_requires_admin which can be set false to
4126 relax this restriction (and also the same requirement for the -M, -R, and
4129 The -q option starts one queue runner process. This scans the queue of
4130 waiting messages, and runs a delivery process for each one in turn. It
4131 waits for each delivery process to finish before starting the next one. A
4132 delivery process may not actually do any deliveries if the retry times for
4133 the addresses have not been reached. Use -qf (see below) if you want to
4136 If the delivery process spawns other processes to deliver other messages
4137 down passed SMTP connections, the queue runner waits for these to finish
4140 When all the queued messages have been considered, the original queue
4141 runner process terminates. In other words, a single pass is made over the
4142 waiting mail, one message at a time. Use -q with a time (see below) if you
4143 want this to be repeated periodically.
4145 Exim processes the waiting messages in an unpredictable order. It isn't
4146 very random, but it is likely to be different each time, which is all that
4147 matters. If one particular message screws up a remote MTA, other messages
4148 to the same MTA have a chance of getting through if they get tried first.
4150 It is possible to cause the messages to be processed in lexical message id
4151 order, which is essentially the order in which they arrived, by setting the
4152 queue_run_in_order option, but this is not recommended for normal use.
4156 The -q option may be followed by one or more flag letters that change its
4157 behaviour. They are all optional, but if more than one is present, they
4158 must appear in the correct order. Each flag is described in a separate item
4163 An option starting with -qq requests a two-stage queue run. In the first
4164 stage, the queue is scanned as if the queue_smtp_domains option matched
4165 every domain. Addresses are routed, local deliveries happen, but no remote
4168 The hints database that remembers which messages are waiting for specific
4169 hosts is updated, as if delivery to those hosts had been deferred. After
4170 this is complete, a second, normal queue scan happens, with routing and
4171 delivery taking place as normal. Messages that are routed to the same host
4172 should mostly be delivered down a single SMTP connection because of the
4173 hints that were set up during the first queue scan. This option may be
4174 useful for hosts that are connected to the Internet intermittently.
4178 If the i flag is present, the queue runner runs delivery processes only for
4179 those messages that haven't previously been tried. (i stands for "initial
4180 delivery".) This can be helpful if you are putting messages on the queue
4181 using -odq and want a queue runner just to process the new messages.
4185 If one f flag is present, a delivery attempt is forced for each non-frozen
4186 message, whereas without f only those non-frozen addresses that have passed
4187 their retry times are tried.
4191 If ff is present, a delivery attempt is forced for every message, whether
4196 The l (the letter "ell") flag specifies that only local deliveries are to
4197 be done. If a message requires any remote deliveries, it remains on the
4198 queue for later delivery.
4200 -q<qflags> <start id> <end id>
4202 When scanning the queue, Exim can be made to skip over messages whose ids
4203 are lexically less than a given value by following the -q option with a
4204 starting message id. For example:
4206 exim -q 0t5C6f-0000c8-00
4208 Messages that arrived earlier than "0t5C6f-0000c8-00" are not inspected. If
4209 a second message id is given, messages whose ids are lexically greater than
4210 it are also skipped. If the same id is given twice, for example,
4212 exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
4214 just one delivery process is started, for that message. This differs from
4215 -M in that retry data is respected, and it also differs from -Mc in that it
4216 counts as a delivery from a queue run. Note that the selection mechanism
4217 does not affect the order in which the messages are scanned. There are also
4218 other ways of selecting specific sets of messages for delivery in a queue
4219 run - see -R and -S.
4223 When a time value is present, the -q option causes Exim to run as a daemon,
4224 starting a queue runner process at intervals specified by the given time
4225 value (whose format is described in section 6.15). This form of the -q
4226 option is commonly combined with the -bd option, in which case a single
4227 daemon process handles both functions. A common way of starting up a
4228 combined daemon at system boot time is to use a command such as
4230 /usr/exim/bin/exim -bd -q30m
4232 Such a daemon listens for incoming SMTP calls, and also starts a queue
4233 runner process every 30 minutes.
4235 When a daemon is started by -q with a time value, but without -bd, no pid
4236 file is written unless one is explicitly requested by the -oP option.
4238 -qR<rsflags> <string>
4240 This option is synonymous with -R. It is provided for Sendmail
4243 -qS<rsflags> <string>
4245 This option is synonymous with -S.
4247 -R<rsflags> <string>
4249 The <rsflags> may be empty, in which case the white space before the string
4250 is optional, unless the string is f, ff, r, rf, or rff, which are the
4251 possible values for <rsflags>. White space is required if <rsflags> is not
4254 This option is similar to -q with no time value, that is, it causes Exim to
4255 perform a single queue run, except that, when scanning the messages on the
4256 queue, Exim processes only those that have at least one undelivered
4257 recipient address containing the given string, which is checked in a
4258 case-independent way. If the <rsflags> start with r, <string> is
4259 interpreted as a regular expression; otherwise it is a literal string.
4261 If you want to do periodic queue runs for messages with specific
4262 recipients, you can combine -R with -q and a time value. For example:
4264 exim -q25m -R @special.domain.example
4266 This example does a queue run for messages with recipients in the given
4267 domain every 25 minutes. Any additional flags that are specified with -q
4268 are applied to each queue run.
4270 Once a message is selected for delivery by this mechanism, all its
4271 addresses are processed. For the first selected message, Exim overrides any
4272 retry information and forces a delivery attempt for each undelivered
4273 address. This means that if delivery of any address in the first message is
4274 successful, any existing retry information is deleted, and so delivery
4275 attempts for that address in subsequently selected messages (which are
4276 processed without forcing) will run. However, if delivery of any address
4277 does not succeed, the retry information is updated, and in subsequently
4278 selected messages, the failing address will be skipped.
4280 If the <rsflags> contain f or ff, the delivery forcing applies to all
4281 selected messages, not just the first; frozen messages are included when ff
4284 The -R option makes it straightforward to initiate delivery of all messages
4285 to a given domain after a host has been down for some time. When the SMTP
4286 command ETRN is accepted by its ACL (see chapter 42), its default effect is
4287 to run Exim with the -R option, but it can be configured to run an
4288 arbitrary command instead.
4292 This is a documented (for Sendmail) obsolete alternative name for -f.
4294 -S<rsflags> <string>
4296 This option acts like -R except that it checks the string against each
4297 message's sender instead of against the recipients. If -R is also set, both
4298 conditions must be met for a message to be selected. If either of the
4299 options has f or ff in its flags, the associated action is taken.
4303 This is an option that is exclusively for use by the Exim testing suite. It
4304 is not recognized when Exim is run normally. It allows for the setting up
4305 of explicit "queue times" so that various warning/retry features can be
4310 When Exim is receiving a locally-generated, non-SMTP message on its
4311 standard input, the -t option causes the recipients of the message to be
4312 obtained from the To:, Cc:, and Bcc: header lines in the message instead of
4313 from the command arguments. The addresses are extracted before any
4314 rewriting takes place and the Bcc: header line, if present, is then
4317 If the command has any arguments, they specify addresses to which the
4318 message is not to be delivered. That is, the argument addresses are removed
4319 from the recipients list obtained from the headers. This is compatible with
4320 Smail 3 and in accordance with the documented behaviour of several versions
4321 of Sendmail, as described in man pages on a number of operating systems
4322 (e.g. Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail
4323 add argument addresses to those obtained from the headers, and the O'Reilly
4324 Sendmail book documents it that way. Exim can be made to add argument
4325 addresses instead of subtracting them by setting the option
4326 extract_addresses_remove_arguments false.
4328 If there are any Resent- header lines in the message, Exim extracts
4329 recipients from all Resent-To:, Resent-Cc:, and Resent-Bcc: header lines
4330 instead of from To:, Cc:, and Bcc:. This is for compatibility with Sendmail
4331 and other MTAs. (Prior to release 4.20, Exim gave an error if -t was used
4332 in conjunction with Resent- header lines.)
4334 RFC 2822 talks about different sets of Resent- header lines (for when a
4335 message is resent several times). The RFC also specifies that they should
4336 be added at the front of the message, and separated by Received: lines. It
4337 is not at all clear how -t should operate in the present of multiple sets,
4338 nor indeed exactly what constitutes a "set". In practice, it seems that
4339 MUAs do not follow the RFC. The Resent- lines are often added at the end of
4340 the header, and if a message is resent more than once, it is common for the
4341 original set of Resent- headers to be renamed as X-Resent- when a new set
4342 is added. This removes any possible ambiguity.
4346 This option is exactly equivalent to -t -i. It is provided for
4347 compatibility with Sendmail.
4351 This option is available when Exim is compiled with TLS support. It forces
4352 all incoming SMTP connections to behave as if the incoming port is listed
4353 in the tls_on_connect_ports option. See section 13.4 and chapter 41 for
4358 Sendmail uses this option for "initial message submission", and its
4359 documentation states that in future releases, it may complain about
4360 syntactically invalid messages rather than fixing them when this flag is
4361 not set. Exim ignores this option.
4365 This option causes Exim to write information to the standard error stream,
4366 describing what it is doing. In particular, it shows the log lines for
4367 receiving and delivering a message, and if an SMTP connection is made, the
4368 SMTP dialogue is shown. Some of the log lines shown may not actually be
4369 written to the log if the setting of log_selector discards them. Any
4370 relevant selectors are shown with each log line. If none are shown, the
4371 logging is unconditional.
4375 AIX uses -x for a private purpose ("mail from a local mail program has
4376 National Language Support extended characters in the body of the mail
4377 item"). It sets -x when calling the MTA from its mail command. Exim ignores
4382 This option is interpreted by Sendmail to cause debug information to be
4383 sent to the named file. It is ignored by Exim.
4387 ===============================================================================
4388 6. THE EXIM RUN TIME CONFIGURATION FILE
4390 Exim uses a single run time configuration file that is read whenever an Exim
4391 binary is executed. Note that in normal operation, this happens frequently,
4392 because Exim is designed to operate in a distributed manner, without central
4395 If a syntax error is detected while reading the configuration file, Exim writes
4396 a message on the standard error, and exits with a non-zero return code. The
4397 message is also written to the panic log. Note: Only simple syntax errors can
4398 be detected at this time. The values of any expanded options are not checked
4399 until the expansion happens, even when the expansion does not actually alter
4402 The name of the configuration file is compiled into the binary for security
4403 reasons, and is specified by the CONFIGURE_FILE compilation option. In most
4404 configurations, this specifies a single file. However, it is permitted to give
4405 a colon-separated list of file names, in which case Exim uses the first
4406 existing file in the list.
4408 The run time configuration file must be owned by root or by the user that is
4409 specified at compile time by the CONFIGURE_OWNER option (if set). The
4410 configuration file must not be world-writeable, or group-writeable unless its
4411 group is the root group or the one specified at compile time by the
4412 CONFIGURE_GROUP option.
4414 Warning: In a conventional configuration, where the Exim binary is setuid to
4415 root, anybody who is able to edit the run time configuration file has an easy
4416 way to run commands as root. If you specify a user or group in the
4417 CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who
4418 are members of that group will trivially be able to obtain root privileges.
4420 Up to Exim version 4.72, the run time configuration file was also permitted to
4421 be writeable by the Exim user and/or group. That has been changed in Exim 4.73
4422 since it offered a simple privilege escalation for any attacker who managed to
4423 compromise the Exim user account.
4425 A default configuration file, which will work correctly in simple situations,
4426 is provided in the file src/configure.default. If CONFIGURE_FILE defines just
4427 one file name, the installation process copies the default configuration to a
4428 new file of that name if it did not previously exist. If CONFIGURE_FILE is a
4429 list, no default is automatically installed. Chapter 7 is a "walk-through"
4430 discussion of the default configuration.
4433 6.1 Using a different configuration file
4434 ----------------------------------------
4436 A one-off alternate configuration can be specified by the -C command line
4437 option, which may specify a single file or a list of files. However, when -C is
4438 used, Exim gives up its root privilege, unless called by root (or unless the
4439 argument for -C is identical to the built-in value from CONFIGURE_FILE), or is
4440 listed in the TRUSTED_CONFIG_LIST file and the caller is the Exim user or the
4441 user specified in the CONFIGURE_OWNER setting. -C is useful mainly for checking
4442 the syntax of configuration files before installing them. No owner or group
4443 checks are done on a configuration file specified by -C, if root privilege has
4446 Even the Exim user is not trusted to specify an arbitrary configuration file
4447 with the -C option to be used with root privileges, unless that file is listed
4448 in the TRUSTED_CONFIG_LIST file. This locks out the possibility of testing a
4449 configuration using -C right through message reception and delivery, even if
4450 the caller is root. The reception works, but by that time, Exim is running as
4451 the Exim user, so when it re-execs to regain privilege for the delivery, the
4452 use of -C causes privilege to be lost. However, root can test reception and
4453 delivery using two separate commands (one to put a message on the queue, using
4454 -odq, and another to do the delivery, using -M).
4456 If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string
4457 with which any file named in a -C command line option must start. In addition,
4458 the file name must not contain the sequence "/../". There is no default setting
4459 for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C.
4461 One-off changes to a configuration can be specified by the -D command line
4462 option, which defines and overrides values for macros used inside the
4463 configuration file. However, like -C, the use of this option by a
4464 non-privileged user causes Exim to discard its root privilege. If
4465 DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely
4466 disabled, and its use causes an immediate error exit.
4468 The WHITELIST_D_MACROS option in Local/Makefile permits the binary builder to
4469 declare certain macro names trusted, such that root privilege will not
4470 necessarily be discarded. WHITELIST_D_MACROS defines a colon-separated list of
4471 macros which are considered safe and, if -D only supplies macros from this
4472 list, and the values are acceptable, then Exim will not give up root privilege
4473 if the caller is root, the Exim run-time user, or the CONFIGURE_OWNER, if set.
4474 This is a transition mechanism and is expected to be removed in the future.
4475 Acceptable values for the macros satisfy the regexp: "^[A-Za-z0-9_/.-]*$"
4477 Some sites may wish to use the same Exim binary on different machines that
4478 share a file system, but to use different configuration files on each machine.
4479 If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a
4480 file whose name is the configuration file name followed by a dot and the
4481 machine's node name, as obtained from the uname() function. If this file does
4482 not exist, the standard name is tried. This processing occurs for each file
4483 name in the list given by CONFIGURE_FILE or -C.
4485 In some esoteric situations different versions of Exim may be run under
4486 different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help
4487 with this. See the comments in src/EDITME for details.
4490 6.2 Configuration file format
4491 -----------------------------
4493 Exim's configuration file is divided into a number of different parts. General
4494 option settings must always appear at the start of the file. The other parts
4495 are all optional, and may appear in any order. Each part other than the first
4496 is introduced by the word "begin" followed by the name of the part. The
4499 * ACL: Access control lists for controlling incoming SMTP mail (see chapter
4502 * authenticators: Configuration settings for the authenticator drivers. These
4503 are concerned with the SMTP AUTH command (see chapter 33).
4505 * routers: Configuration settings for the router drivers. Routers process
4506 addresses and determine how the message is to be delivered (see chapters 15
4509 * transports: Configuration settings for the transport drivers. Transports
4510 define mechanisms for copying messages to destinations (see chapters 24-30
4513 * retry: Retry rules, for use when a message cannot be delivered immediately.
4514 If there is no retry section, or if it is empty (that is, no retry rules
4515 are defined), Exim will not retry deliveries. In this situation, temporary
4516 errors are treated the same as permanent errors. Retry rules are discussed
4519 * rewrite: Global address rewriting rules, for use when a message arrives and
4520 when new addresses are generated during delivery. Rewriting is discussed in
4523 * local_scan: Private options for the local_scan() function. If you want to
4524 use this feature, you must set
4526 LOCAL_SCAN_HAS_OPTIONS=yes
4528 in Local/Makefile before building Exim. Details of the local_scan()
4529 facility are given in chapter 44.
4531 Leading and trailing white space in configuration lines is always ignored.
4533 Blank lines in the file, and lines starting with a # character (ignoring
4534 leading white space) are treated as comments and are ignored. Note: A #
4535 character other than at the beginning of a line is not treated specially, and
4536 does not introduce a comment.
4538 Any non-comment line can be continued by ending it with a backslash. Note that
4539 the general rule for white space means that trailing white space after the
4540 backslash and leading white space at the start of continuation lines is
4541 ignored. Comment lines beginning with # (but not empty lines) may appear in the
4542 middle of a sequence of continuation lines.
4544 A convenient way to create a configuration file is to start from the default,
4545 which is supplied in src/configure.default, and add, delete, or change settings
4548 The ACLs, retry rules, and rewriting rules have their own syntax which is
4549 described in chapters 42, 32, and 31, respectively. The other parts of the
4550 configuration file have some syntactic items in common, and these are described
4551 below, from section 6.10 onwards. Before that, the inclusion, macro, and
4552 conditional facilities are described.
4555 6.3 File inclusions in the configuration file
4556 ---------------------------------------------
4558 You can include other files inside Exim's run time configuration file by using
4561 .include <file name>
4562 .include_if_exists <file name>
4564 on a line by itself. Double quotes round the file name are optional. If you use
4565 the first form, a configuration error occurs if the file does not exist; the
4566 second form does nothing for non-existent files. In all cases, an absolute file
4569 Includes may be nested to any depth, but remember that Exim reads its
4570 configuration file often, so it is a good idea to keep them to a minimum. If
4571 you change the contents of an included file, you must HUP the daemon, because
4572 an included file is read only when the configuration itself is read.
4574 The processing of inclusions happens early, at a physical line level, so, like
4575 comment lines, an inclusion can be used in the middle of an option setting, for
4578 hosts_lookup = a.b.c \
4581 Include processing happens after macro processing (see below). Its effect is to
4582 process the lines of the included file as if they occurred inline where the
4586 6.4 Macros in the configuration file
4587 ------------------------------------
4589 If a line in the main part of the configuration (that is, before the first
4590 "begin" line) begins with an upper case letter, it is taken as a macro
4591 definition, and must be of the form
4593 <name> = <rest of line>
4595 The name must consist of letters, digits, and underscores, and need not all be
4596 in upper case, though that is recommended. The rest of the line, including any
4597 continuations, is the replacement text, and has leading and trailing white
4598 space removed. Quotes are not removed. The replacement text can never end with
4599 a backslash character, but this doesn't seem to be a serious limitation.
4601 Macros may also be defined between router, transport, authenticator, or ACL
4602 definitions. They may not, however, be defined within an individual driver or
4603 ACL, or in the local_scan, retry, or rewrite sections of the configuration.
4606 6.5 Macro substitution
4607 ----------------------
4609 Once a macro is defined, all subsequent lines in the file (and any included
4610 files) are scanned for the macro name; if there are several macros, the line is
4611 scanned for each in turn, in the order in which the macros are defined. The
4612 replacement text is not re-scanned for the current macro, though it is scanned
4613 for subsequently defined macros. For this reason, a macro name may not contain
4614 the name of a previously defined macro as a substring. You could, for example,
4617 ABCD_XYZ = <something>
4618 ABCD = <something else>
4620 but putting the definitions in the opposite order would provoke a configuration
4621 error. Macro expansion is applied to individual physical lines from the file,
4622 before checking for line continuation or file inclusion (see above). If a line
4623 consists solely of a macro name, and the expansion of the macro is empty, the
4624 line is ignored. A macro at the start of a line may turn the line into a
4625 comment line or a ".include" line.
4628 6.6 Redefining macros
4629 ---------------------
4631 Once defined, the value of a macro can be redefined later in the configuration
4632 (or in an included file). Redefinition is specified by using == instead of =.
4637 MAC == updated value
4639 Redefinition does not alter the order in which the macros are applied to the
4640 subsequent lines of the configuration file. It is still the same order in which
4641 the macros were originally defined. All that changes is the macro's value.
4642 Redefinition makes it possible to accumulate values. For example:
4646 MAC == MAC and something added
4648 This can be helpful in situations where the configuration file is built from a
4649 number of other files.
4652 6.7 Overriding macro values
4653 ---------------------------
4655 The values set for macros in the configuration file can be overridden by the -D
4656 command line option, but Exim gives up its root privilege when -D is used,
4657 unless called by root or the Exim user. A definition on the command line using
4658 the -D option causes all definitions and redefinitions within the file to be
4662 6.8 Example of macro usage
4663 --------------------------
4665 As an example of macro usage, consider a configuration where aliases are looked
4666 up in a MySQL database. It helps to keep the file less cluttered if long
4667 strings such as SQL statements are defined separately as macros, for example:
4669 ALIAS_QUERY = select mailbox from user where \
4670 login='${quote_mysql:$local_part}';
4672 This can then be used in a redirect router setting like this:
4674 data = ${lookup mysql{ALIAS_QUERY}}
4676 In earlier versions of Exim macros were sometimes used for domain, host, or
4677 address lists. In Exim 4 these are handled better by named lists - see section
4681 6.9 Conditional skips in the configuration file
4682 -----------------------------------------------
4684 You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef",
4685 ".else", and ".endif" to dynamically include or exclude portions of the
4686 configuration file. The processing happens whenever the file is read (that is,
4687 when an Exim binary starts to run).
4689 The implementation is very simple. Instances of the first four directives must
4690 be followed by text that includes the names of one or macros. The condition
4691 that is tested is whether or not any macro substitution has taken place in the
4695 message_size_limit = 50M
4697 message_size_limit = 100M
4700 sets a message size limit of 50M if the macro "AAA" is defined, and 100M
4701 otherwise. If there is more than one macro named on the line, the condition is
4702 true if any of them are defined. That is, it is an "or" condition. To obtain an
4703 "and" condition, you need to use nested ".ifdef"s.
4705 Although you can use a macro expansion to generate one of these directives, it
4706 is not very useful, because the condition "there was a macro substitution in
4707 this line" will always be true.
4709 Text following ".else" and ".endif" is ignored, and can be used as comment to
4710 clarify complicated nestings.
4713 6.10 Common option syntax
4714 -------------------------
4716 For the main set of options, driver options, and local_scan() options, each
4717 setting is on a line by itself, and starts with a name consisting of lower-case
4718 letters and underscores. Many options require a data value, and in these cases
4719 the name must be followed by an equals sign (with optional white space) and
4720 then the value. For example:
4722 qualify_domain = mydomain.example.com
4724 Some option settings may contain sensitive data, for example, passwords for
4725 accessing databases. To stop non-admin users from using the -bP command line
4726 option to read these values, you can precede the option settings with the word
4727 "hide". For example:
4729 hide mysql_servers = localhost/users/admin/secret-password
4731 For non-admin users, such options are displayed like this:
4733 mysql_servers = <value not displayable>
4735 If "hide" is used on a driver option, it hides the value of that option on all
4736 instances of the same driver.
4738 The following sections describe the syntax used for the different data types
4739 that are found in option settings.
4742 6.11 Boolean options
4743 --------------------
4745 Options whose type is given as boolean are on/off switches. There are two
4746 different ways of specifying such options: with and without a data value. If
4747 the option name is specified on its own without data, the switch is turned on;
4748 if it is preceded by "no_" or "not_" the switch is turned off. However, boolean
4749 options may be followed by an equals sign and one of the words "true", "false",
4750 "yes", or "no", as an alternative syntax. For example, the following two
4751 settings have exactly the same effect:
4756 The following two lines also have the same (opposite) effect:
4761 You can use whichever syntax you prefer.
4767 If an option's type is given as "integer", the value can be given in decimal,
4768 hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
4769 number is assumed. Otherwise, it is treated as an octal number unless it starts
4770 with the characters "0x", in which case the remainder is interpreted as a
4773 If an integer value is followed by the letter K, it is multiplied by 1024; if
4774 it is followed by the letter M, it is multiplied by 1024x1024. When the values
4775 of integer option settings are output, values which are an exact multiple of
4776 1024 or 1024x1024 are sometimes, but not always, printed using the letters K
4777 and M. The printing style is independent of the actual input format that was
4781 6.13 Octal integer values
4782 -------------------------
4784 If an option's type is given as "octal integer", its value is always
4785 interpreted as an octal number, whether or not it starts with the digit zero.
4786 Such options are always output in octal.
4789 6.14 Fixed point numbers
4790 ------------------------
4792 If an option's type is given as "fixed-point", its value must be a decimal
4793 integer, optionally followed by a decimal point and up to three further digits.
4799 A time interval is specified as a sequence of numbers, each followed by one of
4800 the following letters, with no intervening white space:
4808 For example, "3h50m" specifies 3 hours and 50 minutes. The values of time
4809 intervals are output in the same format. Exim does not restrict the values; it
4810 is perfectly acceptable, for example, to specify "90m" instead of "1h30m".
4816 If an option's type is specified as "string", the value can be specified with
4817 or without double-quotes. If it does not start with a double-quote, the value
4818 consists of the remainder of the line plus any continuation lines, starting at
4819 the first character after any leading white space, with trailing white space
4820 removed, and with no interpretation of the characters in the string. Because
4821 Exim removes comment lines (those beginning with #) at an early stage, they can
4822 appear in the middle of a multi-line string. The following two settings are
4823 therefore equivalent:
4825 trusted_users = uucp:mail
4826 trusted_users = uucp:\
4827 # This comment line is ignored
4830 If a string does start with a double-quote, it must end with a closing
4831 double-quote, and any backslash characters other than those used for line
4832 continuation are interpreted as escape characters, as follows:
4834 "\\" single backslash
4836 "\r" carriage return
4838 "\"<octal digits> up to 3 octal digits specify one character
4839 "\x"<hex digits> up to 2 hexadecimal digits specify one character
4841 If a backslash is followed by some other character, including a double-quote
4842 character, that character replaces the pair.
4844 Quoting is necessary only if you want to make use of the backslash escapes to
4845 insert special characters, or if you need to specify a value with leading or
4846 trailing spaces. These cases are rare, so quoting is almost never needed in
4847 current versions of Exim. In versions of Exim before 3.14, quoting was required
4848 in order to continue lines, so you may come across older configuration files
4849 and examples that apparently quote unnecessarily.
4852 6.17 Expanded strings
4853 ---------------------
4855 Some strings in the configuration file are subjected to string expansion, by
4856 which means various parts of the string may be changed according to the
4857 circumstances (see chapter 11). The input syntax for such strings is as just
4858 described; in particular, the handling of backslashes in quoted strings is done
4859 as part of the input process, before expansion takes place. However, backslash
4860 is also an escape character for the expander, so any backslashes that are
4861 required for that reason must be doubled if they are within a quoted
4862 configuration string.
4865 6.18 User and group names
4866 -------------------------
4868 User and group names are specified as strings, using the syntax described
4869 above, but the strings are interpreted specially. A user or group name must
4870 either consist entirely of digits, or be a name that can be looked up using the
4871 getpwnam() or getgrnam() function, as appropriate.
4874 6.19 List construction
4875 ----------------------
4877 The data for some configuration options is a list of items, with colon as the
4878 default separator. Many of these options are shown with type "string list" in
4879 the descriptions later in this document. Others are listed as "domain list",
4880 "host list", "address list", or "local part list". Syntactically, they are all
4881 the same; however, those other than "string list" are subject to particular
4882 kinds of interpretation, as described in chapter 10.
4884 In all these cases, the entire list is treated as a single string as far as the
4885 input syntax is concerned. The trusted_users setting in section 6.16 above is
4886 an example. If a colon is actually needed in an item in a list, it must be
4887 entered as two colons. Leading and trailing white space on each item in a list
4888 is ignored. This makes it possible to include items that start with a colon,
4889 and in particular, certain forms of IPv6 address. For example, the list
4891 local_interfaces = 127.0.0.1 : ::::1
4893 contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
4895 Note: Although leading and trailing white space is ignored in individual list
4896 items, it is not ignored when parsing the list. The space after the first colon
4897 in the example above is necessary. If it were not there, the list would be
4898 interpreted as the two items 127.0.0.1:: and 1.
4901 6.20 Changing list separators
4902 -----------------------------
4904 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
4905 introduced to allow the separator character to be changed. If a list begins
4906 with a left angle bracket, followed by any punctuation character, that
4907 character is used instead of colon as the list separator. For example, the list
4908 above can be rewritten to use a semicolon separator like this:
4910 local_interfaces = <; 127.0.0.1 ; ::1
4912 This facility applies to all lists, with the exception of the list in
4913 log_file_path. It is recommended that the use of non-colon separators be
4914 confined to circumstances where they really are needed.
4916 It is also possible to use newline and other control characters (those with
4917 code values less than 32, plus DEL) as separators in lists. Such separators
4918 must be provided literally at the time the list is processed. For options that
4919 are string-expanded, you can write the separator using a normal escape
4920 sequence. This will be processed by the expander before the string is
4921 interpreted as a list. For example, if a newline-separated list of domains is
4922 generated by a lookup, you can process it directly by a line such as this:
4924 domains = <\n ${lookup mysql{.....}}
4926 This avoids having to change the list separator in such data. You are unlikely
4927 to want to use a control character as a separator in an option that is not
4928 expanded, because the value is literal text. However, it can be done by giving
4929 the value in quotes. For example:
4931 local_interfaces = "<\n 127.0.0.1 \n ::1"
4933 Unlike printing character separators, which can be included in list items by
4934 doubling, it is not possible to include a control character as data when it is
4935 set as the separator. Two such characters in succession are interpreted as
4936 enclosing an empty list item.
4939 6.21 Empty items in lists
4940 -------------------------
4942 An empty item at the end of a list is always ignored. In other words, trailing
4943 separator characters are ignored. Thus, the list in
4945 senders = user@domain :
4947 contains only a single item. If you want to include an empty string as one item
4948 in a list, it must not be the last item. For example, this list contains three
4949 items, the second of which is empty:
4951 senders = user1@domain : : user2@domain
4953 Note: There must be white space between the two colons, as otherwise they are
4954 interpreted as representing a single colon data character (and the list would
4955 then contain just one item). If you want to specify a list that contains just
4956 one, empty item, you can do it as in this example:
4960 In this case, the first item is empty, and the second is discarded because it
4961 is at the end of the list.
4964 6.22 Format of driver configurations
4965 ------------------------------------
4967 There are separate parts in the configuration for defining routers, transports,
4968 and authenticators. In each part, you are defining a number of driver
4969 instances, each with its own set of options. Each driver instance is defined by
4970 a sequence of lines like this:
4977 In the following example, the instance name is localuser, and it is followed by
4978 three options settings:
4983 transport = local_delivery
4985 For each driver instance, you specify which Exim code module it uses - by the
4986 setting of the driver option - and (optionally) some configuration settings.
4987 For example, in the case of transports, if you want a transport to deliver with
4988 SMTP you would use the smtp driver; if you want to deliver to a local file you
4989 would use the appendfile driver. Each of the drivers is described in detail in
4990 its own separate chapter later in this manual.
4992 You can have several routers, transports, or authenticators that are based on
4993 the same underlying driver (each must have a different instance name).
4995 The order in which routers are defined is important, because addresses are
4996 passed to individual routers one by one, in order. The order in which
4997 transports are defined does not matter at all. The order in which
4998 authenticators are defined is used only when Exim, as a client, is searching
4999 them to find one that matches an authentication mechanism offered by the
5002 Within a driver instance definition, there are two kinds of option: generic and
5003 private. The generic options are those that apply to all drivers of the same
5004 type (that is, all routers, all transports or all authenticators). The driver
5005 option is a generic option that must appear in every definition. The private
5006 options are special for each driver, and none need appear, because they all
5007 have default values.
5009 The options may appear in any order, except that the driver option must precede
5010 any private options, since these depend on the particular driver. For this
5011 reason, it is recommended that driver always be the first option.
5013 Driver instance names, which are used for reference in log entries and
5014 elsewhere, can be any sequence of letters, digits, and underscores (starting
5015 with a letter) and must be unique among drivers of the same type. A router and
5016 a transport (for example) can each have the same name, but no two router
5017 instances can have the same name. The name of a driver instance should not be
5018 confused with the name of the underlying driver module. For example, the
5019 configuration lines:
5024 create an instance of the smtp transport driver whose name is remote_smtp. The
5025 same driver code can be used more than once, with different instance names and
5026 different option settings each time. A second instance of the smtp transport,
5027 with different options, might be defined thus:
5032 command_timeout = 10s
5034 The names remote_smtp and special_smtp would be used to reference these
5035 transport instances from routers, and these names would appear in log lines.
5037 Comment lines may be present in the middle of driver specifications. The full
5038 list of option settings for any particular driver instance, including all the
5039 defaulted values, can be extracted by making use of the -bP command line
5044 ===============================================================================
5045 7. THE DEFAULT CONFIGURATION FILE
5047 The default configuration file supplied with Exim as src/configure.default is
5048 sufficient for a host with simple mail requirements. As an introduction to the
5049 way Exim is configured, this chapter "walks through" the default configuration,
5050 giving brief explanations of the settings. Detailed descriptions of the options
5051 are given in subsequent chapters. The default configuration file itself
5052 contains extensive comments about ways you might want to modify the initial
5053 settings. However, note that there are many options that are not mentioned at
5054 all in the default configuration.
5057 7.1 Main configuration settings
5058 -------------------------------
5060 The main (global) configuration option settings must always come first in the
5061 file. The first thing you'll see in the file, after some initial comments, is
5064 # primary_hostname =
5066 This is a commented-out setting of the primary_hostname option. Exim needs to
5067 know the official, fully qualified name of your host, and this is where you can
5068 specify it. However, in most cases you do not need to set this option. When it
5069 is unset, Exim uses the uname() system function to obtain the host name.
5071 The first three non-comment configuration lines are as follows:
5073 domainlist local_domains = @
5074 domainlist relay_to_domains =
5075 hostlist relay_from_hosts = 127.0.0.1
5077 These are not, in fact, option settings. They are definitions of two named
5078 domain lists and one named host list. Exim allows you to give names to lists of
5079 domains, hosts, and email addresses, in order to make it easier to manage the
5080 configuration file (see section 10.5).
5082 The first line defines a domain list called local_domains; this is used later
5083 in the configuration to identify domains that are to be delivered on the local
5086 There is just one item in this list, the string "@". This is a special form of
5087 entry which means "the name of the local host". Thus, if the local host is
5088 called a.host.example, mail to any.user@a.host.example is expected to be
5089 delivered locally. Because the local host's name is referenced indirectly, the
5090 same configuration file can be used on different hosts.
5092 The second line defines a domain list called relay_to_domains, but the list
5093 itself is empty. Later in the configuration we will come to the part that
5094 controls mail relaying through the local host; it allows relaying to any
5095 domains in this list. By default, therefore, no relaying on the basis of a mail
5096 domain is permitted.
5098 The third line defines a host list called relay_from_hosts. This list is used
5099 later in the configuration to permit relaying from any host or IP address that
5100 matches the list. The default contains just the IP address of the IPv4 loopback
5101 interface, which means that processes on the local host are able to submit mail
5102 for relaying by sending it over TCP/IP to that interface. No other hosts are
5103 permitted to submit messages for relaying.
5105 Just to be sure there's no misunderstanding: at this point in the configuration
5106 we aren't actually setting up any controls. We are just defining some domains
5107 and hosts that will be used in the controls that are specified later.
5109 The next two configuration lines are genuine option settings:
5111 acl_smtp_rcpt = acl_check_rcpt
5112 acl_smtp_data = acl_check_data
5114 These options specify Access Control Lists (ACLs) that are to be used during an
5115 incoming SMTP session for every recipient of a message (every RCPT command),
5116 and after the contents of the message have been received, respectively. The
5117 names of the lists are acl_check_rcpt and acl_check_data, and we will come to
5118 their definitions below, in the ACL section of the configuration. The RCPT ACL
5119 controls which recipients are accepted for an incoming message - if a
5120 configuration does not provide an ACL to check recipients, no SMTP mail can be
5121 accepted. The DATA ACL allows the contents of a message to be checked.
5123 Two commented-out option settings are next:
5125 # av_scanner = clamd:/tmp/clamd
5126 # spamd_address = 127.0.0.1 783
5128 These are example settings that can be used when Exim is compiled with the
5129 content-scanning extension. The first specifies the interface to the virus
5130 scanner, and the second specifies the interface to SpamAssassin. Further
5131 details are given in chapter 43.
5133 Three more commented-out option settings follow:
5135 # tls_advertise_hosts = *
5136 # tls_certificate = /etc/ssl/exim.crt
5137 # tls_privatekey = /etc/ssl/exim.pem
5139 These are example settings that can be used when Exim is compiled with support
5140 for TLS (aka SSL) as described in section 4.7. The first one specifies the list
5141 of clients that are allowed to use TLS when connecting to this server; in this
5142 case the wildcard means all clients. The other options specify where Exim
5143 should find its TLS certificate and private key, which together prove the
5144 server's identity to any clients that connect. More details are given in
5147 Another two commented-out option settings follow:
5149 # daemon_smtp_ports = 25 : 465 : 587
5150 # tls_on_connect_ports = 465
5152 These options provide better support for roaming users who wish to use this
5153 server for message submission. They are not much use unless you have turned on
5154 TLS (as described in the previous paragraph) and authentication (about which
5155 more in section 7.7). The usual SMTP port 25 is often blocked on end-user
5156 networks, so RFC 4409 specifies that message submission should use port 587
5157 instead. However some software (notably Microsoft Outlook) cannot be configured
5158 to use port 587 correctly, so these settings also enable the non-standard
5159 "smtps" (aka "ssmtp") port 465 (see section 13.4).
5161 Two more commented-out options settings follow:
5164 # qualify_recipient =
5166 The first of these specifies a domain that Exim uses when it constructs a
5167 complete email address from a local login name. This is often needed when Exim
5168 receives a message from a local process. If you do not set qualify_domain, the
5169 value of primary_hostname is used. If you set both of these options, you can
5170 have different qualification domains for sender and recipient addresses. If you
5171 set only the first one, its value is used in both cases.
5173 The following line must be uncommented if you want Exim to recognize addresses
5174 of the form user@[10.11.12.13] that is, with a "domain literal" (an IP address
5175 within square brackets) instead of a named domain.
5177 # allow_domain_literals
5179 The RFCs still require this form, but many people think that in the modern
5180 Internet it makes little sense to permit mail to be sent to specific hosts by
5181 quoting their IP addresses. This ancient format has been used by people who try
5182 to abuse hosts by using them for unwanted relaying. However, some people
5183 believe there are circumstances (for example, messages addressed to postmaster)
5184 where domain literals are still useful.
5186 The next configuration line is a kind of trigger guard:
5190 It specifies that no delivery must ever be run as the root user. The normal
5191 convention is to set up root as an alias for the system administrator. This
5192 setting is a guard against slips in the configuration. The list of users
5193 specified by never_users is not, however, the complete list; the build-time
5194 configuration in Local/Makefile has an option called FIXED_NEVER_USERS
5195 specifying a list that cannot be overridden. The contents of never_users are
5196 added to this list. By default FIXED_NEVER_USERS also specifies root.
5198 When a remote host connects to Exim in order to send mail, the only information
5199 Exim has about the host's identity is its IP address. The next configuration
5204 specifies that Exim should do a reverse DNS lookup on all incoming connections,
5205 in order to get a host name. This improves the quality of the logging
5206 information, but if you feel it is too expensive, you can remove it entirely,
5207 or restrict the lookup to hosts on "nearby" networks. Note that it is not
5208 always possible to find a host name from an IP address, because not all DNS
5209 reverse zones are maintained, and sometimes DNS servers are unreachable.
5211 The next two lines are concerned with ident callbacks, as defined by RFC 1413
5212 (hence their names):
5215 rfc1413_query_timeout = 0s
5217 These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
5218 Few hosts offer RFC1413 service these days; calls have to be terminated by a
5219 timeout and this needlessly delays the startup of an incoming SMTP connection.
5220 If you have hosts for which you trust RFC1413 and need this information, you
5223 This line enables an efficiency SMTP option. It is negociated by clients and
5224 not expected to cause problems but can be disabled if needed.
5228 When Exim receives messages over SMTP connections, it expects all addresses to
5229 be fully qualified with a domain, as required by the SMTP definition. However,
5230 if you are running a server to which simple clients submit messages, you may
5231 find that they send unqualified addresses. The two commented-out options:
5233 # sender_unqualified_hosts =
5234 # recipient_unqualified_hosts =
5236 show how you can specify hosts that are permitted to send unqualified sender
5237 and recipient addresses, respectively.
5239 The percent_hack_domains option is also commented out:
5241 # percent_hack_domains =
5243 It provides a list of domains for which the "percent hack" is to operate. This
5244 is an almost obsolete form of explicit email routing. If you do not know
5245 anything about it, you can safely ignore this topic.
5247 The last two settings in the main part of the default configuration are
5248 concerned with messages that have been "frozen" on Exim's queue. When a message
5249 is frozen, Exim no longer continues to try to deliver it. Freezing occurs when
5250 a bounce message encounters a permanent failure because the sender address of
5251 the original message that caused the bounce is invalid, so the bounce cannot be
5252 delivered. This is probably the most common case, but there are also other
5253 conditions that cause freezing, and frozen messages are not always bounce
5256 ignore_bounce_errors_after = 2d
5257 timeout_frozen_after = 7d
5259 The first of these options specifies that failing bounce messages are to be
5260 discarded after 2 days on the queue. The second specifies that any frozen
5261 message (whether a bounce message or not) is to be timed out (and discarded)
5262 after a week. In this configuration, the first setting ensures that no failing
5263 bounce message ever lasts a week.
5266 7.2 ACL configuration
5267 ---------------------
5269 In the default configuration, the ACL section follows the main configuration.
5270 It starts with the line
5274 and it contains the definitions of two ACLs, called acl_check_rcpt and
5275 acl_check_data, that were referenced in the settings of acl_smtp_rcpt and
5276 acl_smtp_data above.
5278 The first ACL is used for every RCPT command in an incoming SMTP message. Each
5279 RCPT command specifies one of the message's recipients. The ACL statements are
5280 considered in order, until the recipient address is either accepted or
5281 rejected. The RCPT command is then accepted or rejected, according to the
5282 result of the ACL processing.
5286 This line, consisting of a name terminated by a colon, marks the start of the
5291 This ACL statement accepts the recipient if the sending host matches the list.
5292 But what does that strange list mean? It doesn't actually contain any host
5293 names or IP addresses. The presence of the colon puts an empty item in the
5294 list; Exim matches this only if the incoming message did not come from a remote
5295 host, because in that case, the remote hostname is empty. The colon is
5296 important. Without it, the list itself is empty, and can never match anything.
5298 What this statement is doing is to accept unconditionally all recipients in
5299 messages that are submitted by SMTP from local processes using the standard
5300 input and output (that is, not using TCP/IP). A number of MUAs operate in this
5303 deny message = Restricted characters in address
5304 domains = +local_domains
5305 local_parts = ^[.] : ^.*[@%!/|]
5307 deny message = Restricted characters in address
5308 domains = !+local_domains
5309 local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
5311 These statements are concerned with local parts that contain any of the
5312 characters "@", "%", "!", "/", "|", or dots in unusual places. Although these
5313 characters are entirely legal in local parts (in the case of "@" and leading
5314 dots, only if correctly quoted), they do not commonly occur in Internet mail
5317 The first three have in the past been associated with explicitly routed
5318 addresses (percent is still sometimes used - see the percent_hack_domains
5319 option). Addresses containing these characters are regularly tried by spammers
5320 in an attempt to bypass relaying restrictions, and also by open relay testing
5321 programs. Unless you really need them it is safest to reject these characters
5322 at this early stage. This configuration is heavy-handed in rejecting these
5323 characters for all messages it accepts from remote hosts. This is a deliberate
5324 policy of being as safe as possible.
5326 The first rule above is stricter, and is applied to messages that are addressed
5327 to one of the local domains handled by this host. This is implemented by the
5328 first condition, which restricts it to domains that are listed in the
5329 local_domains domain list. The "+" character is used to indicate a reference to
5330 a named list. In this configuration, there is just one domain in local_domains,
5331 but in general there may be many.
5333 The second condition on the first statement uses two regular expressions to
5334 block local parts that begin with a dot or contain "@", "%", "!", "/", or "|".
5335 If you have local accounts that include these characters, you will have to
5338 Empty components (two dots in a row) are not valid in RFC 2822, but Exim allows
5339 them because they have been encountered in practice. (Consider the common
5340 convention of local parts constructed as "
5341 first-initial.second-initial.family-name" when applied to someone like the
5342 author of Exim, who has no second initial.) However, a local part starting with
5343 a dot or containing "/../" can cause trouble if it is used as part of a file
5344 name (for example, for a mailing list). This is also true for local parts that
5345 contain slashes. A pipe symbol can also be troublesome if the local part is
5346 incorporated unthinkingly into a shell command line.
5348 The second rule above applies to all other domains, and is less strict. This
5349 allows your own users to send outgoing messages to sites that use slashes and
5350 vertical bars in their local parts. It blocks local parts that begin with a
5351 dot, slash, or vertical bar, but allows these characters within the local part.
5352 However, the sequence "/../" is barred. The use of "@", "%", and "!" is
5353 blocked, as before. The motivation here is to prevent your users (or your
5354 users' viruses) from mounting certain kinds of attack on remote sites.
5356 accept local_parts = postmaster
5357 domains = +local_domains
5359 This statement, which has two conditions, accepts an incoming address if the
5360 local part is postmaster and the domain is one of those listed in the
5361 local_domains domain list. The "+" character is used to indicate a reference to
5362 a named list. In this configuration, there is just one domain in local_domains,
5363 but in general there may be many.
5365 The presence of this statement means that mail to postmaster is never blocked
5366 by any of the subsequent tests. This can be helpful while sorting out problems
5367 in cases where the subsequent tests are incorrectly denying access.
5369 require verify = sender
5371 This statement requires the sender address to be verified before any subsequent
5372 ACL statement can be used. If verification fails, the incoming recipient
5373 address is refused. Verification consists of trying to route the address, to
5374 see if a bounce message could be delivered to it. In the case of remote
5375 addresses, basic verification checks only the domain, but callouts can be used
5376 for more verification if required. Section 42.44 discusses the details of
5377 address verification.
5379 accept hosts = +relay_from_hosts
5380 control = submission
5382 This statement accepts the address if the message is coming from one of the
5383 hosts that are defined as being allowed to relay through this host. Recipient
5384 verification is omitted here, because in many cases the clients are dumb MUAs
5385 that do not cope well with SMTP error responses. For the same reason, the
5386 second line specifies "submission mode" for messages that are accepted. This is
5387 described in detail in section 46.1; it causes Exim to fix messages that are
5388 deficient in some way, for example, because they lack a Date: header line. If
5389 you are actually relaying out from MTAs, you should probably add recipient
5390 verification here, and disable submission mode.
5392 accept authenticated = *
5393 control = submission
5395 This statement accepts the address if the client host has authenticated itself.
5396 Submission mode is again specified, on the grounds that such messages are most
5397 likely to come from MUAs. The default configuration does not define any
5398 authenticators, though it does include some nearly complete commented-out
5399 examples described in 7.7. This means that no client can in fact authenticate
5400 until you complete the authenticator definitions.
5402 require message = relay not permitted
5403 domains = +local_domains : +relay_to_domains
5405 This statement rejects the address if its domain is neither a local domain nor
5406 one of the domains for which this host is a relay.
5408 require verify = recipient
5410 This statement requires the recipient address to be verified; if verification
5411 fails, the address is rejected.
5413 # deny message = rejected because $sender_host_address \
5414 # is in a black list at $dnslist_domain\n\
5416 # dnslists = black.list.example
5418 # warn dnslists = black.list.example
5419 # add_header = X-Warning: $sender_host_address is in \
5420 # a black list at $dnslist_domain
5421 # log_message = found in $dnslist_domain
5423 These commented-out lines are examples of how you could configure Exim to check
5424 sending hosts against a DNS black list. The first statement rejects messages
5425 from blacklisted hosts, whereas the second just inserts a warning header line.
5427 # require verify = csa
5429 This commented-out line is an example of how you could turn on client SMTP
5430 authorization (CSA) checking. Such checks do DNS lookups for special SRV
5435 The final statement in the first ACL unconditionally accepts any recipient
5436 address that has successfully passed all the previous tests.
5440 This line marks the start of the second ACL, and names it. Most of the contents
5441 of this ACL are commented out:
5444 # message = This message contains a virus \
5447 These lines are examples of how to arrange for messages to be scanned for
5448 viruses when Exim has been compiled with the content-scanning extension, and a
5449 suitable virus scanner is installed. If the message is found to contain a
5450 virus, it is rejected with the given custom error message.
5452 # warn spam = nobody
5453 # message = X-Spam_score: $spam_score\n\
5454 # X-Spam_score_int: $spam_score_int\n\
5455 # X-Spam_bar: $spam_bar\n\
5456 # X-Spam_report: $spam_report
5458 These lines are an example of how to arrange for messages to be scanned by
5459 SpamAssassin when Exim has been compiled with the content-scanning extension,
5460 and SpamAssassin has been installed. The SpamAssassin check is run with
5461 "nobody" as its user parameter, and the results are added to the message as a
5462 series of extra header line. In this case, the message is not rejected,
5463 whatever the spam score.
5467 This final line in the DATA ACL accepts the message unconditionally.
5470 7.3 Router configuration
5471 ------------------------
5473 The router configuration comes next in the default configuration, introduced by
5478 Routers are the modules in Exim that make decisions about where to send
5479 messages. An address is passed to each router in turn, until it is either
5480 accepted, or failed. This means that the order in which you define the routers
5481 matters. Each router is fully described in its own chapter later in this
5482 manual. Here we give only brief overviews.
5485 # driver = ipliteral
5486 # domains = !+local_domains
5487 # transport = remote_smtp
5489 This router is commented out because the majority of sites do not want to
5490 support domain literal addresses (those of the form user@[10.9.8.7]). If you
5491 uncomment this router, you also need to uncomment the setting of
5492 allow_domain_literals in the main part of the configuration.
5496 domains = ! +local_domains
5497 transport = remote_smtp
5498 ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
5501 The first uncommented router handles addresses that do not involve any local
5502 domains. This is specified by the line
5504 domains = ! +local_domains
5506 The domains option lists the domains to which this router applies, but the
5507 exclamation mark is a negation sign, so the router is used only for domains
5508 that are not in the domain list called local_domains (which was defined at the
5509 start of the configuration). The plus sign before local_domains indicates that
5510 it is referring to a named list. Addresses in other domains are passed on to
5511 the following routers.
5513 The name of the router driver is dnslookup, and is specified by the driver
5514 option. Do not be confused by the fact that the name of this router instance is
5515 the same as the name of the driver. The instance name is arbitrary, but the
5516 name set in the driver option must be one of the driver modules that is in the
5519 The dnslookup router routes addresses by looking up their domains in the DNS in
5520 order to obtain a list of hosts to which the address is routed. If the router
5521 succeeds, the address is queued for the remote_smtp transport, as specified by
5522 the transport option. If the router does not find the domain in the DNS, no
5523 further routers are tried because of the no_more setting, so the address fails
5526 The ignore_target_hosts option specifies a list of IP addresses that are to be
5527 entirely ignored. This option is present because a number of cases have been
5528 encountered where MX records in the DNS point to host names whose IP addresses
5529 are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). Completely ignoring
5530 these IP addresses causes Exim to fail to route the email address, so it
5531 bounces. Otherwise, Exim would log a routing problem, and continue to try to
5532 deliver the message periodically until the address timed out.
5538 data = ${lookup{$local_part}lsearch{/etc/aliases}}
5540 file_transport = address_file
5541 pipe_transport = address_pipe
5543 Control reaches this and subsequent routers only for addresses in the local
5544 domains. This router checks to see whether the local part is defined as an
5545 alias in the /etc/aliases file, and if so, redirects it according to the data
5546 that it looks up from that file. If no data is found for the local part, the
5547 value of the data option is empty, causing the address to be passed to the next
5550 /etc/aliases is a conventional name for the system aliases file that is often
5551 used. That is why it is referenced by from the default configuration file.
5552 However, you can change this by setting SYSTEM_ALIASES_FILE in Local/Makefile
5553 before building Exim.
5558 # local_part_suffix = +* : -*
5559 # local_part_suffix_optional
5560 file = $home/.forward
5565 file_transport = address_file
5566 pipe_transport = address_pipe
5567 reply_transport = address_reply
5569 This is the most complicated router in the default configuration. It is another
5570 redirection router, but this time it is looking for forwarding data set up by
5571 individual users. The check_local_user setting specifies a check that the local
5572 part of the address is the login name of a local user. If it is not, the router
5573 is skipped. The two commented options that follow check_local_user, namely:
5575 # local_part_suffix = +* : -*
5576 # local_part_suffix_optional
5578 show how you can specify the recognition of local part suffixes. If the first
5579 is uncommented, a suffix beginning with either a plus or a minus sign, followed
5580 by any sequence of characters, is removed from the local part and placed in the
5581 variable $local_part_suffix. The second suffix option specifies that the
5582 presence of a suffix in the local part is optional. When a suffix is present,
5583 the check for a local login uses the local part with the suffix removed.
5585 When a local user account is found, the file called .forward in the user's home
5586 directory is consulted. If it does not exist, or is empty, the router declines.
5587 Otherwise, the contents of .forward are interpreted as redirection data (see
5588 chapter 22 for more details).
5590 Traditional .forward files contain just a list of addresses, pipes, or files.
5591 Exim supports this by default. However, if allow_filter is set (it is commented
5592 out by default), the contents of the file are interpreted as a set of Exim or
5593 Sieve filtering instructions, provided the file begins with "#Exim filter" or "
5594 #Sieve filter", respectively. User filtering is discussed in the separate
5595 document entitled Exim's interfaces to mail filtering.
5597 The no_verify and no_expn options mean that this router is skipped when
5598 verifying addresses, or when running as a consequence of an SMTP EXPN command.
5599 There are two reasons for doing this:
5601 1. Whether or not a local user has a .forward file is not really relevant when
5602 checking an address for validity; it makes sense not to waste resources
5603 doing unnecessary work.
5605 2. More importantly, when Exim is verifying addresses or handling an EXPN
5606 command during an SMTP session, it is running as the Exim user, not as
5607 root. The group is the Exim group, and no additional groups are set up. It
5608 may therefore not be possible for Exim to read users' .forward files at
5611 The setting of check_ancestor prevents the router from generating a new address
5612 that is the same as any previous address that was redirected. (This works round
5613 a problem concerning a bad interaction between aliasing and forwarding - see
5616 The final three option settings specify the transports that are to be used when
5617 forwarding generates a direct delivery to a file, or to a pipe, or sets up an
5618 auto-reply, respectively. For example, if a .forward file contains
5620 a.nother@elsewhere.example, /home/spqr/archive
5622 the delivery to /home/spqr/archive is done by running the address_file
5628 # local_part_suffix = +* : -*
5629 # local_part_suffix_optional
5630 transport = local_delivery
5632 The final router sets up delivery into local mailboxes, provided that the local
5633 part is the name of a local login, by accepting the address and assigning it to
5634 the local_delivery transport. Otherwise, we have reached the end of the
5635 routers, so the address is bounced. The commented suffix settings fulfil the
5636 same purpose as they do for the userforward router.
5639 7.4 Transport configuration
5640 ---------------------------
5642 Transports define mechanisms for actually delivering messages. They operate
5643 only when referenced from routers, so the order in which they are defined does
5644 not matter. The transports section of the configuration starts with
5648 One remote transport and four local transports are defined.
5654 This transport is used for delivering messages over SMTP connections. The list
5655 of remote hosts comes from the router. The hosts_try_prdr option enables an
5656 efficiency SMTP option. It is negotiated between client and server and not
5657 expected to cause problems but can be disabled if needed. All other options are
5662 file = /var/mail/$local_part
5669 This appendfile transport is used for local delivery to user mailboxes in
5670 traditional BSD mailbox format. By default it runs under the uid and gid of the
5671 local user, which requires the sticky bit to be set on the /var/mail directory.
5672 Some systems use the alternative approach of running mail deliveries under a
5673 particular group instead of using the sticky bit. The commented options show
5674 how this can be done.
5676 Exim adds three headers to the message as it delivers it: Delivery-date:,
5677 Envelope-to: and Return-path:. This action is requested by the three
5678 similarly-named options above.
5684 This transport is used for handling deliveries to pipes that are generated by
5685 redirection (aliasing or users' .forward files). The return_output option
5686 specifies that any output generated by the pipe is to be returned to the
5695 This transport is used for handling deliveries to files that are generated by
5696 redirection. The name of the file is not specified in this instance of
5697 appendfile, because it comes from the redirect router.
5702 This transport is used for handling automatic replies generated by users'
5706 7.5 Default retry rule
5707 ----------------------
5709 The retry section of the configuration file contains rules which affect the way
5710 Exim retries deliveries that cannot be completed at the first attempt. It is
5711 introduced by the line
5715 In the default configuration, there is just one rule, which applies to all
5718 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
5720 This causes any temporarily failing address to be retried every 15 minutes for
5721 2 hours, then at intervals starting at one hour and increasing by a factor of
5722 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
5723 is not delivered after 4 days of temporary failure, it is bounced.
5725 If the retry section is removed from the configuration, or is empty (that is,
5726 if no retry rules are defined), Exim will not retry deliveries. This turns
5727 temporary errors into permanent errors.
5730 7.6 Rewriting configuration
5731 ---------------------------
5733 The rewriting section of the configuration, introduced by
5737 contains rules for rewriting addresses in messages as they arrive. There are no
5738 rewriting rules in the default configuration file.
5741 7.7 Authenticators configuration
5742 --------------------------------
5744 The authenticators section of the configuration, introduced by
5746 begin authenticators
5748 defines mechanisms for the use of the SMTP AUTH command. The default
5749 configuration file contains two commented-out example authenticators which
5750 support plaintext username/password authentication using the standard PLAIN
5751 mechanism and the traditional but non-standard LOGIN mechanism, with Exim
5752 acting as the server. PLAIN and LOGIN are enough to support most MUA software.
5754 The example PLAIN authenticator looks like this:
5757 # driver = plaintext
5758 # server_set_id = $auth2
5759 # server_prompts = :
5760 # server_condition = Authentication is not yet configured
5761 # server_advertise_condition = ${if def:tls_in_cipher }
5763 And the example LOGIN authenticator looks like this:
5766 # driver = plaintext
5767 # server_set_id = $auth1
5768 # server_prompts = <| Username: | Password:
5769 # server_condition = Authentication is not yet configured
5770 # server_advertise_condition = ${if def:tls_in_cipher }
5772 The server_set_id option makes Exim remember the authenticated username in
5773 $authenticated_id, which can be used later in ACLs or routers. The
5774 server_prompts option configures the plaintext authenticator so that it
5775 implements the details of the specific authentication mechanism, i.e. PLAIN or
5776 LOGIN. The server_advertise_condition setting controls when Exim offers
5777 authentication to clients; in the examples, this is only when TLS or SSL has
5778 been started, so to enable the authenticators you also need to add support for
5779 TLS as described in section 7.1.
5781 The server_condition setting defines how to verify that the username and
5782 password are correct. In the examples it just produces an error message. To
5783 make the authenticators work, you can use a string expansion expression like
5784 one of the examples in chapter 34.
5786 Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
5787 usercode and password are in different positions. Chapter 34 covers both.
5791 ===============================================================================
5792 8. REGULAR EXPRESSIONS
5794 Exim supports the use of regular expressions in many of its options. It uses
5795 the PCRE regular expression library; this provides regular expression matching
5796 that is compatible with Perl 5. The syntax and semantics of regular expressions
5797 is discussed in many Perl reference books, and also in Jeffrey Friedl's
5798 Mastering Regular Expressions, which is published by O'Reilly (see http://
5799 www.oreilly.com/catalog/regex2/).
5801 The documentation for the syntax and semantics of the regular expressions that
5802 are supported by PCRE is included in the PCRE distribution, and no further
5803 description is included here. The PCRE functions are called from Exim using the
5804 default option settings (that is, with no PCRE options set), except that the
5805 PCRE_CASELESS option is set when the matching is required to be
5808 In most cases, when a regular expression is required in an Exim configuration,
5809 it has to start with a circumflex, in order to distinguish it from plain text
5810 or an "ends with" wildcard. In this example of a configuration setting, the
5811 second item in the colon-separated list is a regular expression.
5813 domains = a.b.c : ^\\d{3} : *.y.z : ...
5815 The doubling of the backslash is required because of string expansion that
5816 precedes interpretation - see section 11.1 for more discussion of this issue,
5817 and a way of avoiding the need for doubling backslashes. The regular expression
5818 that is eventually used in this example contains just one backslash. The
5819 circumflex is included in the regular expression, and has the normal effect of
5820 "anchoring" it to the start of the string that is being matched.
5822 There are, however, two cases where a circumflex is not required for the
5823 recognition of a regular expression: these are the match condition in a string
5824 expansion, and the matches condition in an Exim filter file. In these cases,
5825 the relevant string is always treated as a regular expression; if it does not
5826 start with a circumflex, the expression is not anchored, and can match anywhere
5827 in the subject string.
5829 In all cases, if you want a regular expression to match at the end of a string,
5830 you must code the $ metacharacter to indicate this. For example:
5832 domains = ^\\d{3}\\.example
5834 matches the domain 123.example, but it also matches 123.example.com. You need
5837 domains = ^\\d{3}\\.example\$
5839 if you want example to be the top-level domain. The backslash before the $ is
5840 needed because string expansion also interprets dollar characters.
5844 ===============================================================================
5845 9. FILE AND DATABASE LOOKUPS
5847 Exim can be configured to look up data in files or databases as it processes
5848 messages. Two different kinds of syntax are used:
5850 1. A string that is to be expanded may contain explicit lookup requests. These
5851 cause parts of the string to be replaced by data that is obtained from the
5852 lookup. Lookups of this type are conditional expansion items. Different
5853 results can be defined for the cases of lookup success and failure. See
5854 chapter 11, where string expansions are described in detail.
5856 2. Lists of domains, hosts, and email addresses can contain lookup requests as
5857 a way of avoiding excessively long linear lists. In this case, the data
5858 that is returned by the lookup is often (but not always) discarded; whether
5859 the lookup succeeds or fails is what really counts. These kinds of list are
5860 described in chapter 10.
5862 String expansions, lists, and lookups interact with each other in such a way
5863 that there is no order in which to describe any one of them that does not
5864 involve references to the others. Each of these three chapters makes more sense
5865 if you have read the other two first. If you are reading this for the first
5866 time, be aware that some of it will make a lot more sense after you have read
5870 9.1 Examples of different lookup syntax
5871 ---------------------------------------
5873 It is easy to confuse the two different kinds of lookup, especially as the
5874 lists that may contain the second kind are always expanded before being
5875 processed as lists. Therefore, they may also contain lookups of the first kind.
5876 Be careful to distinguish between the following two examples:
5878 domains = ${lookup{$sender_host_address}lsearch{/some/file}}
5879 domains = lsearch;/some/file
5881 The first uses a string expansion, the result of which must be a domain list.
5882 No strings have been specified for a successful or a failing lookup; the
5883 defaults in this case are the looked-up data and an empty string, respectively.
5884 The expansion takes place before the string is processed as a list, and the
5885 file that is searched could contain lines like this:
5887 192.168.3.4: domain1:domain2:...
5888 192.168.1.9: domain3:domain4:...
5890 When the lookup succeeds, the result of the expansion is a list of domains (and
5891 possibly other types of item that are allowed in domain lists).
5893 In the second example, the lookup is a single item in a domain list. It causes
5894 Exim to use a lookup to see if the domain that is being processed can be found
5895 in the file. The file could contains lines like this:
5900 Any data that follows the keys is not relevant when checking that the domain
5901 matches the list item.
5903 It is possible, though no doubt confusing, to use both kinds of lookup at once.
5904 Consider a file containing lines like this:
5906 192.168.5.6: lsearch;/another/file
5908 If the value of $sender_host_address is 192.168.5.6, expansion of the first
5909 domains setting above generates the second setting, which therefore causes a
5910 second lookup to occur.
5912 The rest of this chapter describes the different lookup types that are
5913 available. Any of them can be used in any part of the configuration where a
5914 lookup is permitted.
5920 Two different types of data lookup are implemented:
5922 * The single-key type requires the specification of a file in which to look,
5923 and a single key to search for. The key must be a non-empty string for the
5924 lookup to succeed. The lookup type determines how the file is searched.
5926 * The query-style type accepts a generalized database query. No particular
5927 key value is assumed by Exim for query-style lookups. You can use whichever
5928 Exim variables you need to construct the database query.
5930 The code for each lookup type is in a separate source file that is included in
5931 the binary of Exim only if the corresponding compile-time option is set. The
5932 default settings in src/EDITME are:
5937 which means that only linear searching and DBM lookups are included by default.
5938 For some types of lookup (e.g. SQL databases), you need to install appropriate
5939 libraries and header files before building Exim.
5942 9.3 Single-key lookup types
5943 ---------------------------
5945 The following single-key lookup types are implemented:
5947 * cdb: The given file is searched as a Constant DataBase file, using the key
5948 string without a terminating binary zero. The cdb format is designed for
5949 indexed files that are read frequently and never updated, except by total
5950 re-creation. As such, it is particularly suitable for large files
5951 containing aliases or other indexed data referenced by an MTA. Information
5952 about cdb can be found in several places:
5954 http://www.pobox.com/~djb/cdb.html
5955 ftp://ftp.corpit.ru/pub/tinycdb/
5956 http://packages.debian.org/stable/utils/freecdb.html
5958 A cdb distribution is not needed in order to build Exim with cdb support,
5959 because the code for reading cdb files is included directly in Exim itself.
5960 However, no means of building or testing cdb files is provided with Exim,
5961 so you need to obtain a cdb distribution in order to do this.
5963 * dbm: Calls to DBM library functions are used to extract data from the given
5964 DBM file by looking up the record with the given key. A terminating binary
5965 zero is included in the key that is passed to the DBM library. See section
5966 4.4 for a discussion of DBM libraries.
5968 For all versions of Berkeley DB, Exim uses the DB_HASH style of database
5969 when building DBM files using the exim_dbmbuild utility. However, when
5970 using Berkeley DB versions 3 or 4, it opens existing databases for reading
5971 with the DB_UNKNOWN option. This enables it to handle any of the types of
5972 database that the library supports, and can be useful for accessing DBM
5973 files created by other applications. (For earlier DB versions, DB_HASH is
5976 * dbmjz: This is the same as dbm, except that the lookup key is interpreted
5977 as an Exim list; the elements of the list are joined together with ASCII
5978 NUL characters to form the lookup key. An example usage would be to
5979 authenticate incoming SMTP calls using the passwords from Cyrus SASL's /etc
5980 /sasldb2 file with the gsasl authenticator or Exim's own cram_md5
5983 * dbmnz: This is the same as dbm, except that a terminating binary zero is
5984 not included in the key that is passed to the DBM library. You may need
5985 this if you want to look up data in files that are created by or shared
5986 with some other application that does not use terminating zeros. For
5987 example, you need to use dbmnz rather than dbm if you want to authenticate
5988 incoming SMTP calls using the passwords from Courier's /etc/
5989 userdbshadow.dat file. Exim's utility program for creating DBM files (
5990 exim_dbmbuild) includes the zeros by default, but has an option to omit
5991 them (see section 52.9).
5993 * dsearch: The given file must be a directory; this is searched for an entry
5994 whose name is the key by calling the lstat() function. The key may not
5995 contain any forward slash characters. If lstat() succeeds, the result of
5996 the lookup is the name of the entry, which may be a file, directory,
5997 symbolic link, or any other kind of directory entry. An example of how this
5998 lookup can be used to support virtual domains is given in section 49.7.
6000 * iplsearch: The given file is a text file containing keys and data. A key is
6001 terminated by a colon or white space or the end of the line. The keys in
6002 the file must be IP addresses, or IP addresses with CIDR masks. Keys that
6003 involve IPv6 addresses must be enclosed in quotes to prevent the first
6004 internal colon being interpreted as a key terminator. For example:
6006 1.2.3.4: data for 1.2.3.4
6007 192.168.0.0/16: data for 192.168.0.0/16
6008 "abcd::cdab": data for abcd::cdab
6009 "abcd:abcd::/32" data for abcd:abcd::/32
6011 The key for an iplsearch lookup must be an IP address (without a mask). The
6012 file is searched linearly, using the CIDR masks where present, until a
6013 matching key is found. The first key that matches is used; there is no
6014 attempt to find a "best" match. Apart from the way the keys are matched,
6015 the processing for iplsearch is the same as for lsearch.
6017 Warning 1: Unlike most other single-key lookup types, a file of data for
6018 iplsearch can not be turned into a DBM or cdb file, because those lookup
6019 types support only literal keys.
6021 Warning 2: In a host list, you must always use net-iplsearch so that the
6022 implicit key is the host's IP address rather than its name (see section
6025 * lsearch: The given file is a text file that is searched linearly for a line
6026 beginning with the search key, terminated by a colon or white space or the
6027 end of the line. The search is case-insensitive; that is, upper and lower
6028 case letters are treated as the same. The first occurrence of the key that
6029 is found in the file is used.
6031 White space between the key and the colon is permitted. The remainder of
6032 the line, with leading and trailing white space removed, is the data. This
6033 can be continued onto subsequent lines by starting them with any amount of
6034 white space, but only a single space character is included in the data at
6035 such a junction. If the data begins with a colon, the key must be
6036 terminated by a colon, for example:
6040 Empty lines and lines beginning with # are ignored, even if they occur in
6041 the middle of an item. This is the traditional textual format of alias
6042 files. Note that the keys in an lsearch file are literal strings. There is
6043 no wildcarding of any kind.
6045 In most lsearch files, keys are not required to contain colons or #
6046 characters, or white space. However, if you need this feature, it is
6047 available. If a key begins with a doublequote character, it is terminated
6048 only by a matching quote (or end of line), and the normal escaping rules
6049 apply to its contents (see section 6.16). An optional colon is permitted
6050 after quoted keys (exactly as for unquoted keys). There is no special
6051 handling of quotes for the data part of an lsearch line.
6053 * nis: The given file is the name of a NIS map, and a NIS lookup is done with
6054 the given key, without a terminating binary zero. There is a variant called
6055 nis0 which does include the terminating binary zero in the key. This is
6056 reportedly needed for Sun-style alias files. Exim does not recognize NIS
6057 aliases; the full map names must be used.
6059 * wildlsearch or nwildlsearch: These search a file linearly, like lsearch,
6060 but instead of being interpreted as a literal string, each key in the file
6061 may be wildcarded. The difference between these two lookup types is that
6062 for wildlsearch, each key in the file is string-expanded before being used,
6063 whereas for nwildlsearch, no expansion takes place.
6065 Like lsearch, the testing is done case-insensitively. However, keys in the
6066 file that are regular expressions can be made case-sensitive by the use of
6067 "(-i)" within the pattern. The following forms of wildcard are recognized:
6069 1. The string may begin with an asterisk to mean "ends with". For example:
6071 *.a.b.c data for anything.a.b.c
6072 *fish data for anythingfish
6074 2. The string may begin with a circumflex to indicate a regular
6075 expression. For example, for wildlsearch:
6077 ^\N\d+\.a\.b\N data for <digits>.a.b
6079 Note the use of "\N" to disable expansion of the contents of the
6080 regular expression. If you are using nwildlsearch, where the keys are
6081 not string-expanded, the equivalent entry is:
6083 ^\d+\.a\.b data for <digits>.a.b
6085 The case-insensitive flag is set at the start of compiling the regular
6086 expression, but it can be turned off by using "(-i)" at an appropriate
6087 point. For example, to make the entire pattern case-sensitive:
6089 ^(?-i)\d+\.a\.b data for <digits>.a.b
6091 If the regular expression contains white space or colon characters, you
6092 must either quote it (see lsearch above), or represent these characters
6093 in other ways. For example, "\s" can be used for white space and "\x3A"
6094 for a colon. This may be easier than quoting, because if you quote, you
6095 have to escape all the backslashes inside the quotes.
6097 Note: It is not possible to capture substrings in a regular expression
6098 match for later use, because the results of all lookups are cached. If
6099 a lookup is repeated, the result is taken from the cache, and no actual
6100 pattern matching takes place. The values of all the numeric variables
6101 are unset after a (n)wildlsearch match.
6103 3. Although I cannot see it being of much use, the general matching
6104 function that is used to implement (n)wildlsearch means that the string
6105 may begin with a lookup name terminated by a semicolon, and followed by
6106 lookup data. For example:
6108 cdb;/some/file data for keys that match the file
6110 The data that is obtained from the nested lookup is discarded.
6112 Keys that do not match any of these patterns are interpreted literally. The
6113 continuation rules for the data are the same as for lsearch, and keys may
6114 be followed by optional colons.
6116 Warning: Unlike most other single-key lookup types, a file of data for (n)
6117 wildlsearch can not be turned into a DBM or cdb file, because those lookup
6118 types support only literal keys.
6121 9.4 Query-style lookup types
6122 ----------------------------
6124 The supported query-style lookup types are listed below. Further details about
6125 many of them are given in later sections.
6127 * dnsdb: This does a DNS search for one or more records whose domain names
6128 are given in the supplied query. The resulting data is the contents of the
6129 records. See section 9.10.
6131 * ibase: This does a lookup in an InterBase database.
6133 * ldap: This does an LDAP lookup using a query in the form of a URL, and
6134 returns attributes from a single entry. There is a variant called ldapm
6135 that permits values from multiple entries to be returned. A third variant
6136 called ldapdn returns the Distinguished Name of a single entry instead of
6137 any attribute values. See section 9.13.
6139 * mysql: The format of the query is an SQL statement that is passed to a
6140 MySQL database. See section 9.20.
6142 * nisplus: This does a NIS+ lookup using a query that can specify the name of
6143 the field to be returned. See section 9.19.
6145 * oracle: The format of the query is an SQL statement that is passed to an
6146 Oracle database. See section 9.20.
6148 * passwd is a query-style lookup with queries that are just user names. The
6149 lookup calls getpwnam() to interrogate the system password data, and on
6150 success, the result string is the same as you would get from an lsearch
6151 lookup on a traditional /etc/passwd file, though with "*" for the password
6154 *:42:42:King Rat:/home/kr:/bin/bash
6156 * pgsql: The format of the query is an SQL statement that is passed to a
6157 PostgreSQL database. See section 9.20.
6159 * sqlite: The format of the query is a file name followed by an SQL statement
6160 that is passed to an SQLite database. See section 9.25.
6162 * testdb: This is a lookup type that is used for testing Exim. It is not
6163 likely to be useful in normal operation.
6165 * whoson: Whoson (http://whoson.sourceforge.net) is a protocol that allows a
6166 server to check whether a particular (dynamically allocated) IP address is
6167 currently allocated to a known (trusted) user and, optionally, to obtain
6168 the identity of the said user. For SMTP servers, Whoson was popular at one
6169 time for "POP before SMTP" authentication, but that approach has been
6170 superseded by SMTP authentication. In Exim, Whoson can be used to implement
6171 "POP before SMTP" checking using ACL statements such as
6173 require condition = \
6174 ${lookup whoson {$sender_host_address}{yes}{no}}
6176 The query consists of a single IP address. The value returned is the name
6177 of the authenticated user, which is stored in the variable $value. However,
6178 in this example, the data in $value is not used; the result of the lookup
6179 is one of the fixed strings "yes" or "no".
6182 9.5 Temporary errors in lookups
6183 -------------------------------
6185 Lookup functions can return temporary error codes if the lookup cannot be
6186 completed. For example, an SQL or LDAP database might be unavailable. For this
6187 reason, it is not advisable to use a lookup that might do this for critical
6188 options such as a list of local domains.
6190 When a lookup cannot be completed in a router or transport, delivery of the
6191 message (to the relevant address) is deferred, as for any other temporary
6192 error. In other circumstances Exim may assume the lookup has failed, or may
6196 9.6 Default values in single-key lookups
6197 ----------------------------------------
6199 In this context, a "default value" is a value specified by the administrator
6200 that is to be used if a lookup fails.
6202 Note: This section applies only to single-key lookups. For query-style lookups,
6203 the facilities of the query language must be used. An attempt to specify a
6204 default for a query-style lookup provokes an error.
6206 If "*" is added to a single-key lookup type (for example, lsearch*) and the
6207 initial lookup fails, the key "*" is looked up in the file to provide a default
6208 value. See also the section on partial matching below.
6210 Alternatively, if "*@" is added to a single-key lookup type (for example dbm*@)
6211 then, if the initial lookup fails and the key contains an @ character, a second
6212 lookup is done with everything before the last @ replaced by *. This makes it
6213 possible to provide per-domain defaults in alias files that include the domains
6214 in the keys. If the second lookup fails (or doesn't take place because there is
6215 no @ in the key), "*" is looked up. For example, a redirect router might
6218 data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}}
6220 Suppose the address that is being processed is jane@eyre.example. Exim looks up
6221 these keys, in this order:
6227 The data is taken from whichever key it finds first. Note: In an lsearch file,
6228 this does not mean the first of these keys in the file. A complete scan is done
6229 for each key, and only if it is not found at all does Exim move on to try the
6233 9.7 Partial matching in single-key lookups
6234 ------------------------------------------
6236 The normal operation of a single-key lookup is to search the file for an exact
6237 match with the given key. However, in a number of situations where domains are
6238 being looked up, it is useful to be able to do partial matching. In this case,
6239 information in the file that has a key starting with "*." is matched by any
6240 domain that ends with the components that follow the full stop. For example, if
6241 a key in a DBM file is
6243 *.dates.fict.example
6245 then when partial matching is enabled this is matched by (amongst others)
6246 2001.dates.fict.example and 1984.dates.fict.example. It is also matched by
6247 dates.fict.example, if that does not appear as a separate key in the file.
6249 Note: Partial matching is not available for query-style lookups. It is also not
6250 available for any lookup items in address lists (see section 10.19).
6252 Partial matching is implemented by doing a series of separate lookups using
6253 keys constructed by modifying the original subject key. This means that it can
6254 be used with any of the single-key lookup types, provided that partial matching
6255 keys beginning with a special prefix (default "*.") are included in the data
6256 file. Keys in the file that do not begin with the prefix are matched only by
6257 unmodified subject keys when partial matching is in use.
6259 Partial matching is requested by adding the string "partial-" to the front of
6260 the name of a single-key lookup type, for example, partial-dbm. When this is
6261 done, the subject key is first looked up unmodified; if that fails, "*." is
6262 added at the start of the subject key, and it is looked up again. If that
6263 fails, further lookups are tried with dot-separated components removed from the
6264 start of the subject key, one-by-one, and "*." added on the front of what
6267 A minimum number of two non-* components are required. This can be adjusted by
6268 including a number before the hyphen in the search type. For example,
6269 partial3-lsearch specifies a minimum of three non-* components in the modified
6270 keys. Omitting the number is equivalent to "partial2-". If the subject key is
6271 2250.dates.fict.example then the following keys are looked up when the minimum
6272 number of non-* components is two:
6274 2250.dates.fict.example
6275 *.2250.dates.fict.example
6276 *.dates.fict.example
6279 As soon as one key in the sequence is successfully looked up, the lookup
6282 The use of "*." as the partial matching prefix is a default that can be
6283 changed. The motivation for this feature is to allow Exim to operate with file
6284 formats that are used by other MTAs. A different prefix can be supplied in
6285 parentheses instead of the hyphen after "partial". For example:
6287 domains = partial(.)lsearch;/some/file
6289 In this example, if the domain is a.b.c, the sequence of lookups is "a.b.c",
6290 ".a.b.c", and ".b.c" (the default minimum of 2 non-wild components is
6291 unchanged). The prefix may consist of any punctuation characters other than a
6292 closing parenthesis. It may be empty, for example:
6294 domains = partial1()cdb;/some/file
6296 For this example, if the domain is a.b.c, the sequence of lookups is "a.b.c",
6299 If "partial0" is specified, what happens at the end (when the lookup with just
6300 one non-wild component has failed, and the original key is shortened right down
6301 to the null string) depends on the prefix:
6303 * If the prefix has zero length, the whole lookup fails.
6305 * If the prefix has length 1, a lookup for just the prefix is done. For
6306 example, the final lookup for "partial0(.)" is for "." alone.
6308 * Otherwise, if the prefix ends in a dot, the dot is removed, and the
6309 remainder is looked up. With the default prefix, therefore, the final
6310 lookup is for "*" on its own.
6312 * Otherwise, the whole prefix is looked up.
6314 If the search type ends in "*" or "*@" (see section 9.6 above), the search for
6315 an ultimate default that this implies happens after all partial lookups have
6316 failed. If "partial0" is specified, adding "*" to the search type has no effect
6317 with the default prefix, because the "*" key is already included in the
6318 sequence of partial lookups. However, there might be a use for lookup types
6319 such as "partial0(.)lsearch*".
6321 The use of "*" in lookup partial matching differs from its use as a wildcard in
6322 domain lists and the like. Partial matching works only in terms of
6323 dot-separated components; a key such as "*fict.example" in a database file is
6324 useless, because the asterisk in a partial matching subject key is always
6331 Exim caches all lookup results in order to avoid needless repetition of
6332 lookups. However, because (apart from the daemon) Exim operates as a collection
6333 of independent, short-lived processes, this caching applies only within a
6334 single Exim process. There is no inter-process lookup caching facility.
6336 For single-key lookups, Exim keeps the relevant files open in case there is
6337 another lookup that needs them. In some types of configuration this can lead to
6338 many files being kept open for messages with many recipients. To avoid hitting
6339 the operating system limit on the number of simultaneously open files, Exim
6340 closes the least recently used file when it needs to open more files than its
6341 own internal limit, which can be changed via the lookup_open_max option.
6343 The single-key lookup files are closed and the lookup caches are flushed at
6344 strategic points during delivery - for example, after all routing is complete.
6347 9.9 Quoting lookup data
6348 -----------------------
6350 When data from an incoming message is included in a query-style lookup, there
6351 is the possibility of special characters in the data messing up the syntax of
6352 the query. For example, a NIS+ query that contains
6356 will be broken if the local part happens to contain a closing square bracket.
6357 For NIS+, data can be enclosed in double quotes like this:
6359 [name="$local_part"]
6361 but this still leaves the problem of a double quote in the data. The rule for
6362 NIS+ is that double quotes must be doubled. Other lookup types have different
6363 rules, and to cope with the differing requirements, an expansion operator of
6364 the following form is provided:
6366 ${quote_<lookup-type>:<string>}
6368 For example, the safest way to write the NIS+ query is
6370 [name="${quote_nisplus:$local_part}"]
6372 See chapter 11 for full coverage of string expansions. The quote operator can
6373 be used for all lookup types, but has no effect for single-key lookups, since
6374 no quoting is ever needed in their key strings.
6377 9.10 More about dnsdb
6378 ---------------------
6380 The dnsdb lookup type uses the DNS as its database. A simple query consists of
6381 a record type and a domain name, separated by an equals sign. For example, an
6382 expansion string could contain:
6384 ${lookup dnsdb{mx=a.b.example}{$value}fail}
6386 If the lookup succeeds, the result is placed in $value, which in this case is
6387 used on its own as the result. If the lookup does not succeed, the "fail"
6388 keyword causes a forced expansion failure - see section 11.4 for an explanation
6391 The supported DNS record types are A, CNAME, MX, NS, PTR, SPF, SRV, TLSA and
6392 TXT, and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
6393 configured). If no type is given, TXT is assumed. When the type is PTR, the
6394 data can be an IP address, written as normal; inversion and the addition of
6395 in-addr.arpa or ip6.arpa happens automatically. For example:
6397 ${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
6399 If the data for a PTR record is not a syntactically valid IP address, it is not
6400 altered and nothing is added.
6402 For an MX lookup, both the preference value and the host name are returned for
6403 each record, separated by a space. For an SRV lookup, the priority, weight,
6404 port, and host name are returned for each record, separated by spaces.
6406 For any record type, if multiple records are found (or, for A6 lookups, if a
6407 single record leads to multiple addresses), the data is returned as a
6408 concatenation, with newline as the default separator. The order, of course,
6409 depends on the DNS resolver. You can specify a different separator character
6410 between multiple records by putting a right angle-bracket followed immediately
6411 by the new separator at the start of the query. For example:
6413 ${lookup dnsdb{>: a=host1.example}}
6415 It is permitted to specify a space as the separator character. Further white
6418 For TXT records with multiple items of data, only the first item is returned,
6419 unless a separator for them is specified using a comma after the separator
6420 character followed immediately by the TXT record item separator. To concatenate
6421 items without a separator, use a semicolon instead. For SPF records the default
6422 behaviour is to concatenate multiple items without using a separator.
6424 ${lookup dnsdb{>\n,: txt=a.b.example}}
6425 ${lookup dnsdb{>\n; txt=a.b.example}}
6426 ${lookup dnsdb{spf=example.org}}
6428 It is permitted to specify a space as the separator character. Further white
6432 9.11 Pseudo dnsdb record types
6433 ------------------------------
6435 By default, both the preference value and the host name are returned for each
6436 MX record, separated by a space. If you want only host names, you can use the
6439 ${lookup dnsdb{mxh=a.b.example}}
6441 In this case, the preference values are omitted, and just the host names are
6444 Another pseudo-type is ZNS (for "zone NS"). It performs a lookup for NS records
6445 on the given domain, but if none are found, it removes the first component of
6446 the domain name, and tries again. This process continues until NS records are
6447 found or there are no more components left (or there is a DNS error). In other
6448 words, it may return the name servers for a top-level domain, but it never
6449 returns the root name servers. If there are no NS records for the top-level
6450 domain, the lookup fails. Consider these examples:
6452 ${lookup dnsdb{zns=xxx.quercite.com}}
6453 ${lookup dnsdb{zns=xxx.edu}}
6455 Assuming that in each case there are no NS records for the full domain name,
6456 the first returns the name servers for quercite.com, and the second returns the
6457 name servers for edu.
6459 You should be careful about how you use this lookup because, unless the
6460 top-level domain does not exist, the lookup always returns some host names. The
6461 sort of use to which this might be put is for seeing if the name servers for a
6462 given domain are on a blacklist. You can probably assume that the name servers
6463 for the high-level domains such as com or co.uk are not going to be on such a
6466 A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV
6467 records according to the CSA rules, which are described in section 42.50.
6468 Although dnsdb supports SRV lookups directly, this is not sufficient because of
6469 the extra parent domain search behaviour of CSA. The result of a successful
6472 ${lookup dnsdb {csa=$sender_helo_name}}
6474 has two space-separated fields: an authorization code and a target host name.
6475 The authorization code can be "Y" for yes, "N" for no, "X" for explicit
6476 authorization required but absent, or "?" for unknown.
6478 The pseudo-type A+ performs an A6 lookup (if configured) followed by an AAAA
6479 and then an A lookup. All results are returned; defer processing (see below) is
6480 handled separately for each lookup. Example:
6482 ${lookup dnsdb {>; a+=$sender_helo_name}}
6485 9.12 Multiple dnsdb lookups
6486 ---------------------------
6488 In the previous sections, dnsdb lookups for a single domain are described.
6489 However, you can specify a list of domains or IP addresses in a single dnsdb
6490 lookup. The list is specified in the normal Exim way, with colon as the default
6491 separator, but with the ability to change this. For example:
6493 ${lookup dnsdb{one.domain.com:two.domain.com}}
6494 ${lookup dnsdb{a=one.host.com:two.host.com}}
6495 ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}}
6497 In order to retain backwards compatibility, there is one special case: if the
6498 lookup type is PTR and no change of separator is specified, Exim looks to see
6499 if the rest of the string is precisely one IPv6 address. In this case, it does
6500 not treat it as a list.
6502 The data from each lookup is concatenated, with newline separators by default,
6503 in the same way that multiple DNS records for a single item are handled. A
6504 different separator can be specified, as described above.
6506 Modifiers for dnsdb lookups are givien by optional keywords, each followed by a
6507 comma, that may appear before the record type.
6509 The dnsdb lookup fails only if all the DNS lookups fail. If there is a
6510 temporary DNS error for any of them, the behaviour is controlled by a
6511 defer-option modifier. The possible keywords are "defer_strict", "defer_never",
6512 and "defer_lax". With "strict" behaviour, any temporary DNS error causes the
6513 whole lookup to defer. With "never" behaviour, a temporary DNS error is
6514 ignored, and the behaviour is as if the DNS lookup failed to find anything.
6515 With "lax" behaviour, all the queries are attempted, but a temporary DNS error
6516 causes the whole lookup to defer only if none of the other lookups succeed. The
6517 default is "lax", so the following lookups are equivalent:
6519 ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
6520 ${lookup dnsdb{a=one.host.com:two.host.com}}
6522 Thus, in the default case, as long as at least one of the DNS lookups yields
6523 some data, the lookup succeeds.
6525 Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are
6526 "dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax"
6527 DNSSEC information is requested with the lookup. With "strict" a response from
6528 the DNS resolver that is not labelled as authenticated data is treated as
6529 equivalent to a temporary DNS error. The default is "never".
6531 See also the $lookup_dnssec_authenticated variable.
6534 9.13 More about LDAP
6535 --------------------
6537 The original LDAP implementation came from the University of Michigan; this has
6538 become "Open LDAP", and there are now two different releases. Another
6539 implementation comes from Netscape, and Solaris 7 and subsequent releases
6540 contain inbuilt LDAP support. Unfortunately, though these are all compatible at
6541 the lookup function level, their error handling is different. For this reason
6542 it is necessary to set a compile-time variable when building Exim with LDAP, to
6543 indicate which LDAP library is in use. One of the following should appear in
6544 your Local/Makefile:
6546 LDAP_LIB_TYPE=UMICHIGAN
6547 LDAP_LIB_TYPE=OPENLDAP1
6548 LDAP_LIB_TYPE=OPENLDAP2
6549 LDAP_LIB_TYPE=NETSCAPE
6550 LDAP_LIB_TYPE=SOLARIS
6552 If LDAP_LIB_TYPE is not set, Exim assumes "OPENLDAP1", which has the same
6553 interface as the University of Michigan version.
6555 There are three LDAP lookup types in Exim. These behave slightly differently in
6556 the way they handle the results of a query:
6558 * ldap requires the result to contain just one entry; if there are more, it
6561 * ldapdn also requires the result to contain just one entry, but it is the
6562 Distinguished Name that is returned rather than any attribute values.
6564 * ldapm permits the result to contain more than one entry; the attributes
6565 from all of them are returned.
6567 For ldap and ldapm, if a query finds only entries with no attributes, Exim
6568 behaves as if the entry did not exist, and the lookup fails. The format of the
6569 data returned by a successful lookup is described in the next section. First we
6570 explain how LDAP queries are coded.
6573 9.14 Format of LDAP queries
6574 ---------------------------
6576 An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
6577 the configuration of a redirect router one might have this setting:
6579 data = ${lookup ldap \
6580 {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
6581 c=UK?mailbox?base?}}
6583 The URL may begin with "ldap" or "ldaps" if your LDAP library supports secure
6584 (encrypted) LDAP connections. The second of these ensures that an encrypted TLS
6587 With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular
6588 LDAP connections, rather than the SSL-on-connect "ldaps". See the
6589 ldap_start_tls option.
6591 Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly
6592 controlled. Every part of the TLS configuration can be configured by settings
6593 in exim.conf. Depending on the version of the client libraries installed on
6594 your system, some of the initialization may have required setting options in /
6595 etc/ldap.conf or ~/.ldaprc to get TLS working with self-signed certificates.
6596 This revealed a nuance where the current UID that exim was running as could
6597 affect which config files it read. With Exim 4.83, these methods become
6598 optional, only taking effect if not specifically set in exim.conf.
6604 Two levels of quoting are required in LDAP queries, the first for LDAP itself
6605 and the second because the LDAP query is represented as a URL. Furthermore,
6606 within an LDAP query, two different kinds of quoting are required. For this
6607 reason, there are two different LDAP-specific quoting operators.
6609 The quote_ldap operator is designed for use on strings that are part of filter
6610 specifications. Conceptually, it first does the following conversions on the
6618 in accordance with RFC 2254. The resulting string is then quoted according to
6619 the rules for URLs, that is, all non-alphanumeric characters except
6623 are converted to their hex values, preceded by a percent sign. For example:
6625 ${quote_ldap: a(bc)*, a<yz>; }
6629 %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
6631 Removing the URL quoting, this is (with a leading and a trailing space):
6633 a\28bc\29\2A, a<yz>;
6635 The quote_ldap_dn operator is designed for use on strings that are part of base
6636 DN specifications in queries. Conceptually, it first converts the string by
6637 inserting a backslash in front of any of the following characters:
6641 It also inserts a backslash before any leading spaces or # characters, and
6642 before any trailing spaces. (These rules are in RFC 2253.) The resulting string
6643 is then quoted according to the rules for URLs. For example:
6645 ${quote_ldap_dn: a(bc)*, a<yz>; }
6649 %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
6651 Removing the URL quoting, this is (with a trailing space):
6653 \ a(bc)*\, a\<yz\>\;\
6655 There are some further comments about quoting in the section on LDAP
6656 authentication below.
6659 9.16 LDAP connections
6660 ---------------------
6662 The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
6663 is in use, via a Unix domain socket. The example given above does not specify
6664 an LDAP server. A server that is reached by TCP/IP can be specified in a query
6667 ldap://<hostname>:<port>/...
6669 If the port (and preceding colon) are omitted, the standard LDAP port (389) is
6670 used. When no server is specified in a query, a list of default servers is
6671 taken from the ldap_default_servers configuration option. This supplies a
6672 colon-separated list of servers which are tried in turn until one successfully
6673 handles a query, or there is a serious error. Successful handling either
6674 returns the requested data, or indicates that it does not exist. Serious errors
6675 are syntactical, or multiple values when only a single value is expected.
6676 Errors which cause the next server to be tried are connection failures, bind
6677 failures, and timeouts.
6679 For each server name in the list, a port number can be given. The standard way
6680 of specifying a host and port is to use a colon separator (RFC 1738). Because
6681 ldap_default_servers is a colon-separated list, such colons have to be doubled.
6684 ldap_default_servers = ldap1.example.com::145:ldap2.example.com
6686 If ldap_default_servers is unset, a URL with no server name is passed to the
6687 LDAP library with no server name, and the library's default (normally the local
6690 If you are using the OpenLDAP library, you can connect to an LDAP server using
6691 a Unix domain socket instead of a TCP/IP connection. This is specified by using
6692 "ldapi" instead of "ldap" in LDAP queries. What follows here applies only to
6693 OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
6696 For this type of connection, instead of a host name for the server, a pathname
6697 for the socket is required, and the port number is not relevant. The pathname
6698 can be specified either as an item in ldap_default_servers, or inline in the
6699 query. In the former case, you can have settings such as
6701 ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
6703 When the pathname is given in the query, you have to escape the slashes as
6704 "%2F" to fit in with the LDAP URL syntax. For example:
6706 ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
6708 When Exim processes an LDAP lookup and finds that the "hostname" is really a
6709 pathname, it uses the Unix domain socket code, even if the query actually
6710 specifies "ldap" or "ldaps". In particular, no encryption is used for a socket
6711 connection. This behaviour means that you can use a setting of
6712 ldap_default_servers such as in the example above with traditional "ldap" or
6713 "ldaps" queries, and it will work. First, Exim tries a connection via the Unix
6714 domain socket; if that fails, it tries a TCP/IP connection to the backup host.
6716 If an explicit "ldapi" type is given in a query when a host name is specified,
6717 an error is diagnosed. However, if there are more items in ldap_default_servers
6718 , they are tried. In other words:
6720 * Using a pathname with "ldap" or "ldaps" forces the use of the Unix domain
6723 * Using "ldapi" with a host name causes an error.
6725 Using "ldapi" with no host or path in the query, and no setting of
6726 ldap_default_servers, does whatever the library does by default.
6729 9.17 LDAP authentication and control information
6730 ------------------------------------------------
6732 The LDAP URL syntax provides no way of passing authentication and other control
6733 information to the server. To make this possible, the URL in an LDAP query may
6734 be preceded by any number of <name>=<value> settings, separated by spaces. If a
6735 value contains spaces it must be enclosed in double quotes, and when double
6736 quotes are used, backslash is interpreted in the usual way inside them. The
6737 following names are recognized:
6739 DEREFERENCE set the dereferencing parameter
6740 NETTIME set a timeout for a network operation
6741 USER set the DN, for authenticating the LDAP bind
6742 PASS set the password, likewise
6743 REFERRALS set the referrals parameter
6744 SERVERS set alternate server list for this query only
6745 SIZE set the limit for the number of entries returned
6746 TIME set the maximum waiting time for a query
6748 The value of the DEREFERENCE parameter must be one of the words "never",
6749 "searching", "finding", or "always". The value of the REFERRALS parameter must
6750 be "follow" (the default) or "nofollow". The latter stops the LDAP library from
6751 trying to follow referrals issued by the LDAP server.
6753 The name CONNECT is an obsolete name for NETTIME, retained for backwards
6754 compatibility. This timeout (specified as a number of seconds) is enforced from
6755 the client end for operations that can be carried out over a network.
6756 Specifically, it applies to network connections and calls to the ldap_result()
6757 function. If the value is greater than zero, it is used if
6758 LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or if
6759 LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape SDK 4.1). A
6760 value of zero forces an explicit setting of "no timeout" for Netscape SDK; for
6761 OpenLDAP no action is taken.
6763 The TIME parameter (also a number of seconds) is passed to the server to set a
6764 server-side limit on the time taken to complete a search.
6766 The SERVERS parameter allows you to specify an alternate list of ldap servers
6767 to use for an individual lookup. The global ldap_servers option provides a
6768 default list of ldap servers, and a single lookup can specify a single ldap
6769 server to use. But when you need to do a lookup with a list of servers that is
6770 different than the default list (maybe different order, maybe a completely
6771 different set of servers), the SERVERS parameter allows you to specify this
6774 Here is an example of an LDAP query in an Exim lookup that uses some of these
6775 values. This is a single line, folded to fit on the page:
6778 {user="cn=manager,o=University of Cambridge,c=UK" pass=secret
6779 ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
6782 The encoding of spaces as "%20" is a URL thing which should not be done for any
6783 of the auxiliary data. Exim configuration settings that include lookups which
6784 contain password information should be preceded by "hide" to prevent non-admin
6785 users from using the -bP option to see their values.
6787 The auxiliary data items may be given in any order. The default is no
6788 connection timeout (the system timeout is used), no user or password, no limit
6789 on the number of entries returned, and no time limit on queries.
6791 When a DN is quoted in the USER= setting for LDAP authentication, Exim removes
6792 any URL quoting that it may contain before passing it LDAP. Apparently some
6793 libraries do this for themselves, but some do not. Removing the URL quoting has
6796 * It makes it possible to use the same quote_ldap_dn expansion for USER= DNs
6797 as with DNs inside actual queries.
6799 * It permits spaces inside USER= DNs.
6801 For example, a setting such as
6803 USER=cn=${quote_ldap_dn:$1}
6805 should work even if $1 contains spaces.
6807 Expanded data for the PASS= value should be quoted using the quote expansion
6808 operator, rather than the LDAP quote operators. The only reason this field
6809 needs quoting is to ensure that it conforms to the Exim syntax, which does not
6810 allow unquoted spaces. For example:
6814 The LDAP authentication mechanism can be used to check passwords as part of
6815 SMTP authentication. See the ldapauth expansion string condition in chapter 11.
6818 9.18 Format of data returned by LDAP
6819 ------------------------------------
6821 The ldapdn lookup type returns the Distinguished Name from a single entry as a
6822 sequence of values, for example
6824 cn=manager, o=University of Cambridge, c=UK
6826 The ldap lookup type generates an error if more than one entry matches the
6827 search filter, whereas ldapm permits this case, and inserts a newline in the
6828 result between the data from different entries. It is possible for multiple
6829 values to be returned for both ldap and ldapm, but in the former case you know
6830 that whatever values are returned all came from a single entry in the
6833 In the common case where you specify a single attribute in your LDAP query, the
6834 result is not quoted, and does not contain the attribute name. If the attribute
6835 has multiple values, they are separated by commas.
6837 If you specify multiple attributes, the result contains space-separated, quoted
6838 strings, each preceded by the attribute name and an equals sign. Within the
6839 quotes, the quote character, backslash, and newline are escaped with
6840 backslashes, and commas are used to separate multiple values for the attribute.
6841 Apart from the escaping, the string within quotes takes the same form as the
6842 output when a single attribute is requested. Specifying no attributes is the
6843 same as specifying all of an entry's attributes.
6845 Here are some examples of the output format. The first line of each pair is an
6846 LDAP query, and the second is the data that is returned. The attribute called
6847 attr1 has two values, whereas attr2 has only one value:
6849 ldap:///o=base?attr1?sub?(uid=fred)
6852 ldap:///o=base?attr2?sub?(uid=fred)
6855 ldap:///o=base?attr1,attr2?sub?(uid=fred)
6856 attr1="value1.1, value1.2" attr2="value two"
6858 ldap:///o=base??sub?(uid=fred)
6859 objectClass="top" attr1="value1.1, value1.2" attr2="value two"
6861 The extract operator in string expansions can be used to pick out individual
6862 fields from data that consists of key=value pairs. You can make use of Exim's
6863 -be option to run expansion tests and thereby check the results of LDAP
6867 9.19 More about NIS+
6868 --------------------
6870 NIS+ queries consist of a NIS+ indexed name followed by an optional colon and
6871 field name. If this is given, the result of a successful query is the contents
6872 of the named field; otherwise the result consists of a concatenation of
6873 field-name=field-value pairs, separated by spaces. Empty values and values
6874 containing spaces are quoted. For example, the query
6876 [name=mg1456],passwd.org_dir
6878 might return the string
6880 name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
6881 home=/home/mg1456 shell=/bin/bash shadow=""
6883 (split over two lines here to fit on the page), whereas
6885 [name=mg1456],passwd.org_dir:gcos
6891 with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
6892 for the given indexed key. The effect of the quote_nisplus expansion operator
6893 is to double any quote characters within the text.
6899 Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite
6900 databases. Queries for these databases contain SQL statements, so an example
6903 ${lookup mysql{select mailbox from users where id='userx'}\
6906 If the result of the query contains more than one field, the data for each
6907 field in the row is returned, preceded by its name, so the result of
6909 ${lookup pgsql{select home,name from users where id='userx'}\
6914 home=/home/userx name="Mister X"
6916 Empty values and values containing spaces are double quoted, with embedded
6917 quotes escaped by a backslash. If the result of the query contains just one
6918 field, the value is passed back verbatim, without a field name, for example:
6922 If the result of the query yields more than one row, it is all concatenated,
6923 with a newline between the data for each row.
6926 9.21 More about MySQL, PostgreSQL, Oracle, and InterBase
6927 --------------------------------------------------------
6929 If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the
6930 mysql_servers, pgsql_servers, oracle_servers, or ibase_servers option (as
6931 appropriate) must be set to a colon-separated list of server information. (For
6932 MySQL and PostgreSQL only, the global option need not be set if all queries
6933 contain their own server information - see section 9.22.) Each item in the list
6934 is a slash-separated list of four items: host name, database name, user name,
6935 and password. In the case of Oracle, the host name field is used for the
6936 "service name", and the database name field is not used and should be empty.
6939 hide oracle_servers = oracle.plc.example//userx/abcdwxyz
6941 Because password data is sensitive, you should always precede the setting with
6942 "hide", to prevent non-admin users from obtaining the setting via the -bP
6943 option. Here is an example where two MySQL servers are listed:
6945 hide mysql_servers = localhost/users/root/secret:\
6946 otherhost/users/root/othersecret
6948 For MySQL and PostgreSQL, a host may be specified as <name>:<port> but because
6949 this is a colon-separated list, the colon has to be doubled. For each query,
6950 these parameter groups are tried in order until a connection is made and a
6951 query is successfully processed. The result of a query may be that no data is
6952 found, but that is still a successful query. In other words, the list of
6953 servers provides a backup facility, not a list of different places to look.
6955 The quote_mysql, quote_pgsql, and quote_oracle expansion operators convert
6956 newline, tab, carriage return, and backspace to \n, \t, \r, and \b
6957 respectively, and the characters single-quote, double-quote, and backslash
6958 itself are escaped with backslashes. The quote_pgsql expansion operator, in
6959 addition, escapes the percent and underscore characters. This cannot be done
6960 for MySQL because these escapes are not recognized in contexts where these
6961 characters are not special.
6964 9.22 Specifying the server in the query
6965 ---------------------------------------
6967 For MySQL and PostgreSQL lookups (but not currently for Oracle and InterBase),
6968 it is possible to specify a list of servers with an individual query. This is
6969 done by starting the query with
6971 servers=server1:server2:server3:...;
6973 Each item in the list may take one of two forms:
6975 1. If it contains no slashes it is assumed to be just a host name. The
6976 appropriate global option (mysql_servers or pgsql_servers) is searched for
6977 a host of the same name, and the remaining parameters (database, user,
6978 password) are taken from there.
6980 2. If it contains any slashes, it is taken as a complete parameter set.
6982 The list of servers is used in exactly the same way as the global list. Once a
6983 connection to a server has happened and a query has been successfully executed,
6984 processing of the lookup ceases.
6986 This feature is intended for use in master/slave situations where updates are
6987 occurring and you want to update the master rather than a slave. If the master
6988 is in the list as a backup for reading, you might have a global setting like
6991 mysql_servers = slave1/db/name/pw:\
6995 In an updating lookup, you could then write:
6997 ${lookup mysql{servers=master; UPDATE ...} }
6999 That query would then be sent only to the master server. If, on the other hand,
7000 the master is not to be used for reading, and so is not present in the global
7001 option, you can still update it by a query of this form:
7003 ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} }
7006 9.23 Special MySQL features
7007 ---------------------------
7009 For MySQL, an empty host name or the use of "localhost" in mysql_servers causes
7010 a connection to the server on the local host by means of a Unix domain socket.
7011 An alternate socket can be specified in parentheses. The full syntax of each
7012 item in mysql_servers is:
7014 <hostname>::<port>(<socket name>)/<database>/<user>/<password>
7016 Any of the three sub-parts of the first field can be omitted. For normal use on
7017 the local host it can be left blank or set to just "localhost".
7019 No database need be supplied - but if it is absent here, it must be given in
7022 If a MySQL query is issued that does not request any data (an insert, update,
7023 or delete command), the result of the lookup is the number of rows affected.
7025 Warning: This can be misleading. If an update does not actually change anything
7026 (for example, setting a field to the value it already has), the result is zero
7027 because no rows are affected.
7030 9.24 Special PostgreSQL features
7031 --------------------------------
7033 PostgreSQL lookups can also use Unix domain socket connections to the database.
7034 This is usually faster and costs less CPU time than a TCP/IP connection.
7035 However it can be used only if the mail server runs on the same machine as the
7036 database server. A configuration line for PostgreSQL via Unix domain sockets
7039 hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
7041 In other words, instead of supplying a host name, a path to the socket is
7042 given. The path name is enclosed in parentheses so that its slashes aren't
7043 visually confused with the delimiters for the other server parameters.
7045 If a PostgreSQL query is issued that does not request any data (an insert,
7046 update, or delete command), the result of the lookup is the number of rows
7050 9.25 More about SQLite
7051 ----------------------
7053 SQLite is different to the other SQL lookups because a file name is required in
7054 addition to the SQL query. An SQLite database is a single file, and there is no
7055 daemon as in the other SQL databases. The interface to Exim requires the name
7056 of the file, as an absolute path, to be given at the start of the query. It is
7057 separated from the query by white space. This means that the path name cannot
7058 contain white space. Here is a lookup expansion example:
7060 ${lookup sqlite {/some/thing/sqlitedb \
7061 select name from aliases where id='userx';}}
7063 In a list, the syntax is similar. For example:
7065 domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \
7066 select * from relays where ip='$sender_host_address';
7068 The only character affected by the quote_sqlite operator is a single quote,
7071 The SQLite library handles multiple simultaneous accesses to the database
7072 internally. Multiple readers are permitted, but only one process can update at
7073 once. Attempts to access the database while it is being updated are rejected
7074 after a timeout period, during which the SQLite library waits for the lock to
7075 be released. In Exim, the default timeout is set to 5 seconds, but it can be
7076 changed by means of the sqlite_lock_timeout option.
7080 ===============================================================================
7081 10. DOMAIN, HOST, ADDRESS, AND LOCAL PART LISTS
7083 A number of Exim configuration options contain lists of domains, hosts, email
7084 addresses, or local parts. For example, the hold_domains option contains a list
7085 of domains whose delivery is currently suspended. These lists are also used as
7086 data in ACL statements (see chapter 42), and as arguments to expansion
7087 conditions such as match_domain.
7089 Each item in one of these lists is a pattern to be matched against a domain,
7090 host, email address, or local part, respectively. In the sections below, the
7091 different types of pattern for each case are described, but first we cover some
7092 general facilities that apply to all four kinds of list.
7095 10.1 Expansion of lists
7096 -----------------------
7098 Each list is expanded as a single string before it is used. The result of
7099 expansion must be a list, possibly containing empty items, which is split up
7100 into separate items for matching. By default, colon is the separator character,
7101 but this can be varied if necessary. See sections 6.19 and 6.21 for details of
7102 the list syntax; the second of these discusses the way to specify empty list
7105 If the string expansion is forced to fail, Exim behaves as if the item it is
7106 testing (domain, host, address, or local part) is not in the list. Other
7107 expansion failures cause temporary errors.
7109 If an item in a list is a regular expression, backslashes, dollars and possibly
7110 other special characters in the expression must be protected against
7111 misinterpretation by the string expander. The easiest way to do this is to use
7112 the "\N" expansion feature to indicate that the contents of the regular
7113 expression should not be expanded. For example, in an ACL you might have:
7115 deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \
7116 ${lookup{$domain}lsearch{/badsenders/bydomain}}
7118 The first item is a regular expression that is protected from expansion by "\
7119 N", whereas the second uses the expansion to obtain a list of unwanted senders
7120 based on the receiving domain.
7123 10.2 Negated items in lists
7124 ---------------------------
7126 Items in a list may be positive or negative. Negative items are indicated by a
7127 leading exclamation mark, which may be followed by optional white space. A list
7128 defines a set of items (domains, etc). When Exim processes one of these lists,
7129 it is trying to find out whether a domain, host, address, or local part
7130 (respectively) is in the set that is defined by the list. It works like this:
7132 The list is scanned from left to right. If a positive item is matched, the
7133 subject that is being checked is in the set; if a negative item is matched, the
7134 subject is not in the set. If the end of the list is reached without the
7135 subject having matched any of the patterns, it is in the set if the last item
7136 was a negative one, but not if it was a positive one. For example, the list in
7138 domainlist relay_to_domains = !a.b.c : *.b.c
7140 matches any domain ending in .b.c except for a.b.c. Domains that match neither
7141 a.b.c nor *.b.c do not match, because the last item in the list is positive.
7142 However, if the setting were
7144 domainlist relay_to_domains = !a.b.c
7146 then all domains other than a.b.c would match because the last item in the list
7147 is negative. In other words, a list that ends with a negative item behaves as
7148 if it had an extra item ":*" on the end.
7150 Another way of thinking about positive and negative items in lists is to read
7151 the connector as "or" after a positive item and as "and" after a negative item.
7154 10.3 File names in lists
7155 ------------------------
7157 If an item in a domain, host, address, or local part list is an absolute file
7158 name (beginning with a slash character), each line of the file is read and
7159 processed as if it were an independent item in the list, except that further
7160 file names are not allowed, and no expansion of the data from the file takes
7161 place. Empty lines in the file are ignored, and the file may also contain
7164 * For domain and host lists, if a # character appears anywhere in a line of
7165 the file, it and all following characters are ignored.
7167 * Because local parts may legitimately contain # characters, a comment in an
7168 address list or local part list file is recognized only if # is preceded by
7169 white space or the start of the line. For example:
7171 not#comment@x.y.z # but this is a comment
7173 Putting a file name in a list has the same effect as inserting each line of the
7174 file as an item in the list (blank lines and comments excepted). However, there
7175 is one important difference: the file is read each time the list is processed,
7176 so if its contents vary over time, Exim's behaviour changes.
7178 If a file name is preceded by an exclamation mark, the sense of any match
7179 within the file is inverted. For example, if
7181 hold_domains = !/etc/nohold-domains
7183 and the file contains the lines
7188 then a.b.c is in the set of domains defined by hold_domains, whereas any domain
7189 matching "*.b.c" is not.
7192 10.4 An lsearch file is not an out-of-line list
7193 -----------------------------------------------
7195 As will be described in the sections that follow, lookups can be used in lists
7196 to provide indexed methods of checking list membership. There has been some
7197 confusion about the way lsearch lookups work in lists. Because an lsearch file
7198 contains plain text and is scanned sequentially, it is sometimes thought that
7199 it is allowed to contain wild cards and other kinds of non-constant pattern.
7200 This is not the case. The keys in an lsearch file are always fixed strings,
7201 just as for any other single-key lookup type.
7203 If you want to use a file to contain wild-card patterns that form part of a
7204 list, just give the file name on its own, without a search type, as described
7205 in the previous section. You could also use the wildlsearch or nwildlsearch,
7206 but there is no advantage in doing this.
7212 A list of domains, hosts, email addresses, or local parts can be given a name
7213 which is then used to refer to the list elsewhere in the configuration. This is
7214 particularly convenient if the same list is required in several different
7215 places. It also allows lists to be given meaningful names, which can improve
7216 the readability of the configuration. For example, it is conventional to define
7217 a domain list called local_domains for all the domains that are handled locally
7218 on a host, using a configuration line such as
7220 domainlist local_domains = localhost:my.dom.example
7222 Named lists are referenced by giving their name preceded by a plus sign, so,
7223 for example, a router that is intended to handle local domains would be
7224 configured with the line
7226 domains = +local_domains
7228 The first router in a configuration is often one that handles all domains
7229 except the local ones, using a configuration with a negated item like this:
7233 domains = ! +local_domains
7234 transport = remote_smtp
7237 The four kinds of named list are created by configuration lines starting with
7238 the words domainlist, hostlist, addresslist, or localpartlist, respectively.
7239 Then there follows the name that you are defining, followed by an equals sign
7240 and the list itself. For example:
7242 hostlist relay_from_hosts = 192.168.23.0/24 : my.friend.example
7243 addresslist bad_senders = cdb;/etc/badsenders
7245 A named list may refer to other named lists:
7247 domainlist dom1 = first.example : second.example
7248 domainlist dom2 = +dom1 : third.example
7249 domainlist dom3 = fourth.example : +dom2 : fifth.example
7251 Warning: If the last item in a referenced list is a negative one, the effect
7252 may not be what you intended, because the negation does not propagate out to
7253 the higher level. For example, consider:
7255 domainlist dom1 = !a.b
7256 domainlist dom2 = +dom1 : *.b
7258 The second list specifies "either in the dom1 list or *.b". The first list
7259 specifies just "not a.b", so the domain x.y matches it. That means it matches
7260 the second list as well. The effect is not the same as
7262 domainlist dom2 = !a.b : *.b
7264 where x.y does not match. It's best to avoid negation altogether in referenced
7267 Named lists may have a performance advantage. When Exim is routing an address
7268 or checking an incoming message, it caches the result of tests on named lists.
7269 So, if you have a setting such as
7271 domains = +local_domains
7273 on several of your routers or in several ACL statements, the actual test is
7274 done only for the first one. However, the caching works only if there are no
7275 expansions within the list itself or any sublists that it references. In other
7276 words, caching happens only for lists that are known to be the same each time
7277 they are referenced.
7279 By default, there may be up to 16 named lists of each type. This limit can be
7280 extended by changing a compile-time variable. The use of domain and host lists
7281 is recommended for concepts such as local domains, relay domains, and relay
7282 hosts. The default configuration is set up like this.
7285 10.6 Named lists compared with macros
7286 -------------------------------------
7288 At first sight, named lists might seem to be no different from macros in the
7289 configuration file. However, macros are just textual substitutions. If you
7292 ALIST = host1 : host2
7293 auth_advertise_hosts = !ALIST
7295 it probably won't do what you want, because that is exactly the same as
7297 auth_advertise_hosts = !host1 : host2
7299 Notice that the second host name is not negated. However, if you use a host
7302 hostlist alist = host1 : host2
7303 auth_advertise_hosts = ! +alist
7305 the negation applies to the whole list, and so that is equivalent to
7307 auth_advertise_hosts = !host1 : !host2
7310 10.7 Named list caching
7311 -----------------------
7313 While processing a message, Exim caches the result of checking a named list if
7314 it is sure that the list is the same each time. In practice, this means that
7315 the cache operates only if the list contains no $ characters, which guarantees
7316 that it will not change when it is expanded. Sometimes, however, you may have
7317 an expanded list that you know will be the same each time within a given
7318 message. For example:
7320 domainlist special_domains = \
7321 ${lookup{$sender_host_address}cdb{/some/file}}
7323 This provides a list of domains that depends only on the sending host's IP
7324 address. If this domain list is referenced a number of times (for example, in
7325 several ACL lines, or in several routers) the result of the check is not cached
7326 by default, because Exim does not know that it is going to be the same list
7329 By appending "_cache" to "domainlist" you can tell Exim to go ahead and cache
7330 the result anyway. For example:
7332 domainlist_cache special_domains = ${lookup{...
7334 If you do this, you should be absolutely sure that caching is going to do the
7335 right thing in all cases. When in doubt, leave it out.
7341 Domain lists contain patterns that are to be matched against a mail domain. The
7342 following types of item may appear in domain lists:
7344 * If a pattern consists of a single @ character, it matches the local host
7345 name, as set by the primary_hostname option (or defaulted). This makes it
7346 possible to use the same configuration file on several different hosts that
7347 differ only in their names.
7349 * If a pattern consists of the string "@[]" it matches an IP address enclosed
7350 in square brackets (as in an email address that contains a domain literal),
7351 but only if that IP address is recognized as local for email routing
7352 purposes. The local_interfaces and extra_local_interfaces options can be
7353 used to control which of a host's several IP addresses are treated as
7354 local. In today's Internet, the use of domain literals is controversial.
7356 * If a pattern consists of the string "@mx_any" it matches any domain that
7357 has an MX record pointing to the local host or to any host that is listed
7358 in hosts_treat_as_local. The items "@mx_primary" and "@mx_secondary" are
7359 similar, except that the first matches only when a primary MX target is the
7360 local host, and the second only when no primary MX target is the local
7361 host, but a secondary MX target is. "Primary" means an MX record with the
7362 lowest preference value - there may of course be more than one of them.
7364 The MX lookup that takes place when matching a pattern of this type is
7365 performed with the resolver options for widening names turned off. Thus,
7366 for example, a single-component domain will not be expanded by adding the
7367 resolver's default domain. See the qualify_single and search_parents
7368 options of the dnslookup router for a discussion of domain widening.
7370 Sometimes you may want to ignore certain IP addresses when using one of
7371 these patterns. You can specify this by following the pattern with "/ignore
7372 ="<ip list>, where <ip list> is a list of IP addresses. These addresses are
7373 ignored when processing the pattern (compare the ignore_target_hosts option
7374 on a router). For example:
7376 domains = @mx_any/ignore=127.0.0.1
7378 This example matches any domain that has an MX record pointing to one of
7379 the local host's IP addresses other than 127.0.0.1.
7381 The list of IP addresses is in fact processed by the same code that
7382 processes host lists, so it may contain CIDR-coded network specifications
7383 and it may also contain negative items.
7385 Because the list of IP addresses is a sublist within a domain list, you
7386 have to be careful about delimiters if there is more than one address. Like
7387 any other list, the default delimiter can be changed. Thus, you might have:
7389 domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \
7390 an.other.domain : ...
7392 so that the sublist uses semicolons for delimiters. When IPv6 addresses are
7393 involved, it is easiest to change the delimiter for the main list as well:
7395 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
7396 an.other.domain ? ...
7398 * If a pattern starts with an asterisk, the remaining characters of the
7399 pattern are compared with the terminating characters of the domain. The use
7400 of "*" in domain lists differs from its use in partial matching lookups. In
7401 a domain list, the character following the asterisk need not be a dot,
7402 whereas partial matching works only in terms of dot-separated components.
7403 For example, a domain list item such as "*key.ex" matches donkey.ex as well
7406 * If a pattern starts with a circumflex character, it is treated as a regular
7407 expression, and matched against the domain using a regular expression
7408 matching function. The circumflex is treated as part of the regular
7409 expression. Email domains are case-independent, so this regular expression
7410 match is by default case-independent, but you can make it case-dependent by
7411 starting it with "(?-i)". References to descriptions of the syntax of
7412 regular expressions are given in chapter 8.
7414 Warning: Because domain lists are expanded before being processed, you must
7415 escape any backslash and dollar characters in the regular expression, or
7416 use the special "\N" sequence (see chapter 11) to specify that it is not to
7417 be expanded (unless you really do want to build a regular expression by
7418 expansion, of course).
7420 * If a pattern starts with the name of a single-key lookup type followed by a
7421 semicolon (for example, "dbm;" or "lsearch;"), the remainder of the pattern
7422 must be a file name in a suitable format for the lookup type. For example,
7423 for "cdb;" it must be an absolute path:
7425 domains = cdb;/etc/mail/local_domains.cdb
7427 The appropriate type of lookup is done on the file using the domain name as
7428 the key. In most cases, the data that is looked up is not used; Exim is
7429 interested only in whether or not the key is present in the file. However,
7430 when a lookup is used for the domains option on a router or a domains
7431 condition in an ACL statement, the data is preserved in the $domain_data
7432 variable and can be referred to in other router options or other statements
7435 * Any of the single-key lookup type names may be preceded by "partial"<n>"-",
7436 where the <n> is optional, for example,
7438 domains = partial-dbm;/partial/domains
7440 This causes partial matching logic to be invoked; a description of how this
7441 works is given in section 9.7.
7443 * Any of the single-key lookup types may be followed by an asterisk. This
7444 causes a default lookup for a key consisting of a single asterisk to be
7445 done if the original lookup fails. This is not a useful feature when using
7446 a domain list to select particular domains (because any domain would
7447 match), but it might have value if the result of the lookup is being used
7448 via the $domain_data expansion variable.
7450 * If the pattern starts with the name of a query-style lookup type followed
7451 by a semicolon (for example, "nisplus;" or "ldap;"), the remainder of the
7452 pattern must be an appropriate query for the lookup type, as described in
7453 chapter 9. For example:
7455 hold_domains = mysql;select domain from holdlist \
7456 where domain = '${quote_mysql:$domain}';
7458 In most cases, the data that is looked up is not used (so for an SQL query,
7459 for example, it doesn't matter what field you select). Exim is interested
7460 only in whether or not the query succeeds. However, when a lookup is used
7461 for the domains option on a router, the data is preserved in the
7462 $domain_data variable and can be referred to in other options.
7464 * If none of the above cases apply, a caseless textual comparison is made
7465 between the pattern and the domain.
7467 Here is an example that uses several different kinds of pattern:
7469 domainlist funny_domains = \
7472 *.foundation.fict.example : \
7473 \N^[1-2]\d{3}\.fict\.example$\N : \
7474 partial-dbm;/opt/data/penguin/book : \
7475 nis;domains.byname : \
7476 nisplus;[name=$domain,status=local],domains.org_dir
7478 There are obvious processing trade-offs among the various matching modes. Using
7479 an asterisk is faster than a regular expression, and listing a few names
7480 explicitly probably is too. The use of a file or database lookup is expensive,
7481 but may be the only option if hundreds of names are required. Because the
7482 patterns are tested in order, it makes sense to put the most commonly matched
7489 Host lists are used to control what remote hosts are allowed to do. For
7490 example, some hosts may be allowed to use the local host as a relay, and some
7491 may be permitted to use the SMTP ETRN command. Hosts can be identified in two
7492 different ways, by name or by IP address. In a host list, some types of pattern
7493 are matched to a host name, and some are matched to an IP address. You need to
7494 be particularly careful with this when single-key lookups are involved, to
7495 ensure that the right value is being used as the key.
7498 10.10 Special host list patterns
7499 --------------------------------
7501 If a host list item is the empty string, it matches only when no remote host is
7502 involved. This is the case when a message is being received from a local
7503 process using SMTP on the standard input, that is, when a TCP/IP connection is
7506 The special pattern "*" in a host list matches any host or no host. Neither the
7507 IP address nor the name is actually inspected.
7510 10.11 Host list patterns that match by IP address
7511 -------------------------------------------------
7513 If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
7514 the incoming address actually appears in the IPv6 host as "::ffff:"<v4address>.
7515 When such an address is tested against a host list, it is converted into a
7516 traditional IPv4 address first. (Not all operating systems accept IPv4 calls on
7517 IPv6 sockets, as there have been some security concerns.)
7519 The following types of pattern in a host list check the remote host by
7520 inspecting its IP address:
7522 * If the pattern is a plain domain name (not a regular expression, not
7523 starting with *, not a lookup of any kind), Exim calls the operating system
7524 function to find the associated IP address(es). Exim uses the newer
7525 getipnodebyname() function when available, otherwise gethostbyname(). This
7526 typically causes a forward DNS lookup of the name. The result is compared
7527 with the IP address of the subject host.
7529 If there is a temporary problem (such as a DNS timeout) with the host name
7530 lookup, a temporary error occurs. For example, if the list is being used in
7531 an ACL condition, the ACL gives a "defer" response, usually leading to a
7532 temporary SMTP error code. If no IP address can be found for the host name,
7533 what happens is described in section 10.14 below.
7535 * If the pattern is "@", the primary host name is substituted and used as a
7536 domain name, as just described.
7538 * If the pattern is an IP address, it is matched against the IP address of
7539 the subject host. IPv4 addresses are given in the normal "dotted-quad"
7540 notation. IPv6 addresses can be given in colon-separated format, but the
7541 colons have to be doubled so as not to be taken as item separators when the
7542 default list separator is used. IPv6 addresses are recognized even when
7543 Exim is compiled without IPv6 support. This means that if they appear in a
7544 host list on an IPv4-only host, Exim will not treat them as host names.
7545 They are just addresses that can never match a client host.
7547 * If the pattern is "@[]", it matches the IP address of any IP interface on
7548 the local host. For example, if the local host is an IPv4 host with one
7549 interface address 10.45.23.56, these two ACL statements have the same
7552 accept hosts = 127.0.0.1 : 10.45.23.56
7555 * If the pattern is an IP address followed by a slash and a mask length (for
7556 example 10.11.42.0/24), it is matched against the IP address of the subject
7557 host under the given mask. This allows, an entire network of hosts to be
7558 included (or excluded) by a single item. The mask uses CIDR notation; it
7559 specifies the number of address bits that must match, starting from the
7560 most significant end of the address.
7562 Note: The mask is not a count of addresses, nor is it the high number of a
7563 range of addresses. It is the number of bits in the network portion of the
7564 address. The above example specifies a 24-bit netmask, so it matches all
7565 256 addresses in the 10.11.42.0 network. An item such as
7569 matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value
7570 of 32 for an IPv4 address is the same as no mask at all; just a single
7573 Here is another example which shows an IPv4 and an IPv6 network:
7575 recipient_unqualified_hosts = 192.168.0.0/16: \
7576 3ffe::ffff::836f::::/48
7578 The doubling of list separator characters applies only when these items
7579 appear inline in a host list. It is not required when indirecting via a
7582 recipient_unqualified_hosts = /opt/exim/unqualnets
7584 could make use of a file containing
7589 to have exactly the same effect as the previous example. When listing IPv6
7590 addresses inline, it is usually more convenient to use the facility for
7591 changing separator characters. This list contains the same two networks:
7593 recipient_unqualified_hosts = <; 172.16.0.0/12; \
7596 The separator is changed to semicolon by the leading "<;" at the start of
7600 10.12 Host list patterns for single-key lookups by host address
7601 ---------------------------------------------------------------
7603 When a host is to be identified by a single-key lookup of its complete IP
7604 address, the pattern takes this form:
7606 net-<single-key-search-type>;<search-data>
7610 hosts_lookup = net-cdb;/hosts-by-ip.db
7612 The text form of the IP address of the subject host is used as the lookup key.
7613 IPv6 addresses are converted to an unabbreviated form, using lower case
7614 letters, with dots as separators because colon is the key terminator in lsearch
7615 files. [Colons can in fact be used in keys in lsearch files by quoting the
7616 keys, but this is a facility that was added later.] The data returned by the
7619 Single-key lookups can also be performed using masked IP addresses, using
7620 patterns of this form:
7622 net<number>-<single-key-search-type>;<search-data>
7626 net24-dbm;/networks.db
7628 The IP address of the subject host is masked using <number> as the mask length.
7629 A textual string is constructed from the masked value, followed by the mask,
7630 and this is used as the lookup key. For example, if the host's IP address is
7631 192.168.34.6, the key that is looked up for the above example is "192.168.34.0/
7634 When an IPv6 address is converted to a string, dots are normally used instead
7635 of colons, so that keys in lsearch files need not contain colons (which
7636 terminate lsearch keys). This was implemented some time before the ability to
7637 quote keys was made available in lsearch files. However, the more recently
7638 implemented iplsearch files do require colons in IPv6 keys (notated using the
7639 quoting facility) so as to distinguish them from IPv4 keys. For this reason,
7640 when the lookup type is iplsearch, IPv6 addresses are converted using colons
7641 and not dots. In all cases, full, unabbreviated IPv6 addresses are always used.
7643 Ideally, it would be nice to tidy up this anomalous situation by changing to
7644 colons in all cases, given that quoting is now available for lsearch. However,
7645 this would be an incompatible change that might break some existing
7648 Warning: Specifying net32- (for an IPv4 address) or net128- (for an IPv6
7649 address) is not the same as specifying just net- without a number. In the
7650 former case the key strings include the mask value, whereas in the latter case
7651 the IP address is used on its own.
7654 10.13 Host list patterns that match by host name
7655 ------------------------------------------------
7657 There are several types of pattern that require Exim to know the name of the
7658 remote host. These are either wildcard patterns or lookups by name. (If a
7659 complete hostname is given without any wildcarding, it is used to find an IP
7660 address to match against, as described in section 10.11 above.)
7662 If the remote host name is not already known when Exim encounters one of these
7663 patterns, it has to be found from the IP address. Although many sites on the
7664 Internet are conscientious about maintaining reverse DNS data for their hosts,
7665 there are also many that do not do this. Consequently, a name cannot always be
7666 found, and this may lead to unwanted effects. Take care when configuring host
7667 lists with wildcarded name patterns. Consider what will happen if a name cannot
7670 Because of the problems of determining host names from IP addresses, matching
7671 against host names is not as common as matching against IP addresses.
7673 By default, in order to find a host name, Exim first does a reverse DNS lookup;
7674 if no name is found in the DNS, the system function (gethostbyaddr() or
7675 getipnodebyaddr() if available) is tried. The order in which these lookups are
7676 done can be changed by setting the host_lookup_order option. For security, once
7677 Exim has found one or more names, it looks up the IP addresses for these names
7678 and compares them with the IP address that it started with. Only those names
7679 whose IP addresses match are accepted. Any other names are discarded. If no
7680 names are left, Exim behaves as if the host name cannot be found. In the most
7681 common case there is only one name and one IP address.
7683 There are some options that control what happens if a host name cannot be
7684 found. These are described in section 10.14 below.
7686 As a result of aliasing, hosts may have more than one name. When processing any
7687 of the following types of pattern, all the host's names are checked:
7689 * If a pattern starts with "*" the remainder of the item must match the end
7690 of the host name. For example, "*.b.c" matches all hosts whose names end in
7691 .b.c. This special simple form is provided because this is a very common
7692 requirement. Other kinds of wildcarding require the use of a regular
7695 * If the item starts with "^" it is taken to be a regular expression which is
7696 matched against the host name. Host names are case-independent, so this
7697 regular expression match is by default case-independent, but you can make
7698 it case-dependent by starting it with "(?-i)". References to descriptions
7699 of the syntax of regular expressions are given in chapter 8. For example,
7703 is a regular expression that matches either of the two hosts a.c.d or b.c.d
7704 . When a regular expression is used in a host list, you must take care that
7705 backslash and dollar characters are not misinterpreted as part of the
7706 string expansion. The simplest way to do this is to use "\N" to mark that
7707 part of the string as non-expandable. For example:
7709 sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
7711 Warning: If you want to match a complete host name, you must include the
7712 "$" terminating metacharacter in the regular expression, as in the above
7713 example. Without it, a match at the start of the host name is all that is
7717 10.14 Behaviour when an IP address or name cannot be found
7718 ----------------------------------------------------------
7720 While processing a host list, Exim may need to look up an IP address from a
7721 name (see section 10.11), or it may need to look up a host name from an IP
7722 address (see section 10.13). In either case, the behaviour when it fails to
7723 find the information it is seeking is the same.
7725 Note: This section applies to permanent lookup failures. It does not apply to
7726 temporary DNS errors, whose handling is described in the next section.
7728 Exim parses a host list from left to right. If it encounters a permanent lookup
7729 failure in any item in the host list before it has found a match, Exim treats
7730 it as a failure and the default behavior is as if the host does not match the
7731 list. This may not always be what you want to happen. To change Exim's
7732 behaviour, the special items "+include_unknown" or "+ignore_unknown" may appear
7733 in the list (at top level - they are not recognized in an indirected file).
7735 * If any item that follows "+include_unknown" requires information that
7736 cannot found, Exim behaves as if the host does match the list. For example,
7738 host_reject_connection = +include_unknown:*.enemy.ex
7740 rejects connections from any host whose name matches "*.enemy.ex", and also
7741 any hosts whose name it cannot find.
7743 * If any item that follows "+ignore_unknown" requires information that cannot
7744 be found, Exim ignores that item and proceeds to the rest of the list. For
7747 accept hosts = +ignore_unknown : friend.example : \
7750 accepts from any host whose name is friend.example and from 192.168.4.5,
7751 whether or not its host name can be found. Without "+ignore_unknown", if no
7752 name can be found for 192.168.4.5, it is rejected.
7754 Both "+include_unknown" and "+ignore_unknown" may appear in the same list. The
7755 effect of each one lasts until the next, or until the end of the list.
7758 10.15 Mixing wildcarded host names and addresses in host lists
7759 --------------------------------------------------------------
7761 This section explains the host/ip processing logic with the same concepts as
7762 the previous section, but specifically addresses what happens when a wildcarded
7763 hostname is one of the items in the hostlist.
7765 * If you have name lookups or wildcarded host names and IP addresses in the
7766 same host list, you should normally put the IP addresses first. For
7767 example, in an ACL you could have:
7769 accept hosts = 10.9.8.7 : *.friend.example
7771 The reason you normally would order it this way lies in the left-to-right
7772 way that Exim processes lists. It can test IP addresses without doing any
7773 DNS lookups, but when it reaches an item that requires a host name, it
7774 fails if it cannot find a host name to compare with the pattern. If the
7775 above list is given in the opposite order, the accept statement fails for a
7776 host whose name cannot be found, even if its IP address is 10.9.8.7.
7778 * If you really do want to do the name check first, and still recognize the
7779 IP address, you can rewrite the ACL like this:
7781 accept hosts = *.friend.example
7782 accept hosts = 10.9.8.7
7784 If the first accept fails, Exim goes on to try the second one. See chapter
7785 42 for details of ACLs. Alternatively, you can use "+ignore_unknown", which
7786 was discussed in depth in the first example in this section.
7789 10.16 Temporary DNS errors when looking up host information
7790 -----------------------------------------------------------
7792 A temporary DNS lookup failure normally causes a defer action (except when
7793 dns_again_means_nonexist converts it into a permanent error). However, host
7794 lists can include "+ignore_defer" and "+include_defer", analagous to
7795 "+ignore_unknown" and "+include_unknown", as described in the previous section.
7796 These options should be used with care, probably only in non-critical host
7797 lists such as whitelists.
7800 10.17 Host list patterns for single-key lookups by host name
7801 ------------------------------------------------------------
7803 If a pattern is of the form
7805 <single-key-search-type>;<search-data>
7809 dbm;/host/accept/list
7811 a single-key lookup is performed, using the host name as its key. If the lookup
7812 succeeds, the host matches the item. The actual data that is looked up is not
7815 Reminder: With this kind of pattern, you must have host names as keys in the
7816 file, not IP addresses. If you want to do lookups based on IP addresses, you
7817 must precede the search type with "net-" (see section 10.12). There is,
7818 however, no reason why you could not use two items in the same list, one doing
7819 an address lookup and one doing a name lookup, both using the same file.
7822 10.18 Host list patterns for query-style lookups
7823 ------------------------------------------------
7825 If a pattern is of the form
7827 <query-style-search-type>;<query>
7829 the query is obeyed, and if it succeeds, the host matches the item. The actual
7830 data that is looked up is not used. The variables $sender_host_address and
7831 $sender_host_name can be used in the query. For example:
7833 hosts_lookup = pgsql;\
7834 select ip from hostlist where ip='$sender_host_address'
7836 The value of $sender_host_address for an IPv6 address contains colons. You can
7837 use the sg expansion item to change this if you need to. If you want to use
7838 masked IP addresses in database queries, you can use the mask expansion
7841 If the query contains a reference to $sender_host_name, Exim automatically
7842 looks up the host name if it has not already done so. (See section 10.13 for
7843 comments on finding host names.)
7845 Historical note: prior to release 4.30, Exim would always attempt to find a
7846 host name before running the query, unless the search type was preceded by
7847 "net-". This is no longer the case. For backwards compatibility, "net-" is
7848 still recognized for query-style lookups, but its presence or absence has no
7849 effect. (Of course, for single-key lookups, "net-" is important. See section
7856 Address lists contain patterns that are matched against mail addresses. There
7857 is one special case to be considered: the sender address of a bounce message is
7858 always empty. You can test for this by providing an empty item in an address
7859 list. For example, you can set up a router to process bounce messages by using
7860 this option setting:
7864 The presence of the colon creates an empty item. If you do not provide any
7865 data, the list is empty and matches nothing. The empty sender can also be
7866 detected by a regular expression that matches an empty string, and by a
7867 query-style lookup that succeeds when $sender_address is empty.
7869 Non-empty items in an address list can be straightforward email addresses. For
7872 senders = jbc@askone.example : hs@anacreon.example
7874 A certain amount of wildcarding is permitted. If a pattern contains an @
7875 character, but is not a regular expression and does not begin with a
7876 semicolon-terminated lookup type (described below), the local part of the
7877 subject address is compared with the local part of the pattern, which may start
7878 with an asterisk. If the local parts match, the domain is checked in exactly
7879 the same way as for a pattern in a domain list. For example, the domain can be
7880 wildcarded, refer to a named list, or be a lookup:
7882 deny senders = *@*.spamming.site:\
7883 *@+hostile_domains:\
7884 bozo@partial-lsearch;/list/of/dodgy/sites:\
7885 *@dbm;/bad/domains.db
7887 If a local part that begins with an exclamation mark is required, it has to be
7888 specified using a regular expression, because otherwise the exclamation mark is
7889 treated as a sign of negation, as is standard in lists.
7891 If a non-empty pattern that is not a regular expression or a lookup does not
7892 contain an @ character, it is matched against the domain part of the subject
7893 address. The only two formats that are recognized this way are a literal
7894 domain, or a domain pattern that starts with *. In both these cases, the effect
7895 is the same as if "*@" preceded the pattern. For example:
7897 deny senders = enemy.domain : *.enemy.domain
7899 The following kinds of more complicated address list pattern can match any
7900 address, including the empty address that is characteristic of bounce message
7903 * If (after expansion) a pattern starts with "^", a regular expression match
7904 is done against the complete address, with the pattern as the regular
7905 expression. You must take care that backslash and dollar characters are not
7906 misinterpreted as part of the string expansion. The simplest way to do this
7907 is to use "\N" to mark that part of the string as non-expandable. For
7910 deny senders = \N^.*this.*@example\.com$\N : \
7911 \N^\d{8}.+@spamhaus.example$\N : ...
7913 The "\N" sequences are removed by the expansion, so these items do indeed
7914 start with "^" by the time they are being interpreted as address patterns.
7916 * Complete addresses can be looked up by using a pattern that starts with a
7917 lookup type terminated by a semicolon, followed by the data for the lookup.
7920 deny senders = cdb;/etc/blocked.senders : \
7921 mysql;select address from blocked where \
7922 address='${quote_mysql:$sender_address}'
7924 Both query-style and single-key lookup types can be used. For a single-key
7925 lookup type, Exim uses the complete address as the key. However, empty keys
7926 are not supported for single-key lookups, so a match against the empty
7927 address always fails. This restriction does not apply to query-style
7930 Partial matching for single-key lookups (section 9.7) cannot be used, and
7931 is ignored if specified, with an entry being written to the panic log.
7932 However, you can configure lookup defaults, as described in section 9.6,
7933 but this is useful only for the "*@" type of default. For example, with
7936 accept senders = lsearch*@;/some/file
7938 the file could contains lines like this:
7940 user1@domain1.example
7943 and for the sender address nimrod@jaeger.example, the sequence of keys that
7946 nimrod@jaeger.example
7950 Warning 1: Do not include a line keyed by "*" in the file, because that
7951 would mean that every address matches, thus rendering the test useless.
7953 Warning 2: Do not confuse these two kinds of item:
7955 deny recipients = dbm*@;/some/file
7956 deny recipients = *@dbm;/some/file
7958 The first does a whole address lookup, with defaulting, as just described,
7959 because it starts with a lookup type. The second matches the local part and
7960 domain independently, as described in a bullet point below.
7962 The following kinds of address list pattern can match only non-empty addresses.
7963 If the subject address is empty, a match against any of these pattern types
7966 * If a pattern starts with "@@" followed by a single-key lookup item (for
7967 example, "@@lsearch;/some/file"), the address that is being checked is
7968 split into a local part and a domain. The domain is looked up in the file.
7969 If it is not found, there is no match. If it is found, the data that is
7970 looked up from the file is treated as a colon-separated list of local part
7971 patterns, each of which is matched against the subject local part in turn.
7973 The lookup may be a partial one, and/or one involving a search for a
7974 default keyed by "*" (see section 9.6). The local part patterns that are
7975 looked up can be regular expressions or begin with "*", or even be further
7976 lookups. They may also be independently negated. For example, with
7978 deny senders = @@dbm;/etc/reject-by-domain
7980 the data from which the DBM file is built could contain lines like
7982 baddomain.com: !postmaster : *
7984 to reject all senders except postmaster from that domain.
7986 If a local part that actually begins with an exclamation mark is required,
7987 it has to be specified using a regular expression. In lsearch files, an
7988 entry may be split over several lines by indenting the second and
7989 subsequent lines, but the separating colon must still be included at line
7990 breaks. White space surrounding the colons is ignored. For example:
7992 aol.com: spammer1 : spammer2 : ^[0-9]+$ :
7995 As in all colon-separated lists in Exim, a colon can be included in an item
7998 If the last item in the list starts with a right angle-bracket, the
7999 remainder of the item is taken as a new key to look up in order to obtain a
8000 continuation list of local parts. The new key can be any sequence of
8001 characters. Thus one might have entries like
8003 aol.com: spammer1 : spammer 2 : >*
8004 xyz.com: spammer3 : >*
8007 in a file that was searched with @@dbm*, to specify a match for 8-digit
8008 local parts for all domains, in addition to the specific local parts listed
8009 for each domain. Of course, using this feature costs another lookup each
8010 time a chain is followed, but the effort needed to maintain the data is
8013 It is possible to construct loops using this facility, and in order to
8014 catch them, the chains may be no more than fifty items long.
8016 * The @@<lookup> style of item can also be used with a query-style lookup,
8017 but in this case, the chaining facility is not available. The lookup can
8018 only return a single list of local parts.
8020 Warning: There is an important difference between the address list items in
8024 senders = *@+my_list
8026 In the first one, "my_list" is a named address list, whereas in the second
8027 example it is a named domain list.
8030 10.20 Case of letters in address lists
8031 --------------------------------------
8033 Domains in email addresses are always handled caselessly, but for local parts
8034 case may be significant on some systems (see caseful_local_part for how Exim
8035 deals with this when routing addresses). However, RFC 2505 (Anti-Spam
8036 Recommendations for SMTP MTAs) suggests that matching of addresses to blocking
8037 lists should be done in a case-independent manner. Since most address lists in
8038 Exim are used for this kind of control, Exim attempts to do this by default.
8040 The domain portion of an address is always lowercased before matching it to an
8041 address list. The local part is lowercased by default, and any string
8042 comparisons that take place are done caselessly. This means that the data in
8043 the address list itself, in files included as plain file names, and in any file
8044 that is looked up using the "@@" mechanism, can be in any case. However, the
8045 keys in files that are looked up by a search type other than lsearch (which
8046 works caselessly) must be in lower case, because these lookups are not
8049 To allow for the possibility of caseful address list matching, if an item in an
8050 address list is the string "+caseful", the original case of the local part is
8051 restored for any comparisons that follow, and string comparisons are no longer
8052 case-independent. This does not affect the domain, which remains in lower case.
8053 However, although independent matches on the domain alone are still performed
8054 caselessly, regular expressions that match against an entire address become
8055 case-sensitive after "+caseful" has been seen.
8058 10.21 Local part lists
8059 ----------------------
8061 Case-sensitivity in local part lists is handled in the same way as for address
8062 lists, as just described. The "+caseful" item can be used if required. In a
8063 setting of the local_parts option in a router with caseful_local_part set
8064 false, the subject is lowercased and the matching is initially
8065 case-insensitive. In this case, "+caseful" will restore case-sensitive matching
8066 in the local part list, but not elsewhere in the router. If caseful_local_part
8067 is set true in a router, matching in the local_parts option is case-sensitive
8070 If a local part list is indirected to a file (see section 10.3), comments are
8071 handled in the same way as address lists - they are recognized only if the # is
8072 preceded by white space or the start of the line. Otherwise, local part lists
8073 are matched in the same way as domain lists, except that the special items that
8074 refer to the local host ("@", "@[]", "@mx_any", "@mx_primary", and
8075 "@mx_secondary") are not recognized. Refer to section 10.8 for details of the
8076 other available item types.
8080 ===============================================================================
8081 11. STRING EXPANSIONS
8083 Many strings in Exim's run time configuration are expanded before use. Some of
8084 them are expanded every time they are used; others are expanded only once.
8086 When a string is being expanded it is copied verbatim from left to right except
8087 when a dollar or backslash character is encountered. A dollar specifies the
8088 start of a portion of the string that is interpreted and replaced as described
8089 below in section 11.5 onwards. Backslash is used as an escape character, as
8090 described in the following section.
8092 Whether a string is expanded depends upon the context. Usually this is solely
8093 dependent upon the option for which a value is sought; in this documentation,
8094 options for which string expansion is performed are marked with * after the
8095 data type. ACL rules always expand strings. A couple of expansion conditions do
8096 not expand some of the brace-delimited branches, for security reasons.
8099 11.1 Literal text in expanded strings
8100 -------------------------------------
8102 An uninterpreted dollar can be included in an expanded string by putting a
8103 backslash in front of it. A backslash can be used to prevent any special
8104 character being treated specially in an expansion, including backslash itself.
8105 If the string appears in quotes in the configuration file, two backslashes are
8106 required because the quotes themselves cause interpretation of backslashes when
8107 the string is read in (see section 6.16).
8109 A portion of the string can specified as non-expandable by placing it between
8110 two occurrences of "\N". This is particularly useful for protecting regular
8111 expressions, which often contain backslashes and dollar signs. For example:
8113 deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
8115 On encountering the first "\N", the expander copies subsequent characters
8116 without interpretation until it reaches the next "\N" or the end of the string.
8119 11.2 Character escape sequences in expanded strings
8120 ---------------------------------------------------
8122 A backslash followed by one of the letters "n", "r", or "t" in an expanded
8123 string is recognized as an escape sequence for the character newline, carriage
8124 return, or tab, respectively. A backslash followed by up to three octal digits
8125 is recognized as an octal encoding for a single character, and a backslash
8126 followed by "x" and up to two hexadecimal digits is a hexadecimal encoding.
8128 These escape sequences are also recognized in quoted strings when they are read
8129 in. Their interpretation in expansions as well is useful for unquoted strings,
8130 and for other cases such as looked-up strings that are then expanded.
8133 11.3 Testing string expansions
8134 ------------------------------
8136 Many expansions can be tested by calling Exim with the -be option. This takes
8137 the command arguments, or lines from the standard input if there are no
8138 arguments, runs them through the string expansion code, and writes the results
8139 to the standard output. Variables based on configuration values are set up, but
8140 since no message is being processed, variables such as $local_part have no
8141 value. Nevertheless the -be option can be useful for checking out file and
8142 database lookups, and the use of expansion operators such as sg, substr and
8145 Exim gives up its root privilege when it is called with the -be option, and
8146 instead runs under the uid and gid it was called with, to prevent users from
8147 using -be for reading files to which they do not have access.
8149 If you want to test expansions that include variables whose values are taken
8150 from a message, there are two other options that can be used. The -bem option
8151 is like -be except that it is followed by a file name. The file is read as a
8152 message before doing the test expansions. For example:
8154 exim -bem /tmp/test.message '$h_subject:'
8156 The -Mset option is used in conjunction with -be and is followed by an Exim
8157 message identifier. For example:
8159 exim -be -Mset 1GrA8W-0004WS-LQ '$recipients'
8161 This loads the message from Exim's spool before doing the test expansions, and
8162 is therefore restricted to admin users.
8165 11.4 Forced expansion failure
8166 -----------------------------
8168 A number of expansions that are described in the following section have
8169 alternative "true" and "false" substrings, enclosed in brace characters (which
8170 are sometimes called "curly brackets"). Which of the two strings is used
8171 depends on some condition that is evaluated as part of the expansion. If,
8172 instead of a "false" substring, the word "fail" is used (not in braces), the
8173 entire string expansion fails in a way that can be detected by the code that
8174 requested the expansion. This is called "forced expansion failure", and its
8175 consequences depend on the circumstances. In some cases it is no different from
8176 any other expansion failure, but in others a different action may be taken.
8177 Such variations are mentioned in the documentation of the option that is being
8181 11.5 Expansion items
8182 --------------------
8184 The following items are recognized in expanded strings. White space may be used
8185 between sub-items that are keywords or substrings enclosed in braces inside an
8186 outer set of braces, to improve readability. Warning: Within braces, white
8187 space is significant.
8189 $<variable name> or ${<variable name>}
8191 Substitute the contents of the named variable, for example:
8196 The second form can be used to separate the name from subsequent
8197 alphanumeric characters. This form (using braces) is available only for
8198 variables; it does not apply to message headers. The names of the variables
8199 are given in section 11.9 below. If the name of a non-existent variable is
8200 given, the expansion fails.
8204 The string is first itself expanded, and then the operation specified by <
8205 op> is applied to it. For example:
8209 The string starts with the first character after the colon, which may be
8210 leading white space. A list of operators is given in section 11.6 below.
8211 The operator notation is used for simple expansion items that have just one
8212 argument, because it reduces the number of braces and therefore makes the
8213 string easier to understand.
8215 $bheader_<header name>: or $bh_<header name>:
8217 This item inserts "basic" header lines. It is described with the header
8218 expansion item below.
8220 ${acl{<name>}{<arg>}...}
8222 The name and zero to nine argument strings are first expanded separately.
8223 The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
8224 in order. Any unused are made empty. The variable $acl_narg is set to the
8225 number of arguments. The named ACL (see chapter 42) is called and may use
8226 the variables; if another acl expansion is used the values are restored
8227 after it returns. If the ACL sets a value using a "message =" modifier and
8228 returns accept or deny, the value becomes the result of the expansion. If
8229 no message is set and the ACL returns accept or deny the expansion result
8230 is an empty string. If the ACL returns defer the result is a forced-fail.
8231 Otherwise the expansion fails.
8233 ${certextract{<field>}{<certificate>}{<string2>}{<string3>}}
8235 The <certificate> must be a variable of type certificate. The field name is
8236 expanded and used to retrive the relevant field from the certificate.
8237 Supported fields are:
8247 subj_altname tagged list
8251 If the field is found, <string2> is expanded, and replaces the whole item;
8252 otherwise <string3> is used. During the expansion of <string2> the variable
8253 $value contains the value that has been extracted. Afterwards, it is
8254 restored to any previous value it might have had.
8256 If {<string3>} is omitted, the item is replaced by an empty string if the
8257 key is not found. If {<string2>} is also omitted, the value that was
8260 Some field names take optional modifiers, appended and separated by commas.
8262 The field selectors marked as "RFC4514" above output a Distinguished Name
8263 string which is not quite parseable by Exim as a comma-separated tagged
8264 list (the exceptions being elements containin commas). RDN elements of a
8265 single type may be selected by a modifier of the type label; if so the
8266 expansion result is a list (newline-separated by default). The separator
8267 may be changed by another modifer of a right angle-bracket followed
8268 immediately by the new separator. Recognised RDN type labels include "CN",
8271 The field selectors marked as "time" above may output a number of seconds
8272 since epoch if the modifier "int" is used.
8274 The field selectors marked as "list" above return a list, newline-separated
8275 by default, (embedded separator characters in elements are doubled). The
8276 separator may be changed by a modifier of a right angle-bracket followed
8277 immediately by the new separator.
8279 The field selectors marked as "tagged" above prefix each list element with
8280 a type string and an equals sign. Elements of only one type may be selected
8281 by a modifier which is one of "dns", "uri" or "mail"; if so the elenment
8284 If not otherwise noted field values are presented in human-readable form.
8286 ${dlfunc{<file>}{<function>}{<arg>}{<arg>}...}
8288 This expansion dynamically loads and then calls a locally-written C
8289 function. This functionality is available only if Exim is compiled with
8293 set in Local/Makefile. Once loaded, Exim remembers the dynamically loaded
8294 object so that it doesn't reload the same object file in the same Exim
8295 process (but of course Exim does start new processes frequently).
8297 There may be from zero to eight arguments to the function. When compiling a
8298 local function that is to be called in this way, local_scan.h should be
8299 included. The Exim variables and functions that are defined by that API are
8300 also available for dynamically loaded functions. The function itself must
8301 have the following type:
8303 int dlfunction(uschar **yield, int argc, uschar *argv[])
8305 Where "uschar" is a typedef for "unsigned char" in local_scan.h. The
8306 function should return one of the following values:
8308 "OK": Success. The string that is placed in the variable yield is put into
8309 the expanded string that is being built.
8311 "FAIL": A non-forced expansion failure occurs, with the error message taken
8312 from yield, if it is set.
8314 "FAIL_FORCED": A forced expansion failure occurs, with the error message
8315 taken from yield if it is set.
8317 "ERROR": Same as "FAIL", except that a panic log entry is written.
8319 When compiling a function that is to be used in this way with gcc, you need
8320 to add -shared to the gcc command. Also, in the Exim build-time
8321 configuration, you must add -export-dynamic to EXTRALIBS.
8323 ${extract{<key>}{<string1>}{<string2>}{<string3>}}
8325 The key and <string1> are first expanded separately. Leading and trailing
8326 white space is removed from the key (but not from any of the strings). The
8327 key must not consist entirely of digits. The expanded <string1> must be of
8330 <key1> = <value1> <key2> = <value2> ...
8332 where the equals signs and spaces (but not both) are optional. If any of
8333 the values contain white space, they must be enclosed in double quotes, and
8334 any values that are enclosed in double quotes are subject to escape
8335 processing as described in section 6.16. The expanded <string1> is searched
8336 for the value that corresponds to the key. The search is case-insensitive.
8337 If the key is found, <string2> is expanded, and replaces the whole item;
8338 otherwise <string3> is used. During the expansion of <string2> the variable
8339 $value contains the value that has been extracted. Afterwards, it is
8340 restored to any previous value it might have had.
8342 If {<string3>} is omitted, the item is replaced by an empty string if the
8343 key is not found. If {<string2>} is also omitted, the value that was
8344 extracted is used. Thus, for example, these two expansions are identical,
8347 ${extract{gid}{uid=1984 gid=2001}}
8348 ${extract{gid}{uid=1984 gid=2001}{$value}}
8350 Instead of {<string3>} the word "fail" (not in curly brackets) can appear,
8353 ${extract{Z}{A=... B=...}{$value} fail }
8355 This forces an expansion failure (see section 11.4); {<string2>} must be
8356 present for "fail" to be recognized.
8358 ${extract{<number>}{<separators>}{<string1>}{<string2>}{<string3>}}
8360 The <number> argument must consist entirely of decimal digits, apart from
8361 leading and trailing white space, which is ignored. This is what
8362 distinguishes this form of extract from the previous kind. It behaves in
8363 the same way, except that, instead of extracting a named field, it extracts
8364 from <string1> the field whose number is given as the first argument. You
8365 can use $value in <string2> or "fail" instead of <string3> as before.
8367 The fields in the string are separated by any one of the characters in the
8368 separator string. These may include space or tab characters. The first
8369 field is numbered one. If the number is negative, the fields are counted
8370 from the end of the string, with the rightmost one numbered -1. If the
8371 number given is zero, the entire string is returned. If the modulus of the
8372 number is greater than the number of fields in the string, the result is
8373 the expansion of <string3>, or the empty string if <string3> is not
8374 provided. For example:
8376 ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}}
8380 ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}}
8382 yields "99". Two successive separators mean that the field between them is
8383 empty (for example, the fifth field above).
8385 ${filter{<string>}{<condition>}}
8387 After expansion, <string> is interpreted as a list, colon-separated by
8388 default, but the separator can be changed in the usual way. For each item
8389 in this list, its value is place in $item, and then the condition is
8390 evaluated. If the condition is true, $item is added to the output as an
8391 item in a new list; if the condition is false, the item is discarded. The
8392 separator used for the output list is the same as the one used for the
8393 input, but a separator setting is not included in the output. For example:
8395 ${filter{a:b:c}{!eq{$item}{b}}
8397 yields "a:c". At the end of the expansion, the value of $item is restored
8398 to what it was before. See also the map and reduce expansion items.
8400 ${hash{<string1>}{<string2>}{<string3>}}
8402 This is a textual hashing function, and was the first to be implemented in
8403 early versions of Exim. In current releases, there are other hashing
8404 functions (numeric, MD5, and SHA-1), which are described below.
8406 The first two strings, after expansion, must be numbers. Call them <m> and
8407 <n>. If you are using fixed values for these numbers, that is, if <string1>
8408 and <string2> do not change when they are expanded, you can use the simpler
8409 operator notation that avoids some of the braces:
8411 ${hash_<n>_<m>:<string>}
8413 The second number is optional (in both notations). If <n> is greater than
8414 or equal to the length of the string, the expansion item returns the
8415 string. Otherwise it computes a new string of length <n> by applying a
8416 hashing function to the string. The new string consists of characters taken
8417 from the first <m> characters of the string
8419 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
8421 If <m> is not present the value 26 is used, so that only lower case letters
8422 appear. For example:
8424 $hash{3}{monty}} yields jmg
8425 $hash{5}{monty}} yields monty
8426 $hash{4}{62}{monty python}} yields fbWx
8428 $header_<header name>: or $h_<header name>:, $bheader_<header name>: or $bh_<
8429 header name>:, $rheader_<header name>: or $rh_<header name>:
8431 Substitute the contents of the named message header line, for example
8435 The newline that terminates a header line is not included in the expansion,
8436 but internal newlines (caused by splitting the header line over several
8437 physical lines) may be present.
8439 The difference between rheader, bheader, and header is in the way the data
8440 in the header line is interpreted.
8442 * rheader gives the original "raw" content of the header line, with no
8443 processing at all, and without the removal of leading and trailing
8446 * bheader removes leading and trailing white space, and then decodes
8447 base64 or quoted-printable MIME "words" within the header text, but
8448 does no character set translation. If decoding of what looks
8449 superficially like a MIME "word" fails, the raw string is returned. If
8450 decoding produces a binary zero character, it is replaced by a question
8451 mark - this is what Exim does for binary zeros that are actually
8452 received in header lines.
8454 * header tries to translate the string as decoded by bheader to a
8455 standard character set. This is an attempt to produce the same string
8456 as would be displayed on a user's MUA. If translation fails, the
8457 bheader string is returned. Translation is attempted only on operating
8458 systems that support the iconv() function. This is indicated by the
8459 compile-time macro HAVE_ICONV in a system Makefile or in Local/Makefile
8462 In a filter file, the target character set for header can be specified by a
8463 command of the following form:
8465 headers charset "UTF-8"
8467 This command affects all references to $h_ (or $header_) expansions in
8468 subsequently obeyed filter commands. In the absence of this command, the
8469 target character set in a filter is taken from the setting of the
8470 headers_charset option in the runtime configuration. The value of this
8471 option defaults to the value of HEADERS_CHARSET in Local/Makefile. The
8472 ultimate default is ISO-8859-1.
8474 Header names follow the syntax of RFC 2822, which states that they may
8475 contain any printing characters except space and colon. Consequently, curly
8476 brackets do not terminate header names, and should not be used to enclose
8477 them as if they were variables. Attempting to do so causes a syntax error.
8479 Only header lines that are common to all copies of a message are visible to
8480 this mechanism. These are the original header lines that are received with
8481 the message, and any that are added by an ACL statement or by a system
8482 filter. Header lines that are added to a particular copy of a message by a
8483 router or transport are not accessible.
8485 For incoming SMTP messages, no header lines are visible in ACLs that are
8486 obeyed before the DATA ACL, because the header structure is not set up
8487 until the message is received. Header lines that are added in a RCPT ACL
8488 (for example) are saved until the message's incoming header lines are
8489 available, at which point they are added. When a DATA ACL is running,
8490 however, header lines added by earlier ACLs are visible.
8492 Upper case and lower case letters are synonymous in header names. If the
8493 following character is white space, the terminating colon may be omitted,
8494 but this is not recommended, because you may then forget it when it is
8495 needed. When white space terminates the header name, it is included in the
8496 expanded string. If the message does not contain the given header, the
8497 expansion item is replaced by an empty string. (See the def condition in
8498 section 11.7 for a means of testing for the existence of a header.)
8500 If there is more than one header with the same name, they are all
8501 concatenated to form the substitution string, up to a maximum length of
8502 64K. Unless rheader is being used, leading and trailing white space is
8503 removed from each header before concatenation, and a completely empty
8504 header is ignored. A newline character is then inserted between non-empty
8505 headers, but there is no newline at the very end. For the header and
8506 bheader expansion, for those headers that contain lists of addresses, a
8507 comma is also inserted at the junctions between headers. This does not
8508 happen for the rheader expansion.
8510 ${hmac{<hashname>}{<secret>}{<string>}}
8512 This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
8513 shared secret and some text into a message authentication code, as
8514 specified in RFC 2104. This differs from "${md5:secret_text...}" or "$
8515 {sha1:secret_text...}" in that the hmac step adds a signature to the
8516 cryptographic hash, allowing for authentication that is not possible with
8517 MD5 or SHA-1 alone. The hash name must expand to either "md5" or "sha1" at
8518 present. For example:
8520 ${hmac{md5}{somesecret}{$primary_hostname $tod_log}}
8522 For the hostname mail.example.com and time 2002-10-17 11:30:59, this
8525 dd97e3ba5d1a61b5006108f8c8252953
8527 As an example of how this might be used, you might put in the main part of
8528 an Exim configuration:
8530 SPAMSCAN_SECRET=cohgheeLei2thahw
8532 In a router or a transport you could then have:
8535 X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \
8536 ${hmac{md5}{SPAMSCAN_SECRET}\
8537 {${primary_hostname},${message_exim_id},$h_message-id:}}
8539 Then given a message, you can check where it was scanned by looking at the
8540 X-Spam-Scanned: header line. If you know the secret, you can check that
8541 this header line is authentic by recomputing the authentication code from
8542 the host name, message ID and the Message-id: header line. This can be done
8543 using Exim's -be option, or by other means, for example by using the
8544 hmac_md5_hex() function in Perl.
8546 ${if <condition> {<string1>}{<string2>}}
8548 If <condition> is true, <string1> is expanded and replaces the whole item;
8549 otherwise <string2> is used. The available conditions are described in
8550 section 11.7 below. For example:
8552 ${if eq {$local_part}{postmaster} {yes}{no} }
8554 The second string need not be present; if it is not and the condition is
8555 not true, the item is replaced with nothing. Alternatively, the word "fail"
8556 may be present instead of the second string (without any curly brackets).
8557 In this case, the expansion is forced to fail if the condition is not true
8560 If both strings are omitted, the result is the string "true" if the
8561 condition is true, and the empty string if the condition is false. This
8562 makes it less cumbersome to write custom ACL and router conditions. For
8565 condition = ${if >{$acl_m4}{3}{true}{false}}
8569 condition = ${if >{$acl_m4}{3}}
8571 ${length{<string1>}{<string2>}}
8573 The length item is used to extract the initial portion of a string. Both
8574 strings are expanded, and the first one must yield a number, <n>, say. If
8575 you are using a fixed value for the number, that is, if <string1> does not
8576 change when expanded, you can use the simpler operator notation that avoids
8579 ${length_<n>:<string>}
8581 The result of this item is either the first <n> characters or the whole of
8582 <string2>, whichever is the shorter. Do not confuse length with strlen,
8583 which gives the length of a string.
8585 ${listextract{<number>}{<string1>}{<string2>}{<string3>}}
8587 The <number> argument must consist entirely of decimal digits, apart from
8588 an optional leading minus, and leading and trailing white space (which is
8591 After expansion, <string1> is interpreted as a list, colon-separated by
8592 default, but the separator can be changed in the usual way.
8594 The first field of the list is numbered one. If the number is negative, the
8595 fields are counted from the end of the list, with the rightmost one
8596 numbered -1. The numbered element of the list is extracted and placed in
8597 $value, then <string2> is expanded as the result.
8599 If the modulus of the number is zero or greater than the number of fields
8600 in the string, the result is the expansion of <string3>.
8604 ${listextract{2}{x:42:99}}
8608 ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
8610 yields "result: 99".
8612 If {<string3>} is omitted, an empty string is used for string3. If {<
8613 string2>} is also omitted, the value that was extracted is used. You can
8614 use "fail" instead of {<string3>} as in a string extract.
8616 ${lookup{<key>} <search type> {<file>} {<string1>} {<string2>}}
8618 This is the first of one of two different types of lookup item, which are
8619 both described in the next item.
8621 ${lookup <search type> {<query>} {<string1>} {<string2>}}
8623 The two forms of lookup item specify data lookups in files and databases,
8624 as discussed in chapter 9. The first form is used for single-key lookups,
8625 and the second is used for query-style lookups. The <key>, <file>, and <
8626 query> strings are expanded before use.
8628 If there is any white space in a lookup item which is part of a filter
8629 command, a retry or rewrite rule, a routing rule for the manualroute
8630 router, or any other place where white space is significant, the lookup
8631 item must be enclosed in double quotes. The use of data lookups in users'
8632 filter files may be locked out by the system administrator.
8634 If the lookup succeeds, <string1> is expanded and replaces the entire item.
8635 During its expansion, the variable $value contains the data returned by the
8636 lookup. Afterwards it reverts to the value it had previously (at the outer
8637 level it is empty). If the lookup fails, <string2> is expanded and replaces
8638 the entire item. If {<string2>} is omitted, the replacement is the empty
8639 string on failure. If <string2> is provided, it can itself be a nested
8640 lookup, thus providing a mechanism for looking up a default value when the
8641 original lookup fails.
8643 If a nested lookup is used as part of <string1>, $value contains the data
8644 for the outer lookup while the parameters of the second lookup are
8645 expanded, and also while <string2> of the second lookup is expanded, should
8646 the second lookup fail. Instead of {<string2>} the word "fail" can appear,
8647 and in this case, if the lookup fails, the entire expansion is forced to
8648 fail (see section 11.4). If both {<string1>} and {<string2>} are omitted,
8649 the result is the looked up value in the case of a successful lookup, and
8650 nothing in the case of failure.
8652 For single-key lookups, the string "partial" is permitted to precede the
8653 search type in order to do partial matching, and * or *@ may follow a
8654 search type to request default lookups if the key does not match (see
8655 sections 9.6 and 9.7 for details).
8657 If a partial search is used, the variables $1 and $2 contain the wild and
8658 non-wild parts of the key during the expansion of the replacement text.
8659 They return to their previous values at the end of the lookup item.
8661 This example looks up the postmaster alias in the conventional alias file:
8663 ${lookup {postmaster} lsearch {/etc/aliases} {$value}}
8665 This example uses NIS+ to look up the full name of the user corresponding
8666 to the local part of an address, forcing the expansion to fail if it is not
8669 ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
8672 ${map{<string1>}{<string2>}}
8674 After expansion, <string1> is interpreted as a list, colon-separated by
8675 default, but the separator can be changed in the usual way. For each item
8676 in this list, its value is place in $item, and then <string2> is expanded
8677 and added to the output as an item in a new list. The separator used for
8678 the output list is the same as the one used for the input, but a separator
8679 setting is not included in the output. For example:
8681 ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}}
8683 expands to "[a]:[b]:[c] (x)-(y)-(z)". At the end of the expansion, the
8684 value of $item is restored to what it was before. See also the filter and
8685 reduce expansion items.
8687 ${nhash{<string1>}{<string2>}{<string3>}}
8689 The three strings are expanded; the first two must yield numbers. Call them
8690 <n> and <m>. If you are using fixed values for these numbers, that is, if <
8691 string1> and <string2> do not change when they are expanded, you can use
8692 the simpler operator notation that avoids some of the braces:
8694 ${nhash_<n>_<m>:<string>}
8696 The second number is optional (in both notations). If there is only one
8697 number, the result is a number in the range 0-<n>-1. Otherwise, the string
8698 is processed by a div/mod hash function that returns two numbers, separated
8699 by a slash, in the ranges 0 to <n>-1 and 0 to <m>-1, respectively. For
8702 ${nhash{8}{64}{supercalifragilisticexpialidocious}}
8704 returns the string "6/33".
8706 ${perl{<subroutine>}{<arg>}{<arg>}...}
8708 This item is available only if Exim has been built to include an embedded
8709 Perl interpreter. The subroutine name and the arguments are first
8710 separately expanded, and then the Perl subroutine is called with those
8711 arguments. No additional arguments need be given; the maximum number
8712 permitted, including the name of the subroutine, is nine.
8714 The return value of the subroutine is inserted into the expanded string,
8715 unless the return value is undef. In that case, the expansion fails in the
8716 same way as an explicit "fail" on a lookup item. The return value is a
8717 scalar. Whatever you return is evaluated in a scalar context. For example,
8718 if you return the name of a Perl vector, the return value is the size of
8719 the vector, not its contents.
8721 If the subroutine exits by calling Perl's die function, the expansion fails
8722 with the error message that was passed to die. More details of the embedded
8723 Perl facility are given in chapter 12.
8725 The redirect router has an option called forbid_filter_perl which locks out
8726 the use of this expansion item in filter files.
8728 ${prvs{<address>}{<secret>}{<keynumber>}}
8730 The first argument is a complete email address and the second is secret
8731 keystring. The third argument, specifying a key number, is optional. If
8732 absent, it defaults to 0. The result of the expansion is a prvs-signed
8733 email address, to be typically used with the return_path option on an smtp
8734 transport as part of a bounce address tag validation (BATV) scheme. For
8735 more discussion and an example, see section 42.51.
8737 ${prvscheck{<address>}{<secret>}{<string>}}
8739 This expansion item is the complement of the prvs item. It is used for
8740 checking prvs-signed addresses. If the expansion of the first argument does
8741 not yield a syntactically valid prvs-signed address, the whole item expands
8742 to the empty string. When the first argument does expand to a syntactically
8743 valid prvs-signed address, the second argument is expanded, with the
8744 prvs-decoded version of the address and the key number extracted from the
8745 address in the variables $prvscheck_address and $prvscheck_keynum,
8748 These two variables can be used in the expansion of the second argument to
8749 retrieve the secret. The validity of the prvs-signed address is then
8750 checked against the secret. The result is stored in the variable
8751 $prvscheck_result, which is empty for failure or "1" for success.
8753 The third argument is optional; if it is missing, it defaults to an empty
8754 string. This argument is now expanded. If the result is an empty string,
8755 the result of the expansion is the decoded version of the address. This is
8756 the case whether or not the signature was valid. Otherwise, the result of
8757 the expansion is the expansion of the third argument.
8759 All three variables can be used in the expansion of the third argument.
8760 However, once the expansion is complete, only $prvscheck_result remains
8761 set. For more discussion and an example, see section 42.51.
8763 ${readfile{<file name>}{<eol string>}}
8765 The file name and end-of-line string are first expanded separately. The
8766 file is then read, and its contents replace the entire item. All newline
8767 characters in the file are replaced by the end-of-line string if it is
8768 present. Otherwise, newlines are left in the string. String expansion is
8769 not applied to the contents of the file. If you want this, you must wrap
8770 the item in an expand operator. If the file cannot be read, the string
8773 The redirect router has an option called forbid_filter_readfile which locks
8774 out the use of this expansion item in filter files.
8776 ${readsocket{<name>}{<request>}{<timeout>}{<eol string>}{<fail string>}}
8778 This item inserts data from a Unix domain or Internet socket into the
8779 expanded string. The minimal way of using it uses just two arguments, as in
8782 ${readsocket{/socket/name}{request string}}
8783 ${readsocket{inet:some.host:1234}{request string}}
8785 For a Unix domain socket, the first substring must be the path to the
8786 socket. For an Internet socket, the first substring must contain "inet:"
8787 followed by a host name or IP address, followed by a colon and a port,
8788 which can be a number or the name of a TCP port in /etc/services. An IP
8789 address may optionally be enclosed in square brackets. This is best for
8790 IPv6 addresses. For example:
8792 ${readsocket{inet:[::1]:1234}{request string}}
8794 Only a single host name may be given, but if looking it up yields more than
8795 one IP address, they are each tried in turn until a connection is made. For
8796 both kinds of socket, Exim makes a connection, writes the request string
8797 (unless it is an empty string) and reads from the socket until an
8798 end-of-file is read. A timeout of 5 seconds is applied. Additional,
8799 optional arguments extend what can be done. Firstly, you can vary the
8800 timeout. For example:
8802 ${readsocket{/socket/name}{request string}{3s}}
8804 A fourth argument allows you to change any newlines that are in the data
8805 that is read, in the same way as for readfile (see above). This example
8806 turns them into spaces:
8808 ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }}
8810 As with all expansions, the substrings are expanded before the processing
8811 happens. Errors in these sub-expansions cause the expansion to fail. In
8812 addition, the following errors can occur:
8814 * Failure to create a socket file descriptor;
8816 * Failure to connect the socket;
8818 * Failure to write the request string;
8820 * Timeout on reading from the socket.
8822 By default, any of these errors causes the expansion to fail. However, if
8823 you supply a fifth substring, it is expanded and used when any of the above
8824 errors occurs. For example:
8826 ${readsocket{/socket/name}{request string}{3s}{\n}\
8829 You can test for the existence of a Unix domain socket by wrapping this
8830 expansion in "${if exists", but there is a race condition between that test
8831 and the actual opening of the socket, so it is safer to use the fifth
8832 argument if you want to be absolutely sure of avoiding an expansion error
8833 for a non-existent Unix domain socket, or a failure to connect to an
8836 The redirect router has an option called forbid_filter_readsocket which
8837 locks out the use of this expansion item in filter files.
8839 ${reduce{<string1>}{<string2>}{<string3>}}
8841 This operation reduces a list to a single, scalar string. After expansion,
8842 <string1> is interpreted as a list, colon-separated by default, but the
8843 separator can be changed in the usual way. Then <string2> is expanded and
8844 assigned to the $value variable. After this, each item in the <string1>
8845 list is assigned to $item in turn, and <string3> is expanded for each of
8846 them. The result of that expansion is assigned to $value before the next
8847 iteration. When the end of the list is reached, the final value of $value
8848 is added to the expansion output. The reduce expansion item can be used in
8849 a number of ways. For example, to add up a list of numbers:
8851 ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}}
8853 The result of that expansion would be "6". The maximum of a list of numbers
8856 ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}}
8858 At the end of a reduce expansion, the values of $item and $value are
8859 restored to what they were before. See also the filter and map expansion
8862 $rheader_<header name>: or $rh_<header name>:
8864 This item inserts "raw" header lines. It is described with the header
8865 expansion item above.
8867 ${run{<command> <args>}{<string1>}{<string2>}}
8869 The command and its arguments are first expanded as one string. The string
8870 is split apart into individual arguments by spaces, and then the command is
8871 run in a separate process, but under the same uid and gid. As in other
8872 command executions from Exim, a shell is not used by default. If the
8873 command requires a shell, you must explicitly code it.
8875 Since the arguments are split by spaces, when there is a variable expansion
8876 which has an empty result, it will cause the situation that the argument
8877 will simply be omitted when the program is actually executed by Exim. If
8878 the script/program requires a specific number of arguments and the expanded
8879 variable could possibly result in this empty expansion, the variable must
8880 be quoted. This is more difficult if the expanded variable itself could
8881 result in a string containing quotes, because it would interfere with the
8882 quotes around the command arguments. A possible guard against this is to
8883 wrap the variable in the sg operator to change any quote marks to some
8886 The standard input for the command exists, but is empty. The standard
8887 output and standard error are set to the same file descriptor. If the
8888 command succeeds (gives a zero return code) <string1> is expanded and
8889 replaces the entire item; during this expansion, the standard output/error
8890 from the command is in the variable $value. If the command fails, <string2
8891 >, if present, is expanded and used. Once again, during the expansion, the
8892 standard output/error from the command is in the variable $value.
8894 If <string2> is absent, the result is empty. Alternatively, <string2> can
8895 be the word "fail" (not in braces) to force expansion failure if the
8896 command does not succeed. If both strings are omitted, the result is
8897 contents of the standard output/error on success, and nothing on failure.
8899 The standard output/error of the command is put in the variable $value. In
8900 this ACL example, the output of a command is logged for the admin to
8903 warn condition = ${run{/usr/bin/id}{yes}{no}}
8904 log_message = Output of id: $value
8906 If the command requires shell idioms, such as the > redirect operator, the
8907 shell must be invoked directly, such as with:
8909 ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}}
8911 The return code from the command is put in the variable $runrc, and this
8912 remains set afterwards, so in a filter file you can do things like this:
8914 if "${run{x y z}{}}$runrc" is 1 then ...
8915 elif $runrc is 2 then ...
8919 If execution of the command fails (for example, the command does not
8920 exist), the return code is 127 - the same code that shells use for
8921 non-existent commands.
8923 Warning: In a router or transport, you cannot assume the order in which
8924 option values are expanded, except for those preconditions whose order of
8925 testing is documented. Therefore, you cannot reliably expect to set $runrc
8926 by the expansion of one option, and use it in another.
8928 The redirect router has an option called forbid_filter_run which locks out
8929 the use of this expansion item in filter files.
8931 ${sg{<subject>}{<regex>}{<replacement>}}
8933 This item works like Perl's substitution operator (s) with the global (/g)
8934 option; hence its name. However, unlike the Perl equivalent, Exim does not
8935 modify the subject string; instead it returns the modified string for
8936 insertion into the overall expansion. The item takes three arguments: the
8937 subject string, a regular expression, and a substitution string. For
8940 ${sg{abcdefabcdef}{abc}{xyz}}
8942 yields "xyzdefxyzdef". Because all three arguments are expanded before use,
8943 if any $ or \ characters are required in the regular expression or in the
8944 substitution string, they have to be escaped. For example:
8946 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
8948 yields "defabc", and
8950 ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
8952 yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of
8953 the regular expression from string expansion.
8955 ${substr{<string1>}{<string2>}{<string3>}}
8957 The three strings are expanded; the first two must yield numbers. Call them
8958 <n> and <m>. If you are using fixed values for these numbers, that is, if <
8959 string1> and <string2> do not change when they are expanded, you can use
8960 the simpler operator notation that avoids some of the braces:
8962 ${substr_<n>_<m>:<string>}
8964 The second number is optional (in both notations). If it is absent in the
8965 simpler format, the preceding underscore must also be omitted.
8967 The substr item can be used to extract more general substrings than length.
8968 The first number, <n>, is a starting offset, and <m> is the length
8969 required. For example
8971 ${substr{3}{2}{$local_part}}
8973 If the starting offset is greater than the string length the result is the
8974 null string; if the length plus starting offset is greater than the string
8975 length, the result is the right-hand part of the string, starting from the
8976 given offset. The first character in the string has offset zero.
8978 The substr expansion item can take negative offset values to count from the
8979 right-hand end of its operand. The last character is offset -1, the
8980 second-last is offset -2, and so on. Thus, for example,
8982 ${substr{-5}{2}{1234567}}
8984 yields "34". If the absolute value of a negative offset is greater than the
8985 length of the string, the substring starts at the beginning of the string,
8986 and the length is reduced by the amount of overshoot. Thus, for example,
8988 ${substr{-5}{2}{12}}
8990 yields an empty string, but
8992 ${substr{-3}{2}{12}}
8996 When the second number is omitted from substr, the remainder of the string
8997 is taken if the offset is positive. If it is negative, all characters in
8998 the string preceding the offset point are taken. For example, an offset of
8999 -1 and no length, as in these semantically identical examples:
9002 ${substr{-1}{abcde}}
9004 yields all but the last character of the string, that is, "abcd".
9006 ${tr{<subject>}{<characters>}{<replacements>}}
9008 This item does single-character translation on its subject string. The
9009 second argument is a list of characters to be translated in the subject
9010 string. Each matching character is replaced by the corresponding character
9011 from the replacement list. For example
9013 ${tr{abcdea}{ac}{13}}
9015 yields "1b3de1". If there are duplicates in the second character string,
9016 the last occurrence is used. If the third string is shorter than the
9017 second, its last character is replicated. However, if it is empty, no
9018 translation takes place.
9021 11.6 Expansion operators
9022 ------------------------
9024 For expansion items that perform transformations on a single argument string,
9025 the "operator" notation is used because it is simpler and uses fewer braces.
9026 The substring is first expanded before the operation is applied to it. The
9027 following operations can be performed:
9031 The string is interpreted as an RFC 2822 address, as it might appear in a
9032 header line, and the effective address is extracted from it. If the string
9033 does not parse successfully, the result is empty.
9035 ${addresses:<string>}
9037 The string (after expansion) is interpreted as a list of addresses in RFC
9038 2822 format, such as can be found in a To: or Cc: header line. The
9039 operative address (local-part@domain) is extracted from each item, and the
9040 result of the expansion is a colon-separated list, with appropriate
9041 doubling of colons should any happen to be present in the email addresses.
9042 Syntactically invalid RFC2822 address items are omitted from the output.
9044 It is possible to specify a character other than colon for the output
9045 separator by starting the string with > followed by the new separator
9046 character. For example:
9048 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
9050 expands to "ceo@up.stairs&sec@base.ment". Compare the address (singular)
9051 expansion item, which extracts the working address from a single RFC2822
9052 address. See the filter, map, and reduce items for ways of processing
9055 To clarify "list of addresses in RFC 2822 format" mentioned above, Exim
9056 follows a strict interpretation of header line formatting. Exim parses the
9057 bare, unquoted portion of an email address and if it finds a comma, treats
9058 it as an email address seperator. For the example header line:
9060 From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com>
9062 The first example below demonstrates that Q-encoded email addresses are
9063 parsed properly if it is given the raw header (in this example,
9064 "$rheader_from:"). It does not see the comma because it's still encoded as
9065 "=2C". The second example below is passed the contents of "$header_from:",
9066 meaning it gets de-mimed. Exim sees the decoded "," so it treats it as two
9067 email addresses. The third example shows that the presence of a comma is
9068 skipped when it is quoted.
9070 # exim -be '${addresses:From: \
9071 =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}'
9073 # exim -be '${addresses:From: Last, First <user@example.com>}'
9074 Last:user@example.com
9075 # exim -be '${addresses:From: "Last, First" <user@example.com>}'
9080 The string must consist entirely of decimal digits. The number is converted
9081 to base 62 and output as a string of six characters, including leading
9082 zeros. In the few operating environments where Exim uses base 36 instead of
9083 base 62 for its message identifiers (because those systems do not have
9084 case-sensitive file names), base 36 is used by this operator, despite its
9085 name. Note: Just to be absolutely clear: this is not base64 encoding.
9087 ${base62d:<base-62 digits>}
9089 The string must consist entirely of base-62 digits, or, in operating
9090 environments where Exim uses base 36 instead of base 62 for its message
9091 identifiers, base-36 digits. The number is converted to decimal and output
9096 The string is interpreted as an RFC 2822 address and the domain is
9097 extracted from it. If the string does not parse successfully, the result is
9102 If the string contains any non-printing characters, they are converted to
9103 escape sequences starting with a backslash. Whether characters with the
9104 most significant bit set (so-called "8-bit characters") count as printing
9105 or not is controlled by the print_topbitchars option.
9107 ${eval:<string>} and ${eval10:<string>}
9109 These items supports simple arithmetic and bitwise logical operations in
9110 expansion strings. The string (after expansion) must be a conventional
9111 arithmetic expression, but it is limited to basic arithmetic operators,
9112 bitwise logical operators, and parentheses. All operations are carried out
9113 using integer arithmetic. The operator priorities are as follows (the same
9114 as in the C programming language):
9116 highest: not (~), negate (-)
9117 multiply (*), divide (/), remainder (%)
9119 shift-left (<<), shift-right (>>)
9124 Binary operators with the same priority are evaluated from left to right.
9125 White space is permitted before or after operators.
9127 For eval, numbers may be decimal, octal (starting with "0") or hexadecimal
9128 (starting with "0x"). For eval10, all numbers are taken as decimal, even if
9129 they start with a leading zero; hexadecimal numbers are not permitted. This
9130 can be useful when processing numbers extracted from dates or times, which
9131 often do have leading zeros.
9133 A number may be followed by "K", "M" or "G" to multiply it by 1024,
9134 1024*1024 or 1024*1024*1024, respectively. Negative numbers are supported.
9135 The result of the computation is a decimal representation of the answer
9136 (without "K", "M" or "G"). For example:
9138 ${eval:1+1} yields 2
9139 ${eval:1+2*3} yields 7
9140 ${eval:(1+2)*3} yields 9
9141 ${eval:2+42%5} yields 4
9142 ${eval:0xc&5} yields 4
9143 ${eval:0xc|5} yields 13
9144 ${eval:0xc^5} yields 9
9145 ${eval:0xc>>1} yields 6
9146 ${eval:0xc<<1} yields 24
9147 ${eval:~255&0x1234} yields 4608
9148 ${eval:-(~255&0x1234)} yields -4608
9150 As a more realistic example, in an ACL you might have
9152 deny message = Too many bad recipients
9155 {>{$rcpt_count}{10}} \
9158 {$recipients_count} \
9159 {${eval:$rcpt_count/2}} \
9163 The condition is true if there have been more than 10 RCPT commands and
9164 fewer than half of them have resulted in a valid recipient.
9168 The expand operator causes a string to be expanded for a second time. For
9171 ${expand:${lookup{$domain}dbm{/some/file}{$value}}}
9173 first looks up a string in a file while expanding the operand for expand,
9174 and then re-expands what it has found.
9176 ${from_utf8:<string>}
9178 The world is slowly moving towards Unicode, although there are no standards
9179 for email yet. However, other applications (including some databases) are
9180 starting to store data in Unicode, using UTF-8 encoding. This operator
9181 converts from a UTF-8 string to an ISO-8859-1 string. UTF-8 code values
9182 greater than 255 are converted to underscores. The input must be a valid
9183 UTF-8 string. If it is not, the result is an undefined sequence of bytes.
9185 Unicode code points with values less than 256 are compatible with ASCII and
9186 ISO-8859-1 (also known as Latin-1). For example, character 169 is the
9187 copyright symbol in both cases, though the way it is encoded is different.
9188 In UTF-8, more than one byte is needed for characters with code values
9189 greater than 127, whereas ISO-8859-1 is a single-byte encoding (but thereby
9190 limited to 256 characters). This makes translation from UTF-8 to ISO-8859-1
9193 ${hash_<n>_<m>:<string>}
9195 The hash operator is a simpler interface to the hashing function that can
9196 be used when the two parameters are fixed numbers (as opposed to strings
9197 that change when expanded). The effect is the same as
9199 ${hash{<n>}{<m>}{<string>}}
9201 See the description of the general hash item above for details. The
9202 abbreviation h can be used when hash is used as an operator.
9204 ${hex2b64:<hexstring>}
9206 This operator converts a hex string into one that is base64 encoded. This
9207 can be useful for processing the output of the MD5 and SHA-1 hashing
9210 ${hexquote:<string>}
9212 This operator converts non-printable characters in a string into a hex
9213 escape form. Byte values between 33 (!) and 126 (~) inclusive are left as
9214 is, and other byte values are converted to "\xNN", for example a byte value
9215 127 is converted to "\x7f".
9219 This forces the letters in the string into lower-case, for example:
9223 ${length_<number>:<string>}
9225 The length operator is a simpler interface to the length function that can
9226 be used when the parameter is a fixed number (as opposed to a string that
9227 changes when expanded). The effect is the same as
9229 ${length{<number>}{<string>}}
9231 See the description of the general length item above for details. Note that
9232 length is not the same as strlen. The abbreviation l can be used when
9233 length is used as an operator.
9235 ${listcount:<string>}
9237 The string is interpreted as a list and the number of items is returned.
9239 ${listnamed:<name>} and ${listnamed_<type>:<name>}
9241 The name is interpreted as a named list and the content of the list is
9242 returned, expanding any referenced lists, re-quoting as needed for
9243 colon-separation. If the optional type is given it must be one of "a", "d",
9244 "h" or "l" and selects address-, domain-, host- or localpart- lists to
9245 search among respectively. Otherwise all types are searched in an undefined
9246 order and the first matching list is returned.
9248 ${local_part:<string>}
9250 The string is interpreted as an RFC 2822 address and the local part is
9251 extracted from it. If the string does not parse successfully, the result is
9254 ${mask:<IP address>/<bit count>}
9256 If the form of the string to be operated on is not an IP address followed
9257 by a slash and an integer (that is, a network address in CIDR notation),
9258 the expansion fails. Otherwise, this operator converts the IP address to
9259 binary, masks off the least significant bits according to the bit count,
9260 and converts the result back to text, with mask appended. For example,
9262 ${mask:10.111.131.206/28}
9264 returns the string "10.111.131.192/28". Since this operation is expected to
9265 be mostly used for looking up masked addresses in files, the result for an
9266 IPv6 address uses dots to separate components instead of colons, because
9267 colon terminates a key string in lsearch files. So, for example,
9269 ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99}
9273 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
9275 Letters in IPv6 addresses are always output in lower case.
9279 The md5 operator computes the MD5 hash value of the string, and returns it
9280 as a 32-digit hexadecimal number, in which any letters are in lower case.
9282 ${nhash_<n>_<m>:<string>}
9284 The nhash operator is a simpler interface to the numeric hashing function
9285 that can be used when the two parameters are fixed numbers (as opposed to
9286 strings that change when expanded). The effect is the same as
9288 ${nhash{<n>}{<m>}{<string>}}
9290 See the description of the general nhash item above for details.
9294 The quote operator puts its argument into double quotes if it is an empty
9295 string or contains anything other than letters, digits, underscores, dots,
9296 and hyphens. Any occurrences of double quotes and backslashes are escaped
9297 with a backslash. Newlines and carriage returns are converted to "\n" and "
9298 \r", respectively For example,
9306 The place where this is useful is when the argument is a substitution from
9307 a variable or a message header.
9309 ${quote_local_part:<string>}
9311 This operator is like quote, except that it quotes the string only if
9312 required to do so by the rules of RFC 2822 for quoting local parts. For
9313 example, a plus sign would not cause quoting (but it would for quote). If
9314 you are creating a new email address from the contents of $local_part (or
9315 any other unknown data), you should always use this operator.
9317 ${quote_<lookup-type>:<string>}
9319 This operator applies lookup-specific quoting rules to the string. Each
9320 query-style lookup type has its own quoting rules which are described with
9321 the lookups in chapter 9. For example,
9323 ${quote_ldap:two * two}
9329 For single-key lookup types, no quoting is ever necessary and this operator
9330 yields an unchanged string.
9334 This operator returns a somewhat random number which is less than the
9335 supplied number and is at least 0. The quality of this randomness depends
9336 on how Exim was built; the values are not suitable for keying material. If
9337 Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. If Exim is
9338 linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used, for
9339 versions of GnuTLS with that function. Otherwise, the implementation may be
9340 arc4random(), random() seeded by srandomdev() or srandom(), or a custom
9341 implementation even weaker than random().
9343 ${reverse_ip:<ipaddr>}
9345 This operator reverses an IP address; for IPv4 addresses, the result is in
9346 dotted-quad decimal form, while for IPv6 addreses the result is in
9347 dotted-nibble hexadecimal form. In both cases, this is the "natural" form
9348 for DNS. For example,
9350 ${reverse_ip:192.0.2.4}
9351 ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127}
9356 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
9360 This operator encodes text according to the rules of RFC 2047. This is an
9361 encoding that is used in header lines to encode non-ASCII characters. It is
9362 assumed that the input string is in the encoding specified by the
9363 headers_charset option, which defaults to ISO-8859-1. If the string
9364 contains only characters in the range 33-126, and no instances of the
9367 ? = ( ) < > @ , ; : \ " . [ ] _
9369 it is not modified. Otherwise, the result is the RFC 2047 encoding of the
9370 string, using as many "encoded words" as necessary to encode all the
9373 ${rfc2047d:<string>}
9375 This operator decodes strings that are encoded as per RFC 2047. Binary zero
9376 bytes are replaced by question marks. Characters are converted into the
9377 character set defined by headers_charset. Overlong RFC 2047 "words" are not
9378 recognized unless check_rfc2047_length is set false.
9380 Note: If you use $header_xxx: (or $h_xxx:) to access a header line, RFC
9381 2047 decoding is done automatically. You do not need to use this operator
9386 The rxquote operator inserts a backslash before any non-alphanumeric
9387 characters in its argument. This is useful when substituting the values of
9388 variables or headers inside regular expressions.
9392 The sha1 operator computes the SHA-1 hash value of the string, and returns
9393 it as a 40-digit hexadecimal number, in which any letters are in upper
9396 ${sha256:<certificate>}
9398 The sha256 operator computes the SHA-256 hash fingerprint of the
9399 certificate, and returns it as a 64-digit hexadecimal number, in which any
9400 letters are in upper case. Only arguments which are a single variable of
9401 certificate type are supported.
9405 The string, after expansion, must be a file path. A call to the stat()
9406 function is made for this path. If stat() fails, an error occurs and the
9407 expansion fails. If it succeeds, the data from the stat replaces the item,
9408 as a series of <name>=<value> pairs, where the values are all numerical,
9409 except for the value of "smode". The names are: "mode" (giving the mode as
9410 a 4-digit octal number), "smode" (giving the mode in symbolic format as a
9411 10-character string, as for the ls command), "inode", "device", "links",
9412 "uid", "gid", "size", "atime", "mtime", and "ctime". You can extract
9413 individual fields using the extract expansion item.
9415 The use of the stat expansion in users' filter files can be locked out by
9416 the system administrator. Warning: The file size may be incorrect on 32-bit
9417 systems for files larger than 2GB.
9421 This operator converts a string into one that is base64 encoded.
9425 The item is replace by the length of the expanded string, expressed as a
9426 decimal number. Note: Do not confuse strlen with length.
9428 ${substr_<start>_<length>:<string>}
9430 The substr operator is a simpler interface to the substr function that can
9431 be used when the two parameters are fixed numbers (as opposed to strings
9432 that change when expanded). The effect is the same as
9434 ${substr{<start>}{<length>}{<string>}}
9436 See the description of the general substr item above for details. The
9437 abbreviation s can be used when substr is used as an operator.
9439 ${time_eval:<string>}
9441 This item converts an Exim time interval such as "2d4h5m" into a number of
9444 ${time_interval:<string>}
9446 The argument (after sub-expansion) must be a sequence of decimal digits
9447 that represents an interval of time as a number of seconds. It is converted
9448 into a number of larger units and output in Exim's normal time format, for
9449 example, "1w3d4h2m6s".
9453 This forces the letters in the string into upper-case.
9455 ${utf8clean:<string>}
9457 This replaces any invalid utf-8 sequence in the string by the character "?
9461 11.7 Expansion conditions
9462 -------------------------
9464 The following conditions are available for testing by the ${if construct while
9469 Preceding any condition with an exclamation mark negates the result of the
9472 <symbolic operator> {<string1>}{<string2>}
9474 There are a number of symbolic operators for doing numeric comparisons.
9486 ${if >{$message_size}{10M} ...
9488 Note that the general negation operator provides for inequality testing.
9489 The two strings must take the form of optionally signed decimal integers,
9490 optionally followed by one of the letters "K", "M" or "G" (in either upper
9491 or lower case), signifying multiplication by 1024, 1024*1024 or
9492 1024*1024*1024, respectively. As a special case, the numerical value of an
9493 empty string is taken as zero.
9495 In all cases, a relative comparator OP is testing if <string1> OP <string2
9496 >; the above example is checking if $message_size is larger than 10M, not
9497 if 10M is larger than $message_size.
9499 acl {{<name>}{<arg1>}{<arg2>}...}
9501 The name and zero to nine argument strings are first expanded separately.
9502 The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
9503 in order. Any unused are made empty. The variable $acl_narg is set to the
9504 number of arguments. The named ACL (see chapter 42) is called and may use
9505 the variables; if another acl expansion is used the values are restored
9506 after it returns. If the ACL sets a value using a "message =" modifier the
9507 variable $value becomes the result of the expansion, otherwise it is empty.
9508 If the ACL returns accept the condition is true; if deny, false. If the ACL
9509 returns defer the result is a forced-fail.
9513 This condition turns a string holding a true or false representation into a
9514 boolean state. It parses "true", "false", "yes" and "no"
9515 (case-insensitively); also integer numbers map to true if non-zero, false
9516 if zero. An empty string is treated as false. Leading and trailing
9517 whitespace is ignored; thus a string consisting only of whitespace is
9518 false. All other string values will result in expansion failure.
9520 When combined with ACL variables, this expansion condition will let you
9521 make decisions in one place and act on those decisions in another place.
9524 ${if bool{$acl_m_privileged_sender} ...
9528 Like bool, this condition turns a string into a boolean state. But where
9529 bool accepts a strict set of strings, bool_lax uses the same loose
9530 definition that the Router condition option uses. The empty string and the
9531 values "false", "no" and "0" map to false, all others map to true. Leading
9532 and trailing whitespace is ignored.
9534 Note that where "bool{00}" is false, "bool_lax{00}" is true.
9536 crypteq {<string1>}{<string2>}
9538 This condition is included in the Exim binary if it is built to support any
9539 authentication mechanisms (see chapter 33). Otherwise, it is necessary to
9540 define SUPPORT_CRYPTEQ in Local/Makefile to get crypteq included in the
9543 The crypteq condition has two arguments. The first is encrypted and
9544 compared against the second, which is already encrypted. The second string
9545 may be in the LDAP form for storing encrypted strings, which starts with
9546 the encryption type in curly brackets, followed by the data. If the second
9547 string does not begin with "{" it is assumed to be encrypted with crypt()
9548 or crypt16() (see below), since such strings cannot begin with "{".
9549 Typically this will be a field from a password file. An example of an
9550 encrypted string in LDAP form is:
9552 {md5}CY9rzUYh03PK3k6DJie09g==
9554 If such a string appears directly in an expansion, the curly brackets have
9555 to be quoted, because they are part of the expansion syntax. For example:
9557 ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
9559 The following encryption types (whose names are matched case-independently)
9562 * {md5} computes the MD5 digest of the first string, and expresses this
9563 as printable characters to compare with the remainder of the second
9564 string. If the length of the comparison string is 24, Exim assumes that
9565 it is base64 encoded (as in the above example). If the length is 32,
9566 Exim assumes that it is a hexadecimal encoding of the MD5 digest. If
9567 the length not 24 or 32, the comparison fails.
9569 * {sha1} computes the SHA-1 digest of the first string, and expresses
9570 this as printable characters to compare with the remainder of the
9571 second string. If the length of the comparison string is 28, Exim
9572 assumes that it is base64 encoded. If the length is 40, Exim assumes
9573 that it is a hexadecimal encoding of the SHA-1 digest. If the length is
9574 not 28 or 40, the comparison fails.
9576 * {crypt} calls the crypt() function, which traditionally used to use
9577 only the first eight characters of the password. However, in modern
9578 operating systems this is no longer true, and in many cases the entire
9579 password is used, whatever its length.
9581 * {crypt16} calls the crypt16() function, which was originally created to
9582 use up to 16 characters of the password in some operating systems.
9583 Again, in modern operating systems, more characters may be used.
9585 Exim has its own version of crypt16(), which is just a double call to crypt
9586 (). For operating systems that have their own version, setting HAVE_CRYPT16
9587 in Local/Makefile when building Exim causes it to use the operating system
9588 version instead of its own. This option is set by default in the
9589 OS-dependent Makefile for those operating systems that are known to support
9592 Some years after Exim's crypt16() was implemented, a user discovered that
9593 it was not using the same algorithm as some operating systems' versions. It
9594 turns out that as well as crypt16() there is a function called bigcrypt()
9595 in some operating systems. This may or may not use the same algorithm, and
9596 both of them may be different to Exim's built-in crypt16().
9598 However, since there is now a move away from the traditional crypt()
9599 functions towards using SHA1 and other algorithms, tidying up this area of
9600 Exim is seen as very low priority.
9602 If you do not put a encryption type (in curly brackets) in a crypteq
9603 comparison, the default is usually either "{crypt}" or "{crypt16}", as
9604 determined by the setting of DEFAULT_CRYPT in Local/Makefile. The default
9605 default is "{crypt}". Whatever the default, you can always use either
9606 function by specifying it explicitly in curly brackets.
9610 The def condition must be followed by the name of one of the expansion
9611 variables defined in section 11.9. The condition is true if the variable
9612 does not contain the empty string. For example:
9614 ${if def:sender_ident {from $sender_ident}}
9616 Note that the variable name is given without a leading $ character. If the
9617 variable does not exist, the expansion fails.
9619 def:header_<header name>: or def:h_<header name>:
9621 This condition is true if a message is being processed and the named header
9622 exists in the message. For example,
9624 ${if def:header_reply-to:{$h_reply-to:}{$h_from:}}
9626 Note: No $ appears before header_ or h_ in the condition, and the header
9627 name must be terminated by a colon if white space does not follow.
9629 eq {<string1>}{<string2>}, eqi {<string1>}{<string2>}
9631 The two substrings are first expanded. The condition is true if the two
9632 resulting strings are identical. For eq the comparison includes the case of
9633 letters, whereas for eqi the comparison is case-independent.
9635 exists {<file name>}
9637 The substring is first expanded and then interpreted as an absolute path.
9638 The condition is true if the named file (or directory) exists. The
9639 existence test is done by calling the stat() function. The use of the
9640 exists test in users' filter files may be locked out by the system
9645 This condition, which has no data, is true during a message's first
9646 delivery attempt. It is false during any subsequent delivery attempts.
9648 forall{<a list>}{<a condition>}, forany{<a list>}{<a condition>}
9650 These conditions iterate over a list. The first argument is expanded to
9651 form the list. By default, the list separator is a colon, but it can be
9652 changed by the normal method. The second argument is interpreted as a
9653 condition that is to be applied to each item in the list in turn. During
9654 the interpretation of the condition, the current list item is placed in a
9655 variable called $item.
9657 * For forany, interpretation stops if the condition is true for any item,
9658 and the result of the whole condition is true. If the condition is
9659 false for all items in the list, the overall condition is false.
9661 * For forall, interpretation stops if the condition is false for any
9662 item, and the result of the whole condition is false. If the condition
9663 is true for all items in the list, the overall condition is true.
9665 Note that negation of forany means that the condition must be false for all
9666 items for the overall condition to succeed, and negation of forall means
9667 that the condition must be false for at least one item. In this example,
9668 the list separator is changed to a comma:
9670 ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}}
9672 The value of $item is saved and restored while forany or forall is being
9673 processed, to enable these expansion items to be nested.
9675 To scan a named list, expand it with the listnamed operator.
9677 ge {<string1>}{<string2>}, gei {<string1>}{<string2>}
9679 The two substrings are first expanded. The condition is true if the first
9680 string is lexically greater than or equal to the second string. For ge the
9681 comparison includes the case of letters, whereas for gei the comparison is
9684 gt {<string1>}{<string2>}, gti {<string1>}{<string2>}
9686 The two substrings are first expanded. The condition is true if the first
9687 string is lexically greater than the second string. For gt the comparison
9688 includes the case of letters, whereas for gti the comparison is
9691 inlist {<string1>}{<string2>}, inlisti {<string1>}{<string2>}
9693 Both strings are expanded; the second string is treated as a list of simple
9694 strings; if the first string is a member of the second, then the condition
9697 These are simpler to use versions of the more powerful forany condition.
9698 Examples, and the forany equivalents:
9700 ${if inlist{needle}{foo:needle:bar}}
9701 ${if forany{foo:needle:bar}{eq{$item}{needle}}}
9702 ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
9703 ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
9705 isip {<string>}, isip4 {<string>}, isip6 {<string>}
9707 The substring is first expanded, and then tested to see if it has the form
9708 of an IP address. Both IPv4 and IPv6 addresses are valid for isip, whereas
9709 isip4 and isip6 test specifically for IPv4 or IPv6 addresses.
9711 For an IPv4 address, the test is for four dot-separated components, each of
9712 which consists of from one to three digits. For an IPv6 address, up to
9713 eight colon-separated components are permitted, each containing from one to
9714 four hexadecimal digits. There may be fewer than eight components if an
9715 empty component (adjacent colons) is present. Only one empty component is
9718 Note: The checks are just on the form of the address; actual numerical
9719 values are not considered. Thus, for example, 999.999.999.999 passes the
9720 IPv4 check. The main use of these tests is to distinguish between IP
9721 addresses and host names, or between IPv4 and IPv6 addresses. For example,
9724 ${if isip4{$sender_host_address}...
9726 to test which IP version an incoming SMTP connection is using.
9728 ldapauth {<ldap query>}
9730 This condition supports user authentication using LDAP. See section 9.13
9731 for details of how to use LDAP in lookups and the syntax of queries. For
9732 this use, the query must contain a user name and password. The query itself
9733 is not used, and can be empty. The condition is true if the password is not
9734 empty, and the user name and password are accepted by the LDAP server. An
9735 empty password is rejected without calling LDAP because LDAP binds with an
9736 empty password are considered anonymous regardless of the username, and
9737 will succeed in most configurations. See chapter 33 for details of SMTP
9738 authentication, and chapter 34 for an example of how this can be used.
9740 le {<string1>}{<string2>}, lei {<string1>}{<string2>}
9742 The two substrings are first expanded. The condition is true if the first
9743 string is lexically less than or equal to the second string. For le the
9744 comparison includes the case of letters, whereas for lei the comparison is
9747 lt {<string1>}{<string2>}, lti {<string1>}{<string2>}
9749 The two substrings are first expanded. The condition is true if the first
9750 string is lexically less than the second string. For lt the comparison
9751 includes the case of letters, whereas for lti the comparison is
9754 match {<string1>}{<string2>}
9756 The two substrings are first expanded. The second is then treated as a
9757 regular expression and applied to the first. Because of the pre-expansion,
9758 if the regular expression contains dollar, or backslash characters, they
9759 must be escaped. Care must also be taken if the regular expression contains
9760 braces (curly brackets). A closing brace must be escaped so that it is not
9761 taken as a premature termination of <string2>. The easiest approach is to
9762 use the "\N" feature to disable expansion of the regular expression. For
9765 ${if match {$local_part}{\N^\d{3}\N} ...
9767 If the whole expansion string is in double quotes, further escaping of
9768 backslashes is also required.
9770 The condition is true if the regular expression match succeeds. The regular
9771 expression is not required to begin with a circumflex metacharacter, but if
9772 there is no circumflex, the expression is not anchored, and it may match
9773 anywhere in the subject, not just at the start. If you want the pattern to
9774 match at the end of the subject, you must include the "$" metacharacter at
9775 an appropriate point.
9777 At the start of an if expansion the values of the numeric variable
9778 substitutions $1 etc. are remembered. Obeying a match condition that
9779 succeeds causes them to be reset to the substrings of that condition and
9780 they will have these values during the expansion of the success string. At
9781 the end of the if expansion, the previous values are restored. After
9782 testing a combination of conditions using or, the subsequent values of the
9783 numeric variables are those of the condition that succeeded.
9785 match_address {<string1>}{<string2>}
9787 See match_local_part.
9789 match_domain {<string1>}{<string2>}
9791 See match_local_part.
9793 match_ip {<string1>}{<string2>}
9795 This condition matches an IP address to a list of IP address patterns. It
9796 must be followed by two argument strings. The first (after expansion) must
9797 be an IP address or an empty string. The second (not expanded) is a
9798 restricted host list that can match only an IP address, not a host name.
9801 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
9803 The specific types of host list item that are permitted in the list are:
9805 * An IP address, optionally with a CIDR mask.
9807 * A single asterisk, which matches any IP address.
9809 * An empty item, which matches only if the IP address is empty. This
9810 could be useful for testing for a locally submitted message or one from
9811 specific hosts in a single test such as
9813 ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}}
9815 where the first item in the list is the empty string.
9817 * The item @[] matches any of the local host's interface addresses.
9819 * Single-key lookups are assumed to be like "net-" style lookups in host
9820 lists, even if "net-" is not specified. There is never any attempt to
9821 turn the IP address into a host name. The most common type of linear
9822 search for match_ip is likely to be iplsearch, in which the file can
9823 contain CIDR masks. For example:
9825 ${if match_ip{$sender_host_address}{iplsearch;/some/file}...
9827 It is of course possible to use other kinds of lookup, and in such a
9828 case, you do need to specify the "net-" prefix if you want to specify a
9829 specific address mask, for example:
9831 ${if match_ip{$sender_host_address}{net24-dbm;/some/file}...
9833 However, unless you are combining a match_ip condition with others, it
9834 is just as easy to use the fact that a lookup is itself a condition,
9837 ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}...
9839 Note that <string2> is not itself subject to string expansion, unless Exim
9840 was built with the EXPAND_LISTMATCH_RHS option.
9842 Consult section 10.11 for further details of these patterns.
9844 match_local_part {<string1>}{<string2>}
9846 This condition, together with match_address and match_domain, make it
9847 possible to test domain, address, and local part lists within expansions.
9848 Each condition requires two arguments: an item and a list to match. A
9851 ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
9853 In each case, the second argument may contain any of the allowable items
9854 for a list of the appropriate type. Also, because the second argument
9855 (after expansion) is a standard form of list, it is possible to refer to a
9856 named list. Thus, you can use conditions like this:
9858 ${if match_domain{$domain}{+local_domains}{...
9860 For address lists, the matching starts off caselessly, but the "+caseful"
9861 item can be used, as in all address lists, to cause subsequent items to
9862 have their local parts matched casefully. Domains are always matched
9865 Note that <string2> is not itself subject to string expansion, unless Exim
9866 was built with the EXPAND_LISTMATCH_RHS option.
9868 Note: Host lists are not supported in this way. This is because hosts have
9869 two identities: a name and an IP address, and it is not clear how to
9870 specify cleanly how such a test would work. However, IP addresses can be
9871 matched using match_ip.
9873 pam {<string1>:<string2>:...}
9875 Pluggable Authentication Modules (http://www.kernel.org/pub/linux/libs/pam/
9876 ) are a facility that is available in the latest releases of Solaris and in
9877 some GNU/Linux distributions. The Exim support, which is intended for use
9878 in conjunction with the SMTP AUTH command, is available only if Exim is
9883 in Local/Makefile. You probably need to add -lpam to EXTRALIBS, and in some
9884 releases of GNU/Linux -ldl is also needed.
9886 The argument string is first expanded, and the result must be a
9887 colon-separated list of strings. Leading and trailing white space is
9888 ignored. The PAM module is initialized with the service name "exim" and the
9889 user name taken from the first item in the colon-separated data string (<
9890 string1>). The remaining items in the data string are passed over in
9891 response to requests from the authentication function. In the simple case
9892 there will only be one request, for a password, so the data consists of
9895 There can be problems if any of the strings are permitted to contain colon
9896 characters. In the usual way, these have to be doubled to avoid being taken
9897 as separators. If the data is being inserted from a variable, the sg
9898 expansion item can be used to double any existing colons. For example, the
9899 configuration of a LOGIN authenticator might contain this setting:
9901 server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}}
9903 For a PLAIN authenticator you could use:
9905 server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}}
9907 In some operating systems, PAM authentication can be done only from a
9908 process running as root. Since Exim is running as the Exim user when
9909 receiving messages, this means that PAM cannot be used directly in those
9910 systems. A patched version of the pam_unix module that comes with the Linux
9911 PAM package is available from http://www.e-admin.de/pam_exim/. The patched
9912 module allows one special uid/gid combination, in addition to root, to
9913 authenticate. If you build the patched module to allow the Exim user and
9914 group, PAM can then be used from an Exim authenticator.
9916 pwcheck {<string1>:<string2>}
9918 This condition supports user authentication using the Cyrus pwcheck daemon.
9919 This is one way of making it possible for passwords to be checked by a
9920 process that is not running as root. Note: The use of pwcheck is now
9921 deprecated. Its replacement is saslauthd (see below).
9923 The pwcheck support is not included in Exim by default. You need to specify
9924 the location of the pwcheck daemon's socket in Local/Makefile before
9925 building Exim. For example:
9927 CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck
9929 You do not need to install the full Cyrus software suite in order to use
9930 the pwcheck daemon. You can compile and install just the daemon alone from
9931 the Cyrus SASL library. Ensure that exim is the only user that has access
9932 to the /var/pwcheck directory.
9934 The pwcheck condition takes one argument, which must be the user name and
9935 password, separated by a colon. For example, in a LOGIN authenticator
9936 configuration, you might have this:
9938 server_condition = ${if pwcheck{$auth1:$auth2}}
9940 Again, for a PLAIN authenticator configuration, this would be:
9942 server_condition = ${if pwcheck{$auth2:$auth3}}
9946 This condition, which has no data, is true during delivery attempts that
9947 are initiated by queue runner processes, and false otherwise.
9949 radius {<authentication string>}
9951 Radius authentication (RFC 2865) is supported in a similar way to PAM. You
9952 must set RADIUS_CONFIG_FILE in Local/Makefile to specify the location of
9953 the Radius client configuration file in order to build Exim with Radius
9956 With just that one setting, Exim expects to be linked with the radiusclient
9957 library, using the original API. If you are using release 0.4.0 or later of
9958 this library, you need to set
9960 RADIUS_LIB_TYPE=RADIUSCLIENTNEW
9962 in Local/Makefile when building Exim. You can also link Exim with the
9963 libradius library that comes with FreeBSD. To do this, set
9965 RADIUS_LIB_TYPE=RADLIB
9967 in Local/Makefile, in addition to setting RADIUS_CONFIGURE_FILE. You may
9968 also have to supply a suitable setting in EXTRALIBS so that the Radius
9969 library can be found when Exim is linked.
9971 The string specified by RADIUS_CONFIG_FILE is expanded and passed to the
9972 Radius client library, which calls the Radius server. The condition is true
9973 if the authentication is successful. For example:
9975 server_condition = ${if radius{<arguments>}}
9977 saslauthd {{<user>}{<password>}{<service>}{<realm>}}
9979 This condition supports user authentication using the Cyrus saslauthd
9980 daemon. This replaces the older pwcheck daemon, which is now deprecated.
9981 Using this daemon is one way of making it possible for passwords to be
9982 checked by a process that is not running as root.
9984 The saslauthd support is not included in Exim by default. You need to
9985 specify the location of the saslauthd daemon's socket in Local/Makefile
9986 before building Exim. For example:
9988 CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux
9990 You do not need to install the full Cyrus software suite in order to use
9991 the saslauthd daemon. You can compile and install just the daemon alone
9992 from the Cyrus SASL library.
9994 Up to four arguments can be supplied to the saslauthd condition, but only
9995 two are mandatory. For example:
9997 server_condition = ${if saslauthd{{$auth1}{$auth2}}}
9999 The service and the realm are optional (which is why the arguments are
10000 enclosed in their own set of braces). For details of the meaning of the
10001 service and realm, and how to run the daemon, consult the Cyrus
10005 11.8 Combining expansion conditions
10006 -----------------------------------
10008 Several conditions can be tested at once by combining them using the and and or
10009 combination conditions. Note that and and or are complete conditions on their
10010 own, and precede their lists of sub-conditions. Each sub-condition must be
10011 enclosed in braces within the overall braces that contain the list. No
10012 repetition of if is used.
10014 or {{<cond1>}{<cond2>}...}
10016 The sub-conditions are evaluated from left to right. The condition is true
10017 if any one of the sub-conditions is true. For example,
10019 ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...
10021 When a true sub-condition is found, the following ones are parsed but not
10022 evaluated. If there are several "match" sub-conditions the values of the
10023 numeric variables afterwards are taken from the first one that succeeds.
10025 and {{<cond1>}{<cond2>}...}
10027 The sub-conditions are evaluated from left to right. The condition is true
10028 if all of the sub-conditions are true. If there are several "match"
10029 sub-conditions, the values of the numeric variables afterwards are taken
10030 from the last one. When a false sub-condition is found, the following ones
10031 are parsed but not evaluated.
10034 11.9 Expansion variables
10035 ------------------------
10037 This section contains an alphabetical list of all the expansion variables. Some
10038 of them are available only when Exim is compiled with specific options such as
10039 support for TLS or the content scanning extension.
10043 When a match expansion condition succeeds, these variables contain the
10044 captured substrings identified by the regular expression during subsequent
10045 processing of the success string of the containing if expansion item.
10046 However, they do not retain their values afterwards; in fact, their
10047 previous values are restored at the end of processing an if item. The
10048 numerical variables may also be set externally by some other matching
10049 process which precedes the expansion of the string. For example, the
10050 commands available in Exim filter files include an if command with its own
10051 regular expression matching condition.
10053 $acl_arg1, $acl_arg2, etc
10055 Within an acl condition, expansion condition or expansion item any
10056 arguments are copied to these variables, any unused variables being made
10061 Values can be placed in these variables by the set modifier in an ACL. They
10062 can be given any name that starts with $acl_c and is at least six
10063 characters long, but the sixth character must be either a digit or an
10064 underscore. For example: $acl_c5, $acl_c_mycount. The values of the
10065 $acl_c... variables persist throughout the lifetime of an SMTP connection.
10066 They can be used to pass information between ACLs and between different
10067 invocations of the same ACL. When a message is received, the values of
10068 these variables are saved with the message, and can be accessed by filters,
10069 routers, and transports during subsequent delivery.
10073 These variables are like the $acl_c... variables, except that their values
10074 are reset after a message has been received. Thus, if several messages are
10075 received in one SMTP connection, $acl_m... values are not passed on from
10076 one message to the next, as $acl_c... values are. The $acl_m... variables
10077 are also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session.
10078 When a message is received, the values of these variables are saved with
10079 the message, and can be accessed by filters, routers, and transports during
10080 subsequent delivery.
10084 Within an acl condition, expansion condition or expansion item this
10085 variable has the number of arguments.
10087 $acl_verify_message
10089 After an address verification has failed, this variable contains the
10090 failure message. It retains its value for use in subsequent modifiers. The
10091 message can be preserved by coding like this:
10093 warn !verify = sender
10094 set acl_m0 = $acl_verify_message
10096 You can use $acl_verify_message during the expansion of the message or
10097 log_message modifiers, to include information about the verification
10102 This variable is set by means of the address_data option in routers. The
10103 value then remains with the address while it is processed by subsequent
10104 routers and eventually a transport. If the transport is handling multiple
10105 addresses, the value from the first address is used. See chapter 15 for
10106 more details. Note: The contents of $address_data are visible in user
10109 If $address_data is set when the routers are called from an ACL to verify a
10110 recipient address, the final value is still in the variable for subsequent
10111 conditions and modifiers of the ACL statement. If routing the address
10112 caused it to be redirected to just one address, the child address is also
10113 routed as part of the verification, and in this case the final value of
10114 $address_data is from the child's routing.
10116 If $address_data is set when the routers are called from an ACL to verify a
10117 sender address, the final value is also preserved, but this time in
10118 $sender_address_data, to distinguish it from data from a recipient address.
10120 In both cases (recipient and sender verification), the value does not
10121 persist after the end of the current ACL statement. If you want to preserve
10122 these values for longer, you can save them in ACL variables.
10126 When, as a result of aliasing, forwarding, or filtering, a message is
10127 directed to a specific file, this variable holds the name of the file when
10128 the transport is running. At other times, the variable is empty. For
10129 example, using the default configuration, if user r2d2 has a .forward file
10132 /home/r2d2/savemail
10134 then when the address_file transport is running, $address_file contains the
10135 text string "/home/r2d2/savemail". For Sieve filters, the value may be
10136 "inbox" or a relative folder name. It is then up to the transport
10137 configuration to generate an appropriate absolute path to the relevant
10142 When, as a result of aliasing or forwarding, a message is directed to a
10143 pipe, this variable holds the pipe command when the transport is running.
10147 These variables are used in SMTP authenticators (see chapters 34-40).
10148 Elsewhere, they are empty.
10152 When a server successfully authenticates a client it may be configured to
10153 preserve some of the authentication information in the variable
10154 $authenticated_id (see chapter 33). For example, a user/password
10155 authenticator configuration might preserve the user name for use in the
10156 routers. Note that this is not the same information that is saved in
10157 $sender_host_authenticated. When a message is submitted locally (that is,
10158 not over a TCP connection) the value of $authenticated_id is normally the
10159 login name of the calling process. However, a trusted user can override
10160 this by means of the -oMai command line option.
10162 $authenticated_fail_id
10164 When an authentication attempt fails, the variable $authenticated_fail_id
10165 will contain the failed authentication id. If more than one authentication
10166 id is attempted, it will contain only the last one. The variable is
10167 available for processing in the ACL's, generally the quit or notquit ACL. A
10168 message to a local recipient could still be accepted without requiring
10169 authentication, which means this variable could also be visible in all of
10172 $authenticated_sender
10174 When acting as a server, Exim takes note of the AUTH= parameter on an
10175 incoming SMTP MAIL command if it believes the sender is sufficiently
10176 trusted, as described in section 33.2. Unless the data is the string "<>",
10177 it is set as the authenticated sender of the message, and the value is
10178 available during delivery in the $authenticated_sender variable. If the
10179 sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the
10182 When a message is submitted locally (that is, not over a TCP connection),
10183 the value of $authenticated_sender is an address constructed from the login
10184 name of the calling process and $qualify_domain, except that a trusted user
10185 can override this by means of the -oMas command line option.
10187 $authentication_failed
10189 This variable is set to "1" in an Exim server if a client issues an AUTH
10190 command that does not succeed. Otherwise it is set to "0". This makes it
10191 possible to distinguish between "did not try to authenticate" (
10192 $sender_host_authenticated is empty and $authentication_failed is set to
10193 "0") and "tried to authenticate but failed" ($sender_host_authenticated is
10194 empty and $authentication_failed is set to "1"). Failure includes any
10195 negative response to an AUTH command, including (for example) an attempt to
10196 use an undefined mechanism.
10200 This variable is available when Exim is compiled with the content-scanning
10201 extension. It is set to "0" by default, but will be set to "1" if any
10202 problem occurs with the virus scanner (specified by av_scanner) during the
10203 ACL malware condition.
10207 When a message is being received or delivered, this variable contains the
10208 number of lines in the message's body. See also $message_linecount.
10212 When a message is being received or delivered, this variable contains the
10213 number of binary zero bytes (ASCII NULs) in the message's body.
10217 This is set to the recipient address of a bounce message while Exim is
10218 creating it. It is useful if a customized bounce message text file is in
10219 use (see chapter 48).
10221 $bounce_return_size_limit
10223 This contains the value set in the bounce_return_size_limit option, rounded
10224 up to a multiple of 1000. It is useful when a customized error message text
10225 file is in use (see chapter 48).
10229 The real group id under which the process that called Exim was running.
10230 This is not the same as the group id of the originator of a message (see
10231 $originator_gid). If Exim re-execs itself, this variable in the new
10232 incarnation normally contains the Exim gid.
10236 The real user id under which the process that called Exim was running. This
10237 is not the same as the user id of the originator of a message (see
10238 $originator_uid). If Exim re-execs itself, this variable in the new
10239 incarnation normally contains the Exim uid.
10243 The date on which the Exim binary was compiled.
10247 The building process for Exim keeps a count of the number of times it has
10248 been compiled. This serves to distinguish different compilations of the
10249 same version of the program.
10253 This variable is available when Exim is compiled with the content-scanning
10254 extension and the obsolete demime condition. For details, see section 43.6.
10258 This variable is available when Exim is compiled with the content-scanning
10259 extension and the obsolete demime condition. For details, see section 43.6.
10261 $dnslist_domain, $dnslist_matched, $dnslist_text, $dnslist_value
10263 When a DNS (black) list lookup succeeds, these variables are set to contain
10264 the following data from the lookup: the list's domain name, the key that
10265 was looked up, the contents of any associated TXT record, and the value
10266 from the main A record. See section 42.32 for more details.
10270 When an address is being routed, or delivered on its own, this variable
10271 contains the domain. Uppercase letters in the domain are converted into
10272 lower case for $domain.
10274 Global address rewriting happens when a message is received, so the value
10275 of $domain during routing and delivery is the value after rewriting.
10276 $domain is set during user filtering, but not during system filtering,
10277 because a message may have many recipients and the system filter is called
10280 When more than one address is being delivered at once (for example, several
10281 RCPT commands in one SMTP delivery), $domain is set only if they all have
10282 the same domain. Transports can be restricted to handling only one domain
10283 at a time if the value of $domain is required at transport time - this is
10284 the default for local transports. For further details of the environment in
10285 which local transports are run, see chapter 23.
10287 At the end of a delivery, if all deferred addresses have the same domain,
10288 it is set in $domain during the expansion of delay_warning_condition.
10290 The $domain variable is also used in some other circumstances:
10292 * When an ACL is running for a RCPT command, $domain contains the domain
10293 of the recipient address. The domain of the sender address is in
10294 $sender_address_domain at both MAIL time and at RCPT time. $domain is
10295 not normally set during the running of the MAIL ACL. However, if the
10296 sender address is verified with a callout during the MAIL ACL, the
10297 sender domain is placed in $domain during the expansions of hosts,
10298 interface, and port in the smtp transport.
10300 * When a rewrite item is being processed (see chapter 31), $domain
10301 contains the domain portion of the address that is being rewritten; it
10302 can be used in the expansion of the replacement address, for example,
10303 to rewrite domains by file lookup.
10305 * With one important exception, whenever a domain list is being scanned,
10306 $domain contains the subject domain. Exception: When a domain list in a
10307 sender_domains condition in an ACL is being processed, the subject
10308 domain is in $sender_address_domain and not in $domain. It works this
10309 way so that, in a RCPT ACL, the sender domain list can be dependent on
10310 the recipient domain (which is what is in $domain at this time).
10312 * When the smtp_etrn_command option is being expanded, $domain contains
10313 the complete argument of the ETRN command (see section 47.8).
10317 When the domains option on a router matches a domain by means of a lookup,
10318 the data read by the lookup is available during the running of the router
10319 as $domain_data. In addition, if the driver routes the address to a
10320 transport, the value is available in that transport. If the transport is
10321 handling multiple addresses, the value from the first address is used.
10323 $domain_data is also set when the domains condition in an ACL matches a
10324 domain by means of a lookup. The data read by the lookup is available
10325 during the rest of the ACL statement. In all other situations, this
10326 variable expands to nothing.
10330 This variable contains the numerical value of the Exim group id.
10334 This variable contains the path to the Exim binary.
10338 This variable contains the numerical value of the Exim user id.
10342 This variable is available when Exim is compiled with the content-scanning
10343 extension and the obsolete demime condition. For details, see section 43.6.
10347 This is not strictly an expansion variable. It is expansion syntax for
10348 inserting the message header line with the given name. Note that the name
10349 must be terminated by colon or white space, because it may contain a wide
10350 variety of characters. Note also that braces must not be used.
10354 Within an ACL this variable contains the headers added so far by the ACL
10355 modifier add_header (section 42.24). The headers are a newline-separated
10360 When the check_local_user option is set for a router, the user's home
10361 directory is placed in $home when the check succeeds. In particular, this
10362 means it is set during the running of users' filter files. A router may
10363 also explicitly set a home directory for use by a transport; this can be
10364 overridden by a setting on the transport itself.
10366 When running a filter test via the -bf option, $home is set to the value of
10367 the environment variable HOME.
10371 If a router assigns an address to a transport (any transport), and passes a
10372 list of hosts with the address, the value of $host when the transport
10373 starts to run is the name of the first host on the list. Note that this
10374 applies both to local and remote transports.
10376 For the smtp transport, if there is more than one host, the value of $host
10377 changes as the transport works its way through the list. In particular,
10378 when the smtp transport is expanding its options for encryption using TLS,
10379 or for specifying a transport filter (see chapter 24), $host contains the
10380 name of the host to which it is connected.
10382 When used in the client part of an authenticator configuration (see chapter
10383 33), $host contains the name of the server to which the client is
10388 This variable is set to the remote host's IP address whenever $host is set
10389 for a remote connection. It is also set to the IP address that is being
10390 checked when the ignore_target_hosts option is being processed.
10394 If a hosts condition in an ACL is satisfied by means of a lookup, the
10395 result of the lookup is made available in the $host_data variable. This
10396 allows you, for example, to do things like this:
10398 deny hosts = net-lsearch;/some/file
10399 message = $host_data
10401 $host_lookup_deferred
10403 This variable normally contains "0", as does $host_lookup_failed. When a
10404 message comes from a remote host and there is an attempt to look up the
10405 host's name from its IP address, and the attempt is not successful, one of
10406 these variables is set to "1".
10408 * If the lookup receives a definite negative response (for example, a DNS
10409 lookup succeeded, but no records were found), $host_lookup_failed is
10412 * If there is any kind of problem during the lookup, such that Exim
10413 cannot tell whether or not the host name is defined (for example, a
10414 timeout for a DNS lookup), $host_lookup_deferred is set to "1".
10416 Looking up a host's name from its IP address consists of more than just a
10417 single reverse lookup. Exim checks that a forward lookup of at least one of
10418 the names it receives from a reverse lookup yields the original IP address.
10419 If this is not the case, Exim does not accept the looked up name(s), and
10420 $host_lookup_failed is set to "1". Thus, being able to find a name from an
10421 IP address (for example, the existence of a PTR record in the DNS) is not
10422 sufficient on its own for the success of a host name lookup. If the reverse
10423 lookup succeeds, but there is a lookup problem such as a timeout when
10424 checking the result, the name is not accepted, and $host_lookup_deferred is
10425 set to "1". See also $sender_host_name.
10427 $host_lookup_failed
10429 See $host_lookup_deferred.
10433 The only time this variable is set is while expanding the directory_file
10434 option in the appendfile transport. The variable contains the inode number
10435 of the temporary file which is about to be renamed. It can be used to
10436 construct a unique name for the file.
10440 This is an obsolete name for $received_ip_address.
10444 This is an obsolete name for $received_port.
10448 This variable is used during the expansion of forall and forany conditions
10449 (see section 11.7), and filter, map, and reduce items (see section 11.7).
10450 In other circumstances, it is empty.
10454 This variable, which is available only when Exim is compiled with LDAP
10455 support, contains the DN from the last entry in the most recently
10456 successful LDAP lookup.
10460 This variable contains the system load average, multiplied by 1000 so that
10461 it is an integer. For example, if the load average is 0.21, the value of
10462 the variable is 210. The value is recomputed every time the variable is
10467 When an address is being routed, or delivered on its own, this variable
10468 contains the local part. When a number of addresses are being delivered
10469 together (for example, multiple RCPT commands in an SMTP session),
10470 $local_part is not set.
10472 Global address rewriting happens when a message is received, so the value
10473 of $local_part during routing and delivery is the value after rewriting.
10474 $local_part is set during user filtering, but not during system filtering,
10475 because a message may have many recipients and the system filter is called
10478 If a local part prefix or suffix has been recognized, it is not included in
10479 the value of $local_part during routing and subsequent delivery. The values
10480 of any prefix or suffix are in $local_part_prefix and $local_part_suffix,
10483 When a message is being delivered to a file, pipe, or autoreply transport
10484 as a result of aliasing or forwarding, $local_part is set to the local part
10485 of the parent address, not to the file name or command (see $address_file
10486 and $address_pipe).
10488 When an ACL is running for a RCPT command, $local_part contains the local
10489 part of the recipient address.
10491 When a rewrite item is being processed (see chapter 31), $local_part
10492 contains the local part of the address that is being rewritten; it can be
10493 used in the expansion of the replacement address, for example.
10495 In all cases, all quoting is removed from the local part. For example, for
10498 "abc:xyz"@test.example
10499 abc\:xyz@test.example
10501 the value of $local_part is
10505 If you use $local_part to create another address, you should always wrap it
10506 inside a quoting operator. For example, in a redirect router you could
10509 data = ${quote_local_part:$local_part}@new.domain.example
10511 Note: The value of $local_part is normally lower cased. If you want to
10512 process local parts in a case-dependent manner in a router, you can set the
10513 caseful_local_part option (see chapter 15).
10517 When the local_parts option on a router matches a local part by means of a
10518 lookup, the data read by the lookup is available during the running of the
10519 router as $local_part_data. In addition, if the driver routes the address
10520 to a transport, the value is available in that transport. If the transport
10521 is handling multiple addresses, the value from the first address is used.
10523 $local_part_data is also set when the local_parts condition in an ACL
10524 matches a local part by means of a lookup. The data read by the lookup is
10525 available during the rest of the ACL statement. In all other situations,
10526 this variable expands to nothing.
10530 When an address is being routed or delivered, and a specific prefix for the
10531 local part was recognized, it is available in this variable, having been
10532 removed from $local_part.
10536 When an address is being routed or delivered, and a specific suffix for the
10537 local part was recognized, it is available in this variable, having been
10538 removed from $local_part.
10542 This variable contains the text returned by the local_scan() function when
10543 a message is received. See chapter 44 for more details.
10547 See $local_user_uid.
10551 This variable and $local_user_gid are set to the uid and gid after the
10552 check_local_user router precondition succeeds. This means that their values
10553 are available for the remaining preconditions (senders, require_files, and
10554 condition), for the address_data expansion, and for any router-specific
10555 expansions. At all other times, the values in these variables are "(uid_t)
10556 (-1)" and "(gid_t)(-1)", respectively.
10560 This contains the expanded value of the localhost_number option. The
10561 expansion happens after the main options have been read.
10565 The number of free inodes in the disk partition where Exim's log files are
10566 being written. The value is recalculated whenever the variable is
10567 referenced. If the relevant file system does not have the concept of
10568 inodes, the value of is -1. See also the check_log_inodes option.
10572 The amount of free space (as a number of kilobytes) in the disk partition
10573 where Exim's log files are being written. The value is recalculated
10574 whenever the variable is referenced. If the operating system does not have
10575 the ability to find the amount of free space (only true for experimental
10576 systems), the space value is -1. See also the check_log_space option.
10578 $lookup_dnssec_authenticated
10580 This variable is set after a DNS lookup done by a dnsdb lookup expansion,
10581 dnslookup router or smtp transport. It will be empty if DNSSEC was not
10582 requested, "no" if the result was not labelled as authenticated data and
10585 $mailstore_basename
10587 This variable is set only when doing deliveries in "mailstore" format in
10588 the appendfile transport. During the expansion of the mailstore_prefix,
10589 mailstore_suffix, message_prefix, and message_suffix options, it contains
10590 the basename of the files that are being written, that is, the name without
10591 the ".tmp", ".env", or ".msg" suffix. At all other times, this variable is
10596 This variable is available when Exim is compiled with the content-scanning
10597 extension. It is set to the name of the virus that was found when the ACL
10598 malware condition is true (see section 43.1).
10600 $max_received_linelength
10602 This variable contains the number of bytes in the longest line that was
10603 received as part of the message, not counting the line termination
10608 This variable is set at the start of a delivery attempt to contain the
10609 number of seconds since the message was received. It does not change during
10610 a single delivery attempt.
10614 This variable contains the initial portion of a message's body while it is
10615 being delivered, and is intended mainly for use in filter files. The
10616 maximum number of characters of the body that are put into the variable is
10617 set by the message_body_visible configuration option; the default is 500.
10619 By default, newlines are converted into spaces in $message_body, to make it
10620 easier to search for phrases that might be split over a line break.
10621 However, this can be disabled by setting message_body_newlines to be true.
10622 Binary zeros are always converted into spaces.
10626 This variable contains the final portion of a message's body while it is
10627 being delivered. The format and maximum size are as for $message_body.
10631 When a message is being delivered, this variable contains the size of the
10632 body in bytes. The count starts from the character after the blank line
10633 that separates the body from the header. Newlines are included in the
10634 count. See also $message_size, $body_linecount, and $body_zerocount.
10638 When a message is being received or delivered, this variable contains the
10639 unique message id that is generated and used by Exim to identify the
10640 message. An id is not created for a message until after its header has been
10641 successfully received. Note: This is not the contents of the Message-ID:
10642 header line; it is the local id that Exim assigns to the message, for
10643 example: "1BXTIK-0001yO-VA".
10647 This variable contains a concatenation of all the header lines when a
10648 message is being processed, except for lines added by routers or
10649 transports. The header lines are separated by newline characters. Their
10650 contents are decoded in the same way as a header line that is inserted by
10653 $message_headers_raw
10655 This variable is like $message_headers except that no processing of the
10656 contents of header lines is done.
10660 This is an old name for $message_exim_id, which is now deprecated.
10664 This variable contains the total number of lines in the header and body of
10665 the message. Compare $body_linecount, which is the count for the body only.
10666 During the DATA and content-scanning ACLs, $message_linecount contains the
10667 number of lines received. Before delivery happens (that is, before filters,
10668 routers, and transports run) the count is increased to include the
10669 Received: header line that Exim standardly adds, and also any other header
10670 lines that are added by ACLs. The blank line that separates the message
10671 header from the body is not counted.
10673 As with the special case of $message_size, during the expansion of the
10674 appendfile transport's maildir_tag option in maildir format, the value of
10675 $message_linecount is the precise size of the number of newlines in the
10676 file that has been written (minus one for the blank line between the header
10679 Here is an example of the use of this variable in a DATA ACL:
10681 deny message = Too many lines in message header
10683 ${if <{250}{${eval:$message_linecount - $body_linecount}}}
10685 In the MAIL and RCPT ACLs, the value is zero because at that stage the
10686 message has not yet been received.
10690 When a message is being processed, this variable contains its size in
10691 bytes. In most cases, the size includes those headers that were received
10692 with the message, but not those (such as Envelope-to:) that are added to
10693 individual deliveries as they are written. However, there is one special
10694 case: during the expansion of the maildir_tag option in the appendfile
10695 transport while doing a delivery in maildir format, the value of
10696 $message_size is the precise size of the file that has been written. See
10697 also $message_body_size, $body_linecount, and $body_zerocount.
10699 While running a per message ACL (mail/rcpt/predata), $message_size contains
10700 the size supplied on the MAIL command, or -1 if no size was given. The
10701 value may not, of course, be truthful.
10705 A number of variables whose names start with $mime are available when Exim
10706 is compiled with the content-scanning extension. For details, see section
10711 These variables are counters that can be incremented by means of the add
10712 command in filter files.
10716 When a top-level address is being processed for delivery, this contains the
10717 same value as $domain. However, if a "child" address (for example,
10718 generated by an alias, forward, or filter file) is being processed, this
10719 variable contains the domain of the original address (lower cased). This
10720 differs from $parent_domain only when there is more than one level of
10721 aliasing or forwarding. When more than one address is being delivered in a
10722 single transport run, $original_domain is not set.
10724 If a new address is created by means of a deliver command in a system
10725 filter, it is set up with an artificial "parent" address. This has the
10726 local part system-filter and the default qualify domain.
10728 $original_local_part
10730 When a top-level address is being processed for delivery, this contains the
10731 same value as $local_part, unless a prefix or suffix was removed from the
10732 local part, because $original_local_part always contains the full local
10733 part. When a "child" address (for example, generated by an alias, forward,
10734 or filter file) is being processed, this variable contains the full local
10735 part of the original address.
10737 If the router that did the redirection processed the local part
10738 case-insensitively, the value in $original_local_part is in lower case.
10739 This variable differs from $parent_local_part only when there is more than
10740 one level of aliasing or forwarding. When more than one address is being
10741 delivered in a single transport run, $original_local_part is not set.
10743 If a new address is created by means of a deliver command in a system
10744 filter, it is set up with an artificial "parent" address. This has the
10745 local part system-filter and the default qualify domain.
10749 This variable contains the value of $caller_gid that was set when the
10750 message was received. For messages received via the command line, this is
10751 the gid of the sending user. For messages received by SMTP over TCP/IP,
10752 this is normally the gid of the Exim user.
10756 The value of $caller_uid that was set when the message was received. For
10757 messages received via the command line, this is the uid of the sending
10758 user. For messages received by SMTP over TCP/IP, this is normally the uid
10763 This variable is similar to $original_domain (see above), except that it
10764 refers to the immediately preceding parent address.
10768 This variable is similar to $original_local_part (see above), except that
10769 it refers to the immediately preceding parent address.
10773 This variable contains the current process id.
10777 This is not an expansion variable, but is mentioned here because the string
10778 "$pipe_addresses" is handled specially in the command specification for the
10779 pipe transport (chapter 29) and in transport filters (described under
10780 transport_filter in chapter 24). It cannot be used in general expansion
10781 strings, and provokes an "unknown variable" error if encountered.
10785 This variable contains the value set by primary_hostname in the
10786 configuration file, or read by the uname() function. If uname() returns a
10787 single-component name, Exim calls gethostbyname() (or getipnodebyname()
10788 where available) in an attempt to acquire a fully qualified host name. See
10789 also $smtp_active_hostname.
10793 This variable is used in conjunction with the prvscheck expansion item,
10794 which is described in sections 11.5 and 42.51.
10798 This variable is used in conjunction with the prvscheck expansion item,
10799 which is described in sections 11.5 and 42.51.
10803 This variable is used in conjunction with the prvscheck expansion item,
10804 which is described in sections 11.5 and 42.51.
10808 The value set for the qualify_domain option in the configuration file.
10812 The value set for the qualify_recipient option in the configuration file,
10813 or if not set, the value of $qualify_domain.
10817 When a message is being received by SMTP, this variable contains the number
10818 of RCPT commands received for the current message. If this variable is used
10819 in a RCPT ACL, its value includes the current command.
10823 When a message is being received by SMTP, this variable contains the number
10824 of RCPT commands in the current message that have previously been rejected
10825 with a temporary (4xx) response.
10829 When a message is being received by SMTP, this variable contains the number
10830 of RCPT commands in the current message that have previously been rejected
10831 with a permanent (5xx) response.
10835 This variable contains the number of Received: header lines in the message,
10836 including the one added by Exim (so its value is always greater than zero).
10837 It is available in the DATA ACL, the non-SMTP ACL, and while routing and
10842 If there is only a single recipient address in an incoming message, this
10843 variable contains that address when the Received: header line is being
10844 built. The value is copied after recipient rewriting has happened, but
10845 before the local_scan() function is run.
10847 $received_ip_address
10849 As soon as an Exim server starts processing an incoming TCP/IP connection,
10850 this variable is set to the address of the local IP interface, and
10851 $received_port is set to the local port number. (The remote IP address and
10852 port are in $sender_host_address and $sender_host_port.) When testing with
10853 -bh, the port value is -1 unless it has been set using the -oMi command
10856 As well as being useful in ACLs (including the "connect" ACL), these
10857 variable could be used, for example, to make the file name for a TLS
10858 certificate depend on which interface and/or port is being used for the
10859 incoming connection. The values of $received_ip_address and $received_port
10860 are saved with any messages that are received, thus making these variables
10861 available at delivery time.
10863 Note: There are no equivalent variables for outgoing connections, because
10864 the values are unknown (unless they are explicitly set by options of the
10869 See $received_ip_address.
10873 When a message is being processed, this variable contains the name of the
10874 protocol by which it was received. Most of the names used by Exim are
10875 defined by RFCs 821, 2821, and 3848. They start with "smtp" (the client
10876 used HELO) or "esmtp" (the client used EHLO). This can be followed by "s"
10877 for secure (encrypted) and/or "a" for authenticated. Thus, for example, if
10878 the protocol is set to "esmtpsa", the message was received over an
10879 encrypted SMTP connection and the client was successfully authenticated.
10881 Exim uses the protocol name "smtps" for the case when encryption is
10882 automatically set up on connection without the use of STARTTLS (see
10883 tls_on_connect_ports), and the client uses HELO to initiate the encrypted
10884 SMTP session. The name "smtps" is also used for the rare situation where
10885 the client initially uses EHLO, sets up an encrypted connection using
10886 STARTTLS, and then uses HELO afterwards.
10888 The -oMr option provides a way of specifying a custom protocol name for
10889 messages that are injected locally by trusted callers. This is commonly
10890 used to identify messages that are being re-injected after some kind of
10895 This variable contains the date and time when the current message was
10896 received, as a number of seconds since the start of the Unix epoch.
10900 This variable is set after an indexing lookup success in an ACL recipients
10901 condition. It contains the data from the lookup, and the value remains set
10902 until the next recipients test. Thus, you can do things like this:
10904 require recipients = cdb*@;/some/file
10905 deny some further test involving $recipient_data
10907 Warning: This variable is set only when a lookup is used as an indexing
10908 method in the address list, using the semicolon syntax as in the example
10909 above. The variable is not set for a lookup that is used as part of the
10910 string expansion that all such lists undergo before being interpreted.
10912 $recipient_verify_failure
10914 In an ACL, when a recipient verification fails, this variable contains
10915 information about the failure. It is set to one of the following words:
10917 * "qualify": The address was unqualified (no domain), and the message was
10918 neither local nor came from an exempted host.
10920 * "route": Routing failed.
10922 * "mail": Routing succeeded, and a callout was attempted; rejection
10923 occurred at or before the MAIL command (that is, on initial connection,
10926 * "recipient": The RCPT command in a callout was rejected.
10928 * "postmaster": The postmaster check in a callout was rejected.
10930 The main use of this variable is expected to be to distinguish between
10931 rejections of MAIL and rejections of RCPT.
10935 This variable contains a list of envelope recipients for a message. A comma
10936 and a space separate the addresses in the replacement text. However, the
10937 variable is not generally available, to prevent exposure of Bcc recipients
10938 in unprivileged users' filter files. You can use $recipients only in these
10941 1. In a system filter file.
10943 2. In the ACLs associated with the DATA command and with non-SMTP
10944 messages, that is, the ACLs defined by acl_smtp_predata, acl_smtp_data,
10945 acl_smtp_mime, acl_not_smtp_start, acl_not_smtp, and acl_not_smtp_mime.
10947 3. From within a local_scan() function.
10951 When a message is being processed, this variable contains the number of
10952 envelope recipients that came with the message. Duplicates are not excluded
10953 from the count. While a message is being received over SMTP, the number
10954 increases for each accepted recipient. It can be referenced in an ACL.
10956 $regex_match_string
10958 This variable is set to contain the matching regular expression after a
10959 regex ACL condition has matched (see section 43.5).
10963 When a message is being processed, this variable contains the contents of
10964 the Reply-To: header line if one exists and it is not empty, or otherwise
10965 the contents of the From: header line. Apart from the removal of leading
10966 white space, the value is not processed in any way. In particular, no RFC
10967 2047 decoding or character code translation takes place.
10971 When a message is being delivered, this variable contains the return path -
10972 the sender field that will be sent as part of the envelope. It is not
10973 enclosed in <> characters. At the start of routing an address, $return_path
10974 has the same value as $sender_address, but if, for example, an incoming
10975 message to a mailing list has been expanded by a router which specifies a
10976 different address for bounce messages, $return_path subsequently contains
10977 the new bounce address, whereas $sender_address always contains the
10978 original sender address that was received with the message. In other words,
10979 $sender_address contains the incoming envelope sender, and $return_path
10980 contains the outgoing envelope sender.
10984 This is an obsolete name for $bounce_return_size_limit.
10988 During the running of a router this variable contains its name.
10992 This variable contains the return code from a command that is run by the $
10993 {run...} expansion item. Warning: In a router or transport, you cannot
10994 assume the order in which option values are expanded, except for those
10995 preconditions whose order of testing is documented. Therefore, you cannot
10996 reliably expect to set $runrc by the expansion of one option, and use it in
11001 When an address is routed to a supposedly remote host that turns out to be
11002 the local host, what happens is controlled by the self generic router
11003 option. One of its values causes the address to be passed to another
11004 router. When this happens, $self_hostname is set to the name of the local
11005 host that the original router encountered. In other circumstances its
11010 When a message is being processed, this variable contains the sender's
11011 address that was received in the message's envelope. The case of letters in
11012 the address is retained, in both the local part and the domain. For bounce
11013 messages, the value of this variable is the empty string. See also
11016 $sender_address_data
11018 If $address_data is set when the routers are called from an ACL to verify a
11019 sender address, the final value is preserved in $sender_address_data, to
11020 distinguish it from data from a recipient address. The value does not
11021 persist after the end of the current ACL statement. If you want to preserve
11022 it for longer, you can save it in an ACL variable.
11024 $sender_address_domain
11026 The domain portion of $sender_address.
11028 $sender_address_local_part
11030 The local part portion of $sender_address.
11034 This variable is set after a lookup success in an ACL senders condition or
11035 in a router senders option. It contains the data from the lookup, and the
11036 value remains set until the next senders test. Thus, you can do things like
11039 require senders = cdb*@;/some/file
11040 deny some further test involving $sender_data
11042 Warning: This variable is set only when a lookup is used as an indexing
11043 method in the address list, using the semicolon syntax as in the example
11044 above. The variable is not set for a lookup that is used as part of the
11045 string expansion that all such lists undergo before being interpreted.
11049 When a message is received from a remote host, this variable contains the
11050 host name and IP address in a single string. It ends with the IP address in
11051 square brackets, followed by a colon and a port number if the logging of
11052 ports is enabled. The format of the rest of the string depends on whether
11053 the host issued a HELO or EHLO SMTP command, and whether the host name was
11054 verified by looking up its IP address. (Looking up the IP address can be
11055 forced by the host_lookup option, independent of verification.) A plain
11056 host name at the start of the string is a verified host name; if this is
11057 not present, verification either failed or was not requested. A host name
11058 in parentheses is the argument of a HELO or EHLO command. This is omitted
11059 if it is identical to the verified host name or to the host's IP address in
11064 When a message is received from a remote host that has issued a HELO or
11065 EHLO command, the argument of that command is placed in this variable. It
11066 is also set if HELO or EHLO is used when a message is received using SMTP
11067 locally via the -bs or -bS options.
11069 $sender_host_address
11071 When a message is received from a remote host, this variable contains that
11072 host's IP address. For locally submitted messages, it is empty.
11074 $sender_host_authenticated
11076 This variable contains the name (not the public name) of the authenticator
11077 driver that successfully authenticated the client from which the message
11078 was received. It is empty if there was no successful authentication. See
11079 also $authenticated_id.
11081 $sender_host_dnssec
11083 If an attempt to populate $sender_host_name has been made (by reference,
11084 hosts_lookup or otherwise) then this boolean will have been set true if,
11085 and only if, the resolver library states that the reverse DNS was
11086 authenticated data. At all other times, this variable is false.
11088 It is likely that you will need to coerce DNSSEC support on in the resolver
11089 library, by setting:
11093 Exim does not perform DNSSEC validation itself, instead leaving that to a
11094 validating resolver (eg, unbound, or bind with suitable configuration).
11096 Exim does not (currently) check to see if the forward DNS was also secured
11097 with DNSSEC, only the reverse DNS.
11099 If you have changed host_lookup_order so that "bydns" is not the first
11100 mechanism in the list, then this variable will be false.
11104 When a message is received from a remote host, this variable contains the
11105 host's name as obtained by looking up its IP address. For messages received
11106 by other means, this variable is empty.
11108 If the host name has not previously been looked up, a reference to
11109 $sender_host_name triggers a lookup (for messages from remote hosts). A
11110 looked up name is accepted only if it leads back to the original IP address
11111 via a forward lookup. If either the reverse or the forward lookup fails to
11112 find any data, or if the forward lookup does not yield the original IP
11113 address, $sender_host_name remains empty, and $host_lookup_failed is set to
11116 However, if either of the lookups cannot be completed (for example, there
11117 is a DNS timeout), $host_lookup_deferred is set to "1", and
11118 $host_lookup_failed remains set to "0".
11120 Once $host_lookup_failed is set to "1", Exim does not try to look up the
11121 host name again if there is a subsequent reference to $sender_host_name in
11122 the same Exim process, but it does try again if $host_lookup_deferred is
11125 Exim does not automatically look up every calling host's name. If you want
11126 maximum efficiency, you should arrange your configuration so that it avoids
11127 these lookups altogether. The lookup happens only if one or more of the
11128 following are true:
11130 * A string containing $sender_host_name is expanded.
11132 * The calling host matches the list in host_lookup. In the default
11133 configuration, this option is set to *, so it must be changed if
11134 lookups are to be avoided. (In the code, the default for host_lookup is
11137 * Exim needs the host name in order to test an item in a host list. The
11138 items that require this are described in sections 10.13 and 10.17.
11140 * The calling host matches helo_try_verify_hosts or helo_verify_hosts. In
11141 this case, the host name is required to compare with the name quoted in
11142 any EHLO or HELO commands that the client issues.
11144 * The remote host issues a EHLO or HELO command that quotes one of the
11145 domains in helo_lookup_domains. The default value of this option is
11147 helo_lookup_domains = @ : @[]
11149 which causes a lookup if a remote host (incorrectly) gives the server's
11150 name or IP address in an EHLO or HELO command.
11154 When a message is received from a remote host, this variable contains the
11155 port number that was used on the remote host.
11159 When a message is received from a remote host, this variable contains the
11160 identification received in response to an RFC 1413 request. When a message
11161 has been received locally, this variable contains the login name of the
11162 user that called Exim.
11166 A number of variables whose names begin $sender_rate_ are set as part of
11167 the ratelimit ACL condition. Details are given in section 42.38.
11171 This is provided specifically for use in Received: headers. It starts with
11172 either the verified host name (as obtained from a reverse DNS lookup) or,
11173 if there is no verified host name, the IP address in square brackets. After
11174 that there may be text in parentheses. When the first item is a verified
11175 host name, the first thing in the parentheses is the IP address in square
11176 brackets, followed by a colon and a port number if port logging is enabled.
11177 When the first item is an IP address, the port is recorded as "port=xxxx"
11178 inside the parentheses.
11180 There may also be items of the form "helo=xxxx" if HELO or EHLO was used
11181 and its argument was not identical to the real host name or IP address, and
11182 "ident=xxxx" if an RFC 1413 ident string is available. If all three items
11183 are present in the parentheses, a newline and tab are inserted into the
11184 string, to improve the formatting of the Received: header.
11186 $sender_verify_failure
11188 In an ACL, when a sender verification fails, this variable contains
11189 information about the failure. The details are the same as for
11190 $recipient_verify_failure.
11192 $sending_ip_address
11194 This variable is set whenever an outgoing SMTP connection to another host
11195 has been set up. It contains the IP address of the local interface that is
11196 being used. This is useful if a host that has more than one IP address
11197 wants to take on different personalities depending on which one is being
11198 used. For incoming connections, see $received_ip_address.
11202 This variable is set whenever an outgoing SMTP connection to another host
11203 has been set up. It contains the local port that is being used. For
11204 incoming connections, see $received_port.
11206 $smtp_active_hostname
11208 During an incoming SMTP session, this variable contains the value of the
11209 active host name, as specified by the smtp_active_hostname option. The
11210 value of $smtp_active_hostname is saved with any message that is received,
11211 so its value can be consulted during routing and delivery.
11215 During the processing of an incoming SMTP command, this variable contains
11216 the entire command. This makes it possible to distinguish between HELO and
11217 EHLO in the HELO ACL, and also to distinguish between commands such as
11223 For a MAIL command, extra parameters such as SIZE can be inspected. For a
11224 RCPT command, the address in $smtp_command is the original address before
11225 any rewriting, whereas the values in $local_part and $domain are taken from
11226 the address after SMTP-time rewriting.
11228 $smtp_command_argument
11230 While an ACL is running to check an SMTP command, this variable contains
11231 the argument, that is, the text that follows the command name, with leading
11232 white space removed. Following the introduction of $smtp_command, this
11233 variable is somewhat redundant, but is retained for backwards
11236 $smtp_count_at_connection_start
11238 This variable is set greater than zero only in processes spawned by the
11239 Exim daemon for handling incoming SMTP connections. The name is
11240 deliberately long, in order to emphasize what the contents are. When the
11241 daemon accepts a new connection, it increments this variable. A copy of the
11242 variable is passed to the child process that handles the connection, but
11243 its value is fixed, and never changes. It is only an approximation of how
11244 many incoming connections there actually are, because many other
11245 connections may come and go while a single connection is being processed.
11246 When a child process terminates, the daemon decrements its copy of the
11251 These variables are copies of the values of the $n0 - $n9 accumulators that
11252 were current at the end of the system filter file. This allows a system
11253 filter file to set values that can be tested in users' filter files. For
11254 example, a system filter could set a value indicating how likely it is that
11255 a message is junk mail.
11259 A number of variables whose names start with $spam are available when Exim
11260 is compiled with the content-scanning extension. For details, see section
11265 The name of Exim's spool directory.
11269 The number of free inodes in the disk partition where Exim's spool files
11270 are being written. The value is recalculated whenever the variable is
11271 referenced. If the relevant file system does not have the concept of
11272 inodes, the value of is -1. See also the check_spool_inodes option.
11276 The amount of free space (as a number of kilobytes) in the disk partition
11277 where Exim's spool files are being written. The value is recalculated
11278 whenever the variable is referenced. If the operating system does not have
11279 the ability to find the amount of free space (only true for experimental
11280 systems), the space value is -1. For example, to check in an ACL that there
11281 is at least 50 megabytes free on the spool, you could write:
11283 condition = ${if > {$spool_space}{50000}}
11285 See also the check_spool_space option.
11289 This variable is set only during the processing of the foranyaddress
11290 command in a filter file. Its use is explained in the description of that
11291 command, which can be found in the separate document entitled Exim's
11292 interfaces to mail filtering.
11296 Contains an approximation of the TLS cipher's bit-strength on the inbound
11297 connection; the meaning of this depends upon the TLS implementation used.
11298 If TLS has not been negotiated, the value will be 0. The value of this is
11299 automatically fed into the Cyrus SASL authenticator when acting as a
11300 server, to specify the "external SSF" (a SASL term).
11302 The deprecated $tls_bits variable refers to the inbound side except when
11303 used in the context of an outbound SMTP delivery, when it refers to the
11308 Contains an approximation of the TLS cipher's bit-strength on an outbound
11309 SMTP connection; the meaning of this depends upon the TLS implementation
11310 used. If TLS has not been negotiated, the value will be 0.
11314 This variable refers to the certificate presented to the peer of an inbound
11315 connection when the message was received. It is only useful as the argument
11316 of a certextract expansion item, md5 or sha1 operator, or a def condition.
11320 This variable refers to the certificate presented by the peer of an inbound
11321 connection when the message was received. It is only useful as the argument
11322 of a certextract expansion item, md5 or sha1 operator, or a def condition.
11326 This variable refers to the certificate presented to the peer of an
11327 outbound connection. It is only useful as the argument of a certextract
11328 expansion item, md5 or sha1 operator, or a def condition.
11332 This variable refers to the certificate presented by the peer of an
11333 outbound connection. It is only useful as the argument of a certextract
11334 expansion item, md5 or sha1 operator, or a def condition.
11336 $tls_in_certificate_verified
11338 This variable is set to "1" if a TLS certificate was verified when the
11339 message was received, and "0" otherwise.
11341 The deprecated $tls_certificate_verfied variable refers to the inbound side
11342 except when used in the context of an outbound SMTP delivery, when it
11343 refers to the outbound.
11345 $tls_out_certificate_verified
11347 This variable is set to "1" if a TLS certificate was verified when an
11348 outbound SMTP connection was made, and "0" otherwise.
11352 When a message is received from a remote host over an encrypted SMTP
11353 connection, this variable is set to the cipher suite that was negotiated,
11354 for example DES-CBC3-SHA. In other circumstances, in particular, for
11355 message received over unencrypted connections, the variable is empty.
11356 Testing $tls_cipher for emptiness is one way of distinguishing between
11357 encrypted and non-encrypted connections during ACL processing.
11359 The deprecated $tls_cipher variable is the same as $tls_in_cipher during
11360 message reception, but in the context of an outward SMTP delivery taking
11361 place via the smtp transport becomes the same as $tls_out_cipher.
11365 This variable is cleared before any outgoing SMTP connection is made, and
11366 then set to the outgoing cipher suite if one is negotiated. See chapter 41
11367 for details of TLS support and chapter 30 for details of the smtp
11372 When a message is received from a remote client connection the result of
11373 any OCSP request from the client is encoded in this variable:
11375 0 OCSP proof was not requested (default value)
11376 1 No response to request
11377 2 Response not verified
11378 3 Verification failed
11379 4 Verification succeeded
11383 When a message is sent to a remote host connection the result of any OCSP
11384 request made is encoded in this variable. See $tls_in_ocsp for values.
11388 When a message is received from a remote host over an encrypted SMTP
11389 connection, and Exim is configured to request a certificate from the
11390 client, the value of the Distinguished Name of the certificate is made
11391 available in the $tls_in_peerdn during subsequent processing.
11393 The deprecated $tls_peerdn variable refers to the inbound side except when
11394 used in the context of an outbound SMTP delivery, when it refers to the
11399 When a message is being delivered to a remote host over an encrypted SMTP
11400 connection, and Exim is configured to request a certificate from the
11401 server, the value of the Distinguished Name of the certificate is made
11402 available in the $tls_out_peerdn during subsequent processing.
11406 When a TLS session is being established, if the client sends the Server
11407 Name Indication extension, the value will be placed in this variable. If
11408 the variable appears in tls_certificate then this option and some others,
11409 described in 41.10, will be re-expanded early in the TLS session, to permit
11410 a different certificate to be presented (and optionally a different key to
11411 be used) to the client, based upon the value of the SNI extension.
11413 The deprecated $tls_sni variable refers to the inbound side except when
11414 used in the context of an outbound SMTP delivery, when it refers to the
11419 During outbound SMTP deliveries, this variable reflects the value of the
11420 tls_sni option on the transport.
11424 The time of day and the date, in the format required for BSD-style mailbox
11425 files, for example: Thu Oct 17 17:14:09 1995.
11429 The time and date as a number of seconds since the start of the Unix epoch.
11433 The time and date as a number of microseconds since the start of the Unix
11438 A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40
11439 +0100. The timezone is always given as a numerical offset from UTC, with
11440 positive values used for timezones that are ahead (east) of UTC, and
11441 negative values for those that are behind (west).
11445 The time and date in the format used for writing Exim's log files, for
11446 example: 1995-10-12 15:32:29, but without a timezone.
11450 This variable contains the date in the format yyyymmdd. This is the format
11451 that is used for datestamping log files when log_file_path contains the
11456 This variable contains the numerical value of the local timezone, for
11461 This variable contains the UTC date and time in "Zulu" format, as specified
11462 by ISO 8601, for example: 20030221154023Z.
11466 During the running of a transport, this variable contains its name.
11470 This variable contains the result of an expansion lookup, extraction
11471 operation, or external command, as described above. It is also used during
11472 a reduce expansion.
11476 The version number of Exim.
11478 $warn_message_delay
11480 This variable is set only during the creation of a message warning about a
11481 delivery delay. Details of its use are explained in section 48.2.
11483 $warn_message_recipients
11485 This variable is set only during the creation of a message warning about a
11486 delivery delay. Details of its use are explained in section 48.2.
11490 ===============================================================================
11493 Exim can be built to include an embedded Perl interpreter. When this is done,
11494 Perl subroutines can be called as part of the string expansion process. To make
11495 use of the Perl support, you need version 5.004 or later of Perl installed on
11496 your system. To include the embedded interpreter in the Exim binary, include
11501 in your Local/Makefile and then build Exim in the normal way.
11504 12.1 Setting up so Perl can be used
11505 -----------------------------------
11507 Access to Perl subroutines is via a global configuration option called
11508 perl_startup and an expansion string operator ${perl ...}. If there is no
11509 perl_startup option in the Exim configuration file then no Perl interpreter is
11510 started and there is almost no overhead for Exim (since none of the Perl
11511 library will be paged in unless used). If there is a perl_startup option then
11512 the associated value is taken to be Perl code which is executed in a newly
11513 created Perl interpreter.
11515 The value of perl_startup is not expanded in the Exim sense, so you do not need
11516 backslashes before any characters to escape special meanings. The option should
11517 usually be something like
11519 perl_startup = do '/etc/exim.pl'
11521 where /etc/exim.pl is Perl code which defines any subroutines you want to use
11522 from Exim. Exim can be configured either to start up a Perl interpreter as soon
11523 as it is entered, or to wait until the first time it is needed. Starting the
11524 interpreter at the beginning ensures that it is done while Exim still has its
11525 setuid privilege, but can impose an unnecessary overhead if Perl is not in fact
11526 used in a particular run. Also, note that this does not mean that Exim is
11527 necessarily running as root when Perl is called at a later time. By default,
11528 the interpreter is started only when it is needed, but this can be changed in
11531 * Setting perl_at_start (a boolean option) in the configuration requests a
11532 startup when Exim is entered.
11534 * The command line option -ps also requests a startup when Exim is entered,
11535 overriding the setting of perl_at_start.
11537 There is also a command line option -pd (for delay) which suppresses the
11538 initial startup, even if perl_at_start is set.
11541 12.2 Calling Perl subroutines
11542 -----------------------------
11544 When the configuration file includes a perl_startup option you can make use of
11545 the string expansion item to call the Perl subroutines that are defined by the
11546 perl_startup code. The operator is used in any of the following forms:
11549 ${perl{foo}{argument}}
11550 ${perl{foo}{argument1}{argument2} ... }
11552 which calls the subroutine foo with the given arguments. A maximum of eight
11553 arguments may be passed. Passing more than this results in an expansion failure
11554 with an error message of the form
11556 Too many arguments passed to Perl subroutine "foo" (max is 8)
11558 The return value of the Perl subroutine is evaluated in a scalar context before
11559 it is passed back to Exim to be inserted into the expanded string. If the
11560 return value is undef, the expansion is forced to fail in the same way as an
11561 explicit "fail" on an if or lookup item. If the subroutine aborts by obeying
11562 Perl's die function, the expansion fails with the error message that was passed
11566 12.3 Calling Exim functions from Perl
11567 -------------------------------------
11569 Within any Perl code called from Exim, the function Exim::expand_string() is
11570 available to call back into Exim's string expansion function. For example, the
11573 my $lp = Exim::expand_string('$local_part');
11575 makes the current Exim $local_part available in the Perl variable $lp. Note
11576 those are single quotes and not double quotes to protect against $local_part
11577 being interpolated as a Perl variable.
11579 If the string expansion is forced to fail by a "fail" item, the result of
11580 Exim::expand_string() is undef. If there is a syntax error in the expansion
11581 string, the Perl call from the original expansion string fails with an
11582 appropriate error message, in the same way as if die were used.
11584 Two other Exim functions are available for use from within Perl code.
11585 Exim::debug_write() writes a string to the standard error stream if Exim's
11586 debugging is enabled. If you want a newline at the end, you must supply it.
11587 Exim::log_write() writes a string to Exim's main log, adding a leading
11588 timestamp. In this case, you should not supply a terminating newline.
11591 12.4 Use of standard output and error by Perl
11592 ---------------------------------------------
11594 You should not write to the standard error or output streams from within your
11595 Perl code, as it is not defined how these are set up. In versions of Exim
11596 before 4.50, it is possible for the standard output or error to refer to the
11597 SMTP connection during message reception via the daemon. Writing to this stream
11598 is certain to cause chaos. From Exim 4.50 onwards, the standard output and
11599 error streams are connected to /dev/null in the daemon. The chaos is avoided,
11600 but the output is lost.
11602 The Perl warn statement writes to the standard error stream by default. Calls
11603 to warn may be embedded in Perl modules that you use, but over which you have
11604 no control. When Exim starts up the Perl interpreter, it arranges for output
11605 from the warn statement to be written to the Exim main log. You can change this
11606 by including appropriate Perl magic somewhere in your Perl code. For example,
11607 to discard warn output completely, you need this:
11609 $SIG{__WARN__} = sub { };
11611 Whenever a warn is obeyed, the anonymous subroutine is called. In this example,
11612 the code for the subroutine is empty, so it does nothing, but you can include
11613 any Perl code that you like. The text of the warn message is passed as the
11614 first subroutine argument.
11618 ===============================================================================
11619 13. STARTING THE DAEMON AND THE USE OF NETWORK INTERFACES
11621 A host that is connected to a TCP/IP network may have one or more physical
11622 hardware network interfaces. Each of these interfaces may be configured as one
11623 or more "logical" interfaces, which are the entities that a program actually
11624 works with. Each of these logical interfaces is associated with an IP address.
11625 In addition, TCP/IP software supports "loopback" interfaces (127.0.0.1 in IPv4
11626 and ::1 in IPv6), which do not use any physical hardware. Exim requires
11627 knowledge about the host's interfaces for use in three different circumstances:
11629 1. When a listening daemon is started, Exim needs to know which interfaces and
11630 ports to listen on.
11632 2. When Exim is routing an address, it needs to know which IP addresses are
11633 associated with local interfaces. This is required for the correct
11634 processing of MX lists by removing the local host and others with the same
11635 or higher priority values. Also, Exim needs to detect cases when an address
11636 is routed to an IP address that in fact belongs to the local host. Unless
11637 the self router option or the allow_localhost option of the smtp transport
11638 is set (as appropriate), this is treated as an error situation.
11640 3. When Exim connects to a remote host, it may need to know which interface to
11641 use for the outgoing connection.
11643 Exim's default behaviour is likely to be appropriate in the vast majority of
11644 cases. If your host has only one interface, and you want all its IP addresses
11645 to be treated in the same way, and you are using only the standard SMTP port,
11646 you should not need to take any special action. The rest of this chapter does
11649 In a more complicated situation you may want to listen only on certain
11650 interfaces, or on different ports, and for this reason there are a number of
11651 options that can be used to influence Exim's behaviour. The rest of this
11652 chapter describes how they operate.
11654 When a message is received over TCP/IP, the interface and port that were
11655 actually used are set in $received_ip_address and $received_port.
11658 13.1 Starting a listening daemon
11659 --------------------------------
11661 When a listening daemon is started (by means of the -bd command line option),
11662 the interfaces and ports on which it listens are controlled by the following
11665 * daemon_smtp_ports contains a list of default ports or service names. (For
11666 backward compatibility, this option can also be specified in the singular.)
11668 * local_interfaces contains list of interface IP addresses on which to
11669 listen. Each item may optionally also specify a port.
11671 The default list separator in both cases is a colon, but this can be changed as
11672 described in section 6.19. When IPv6 addresses are involved, it is usually best
11673 to change the separator to avoid having to double all the colons. For example:
11675 local_interfaces = <; 127.0.0.1 ; \
11678 3ffe:ffff:836f::fe86:a061
11680 There are two different formats for specifying a port along with an IP address
11681 in local_interfaces:
11683 1. The port is added onto the address with a dot separator. For example, to
11684 listen on port 1234 on two different IP addresses:
11686 local_interfaces = <; 192.168.23.65.1234 ; \
11687 3ffe:ffff:836f::fe86:a061.1234
11689 2. The IP address is enclosed in square brackets, and the port is added with a
11690 colon separator, for example:
11692 local_interfaces = <; [192.168.23.65]:1234 ; \
11693 [3ffe:ffff:836f::fe86:a061]:1234
11695 When a port is not specified, the value of daemon_smtp_ports is used. The
11696 default setting contains just one port:
11698 daemon_smtp_ports = smtp
11700 If more than one port is listed, each interface that does not have its own port
11701 specified listens on all of them. Ports that are listed in daemon_smtp_ports
11702 can be identified either by name (defined in /etc/services) or by number.
11703 However, when ports are given with individual IP addresses in local_interfaces,
11704 only numbers (not names) can be used.
11707 13.2 Special IP listening addresses
11708 -----------------------------------
11710 The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted as
11711 "all IPv4 interfaces" and "all IPv6 interfaces", respectively. In each case,
11712 Exim tells the TCP/IP stack to "listen on all IPvx interfaces" instead of
11713 setting up separate listening sockets for each interface. The default value of
11714 local_interfaces is
11716 local_interfaces = 0.0.0.0
11718 when Exim is built without IPv6 support; otherwise it is:
11720 local_interfaces = <; ::0 ; 0.0.0.0
11722 Thus, by default, Exim listens on all available interfaces, on the SMTP port.
11725 13.3 Overriding local_interfaces and daemon_smtp_ports
11726 ------------------------------------------------------
11728 The -oX command line option can be used to override the values of
11729 daemon_smtp_ports and/or local_interfaces for a particular daemon instance.
11730 Another way of doing this would be to use macros and the -D option. However,
11731 -oX can be used by any admin user, whereas modification of the runtime
11732 configuration by -D is allowed only when the caller is root or exim.
11734 The value of -oX is a list of items. The default colon separator can be changed
11735 in the usual way if required. If there are any items that do not contain dots
11736 or colons (that is, are not IP addresses), the value of daemon_smtp_ports is
11737 replaced by the list of those items. If there are any items that do contain
11738 dots or colons, the value of local_interfaces is replaced by those items. Thus,
11743 overrides daemon_smtp_ports, but leaves local_interfaces unchanged, whereas
11745 -oX 192.168.34.5.1125
11747 overrides local_interfaces, leaving daemon_smtp_ports unchanged. (However,
11748 since local_interfaces now contains no items without ports, the value of
11749 daemon_smtp_ports is no longer relevant in this example.)
11752 13.4 Support for the obsolete SSMTP (or SMTPS) protocol
11753 -------------------------------------------------------
11755 Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used
11756 before the STARTTLS command was standardized for SMTP. Some legacy clients
11757 still use this protocol. If the tls_on_connect_ports option is set to a list of
11758 port numbers or service names, connections to those ports must use SSMTP. The
11759 most common use of this option is expected to be
11761 tls_on_connect_ports = 465
11763 because 465 is the usual port number used by the legacy clients. There is also
11764 a command line option -tls-on-connect, which forces all ports to behave in this
11765 way when a daemon is started.
11767 Warning: Setting tls_on_connect_ports does not of itself cause the daemon to
11768 listen on those ports. You must still specify them in daemon_smtp_ports,
11769 local_interfaces, or the -oX option. (This is because tls_on_connect_ports
11770 applies to inetd connections as well as to connections via the daemon.)
11773 13.5 IPv6 address scopes
11774 ------------------------
11776 IPv6 addresses have "scopes", and a host with multiple hardware interfaces can,
11777 in principle, have the same link-local IPv6 address on different interfaces.
11778 Thus, additional information is needed, over and above the IP address, to
11779 distinguish individual interfaces. A convention of using a percent sign
11780 followed by something (often the interface name) has been adopted in some
11781 cases, leading to addresses like this:
11783 fe80::202:b3ff:fe03:45c1%eth0
11785 To accommodate this usage, a percent sign followed by an arbitrary string is
11786 allowed at the end of an IPv6 address. By default, Exim calls getaddrinfo() to
11787 convert a textual IPv6 address for actual use. This function recognizes the
11788 percent convention in operating systems that support it, and it processes the
11789 address appropriately. Unfortunately, some older libraries have problems with
11792 IPV6_USE_INET_PTON=yes
11794 is set in Local/Makefile (or an OS-dependent Makefile) when Exim is built, Exim
11795 uses inet_pton() to convert a textual IPv6 address for actual use, instead of
11796 getaddrinfo(). (Before version 4.14, it always used this function.) Of course,
11797 this means that the additional functionality of getaddrinfo() - recognizing
11798 scoped addresses - is lost.
11801 13.6 Disabling IPv6
11802 -------------------
11804 Sometimes it happens that an Exim binary that was compiled with IPv6 support is
11805 run on a host whose kernel does not support IPv6. The binary will fall back to
11806 using IPv4, but it may waste resources looking up AAAA records, and trying to
11807 connect to IPv6 addresses, causing delays to mail delivery. If you set the
11808 disable_ipv6 option true, even if the Exim binary has IPv6 support, no IPv6
11809 activities take place. AAAA records are never looked up, and any IPv6 addresses
11810 that are listed in local_interfaces, data for the manualroute router, etc. are
11811 ignored. If IP literals are enabled, the ipliteral router declines to handle
11812 IPv6 literal addresses.
11814 On the other hand, when IPv6 is in use, there may be times when you want to
11815 disable it for certain hosts or domains. You can use the dns_ipv4_lookup option
11816 to globally suppress the lookup of AAAA records for specified domains, and you
11817 can use the ignore_target_hosts generic router option to ignore IPv6 addresses
11818 in an individual router.
11821 13.7 Examples of starting a listening daemon
11822 --------------------------------------------
11824 The default case in an IPv6 environment is
11826 daemon_smtp_ports = smtp
11827 local_interfaces = <; ::0 ; 0.0.0.0
11829 This specifies listening on the smtp port on all IPv6 and IPv4 interfaces.
11830 Either one or two sockets may be used, depending on the characteristics of the
11831 TCP/IP stack. (This is complicated and messy; for more information, read the
11832 comments in the daemon.c source file.)
11834 To specify listening on ports 25 and 26 on all interfaces:
11836 daemon_smtp_ports = 25 : 26
11838 (leaving local_interfaces at the default setting) or, more explicitly:
11840 local_interfaces = <; ::0.25 ; ::0.26 \
11841 0.0.0.0.25 ; 0.0.0.0.26
11843 To listen on the default port on all IPv4 interfaces, and on port 26 on the
11844 IPv4 loopback address only:
11846 local_interfaces = 0.0.0.0 : 127.0.0.1.26
11848 To specify listening on the default port on specific interfaces only:
11850 local_interfaces = 10.0.0.67 : 192.168.34.67
11852 Warning: Such a setting excludes listening on the loopback interfaces.
11855 13.8 Recognizing the local host
11856 -------------------------------
11858 The local_interfaces option is also used when Exim needs to determine whether
11859 or not an IP address refers to the local host. That is, the IP addresses of all
11860 the interfaces on which a daemon is listening are always treated as local.
11862 For this usage, port numbers in local_interfaces are ignored. If either of the
11863 items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of available
11864 interfaces from the operating system, and extracts the relevant (that is, IPv4
11865 or IPv6) addresses to use for checking.
11867 Some systems set up large numbers of virtual interfaces in order to provide
11868 many virtual web servers. In this situation, you may want to listen for email
11869 on only a few of the available interfaces, but nevertheless treat all
11870 interfaces as local when routing. You can do this by setting
11871 extra_local_interfaces to a list of IP addresses, possibly including the "all"
11872 wildcard values. These addresses are recognized as local, but are not used for
11873 listening. Consider this example:
11875 local_interfaces = <; 127.0.0.1 ; ::1 ; \
11877 3ffe:2101:12:1:a00:20ff:fe86:a061
11879 extra_local_interfaces = <; ::0 ; 0.0.0.0
11881 The daemon listens on the loopback interfaces and just one IPv4 and one IPv6
11882 address, but all available interface addresses are treated as local when Exim
11885 In some environments the local host name may be in an MX list, but with an IP
11886 address that is not assigned to any local interface. In other cases it may be
11887 desirable to treat other host names as if they referred to the local host. Both
11888 these cases can be handled by setting the hosts_treat_as_local option. This
11889 contains host names rather than IP addresses. When a host is referenced during
11890 routing, either via an MX record or directly, it is treated as the local host
11891 if its name matches hosts_treat_as_local, or if any of its IP addresses match
11892 local_interfaces or extra_local_interfaces.
11895 13.9 Delivering to a remote host
11896 --------------------------------
11898 Delivery to a remote host is handled by the smtp transport. By default, it
11899 allows the system's TCP/IP functions to choose which interface to use (if there
11900 is more than one) when connecting to a remote host. However, the interface
11901 option can be set to specify which interface is used. See the description of
11902 the smtp transport in chapter 30 for more details.
11906 ===============================================================================
11907 14. MAIN CONFIGURATION
11909 The first part of the run time configuration file contains three types of item:
11911 * Macro definitions: These lines start with an upper case letter. See section
11912 6.4 for details of macro processing.
11914 * Named list definitions: These lines start with one of the words
11915 "domainlist", "hostlist", "addresslist", or "localpartlist". Their use is
11916 described in section 10.5.
11918 * Main configuration settings: Each setting occupies one line of the file
11919 (with possible continuations). If any setting is preceded by the word
11920 "hide", the -bP command line option displays its value to admin users only.
11921 See section 6.10 for a description of the syntax of these option settings.
11923 This chapter specifies all the main configuration options, along with their
11924 types and default values. For ease of finding a particular option, they appear
11925 in alphabetical order in section 14.23 below. However, because there are now so
11926 many options, they are first listed briefly in functional groups, as an aid to
11927 finding the name of the option you are looking for. Some options are listed in
11928 more than one group.
11934 bi_command to run for -bi command line option
11935 disable_ipv6 do no IPv6 processing
11936 keep_malformed for broken files - should not happen
11937 localhost_number for unique message ids in clusters
11938 message_body_newlines retain newlines in $message_body
11939 message_body_visible how much to show in $message_body
11940 mua_wrapper run in "MUA wrapper" mode
11941 print_topbitchars top-bit characters are printing
11942 timezone force time zone
11945 14.2 Exim parameters
11946 --------------------
11948 exim_group override compiled-in value
11949 exim_path override compiled-in value
11950 exim_user override compiled-in value
11951 primary_hostname default from uname()
11952 split_spool_directory use multiple directories
11953 spool_directory override compiled-in value
11956 14.3 Privilege controls
11957 -----------------------
11959 admin_groups groups that are Exim admin users
11960 deliver_drop_privilege drop root for delivery processes
11961 local_from_check insert Sender: if necessary
11962 local_from_prefix for testing From: for local sender
11963 local_from_suffix for testing From: for local sender
11964 local_sender_retain keep Sender: from untrusted user
11965 never_users do not run deliveries as these
11966 prod_requires_admin forced delivery requires admin user
11967 queue_list_requires_admin queue listing requires admin user
11968 trusted_groups groups that are trusted
11969 trusted_users users that are trusted
11975 hosts_connection_nolog exemption from connect logging
11976 log_file_path override compiled-in value
11977 log_selector set/unset optional logging
11978 log_timezone add timezone to log lines
11979 message_logs create per-message logs
11980 preserve_message_logs after message completion
11981 process_log_path for SIGUSR1 and exiwhat
11982 syslog_duplication controls duplicate log lines on syslog
11983 syslog_facility set syslog "facility" field
11984 syslog_processname set syslog "ident" field
11985 syslog_timestamp timestamp syslog lines
11986 write_rejectlog control use of message log
11989 14.5 Frozen messages
11990 --------------------
11992 auto_thaw sets time for retrying frozen messages
11993 freeze_tell send message when freezing
11994 move_frozen_messages to another directory
11995 timeout_frozen_after keep frozen messages only so long
12001 ibase_servers InterBase servers
12002 ldap_ca_cert_dir dir of CA certs to verify LDAP server's
12003 ldap_ca_cert_file file of CA certs to verify LDAP server's
12004 ldap_cert_file client cert file for LDAP
12005 ldap_cert_key client key file for LDAP
12006 ldap_cipher_suite TLS negotiation preference control
12007 ldap_default_servers used if no server in query
12008 ldap_require_cert action to take without LDAP server cert
12009 ldap_start_tls require TLS within LDAP
12010 ldap_version set protocol version
12011 lookup_open_max lookup files held open
12012 mysql_servers default MySQL servers
12013 oracle_servers Oracle servers
12014 pgsql_servers default PostgreSQL servers
12015 sqlite_lock_timeout as it says
12021 message_id_header_domain used to build Message-ID: header
12022 message_id_header_text ditto
12025 14.8 Embedded Perl Startup
12026 --------------------------
12028 perl_at_start always start the interpreter
12029 perl_startup code to obey when starting Perl
12035 daemon_smtp_ports default ports
12036 daemon_startup_retries number of times to retry
12037 daemon_startup_sleep time to sleep between tries
12038 extra_local_interfaces not necessarily listened on
12039 local_interfaces on which to listen, with optional ports
12040 pid_file_path override compiled-in value
12041 queue_run_max maximum simultaneous queue runners
12044 14.10 Resource control
12045 ----------------------
12047 check_log_inodes before accepting a message
12048 check_log_space before accepting a message
12049 check_spool_inodes before accepting a message
12050 check_spool_space before accepting a message
12051 deliver_queue_load_max no queue deliveries if load high
12052 queue_only_load queue incoming if load high
12053 queue_only_load_latch don't re-evaluate load for each message
12054 queue_run_max maximum simultaneous queue runners
12055 remote_max_parallel parallel SMTP delivery per message
12056 smtp_accept_max simultaneous incoming connections
12057 smtp_accept_max_nonmail non-mail commands
12058 smtp_accept_max_nonmail_hosts hosts to which the limit applies
12059 smtp_accept_max_per_connection messages per connection
12060 smtp_accept_max_per_host connections from one host
12061 smtp_accept_queue queue mail if more connections
12062 smtp_accept_queue_per_connection queue if more messages per connection
12063 smtp_accept_reserve only reserve hosts if more connections
12064 smtp_check_spool_space from SIZE on MAIL command
12065 smtp_connect_backlog passed to TCP/IP stack
12066 smtp_load_reserve SMTP from reserved hosts if load high
12067 smtp_reserve_hosts these are the reserve hosts
12070 14.11 Policy controls
12071 ---------------------
12073 acl_not_smtp ACL for non-SMTP messages
12074 acl_not_smtp_mime ACL for non-SMTP MIME parts
12075 acl_not_smtp_start ACL for start of non-SMTP message
12076 acl_smtp_auth ACL for AUTH
12077 acl_smtp_connect ACL for connection
12078 acl_smtp_data ACL for DATA
12079 acl_smtp_data_prdr ACL for DATA, per-recipient
12080 acl_smtp_dkim ACL for DKIM verification
12081 acl_smtp_etrn ACL for ETRN
12082 acl_smtp_expn ACL for EXPN
12083 acl_smtp_helo ACL for EHLO or HELO
12084 acl_smtp_mail ACL for MAIL
12085 acl_smtp_mailauth ACL for AUTH on MAIL command
12086 acl_smtp_mime ACL for MIME parts
12087 acl_smtp_predata ACL for start of data
12088 acl_smtp_quit ACL for QUIT
12089 acl_smtp_rcpt ACL for RCPT
12090 acl_smtp_starttls ACL for STARTTLS
12091 acl_smtp_vrfy ACL for VRFY
12092 av_scanner specify virus scanner
12093 check_rfc2047_length check length of RFC 2047 "encoded words"
12094 dns_csa_search_limit control CSA parent search depth
12095 dns_csa_use_reverse en/disable CSA IP reverse search
12096 header_maxsize total size of message header
12097 header_line_maxsize individual header line limit
12098 helo_accept_junk_hosts allow syntactic junk from these hosts
12099 helo_allow_chars allow illegal chars in HELO names
12100 helo_lookup_domains lookup hostname for these HELO names
12101 helo_try_verify_hosts HELO soft-checked for these hosts
12102 helo_verify_hosts HELO hard-checked for these hosts
12103 host_lookup host name looked up for these hosts
12104 host_lookup_order order of DNS and local name lookups
12105 host_reject_connection reject connection from these hosts
12106 hosts_treat_as_local useful in some cluster configurations
12107 local_scan_timeout timeout for local_scan()
12108 message_size_limit for all messages
12109 percent_hack_domains recognize %-hack for these domains
12110 spamd_address set interface to SpamAssassin
12111 strict_acl_vars object to unset ACL variables
12114 14.12 Callout cache
12115 -------------------
12117 callout_domain_negative_expire timeout for negative domain cache item
12118 callout_domain_positive_expire timeout for positive domain cache item
12119 callout_negative_expire timeout for negative address cache item
12120 callout_positive_expire timeout for positive address cache item
12121 callout_random_local_part string to use for "random" testing
12127 gnutls_compat_mode use GnuTLS compatibility mode
12128 gnutls_allow_auto_pkcs11 allow GnuTLS to autoload PKCS11 modules
12129 openssl_options adjust OpenSSL compatibility options
12130 tls_advertise_hosts advertise TLS to these hosts
12131 tls_certificate location of server certificate
12132 tls_crl certificate revocation list
12133 tls_dh_max_bits clamp D-H bit count suggestion
12134 tls_dhparam DH parameters for server
12135 tls_ocsp_file location of server certificate status proof
12136 tls_on_connect_ports specify SSMTP (SMTPS) ports
12137 tls_privatekey location of server private key
12138 tls_remember_esmtp don't reset after starting TLS
12139 tls_require_ciphers specify acceptable ciphers
12140 tls_try_verify_hosts try to verify client certificate
12141 tls_verify_certificates expected client certificates
12142 tls_verify_hosts insist on client certificate verify
12145 14.14 Local user handling
12146 -------------------------
12148 finduser_retries useful in NIS environments
12149 gecos_name used when creating Sender:
12150 gecos_pattern ditto
12151 max_username_length for systems that truncate
12152 unknown_login used when no login name found
12153 unknown_username ditto
12154 uucp_from_pattern for recognizing "From " lines
12155 uucp_from_sender ditto
12158 14.15 All incoming messages (SMTP and non-SMTP)
12159 -----------------------------------------------
12161 header_maxsize total size of message header
12162 header_line_maxsize individual header line limit
12163 message_size_limit applies to all messages
12164 percent_hack_domains recognize %-hack for these domains
12165 received_header_text expanded to make Received:
12166 received_headers_max for mail loop detection
12167 recipients_max limit per message
12168 recipients_max_reject permanently reject excess recipients
12171 14.16 Non-SMTP incoming messages
12172 --------------------------------
12174 receive_timeout for non-SMTP messages
12177 14.17 Incoming SMTP messages
12178 ----------------------------
12180 See also the Policy controls section above.
12182 host_lookup host name looked up for these hosts
12183 host_lookup_order order of DNS and local name lookups
12184 recipient_unqualified_hosts may send unqualified recipients
12185 rfc1413_hosts make ident calls to these hosts
12186 rfc1413_query_timeout zero disables ident calls
12187 sender_unqualified_hosts may send unqualified senders
12188 smtp_accept_keepalive some TCP/IP magic
12189 smtp_accept_max simultaneous incoming connections
12190 smtp_accept_max_nonmail non-mail commands
12191 smtp_accept_max_nonmail_hosts hosts to which the limit applies
12192 smtp_accept_max_per_connection messages per connection
12193 smtp_accept_max_per_host connections from one host
12194 smtp_accept_queue queue mail if more connections
12195 smtp_accept_queue_per_connection queue if more messages per connection
12196 smtp_accept_reserve only reserve hosts if more connections
12197 smtp_active_hostname host name to use in messages
12198 smtp_banner text for welcome banner
12199 smtp_check_spool_space from SIZE on MAIL command
12200 smtp_connect_backlog passed to TCP/IP stack
12201 smtp_enforce_sync of SMTP command/responses
12202 smtp_etrn_command what to run for ETRN
12203 smtp_etrn_serialize only one at once
12204 smtp_load_reserve only reserve hosts if this load
12205 smtp_max_unknown_commands before dropping connection
12206 smtp_ratelimit_hosts apply ratelimiting to these hosts
12207 smtp_ratelimit_mail ratelimit for MAIL commands
12208 smtp_ratelimit_rcpt ratelimit for RCPT commands
12209 smtp_receive_timeout per command or data line
12210 smtp_reserve_hosts these are the reserve hosts
12211 smtp_return_error_details give detail on rejections
12214 14.18 SMTP extensions
12215 ---------------------
12217 accept_8bitmime advertise 8BITMIME
12218 auth_advertise_hosts advertise AUTH to these hosts
12219 ignore_fromline_hosts allow "From " from these hosts
12220 ignore_fromline_local allow "From " from local SMTP
12221 pipelining_advertise_hosts advertise pipelining to these hosts
12222 prdr_enable advertise PRDR to all hosts
12223 tls_advertise_hosts advertise TLS to these hosts
12226 14.19 Processing messages
12227 -------------------------
12229 allow_domain_literals recognize domain literal syntax
12230 allow_mx_to_ip allow MX to point to IP address
12231 allow_utf8_domains in addresses
12232 check_rfc2047_length check length of RFC 2047 "encoded words"
12233 delivery_date_remove from incoming messages
12234 envelope_to_remove from incoming messages
12235 extract_addresses_remove_arguments affects -t processing
12236 headers_charset default for translations
12237 qualify_domain default for senders
12238 qualify_recipient default for recipients
12239 return_path_remove from incoming messages
12240 strip_excess_angle_brackets in addresses
12241 strip_trailing_dot at end of addresses
12242 untrusted_set_sender untrusted can set envelope sender
12245 14.20 System filter
12246 -------------------
12248 system_filter locate system filter
12249 system_filter_directory_transport transport for delivery to a directory
12250 system_filter_file_transport transport for delivery to a file
12251 system_filter_group group for filter running
12252 system_filter_pipe_transport transport for delivery to a pipe
12253 system_filter_reply_transport transport for autoreply delivery
12254 system_filter_user user for filter running
12257 14.21 Routing and delivery
12258 --------------------------
12260 disable_ipv6 do no IPv6 processing
12261 dns_again_means_nonexist for broken domains
12262 dns_check_names_pattern pre-DNS syntax check
12263 dns_dnssec_ok parameter for resolver
12264 dns_ipv4_lookup only v4 lookup for these domains
12265 dns_retrans parameter for resolver
12266 dns_retry parameter for resolver
12267 dns_use_edns0 parameter for resolver
12268 hold_domains hold delivery for these domains
12269 local_interfaces for routing checks
12270 queue_domains no immediate delivery for these
12271 queue_only no immediate delivery at all
12272 queue_only_file no immediate delivery if file exists
12273 queue_only_load no immediate delivery if load is high
12274 queue_only_load_latch don't re-evaluate load for each message
12275 queue_only_override allow command line to override
12276 queue_run_in_order order of arrival
12277 queue_run_max of simultaneous queue runners
12278 queue_smtp_domains no immediate SMTP delivery for these
12279 remote_max_parallel parallel SMTP delivery per message
12280 remote_sort_domains order of remote deliveries
12281 retry_data_expire timeout for retry data
12282 retry_interval_max safety net for retry rules
12285 14.22 Bounce and warning messages
12286 ---------------------------------
12288 bounce_message_file content of bounce
12289 bounce_message_text content of bounce
12290 bounce_return_body include body if returning message
12291 bounce_return_message include original message in bounce
12292 bounce_return_size_limit limit on returned message
12293 bounce_sender_authentication send authenticated sender with bounce
12294 dsn_from set From: contents in bounces
12295 errors_copy copy bounce messages
12296 errors_reply_to Reply-to: in bounces
12297 delay_warning time schedule
12298 delay_warning_condition condition for warning messages
12299 ignore_bounce_errors_after discard undeliverable bounces
12300 smtp_return_error_details give detail on rejections
12301 warn_message_file content of warning message
12304 14.23 Alphabetical list of main options
12305 ---------------------------------------
12307 Those options that undergo string expansion before use are marked with *.
12309 +---------------+---------+-------------+-------------+
12310 |accept_8bitmime|Use: main|Type: boolean|Default: true|
12311 +---------------+---------+-------------+-------------+
12313 This option causes Exim to send 8BITMIME in its response to an SMTP EHLO
12314 command, and to accept the BODY= parameter on MAIL commands. However, though
12315 Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to
12316 do anything special with messages received by this route.
12318 Historically Exim kept this option off by default, but the maintainers feel
12319 that in today's Internet, this causes more problems than it solves. It now
12320 defaults to true. A more detailed analysis of the issues is provided by Dan
12323 http://cr.yp.to/smtp/8bitmime.html
12325 To log received 8BITMIME status use
12327 log_selector = +8bitmime
12329 +------------+---------+-------------+--------------+
12330 |acl_not_smtp|Use: main|Type: string*|Default: unset|
12331 +------------+---------+-------------+--------------+
12333 This option defines the ACL that is run when a non-SMTP message has been read
12334 and is on the point of being accepted. See chapter 42 for further details.
12336 +-----------------+---------+-------------+--------------+
12337 |acl_not_smtp_mime|Use: main|Type: string*|Default: unset|
12338 +-----------------+---------+-------------+--------------+
12340 This option defines the ACL that is run for individual MIME parts of non-SMTP
12341 messages. It operates in exactly the same way as acl_smtp_mime operates for
12344 +------------------+---------+-------------+--------------+
12345 |acl_not_smtp_start|Use: main|Type: string*|Default: unset|
12346 +------------------+---------+-------------+--------------+
12348 This option defines the ACL that is run before Exim starts reading a non-SMTP
12349 message. See chapter 42 for further details.
12351 +-------------+---------+-------------+--------------+
12352 |acl_smtp_auth|Use: main|Type: string*|Default: unset|
12353 +-------------+---------+-------------+--------------+
12355 This option defines the ACL that is run when an SMTP AUTH command is received.
12356 See chapter 42 for further details.
12358 +----------------+---------+-------------+--------------+
12359 |acl_smtp_connect|Use: main|Type: string*|Default: unset|
12360 +----------------+---------+-------------+--------------+
12362 This option defines the ACL that is run when an SMTP connection is received.
12363 See chapter 42 for further details.
12365 +-------------+---------+-------------+--------------+
12366 |acl_smtp_data|Use: main|Type: string*|Default: unset|
12367 +-------------+---------+-------------+--------------+
12369 This option defines the ACL that is run after an SMTP DATA command has been
12370 processed and the message itself has been received, but before the final
12371 acknowledgment is sent. See chapter 42 for further details.
12373 +------------------+---------+-------------+--------------+
12374 |acl_smtp_data_prdr|Use: main|Type: string*|Default: unset|
12375 +------------------+---------+-------------+--------------+
12377 This option defines the ACL that, if the PRDR feature has been negotiated, is
12378 run for each recipient after an SMTP DATA command has been processed and the
12379 message itself has been received, but before the acknowledgment is sent. See
12380 chapter 42 for further details.
12382 +-------------+---------+-------------+--------------+
12383 |acl_smtp_etrn|Use: main|Type: string*|Default: unset|
12384 +-------------+---------+-------------+--------------+
12386 This option defines the ACL that is run when an SMTP ETRN command is received.
12387 See chapter 42 for further details.
12389 +-------------+---------+-------------+--------------+
12390 |acl_smtp_expn|Use: main|Type: string*|Default: unset|
12391 +-------------+---------+-------------+--------------+
12393 This option defines the ACL that is run when an SMTP EXPN command is received.
12394 See chapter 42 for further details.
12396 +-------------+---------+-------------+--------------+
12397 |acl_smtp_helo|Use: main|Type: string*|Default: unset|
12398 +-------------+---------+-------------+--------------+
12400 This option defines the ACL that is run when an SMTP EHLO or HELO command is
12401 received. See chapter 42 for further details.
12403 +-------------+---------+-------------+--------------+
12404 |acl_smtp_mail|Use: main|Type: string*|Default: unset|
12405 +-------------+---------+-------------+--------------+
12407 This option defines the ACL that is run when an SMTP MAIL command is received.
12408 See chapter 42 for further details.
12410 +-----------------+---------+-------------+--------------+
12411 |acl_smtp_mailauth|Use: main|Type: string*|Default: unset|
12412 +-----------------+---------+-------------+--------------+
12414 This option defines the ACL that is run when there is an AUTH parameter on a
12415 MAIL command. See chapter 42 for details of ACLs, and chapter 33 for details of
12418 +-------------+---------+-------------+--------------+
12419 |acl_smtp_mime|Use: main|Type: string*|Default: unset|
12420 +-------------+---------+-------------+--------------+
12422 This option is available when Exim is built with the content-scanning
12423 extension. It defines the ACL that is run for each MIME part in a message. See
12424 section 43.4 for details.
12426 +----------------+---------+-------------+--------------+
12427 |acl_smtp_predata|Use: main|Type: string*|Default: unset|
12428 +----------------+---------+-------------+--------------+
12430 This option defines the ACL that is run when an SMTP DATA command is received,
12431 before the message itself is received. See chapter 42 for further details.
12433 +-------------+---------+-------------+--------------+
12434 |acl_smtp_quit|Use: main|Type: string*|Default: unset|
12435 +-------------+---------+-------------+--------------+
12437 This option defines the ACL that is run when an SMTP QUIT command is received.
12438 See chapter 42 for further details.
12440 +-------------+---------+-------------+--------------+
12441 |acl_smtp_rcpt|Use: main|Type: string*|Default: unset|
12442 +-------------+---------+-------------+--------------+
12444 This option defines the ACL that is run when an SMTP RCPT command is received.
12445 See chapter 42 for further details.
12447 +-----------------+---------+-------------+--------------+
12448 |acl_smtp_starttls|Use: main|Type: string*|Default: unset|
12449 +-----------------+---------+-------------+--------------+
12451 This option defines the ACL that is run when an SMTP STARTTLS command is
12452 received. See chapter 42 for further details.
12454 +-------------+---------+-------------+--------------+
12455 |acl_smtp_vrfy|Use: main|Type: string*|Default: unset|
12456 +-------------+---------+-------------+--------------+
12458 This option defines the ACL that is run when an SMTP VRFY command is received.
12459 See chapter 42 for further details.
12461 +---------------+---------+-----------------+--------------+
12462 |add_environment|Use: main|Type: string list|Default: empty|
12463 +---------------+---------+-----------------+--------------+
12465 This option allows to set individual environment variables that the currently
12466 linked libraries and programs in child processes use. The default list is
12469 +------------+---------+------------------+--------------+
12470 |admin_groups|Use: main|Type: string list*|Default: unset|
12471 +------------+---------+------------------+--------------+
12473 This option is expanded just once, at the start of Exim's processing. If the
12474 current group or any of the supplementary groups of an Exim caller is in this
12475 colon-separated list, the caller has admin privileges. If all your system
12476 programmers are in a specific group, for example, you can give them all Exim
12477 admin privileges by putting that group in admin_groups. However, this does not
12478 permit them to read Exim's spool files (whose group owner is the Exim gid). To
12479 permit this, you have to add individuals to the Exim group.
12481 +---------------------+---------+-------------+--------------+
12482 |allow_domain_literals|Use: main|Type: boolean|Default: false|
12483 +---------------------+---------+-------------+--------------+
12485 If this option is set, the RFC 2822 domain literal format is permitted in email
12486 addresses. The option is not set by default, because the domain literal format
12487 is not normally required these days, and few people know about it. It has,
12488 however, been exploited by mail abusers.
12490 Unfortunately, it seems that some DNS black list maintainers are using this
12491 format to report black listing to postmasters. If you want to accept messages
12492 addressed to your hosts by IP address, you need to set allow_domain_literals
12493 true, and also to add "@[]" to the list of local domains (defined in the named
12494 domain list local_domains in the default configuration). This "magic string"
12495 matches the domain literal form of all the local host's IP addresses.
12497 +--------------+---------+-------------+--------------+
12498 |allow_mx_to_ip|Use: main|Type: boolean|Default: false|
12499 +--------------+---------+-------------+--------------+
12501 It appears that more and more DNS zone administrators are breaking the rules
12502 and putting domain names that look like IP addresses on the right hand side of
12503 MX records. Exim follows the rules and rejects this, giving an error message
12504 that explains the mis-configuration. However, some other MTAs support this
12505 practice, so to avoid "Why can't Exim do this?" complaints, allow_mx_to_ip
12506 exists, in order to enable this heinous activity. It is not recommended, except
12507 when you have no other choice.
12509 +------------------+---------+-------------+--------------+
12510 |allow_utf8_domains|Use: main|Type: boolean|Default: false|
12511 +------------------+---------+-------------+--------------+
12513 Lots of discussion is going on about internationalized domain names. One camp
12514 is strongly in favour of just using UTF-8 characters, and it seems that at
12515 least two other MTAs permit this. This option allows Exim users to experiment
12518 If it is set true, Exim's domain parsing function allows valid UTF-8
12519 multicharacters to appear in domain name components, in addition to letters,
12520 digits, and hyphens. However, just setting this option is not enough; if you
12521 want to look up these domain names in the DNS, you must also adjust the value
12522 of dns_check_names_pattern to match the extended form. A suitable setting is:
12524 dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\
12525 (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$
12527 Alternatively, you can just disable this feature by setting
12529 dns_check_names_pattern =
12531 That is, set the option to an empty string so that no check is done.
12533 +--------------------+---------+----------------+----------+
12534 |auth_advertise_hosts|Use: main|Type: host list*|Default: *|
12535 +--------------------+---------+----------------+----------+
12537 If any server authentication mechanisms are configured, Exim advertises them in
12538 response to an EHLO command only if the calling host matches this list.
12539 Otherwise, Exim does not advertise AUTH. Exim does not accept AUTH commands
12540 from clients to which it has not advertised the availability of AUTH. The
12541 advertising of individual authentication mechanisms can be controlled by the
12542 use of the server_advertise_condition generic authenticator option on the
12543 individual authenticators. See chapter 33 for further details.
12545 Certain mail clients (for example, Netscape) require the user to provide a name
12546 and password for authentication if AUTH is advertised, even though it may not
12547 be needed (the host may accept messages from hosts on its local LAN without
12548 authentication, for example). The auth_advertise_hosts option can be used to
12549 make these clients more friendly by excluding them from the set of hosts to
12550 which Exim advertises AUTH.
12552 If you want to advertise the availability of AUTH only when the connection is
12553 encrypted using TLS, you can make use of the fact that the value of this option
12554 is expanded, with a setting like this:
12556 auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}}
12558 If $tls_in_cipher is empty, the session is not encrypted, and the result of the
12559 expansion is empty, thus matching no hosts. Otherwise, the result of the
12560 expansion is *, which matches all hosts.
12562 +---------+---------+----------+-----------+
12563 |auto_thaw|Use: main|Type: time|Default: 0s|
12564 +---------+---------+----------+-----------+
12566 If this option is set to a time greater than zero, a queue runner will try a
12567 new delivery attempt on any frozen message, other than a bounce message, if
12568 this much time has passed since it was frozen. This may result in the message
12569 being re-frozen if nothing has changed since the last attempt. It is a way of
12570 saying "keep on trying, even though there are big problems".
12572 Note: This is an old option, which predates timeout_frozen_after and
12573 ignore_bounce_errors_after. It is retained for compatibility, but it is not
12574 thought to be very useful any more, and its use should probably be avoided.
12576 +----------+---------+------------+------------------+
12577 |av_scanner|Use: main|Type: string|Default: see below|
12578 +----------+---------+------------+------------------+
12580 This option is available if Exim is built with the content-scanning extension.
12581 It specifies which anti-virus scanner to use. The default value is:
12583 sophie:/var/run/sophie
12585 If the value of av_scanner starts with a dollar character, it is expanded
12586 before use. See section 43.1 for further details.
12588 +----------+---------+------------+--------------+
12589 |bi_command|Use: main|Type: string|Default: unset|
12590 +----------+---------+------------+--------------+
12592 This option supplies the name of a command that is run when Exim is called with
12593 the -bi option (see chapter 5). The string value is just the command name, it
12594 is not a complete command line. If an argument is required, it must come from
12595 the -oA command line option.
12597 +-------------------+---------+------------+--------------+
12598 |bounce_message_file|Use: main|Type: string|Default: unset|
12599 +-------------------+---------+------------+--------------+
12601 This option defines a template file containing paragraphs of text to be used
12602 for constructing bounce messages. Details of the file's contents are given in
12603 chapter 48. See also warn_message_file.
12605 +-------------------+---------+------------+--------------+
12606 |bounce_message_text|Use: main|Type: string|Default: unset|
12607 +-------------------+---------+------------+--------------+
12609 When this option is set, its contents are included in the default bounce
12610 message immediately after "This message was created automatically by mail
12611 delivery software." It is not used if bounce_message_file is set.
12613 +------------------+---------+-------------+-------------+
12614 |bounce_return_body|Use: main|Type: boolean|Default: true|
12615 +------------------+---------+-------------+-------------+
12617 This option controls whether the body of an incoming message is included in a
12618 bounce message when bounce_return_message is true. The default setting causes
12619 the entire message, both header and body, to be returned (subject to the value
12620 of bounce_return_size_limit). If this option is false, only the message header
12621 is included. In the case of a non-SMTP message containing an error that is
12622 detected during reception, only those header lines preceding the point at which
12623 the error was detected are returned.
12625 +---------------------+---------+-------------+-------------+
12626 |bounce_return_message|Use: main|Type: boolean|Default: true|
12627 +---------------------+---------+-------------+-------------+
12629 If this option is set false, none of the original message is included in bounce
12630 messages generated by Exim. See also bounce_return_size_limit and
12631 bounce_return_body.
12633 +------------------------+---------+-------------+-------------+
12634 |bounce_return_size_limit|Use: main|Type: integer|Default: 100K|
12635 +------------------------+---------+-------------+-------------+
12637 This option sets a limit in bytes on the size of messages that are returned to
12638 senders as part of bounce messages when bounce_return_message is true. The
12639 limit should be less than the value of the global message_size_limit and of any
12640 message_size_limit settings on transports, to allow for the bounce text that
12641 Exim generates. If this option is set to zero there is no limit.
12643 When the body of any message that is to be included in a bounce message is
12644 greater than the limit, it is truncated, and a comment pointing this out is
12645 added at the top. The actual cutoff may be greater than the value given, owing
12646 to the use of buffering for transferring the message in chunks (typically 8K in
12647 size). The idea is to save bandwidth on those undeliverable 15-megabyte
12650 +----------------------------+---------+------------+--------------+
12651 |bounce_sender_authentication|Use: main|Type: string|Default: unset|
12652 +----------------------------+---------+------------+--------------+
12654 This option provides an authenticated sender address that is sent with any
12655 bounce messages generated by Exim that are sent over an authenticated SMTP
12656 connection. A typical setting might be:
12658 bounce_sender_authentication = mailer-daemon@my.domain.example
12660 which would cause bounce messages to be sent using the SMTP command:
12662 MAIL FROM:<> AUTH=mailer-daemon@my.domain.example
12664 The value of bounce_sender_authentication must always be a complete email
12667 +------------------------------+---------+----------+-----------+
12668 |callout_domain_negative_expire|Use: main|Type: time|Default: 3h|
12669 +------------------------------+---------+----------+-----------+
12671 This option specifies the expiry time for negative callout cache data for a
12672 domain. See section 42.45 for details of callout verification, and section
12673 42.47 for details of the caching.
12675 +------------------------------+---------+----------+-----------+
12676 |callout_domain_positive_expire|Use: main|Type: time|Default: 7d|
12677 +------------------------------+---------+----------+-----------+
12679 This option specifies the expiry time for positive callout cache data for a
12680 domain. See section 42.45 for details of callout verification, and section
12681 42.47 for details of the caching.
12683 +-----------------------+---------+----------+-----------+
12684 |callout_negative_expire|Use: main|Type: time|Default: 2h|
12685 +-----------------------+---------+----------+-----------+
12687 This option specifies the expiry time for negative callout cache data for an
12688 address. See section 42.45 for details of callout verification, and section
12689 42.47 for details of the caching.
12691 +-----------------------+---------+----------+------------+
12692 |callout_positive_expire|Use: main|Type: time|Default: 24h|
12693 +-----------------------+---------+----------+------------+
12695 This option specifies the expiry time for positive callout cache data for an
12696 address. See section 42.45 for details of callout verification, and section
12697 42.47 for details of the caching.
12699 +-------------------------+---------+-------------+------------------+
12700 |callout_random_local_part|Use: main|Type: string*|Default: see below|
12701 +-------------------------+---------+-------------+------------------+
12703 This option defines the "random" local part that can be used as part of callout
12704 verification. The default value is
12706 $primary_hostname-$tod_epoch-testing
12708 See section 42.46 for details of how this value is used.
12710 +----------------+---------+-------------+----------+
12711 |check_log_inodes|Use: main|Type: integer|Default: 0|
12712 +----------------+---------+-------------+----------+
12714 See check_spool_space below.
12716 +---------------+---------+-------------+----------+
12717 |check_log_space|Use: main|Type: integer|Default: 0|
12718 +---------------+---------+-------------+----------+
12720 See check_spool_space below.
12722 +--------------------+---------+-------------+-------------+
12723 |check_rfc2047_length|Use: main|Type: boolean|Default: true|
12724 +--------------------+---------+-------------+-------------+
12726 RFC 2047 defines a way of encoding non-ASCII characters in headers using a
12727 system of "encoded words". The RFC specifies a maximum length for an encoded
12728 word; strings to be encoded that exceed this length are supposed to use
12729 multiple encoded words. By default, Exim does not recognize encoded words that
12730 exceed the maximum length. However, it seems that some software, in violation
12731 of the RFC, generates overlong encoded words. If check_rfc2047_length is set
12732 false, Exim recognizes encoded words of any length.
12734 +------------------+---------+-------------+----------+
12735 |check_spool_inodes|Use: main|Type: integer|Default: 0|
12736 +------------------+---------+-------------+----------+
12738 See check_spool_space below.
12740 +-----------------+---------+-------------+----------+
12741 |check_spool_space|Use: main|Type: integer|Default: 0|
12742 +-----------------+---------+-------------+----------+
12744 The four check_... options allow for checking of disk resources before a
12745 message is accepted.
12747 When any of these options are set, they apply to all incoming messages. If you
12748 want to apply different checks to different kinds of message, you can do so by
12749 testing the variables $log_inodes, $log_space, $spool_inodes, and $spool_space
12750 in an ACL with appropriate additional conditions.
12752 check_spool_space and check_spool_inodes check the spool partition if either
12753 value is greater than zero, for example:
12755 check_spool_space = 10M
12756 check_spool_inodes = 100
12758 The spool partition is the one that contains the directory defined by
12759 SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit.
12761 check_log_space and check_log_inodes check the partition in which log files are
12762 written if either is greater than zero. These should be set only if
12763 log_file_path and spool_directory refer to different partitions.
12765 If there is less space or fewer inodes than requested, Exim refuses to accept
12766 incoming mail. In the case of SMTP input this is done by giving a 452 temporary
12767 error response to the MAIL command. If ESMTP is in use and there was a SIZE
12768 parameter on the MAIL command, its value is added to the check_spool_space
12769 value, and the check is performed even if check_spool_space is zero, unless
12770 no_smtp_check_spool_space is set.
12772 The values for check_spool_space and check_log_space are held as a number of
12773 kilobytes. If a non-multiple of 1024 is specified, it is rounded up.
12775 For non-SMTP input and for batched SMTP input, the test is done at start-up; on
12776 failure a message is written to stderr and Exim exits with a non-zero code, as
12777 it obviously cannot send an error message of any kind.
12779 +-----------------+---------+------------+---------------+
12780 |daemon_smtp_ports|Use: main|Type: string|Default: "smtp"|
12781 +-----------------+---------+------------+---------------+
12783 This option specifies one or more default SMTP ports on which the Exim daemon
12784 listens. See chapter 13 for details of how it is used. For backward
12785 compatibility, daemon_smtp_port (singular) is a synonym.
12787 +----------------------+---------+-------------+----------+
12788 |daemon_startup_retries|Use: main|Type: integer|Default: 9|
12789 +----------------------+---------+-------------+----------+
12791 This option, along with daemon_startup_sleep, controls the retrying done by the
12792 daemon at startup when it cannot immediately bind a listening socket (typically
12793 because the socket is already in use): daemon_startup_retries defines the
12794 number of retries after the first failure, and daemon_startup_sleep defines the
12795 length of time to wait between retries.
12797 +--------------------+---------+----------+------------+
12798 |daemon_startup_sleep|Use: main|Type: time|Default: 30s|
12799 +--------------------+---------+----------+------------+
12801 See daemon_startup_retries.
12803 +-------------+---------+---------------+------------+
12804 |delay_warning|Use: main|Type: time list|Default: 24h|
12805 +-------------+---------+---------------+------------+
12807 When a message is delayed, Exim sends a warning message to the sender at
12808 intervals specified by this option. The data is a colon-separated list of times
12809 after which to send warning messages. If the value of the option is an empty
12810 string or a zero time, no warnings are sent. Up to 10 times may be given. If a
12811 message has been on the queue for longer than the last time, the last interval
12812 between the times is used to compute subsequent warning times. For example,
12815 delay_warning = 4h:8h:24h
12817 the first message is sent after 4 hours, the second after 8 hours, and the
12818 third one after 24 hours. After that, messages are sent every 16 hours, because
12819 that is the interval between the last two times on the list. If you set just
12820 one time, it specifies the repeat interval. For example, with:
12824 messages are repeated every six hours. To stop warnings after a given time, set
12825 a very large time at the end of the list. For example:
12827 delay_warning = 2h:12h:99d
12829 Note that the option is only evaluated at the time a delivery attempt fails,
12830 which depends on retry and queue-runner configuration. Typically retries will
12831 be configured more frequently than warning messages.
12833 +-----------------------+---------+-------------+------------------+
12834 |delay_warning_condition|Use: main|Type: string*|Default: see below|
12835 +-----------------------+---------+-------------+------------------+
12837 The string is expanded at the time a warning message might be sent. If all the
12838 deferred addresses have the same domain, it is set in $domain during the
12839 expansion. Otherwise $domain is empty. If the result of the expansion is a
12840 forced failure, an empty string, or a string matching any of "0", "no" or
12841 "false" (the comparison being done caselessly) then the warning message is not
12842 sent. The default is:
12844 delay_warning_condition = ${if or {\
12845 { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\
12846 { match{$h_precedence:}{(?i)bulk|list|junk} }\
12847 { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\
12850 This suppresses the sending of warnings for messages that contain List-ID:,
12851 List-Post:, or List-Subscribe: headers, or have "bulk", "list" or "junk" in a
12852 Precedence: header, or have "auto-generated" or "auto-replied" in an
12853 Auto-Submitted: header.
12855 +----------------------+---------+-------------+--------------+
12856 |deliver_drop_privilege|Use: main|Type: boolean|Default: false|
12857 +----------------------+---------+-------------+--------------+
12859 If this option is set true, Exim drops its root privilege at the start of a
12860 delivery process, and runs as the Exim user throughout. This severely restricts
12861 the kinds of local delivery that are possible, but is viable in certain types
12862 of configuration. There is a discussion about the use of root privilege in
12865 +----------------------+---------+-----------------+--------------+
12866 |deliver_queue_load_max|Use: main|Type: fixed-point|Default: unset|
12867 +----------------------+---------+-----------------+--------------+
12869 When this option is set, a queue run is abandoned if the system load average
12870 becomes greater than the value of the option. The option has no effect on
12871 ancient operating systems on which Exim cannot determine the load average. See
12872 also queue_only_load and smtp_load_reserve.
12874 +--------------------+---------+-------------+-------------+
12875 |delivery_date_remove|Use: main|Type: boolean|Default: true|
12876 +--------------------+---------+-------------+-------------+
12878 Exim's transports have an option for adding a Delivery-date: header to a
12879 message when it is delivered, in exactly the same way as Return-path: is
12880 handled. Delivery-date: records the actual time of delivery. Such headers
12881 should not be present in incoming messages, and this option causes them to be
12882 removed at the time the message is received, to avoid any problems that might
12883 occur when a delivered message is subsequently sent on to some other recipient.
12885 +-------------+---------+-------------+--------------+
12886 |disable_fsync|Use: main|Type: boolean|Default: false|
12887 +-------------+---------+-------------+--------------+
12889 This option is available only if Exim was built with the compile-time option
12890 ENABLE_DISABLE_FSYNC. When this is not set, a reference to disable_fsync in a
12891 runtime configuration generates an "unknown option" error. You should not build
12892 Exim with ENABLE_DISABLE_FSYNC or set disable_fsync unless you really, really,
12893 really understand what you are doing. No pre-compiled distributions of Exim
12894 should ever make this option available.
12896 When disable_fsync is set true, Exim no longer calls fsync() to force updated
12897 files' data to be written to disc before continuing. Unexpected events such as
12898 crashes and power outages may cause data to be lost or scrambled. Here be
12901 +------------+---------+-------------+--------------+
12902 |disable_ipv6|Use: main|Type: boolean|Default: false|
12903 +------------+---------+-------------+--------------+
12905 If this option is set true, even if the Exim binary has IPv6 support, no IPv6
12906 activities take place. AAAA records are never looked up, and any IPv6 addresses
12907 that are listed in local_interfaces, data for the manualroute router, etc. are
12908 ignored. If IP literals are enabled, the ipliteral router declines to handle
12909 IPv6 literal addresses.
12911 +------------------------+---------+------------------+--------------+
12912 |dns_again_means_nonexist|Use: main|Type: domain list*|Default: unset|
12913 +------------------------+---------+------------------+--------------+
12915 DNS lookups give a "try again" response for the DNS errors "non-authoritative
12916 host not found" and "SERVERFAIL". This can cause Exim to keep trying to deliver
12917 a message, or to give repeated temporary errors to incoming mail. Sometimes the
12918 effect is caused by a badly set up name server and may persist for a long time.
12919 If a domain which exhibits this problem matches anything in
12920 dns_again_means_nonexist, it is treated as if it did not exist. This option
12921 should be used with care. You can make it apply to reverse lookups by a setting
12924 dns_again_means_nonexist = *.in-addr.arpa
12926 This option applies to all DNS lookups that Exim does. It also applies when the
12927 gethostbyname() or getipnodebyname() functions give temporary errors, since
12928 these are most likely to be caused by DNS lookup problems. The dnslookup router
12929 has some options of its own for controlling what happens when lookups for MX or
12930 SRV records give temporary errors. These more specific options are applied
12931 after this global option.
12933 +-----------------------+---------+------------+------------------+
12934 |dns_check_names_pattern|Use: main|Type: string|Default: see below|
12935 +-----------------------+---------+------------+------------------+
12937 When this option is set to a non-empty string, it causes Exim to check domain
12938 names for characters that are not allowed in host names before handing them to
12939 the DNS resolver, because some resolvers give temporary errors for names that
12940 contain unusual characters. If a domain name contains any unwanted characters,
12941 a "not found" result is forced, and the resolver is not called. The check is
12942 done by matching the domain name against a regular expression, which is the
12943 value of this option. The default pattern is
12945 dns_check_names_pattern = \
12946 (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$
12948 which permits only letters, digits, slashes, and hyphens in components, but
12949 they must start and end with a letter or digit. Slashes are not, in fact,
12950 permitted in host names, but they are found in certain NS records (which can be
12951 accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you
12952 must modify this pattern, or set the option to an empty string.
12954 +--------------------+---------+-------------+----------+
12955 |dns_csa_search_limit|Use: main|Type: integer|Default: 5|
12956 +--------------------+---------+-------------+----------+
12958 This option controls the depth of parental searching for CSA SRV records in the
12959 DNS, as described in more detail in section 42.50.
12961 +-------------------+---------+-------------+-------------+
12962 |dns_csa_use_reverse|Use: main|Type: boolean|Default: true|
12963 +-------------------+---------+-------------+-------------+
12965 This option controls whether or not an IP address, given as a CSA domain, is
12966 reversed and looked up in the reverse DNS, as described in more detail in
12969 +-------------+---------+-------------+-----------+
12970 |dns_dnssec_ok|Use: main|Type: integer|Default: -1|
12971 +-------------+---------+-------------+-----------+
12973 If this option is set to a non-negative number then Exim will initialise the
12974 DNS resolver library to either use or not use DNSSEC, overriding the system
12975 default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on.
12977 If the resolver library does not support DNSSEC then this option has no effect.
12979 +---------------+---------+------------------+--------------+
12980 |dns_ipv4_lookup|Use: main|Type: domain list*|Default: unset|
12981 +---------------+---------+------------------+--------------+
12983 When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks
12984 for IPv6 address records (AAAA records) as well as IPv4 address records (A
12985 records) when trying to find IP addresses for hosts, unless the host's domain
12988 This is a fudge to help with name servers that give big delays or otherwise do
12989 not work for the AAAA record type. In due course, when the world's name servers
12990 have all been upgraded, there should be no need for this option.
12992 +-----------+---------+----------+-----------+
12993 |dns_retrans|Use: main|Type: time|Default: 0s|
12994 +-----------+---------+----------+-----------+
12996 The options dns_retrans and dns_retry can be used to set the retransmission and
12997 retry parameters for DNS lookups. Values of zero (the defaults) leave the
12998 system default settings unchanged. The first value is the time between retries,
12999 and the second is the number of retries. It isn't totally clear exactly how
13000 these settings affect the total time a DNS lookup may take. I haven't found any
13001 documentation about timeouts on DNS lookups; these parameter values are
13002 available in the external resolver interface structure, but nowhere does it
13003 seem to describe how they are used or what you might want to set in them.
13005 +---------+---------+-------------+----------+
13006 |dns_retry|Use: main|Type: integer|Default: 0|
13007 +---------+---------+-------------+----------+
13009 See dns_retrans above.
13011 +-------------+---------+-------------+-----------+
13012 |dns_use_edns0|Use: main|Type: integer|Default: -1|
13013 +-------------+---------+-------------+-----------+
13015 If this option is set to a non-negative number then Exim will initialise the
13016 DNS resolver library to either use or not use EDNS0 extensions, overriding the
13017 system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0 on.
13019 If the resolver library does not support EDNS0 then this option has no effect.
13021 +-------+---------+-------------+--------------+
13022 |drop_cr|Use: main|Type: boolean|Default: false|
13023 +-------+---------+-------------+--------------+
13025 This is an obsolete option that is now a no-op. It used to affect the way Exim
13026 handled CR and LF characters in incoming messages. What happens now is
13027 described in section 46.2.
13029 +--------+---------+-------------+------------------+
13030 |dsn_from|Use: main|Type: string*|Default: see below|
13031 +--------+---------+-------------+------------------+
13033 This option can be used to vary the contents of From: header lines in bounces
13034 and other automatically generated messages ("Delivery Status Notifications" -
13035 hence the name of the option). The default setting is:
13037 dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain>
13039 The value is expanded every time it is needed. If the expansion fails, a panic
13040 is logged, and the default value is used.
13042 +------------------+---------+-------------+-------------+
13043 |envelope_to_remove|Use: main|Type: boolean|Default: true|
13044 +------------------+---------+-------------+-------------+
13046 Exim's transports have an option for adding an Envelope-to: header to a message
13047 when it is delivered, in exactly the same way as Return-path: is handled.
13048 Envelope-to: records the original recipient address from the messages's
13049 envelope that caused the delivery to happen. Such headers should not be present
13050 in incoming messages, and this option causes them to be removed at the time the
13051 message is received, to avoid any problems that might occur when a delivered
13052 message is subsequently sent on to some other recipient.
13054 +-----------+---------+------------------+--------------+
13055 |errors_copy|Use: main|Type: string list*|Default: unset|
13056 +-----------+---------+------------------+--------------+
13058 Setting this option causes Exim to send bcc copies of bounce messages that it
13059 generates to other addresses. Note: This does not apply to bounce messages
13060 coming from elsewhere. The value of the option is a colon-separated list of
13061 items. Each item consists of a pattern, terminated by white space, followed by
13062 a comma-separated list of email addresses. If a pattern contains spaces, it
13063 must be enclosed in double quotes.
13065 Each pattern is processed in the same way as a single item in an address list
13066 (see section 10.19). When a pattern matches the recipient of the bounce
13067 message, the message is copied to the addresses on the list. The items are
13068 scanned in order, and once a matching one is found, no further items are
13069 examined. For example:
13071 errors_copy = spqr@mydomain postmaster@mydomain.example :\
13072 rqps@mydomain hostmaster@mydomain.example,\
13073 postmaster@mydomain.example
13075 The address list is expanded before use. The expansion variables $local_part
13076 and $domain are set from the original recipient of the error message, and if
13077 there was any wildcard matching in the pattern, the expansion variables $0, $1,
13078 etc. are set in the normal way.
13080 +---------------+---------+------------+--------------+
13081 |errors_reply_to|Use: main|Type: string|Default: unset|
13082 +---------------+---------+------------+--------------+
13084 By default, Exim's bounce and delivery warning messages contain the header line
13086 From: Mail Delivery System <Mailer-Daemon@qualify-domain>
13088 where qualify-domain is the value of the qualify_domain option. A warning
13089 message that is generated by the quota_warn_message option in an appendfile
13090 transport may contain its own From: header line that overrides the default.
13092 Experience shows that people reply to bounce messages. If the errors_reply_to
13093 option is set, a Reply-To: header is added to bounce and warning messages. For
13096 errors_reply_to = postmaster@my.domain.example
13098 The value of the option is not expanded. It must specify a valid RFC 2822
13099 address. However, if a warning message that is generated by the
13100 quota_warn_message option in an appendfile transport contain its own Reply-To:
13101 header line, the value of the errors_reply_to option is not used.
13103 +----------+---------+------------+--------------------------------+
13104 |exim_group|Use: main|Type: string|Default: compile-time configured|
13105 +----------+---------+------------+--------------------------------+
13107 This option changes the gid under which Exim runs when it gives up root
13108 privilege. The default value is compiled into the binary. The value of this
13109 option is used only when exim_user is also set. Unless it consists entirely of
13110 digits, the string is looked up using getgrnam(), and failure causes a
13111 configuration error. See chapter 54 for a discussion of security issues.
13113 +---------+---------+------------+------------------+
13114 |exim_path|Use: main|Type: string|Default: see below|
13115 +---------+---------+------------+------------------+
13117 This option specifies the path name of the Exim binary, which is used when Exim
13118 needs to re-exec itself. The default is set up to point to the file exim in the
13119 directory configured at compile time by the BIN_DIRECTORY setting. It is
13120 necessary to change exim_path if, exceptionally, Exim is run from some other
13121 place. Warning: Do not use a macro to define the value of this option, because
13122 you will break those Exim utilities that scan the configuration file to find
13123 where the binary is. (They then use the -bP option to extract option settings
13124 such as the value of spool_directory.)
13126 +---------+---------+------------+--------------------------------+
13127 |exim_user|Use: main|Type: string|Default: compile-time configured|
13128 +---------+---------+------------+--------------------------------+
13130 This option changes the uid under which Exim runs when it gives up root
13131 privilege. The default value is compiled into the binary. Ownership of the run
13132 time configuration file and the use of the -C and -D command line options is
13133 checked against the values in the binary, not what is set here.
13135 Unless it consists entirely of digits, the string is looked up using getpwnam()
13136 , and failure causes a configuration error. If exim_group is not also supplied,
13137 the gid is taken from the result of getpwnam() if it is used. See chapter 54
13138 for a discussion of security issues.
13140 +----------------------+---------+-----------------+--------------+
13141 |extra_local_interfaces|Use: main|Type: string list|Default: unset|
13142 +----------------------+---------+-----------------+--------------+
13144 This option defines network interfaces that are to be considered local when
13145 routing, but which are not used for listening by the daemon. See section 13.8
13148 +-------------------------------------+---------+-------------+-------------+
13149 |extract_addresses_remove_ arguments|Use: main|Type: boolean|Default: true|
13150 +-------------------------------------+---------+-------------+-------------+
13152 According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses
13153 are present on the command line when the -t option is used to build an envelope
13154 from a message's To:, Cc: and Bcc: headers, the command line addresses are
13155 removed from the recipients list. This is also how Smail behaves. However,
13156 other Sendmail documentation (the O'Reilly book) states that command line
13157 addresses are added to those obtained from the header lines. When
13158 extract_addresses_remove_arguments is true (the default), Exim subtracts
13159 argument headers. If it is set false, Exim adds rather than removes argument
13162 +----------------+---------+-------------+----------+
13163 |finduser_retries|Use: main|Type: integer|Default: 0|
13164 +----------------+---------+-------------+----------+
13166 On systems running NIS or other schemes in which user and group information is
13167 distributed from a remote system, there can be times when getpwnam() and
13168 related functions fail, even when given valid data, because things time out.
13169 Unfortunately these failures cannot be distinguished from genuine "not found"
13170 errors. If finduser_retries is set greater than zero, Exim will try that many
13171 extra times to find a user or a group, waiting for one second between retries.
13173 You should not set this option greater than zero if your user information is in
13174 a traditional /etc/passwd file, because it will cause Exim needlessly to search
13175 the file multiple times for non-existent users, and also cause delay.
13177 +-----------+---------+----------------------------------+--------------+
13178 |freeze_tell|Use: main|Type: string list, comma separated|Default: unset|
13179 +-----------+---------+----------------------------------+--------------+
13181 On encountering certain errors, or when configured to do so in a system filter,
13182 ACL, or special router, Exim freezes a message. This means that no further
13183 delivery attempts take place until an administrator thaws the message, or the
13184 auto_thaw, ignore_bounce_errors_after, or timeout_frozen_after feature cause it
13185 to be processed. If freeze_tell is set, Exim generates a warning message
13186 whenever it freezes something, unless the message it is freezing is a
13187 locally-generated bounce message. (Without this exception there is the
13188 possibility of looping.) The warning message is sent to the addresses supplied
13189 as the comma-separated value of this option. If several of the message's
13190 addresses cause freezing, only a single message is sent. If the freezing was
13191 automatic, the reason(s) for freezing can be found in the message log. If you
13192 configure freezing in a filter or ACL, you must arrange for any logging that
13195 +----------+---------+-------------+--------------+
13196 |gecos_name|Use: main|Type: string*|Default: unset|
13197 +----------+---------+-------------+--------------+
13199 Some operating systems, notably HP-UX, use the "gecos" field in the system
13200 password file to hold other information in addition to users' real names. Exim
13201 looks up this field for use when it is creating Sender: or From: headers. If
13202 either gecos_pattern or gecos_name are unset, the contents of the field are
13203 used unchanged, except that, if an ampersand is encountered, it is replaced by
13204 the user's login name with the first character forced to upper case, since this
13205 is a convention that is observed on many systems.
13207 When these options are set, gecos_pattern is treated as a regular expression
13208 that is to be applied to the field (again with & replaced by the login name),
13209 and if it matches, gecos_name is expanded and used as the user's name.
13211 Numeric variables such as $1, $2, etc. can be used in the expansion to pick up
13212 sub-fields that were matched by the pattern. In HP-UX, where the user's name
13213 terminates at the first comma, the following can be used:
13215 gecos_pattern = ([^,]*)
13218 +-------------+---------+------------+--------------+
13219 |gecos_pattern|Use: main|Type: string|Default: unset|
13220 +-------------+---------+------------+--------------+
13222 See gecos_name above.
13224 +------------------+---------+-------------+--------------+
13225 |gnutls_compat_mode|Use: main|Type: boolean|Default: unset|
13226 +------------------+---------+-------------+--------------+
13228 This option controls whether GnuTLS is used in compatibility mode in an Exim
13229 server. This reduces security slightly, but improves interworking with older
13230 implementations of TLS.
13232 option gnutls_allow_auto_pkcs11 main boolean unset This option will let GnuTLS
13233 (2.12.0 or later) autoload PKCS11 modules with the p11-kit configuration files
13234 in /etc/pkcs11/modules/.
13236 See http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for
13239 +---------------+---------+------------+------------------+
13240 |headers_charset|Use: main|Type: string|Default: see below|
13241 +---------------+---------+------------+------------------+
13243 This option sets a default character set for translating from encoded MIME
13244 "words" in header lines, when referenced by an $h_xxx expansion item. The
13245 default is the value of HEADERS_CHARSET in Local/Makefile. The ultimate default
13246 is ISO-8859-1. For more details see the description of header insertions in
13249 +--------------+---------+-------------+------------------+
13250 |header_maxsize|Use: main|Type: integer|Default: see below|
13251 +--------------+---------+-------------+------------------+
13253 This option controls the overall maximum size of a message's header section.
13254 The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for
13255 that is 1M. Messages with larger header sections are rejected.
13257 +-------------------+---------+-------------+----------+
13258 |header_line_maxsize|Use: main|Type: integer|Default: 0|
13259 +-------------------+---------+-------------+----------+
13261 This option limits the length of any individual header line in a message, after
13262 all the continuations have been joined together. Messages with individual
13263 header lines that are longer than the limit are rejected. The default value of
13264 zero means "no limit".
13266 +----------------------+---------+----------------+--------------+
13267 |helo_accept_junk_hosts|Use: main|Type: host list*|Default: unset|
13268 +----------------------+---------+----------------+--------------+
13270 Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and
13271 gives an error response for invalid data. Unfortunately, there are some SMTP
13272 clients that send syntactic junk. They can be accommodated by setting this
13273 option. Note that this is a syntax check only. See helo_verify_hosts if you
13274 want to do semantic checking. See also helo_allow_chars for a way of extending
13275 the permitted character set.
13277 +----------------+---------+------------+--------------+
13278 |helo_allow_chars|Use: main|Type: string|Default: unset|
13279 +----------------+---------+------------+--------------+
13281 This option can be set to a string of rogue characters that are permitted in
13282 all EHLO and HELO names in addition to the standard letters, digits, hyphens,
13283 and dots. If you really must allow underscores, you can set
13285 helo_allow_chars = _
13287 Note that the value is one string, not a list.
13289 +-------------------+---------+------------------+----------------+
13290 |helo_lookup_domains|Use: main|Type: domain list*|Default: "@:@[]"|
13291 +-------------------+---------+------------------+----------------+
13293 If the domain given by a client in a HELO or EHLO command matches this list, a
13294 reverse lookup is done in order to establish the host's true name. The default
13295 forces a lookup if the client host gives the server's name or any of its IP
13296 addresses (in brackets), something that broken clients have been seen to do.
13298 +---------------------+---------+----------------+--------------+
13299 |helo_try_verify_hosts|Use: main|Type: host list*|Default: unset|
13300 +---------------------+---------+----------------+--------------+
13302 By default, Exim just checks the syntax of HELO and EHLO commands (see
13303 helo_accept_junk_hosts and helo_allow_chars). However, some sites like to do
13304 more extensive checking of the data supplied by these commands. The ACL
13305 condition "verify = helo" is provided to make this possible. Formerly, it was
13306 necessary also to set this option (helo_try_verify_hosts) to force the check to
13307 occur. From release 4.53 onwards, this is no longer necessary. If the check has
13308 not been done before "verify = helo" is encountered, it is done at that time.
13309 Consequently, this option is obsolete. Its specification is retained here for
13310 backwards compatibility.
13312 When an EHLO or HELO command is received, if the calling host matches
13313 helo_try_verify_hosts, Exim checks that the host name given in the HELO or EHLO
13316 * is an IP literal matching the calling address of the host, or
13318 * matches the host name that Exim obtains by doing a reverse lookup of the
13319 calling host address, or
13321 * when looked up using gethostbyname() (or getipnodebyname() when available)
13322 yields the calling host address.
13324 However, the EHLO or HELO command is not rejected if any of the checks fail.
13325 Processing continues, but the result of the check is remembered, and can be
13326 detected later in an ACL by the "verify = helo" condition.
13328 +-----------------+---------+----------------+--------------+
13329 |helo_verify_hosts|Use: main|Type: host list*|Default: unset|
13330 +-----------------+---------+----------------+--------------+
13332 Like helo_try_verify_hosts, this option is obsolete, and retained only for
13333 backwards compatibility. For hosts that match this option, Exim checks the host
13334 name given in the HELO or EHLO in the same way as for helo_try_verify_hosts. If
13335 the check fails, the HELO or EHLO command is rejected with a 550 error, and
13336 entries are written to the main and reject logs. If a MAIL command is received
13337 before EHLO or HELO, it is rejected with a 503 error.
13339 +------------+---------+------------------+--------------+
13340 |hold_domains|Use: main|Type: domain list*|Default: unset|
13341 +------------+---------+------------------+--------------+
13343 This option allows mail for particular domains to be held on the queue
13344 manually. The option is overridden if a message delivery is forced with the -M,
13345 -qf, -Rf or -Sf options, and also while testing or verifying addresses using
13346 -bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing
13347 or delivery for that address is done, and it is deferred every time the message
13350 This option is intended as a temporary operational measure for delaying the
13351 delivery of mail while some problem is being sorted out, or some new
13352 configuration tested. If you just want to delay the processing of some domains
13353 until a queue run occurs, you should use queue_domains or queue_smtp_domains,
13356 A setting of hold_domains does not override Exim's code for removing messages
13357 from the queue if they have been there longer than the longest retry time in
13358 any retry rule. If you want to hold messages for longer than the normal retry
13359 times, insert a dummy retry rule with a long retry time.
13361 +-----------+---------+----------------+--------------+
13362 |host_lookup|Use: main|Type: host list*|Default: unset|
13363 +-----------+---------+----------------+--------------+
13365 Exim does not look up the name of a calling host from its IP address unless it
13366 is required to compare against some host list, or the host matches
13367 helo_try_verify_hosts or helo_verify_hosts, or the host matches this option
13368 (which normally contains IP addresses rather than host names). The default
13369 configuration file contains
13373 which causes a lookup to happen for all hosts. If the expense of these lookups
13374 is felt to be too great, the setting can be changed or removed.
13376 After a successful reverse lookup, Exim does a forward lookup on the name it
13377 has obtained, to verify that it yields the IP address that it started with. If
13378 this check fails, Exim behaves as if the name lookup failed.
13380 After any kind of failure, the host name (in $sender_host_name) remains unset,
13381 and $host_lookup_failed is set to the string "1". See also
13382 dns_again_means_nonexist, helo_lookup_domains, and "verify =
13383 reverse_host_lookup" in ACLs.
13385 +-----------------+---------+-----------------+-----------------------+
13386 |host_lookup_order|Use: main|Type: string list|Default: "bydns:byaddr"|
13387 +-----------------+---------+-----------------+-----------------------+
13389 This option specifies the order of different lookup methods when Exim is trying
13390 to find a host name from an IP address. The default is to do a DNS lookup
13391 first, and then to try a local lookup (using gethostbyaddr() or equivalent) if
13392 that fails. You can change the order of these lookups, or omit one entirely, if
13395 Warning: The "byaddr" method does not always yield aliases when there are
13396 multiple PTR records in the DNS and the IP address is not listed in /etc/hosts.
13397 Different operating systems give different results in this case. That is why
13398 the default tries a DNS lookup first.
13400 +----------------------+---------+----------------+--------------+
13401 |host_reject_connection|Use: main|Type: host list*|Default: unset|
13402 +----------------------+---------+----------------+--------------+
13404 If this option is set, incoming SMTP calls from the hosts listed are rejected
13405 as soon as the connection is made. This option is obsolete, and retained only
13406 for backward compatibility, because nowadays the ACL specified by
13407 acl_smtp_connect can also reject incoming connections immediately.
13409 The ability to give an immediate rejection (either by this option or using an
13410 ACL) is provided for use in unusual cases. Many hosts will just try again,
13411 sometimes without much delay. Normally, it is better to use an ACL to reject
13412 incoming messages at a later stage, such as after RCPT commands. See chapter 42
13415 +----------------------+---------+----------------+--------------+
13416 |hosts_connection_nolog|Use: main|Type: host list*|Default: unset|
13417 +----------------------+---------+----------------+--------------+
13419 This option defines a list of hosts for which connection logging does not
13420 happen, even though the smtp_connection log selector is set. For example, you
13421 might want not to log SMTP connections from local processes, or from 127.0.0.1,
13422 or from your local LAN. This option is consulted in the main loop of the
13423 daemon; you should therefore strive to restrict its value to a short inline
13424 list of IP addresses and networks. To disable logging SMTP connections from
13425 local processes, you must create a host list with an empty item. For example:
13427 hosts_connection_nolog = :
13429 If the smtp_connection log selector is not set, this option has no effect.
13431 +--------------------+---------+------------------+--------------+
13432 |hosts_treat_as_local|Use: main|Type: domain list*|Default: unset|
13433 +--------------------+---------+------------------+--------------+
13435 If this option is set, any host names that match the domain list are treated as
13436 if they were the local host when Exim is scanning host lists obtained from MX
13437 records or other sources. Note that the value of this option is a domain list,
13438 not a host list, because it is always used to check host names, not IP
13441 This option also applies when Exim is matching the special items "@mx_any",
13442 "@mx_primary", and "@mx_secondary" in a domain list (see section 10.8), and
13443 when checking the hosts option in the smtp transport for the local host (see
13444 the allow_localhost option in that transport). See also local_interfaces,
13445 extra_local_interfaces, and chapter 13, which contains a discussion about local
13446 network interfaces and recognizing the local host.
13448 +-------------+---------+-----------------+--------------+
13449 |ibase_servers|Use: main|Type: string list|Default: unset|
13450 +-------------+---------+-----------------+--------------+
13452 This option provides a list of InterBase servers and associated connection
13453 data, to be used in conjunction with ibase lookups (see section 9.21). The
13454 option is available only if Exim has been built with InterBase support.
13456 +--------------------------+---------+----------+------------+
13457 |ignore_bounce_errors_after|Use: main|Type: time|Default: 10w|
13458 +--------------------------+---------+----------+------------+
13460 This option affects the processing of bounce messages that cannot be delivered,
13461 that is, those that suffer a permanent delivery failure. (Bounce messages that
13462 suffer temporary delivery failures are of course retried in the usual way.)
13464 After a permanent delivery failure, bounce messages are frozen, because there
13465 is no sender to whom they can be returned. When a frozen bounce message has
13466 been on the queue for more than the given time, it is unfrozen at the next
13467 queue run, and a further delivery is attempted. If delivery fails again, the
13468 bounce message is discarded. This makes it possible to keep failed bounce
13469 messages around for a shorter time than the normal maximum retry time for
13470 frozen messages. For example,
13472 ignore_bounce_errors_after = 12h
13474 retries failed bounce message deliveries after 12 hours, discarding any further
13475 failures. If the value of this option is set to a zero time period, bounce
13476 failures are discarded immediately. Setting a very long time (as in the default
13477 value) has the effect of disabling this option. For ways of automatically
13478 dealing with other kinds of frozen message, see auto_thaw and
13479 timeout_frozen_after.
13481 +---------------------+---------+----------------+--------------+
13482 |ignore_fromline_hosts|Use: main|Type: host list*|Default: unset|
13483 +---------------------+---------+----------------+--------------+
13485 Some broken SMTP clients insist on sending a UUCP-like "From " line before the
13486 headers of a message. By default this is treated as the start of the message's
13487 body, which means that any following headers are not recognized as such. Exim
13488 can be made to ignore it by setting ignore_fromline_hosts to match those hosts
13489 that insist on sending it. If the sender is actually a local process rather
13490 than a remote host, and is using -bs to inject the messages,
13491 ignore_fromline_local must be set to achieve this effect.
13493 +---------------------+---------+-------------+--------------+
13494 |ignore_fromline_local|Use: main|Type: boolean|Default: false|
13495 +---------------------+---------+-------------+--------------+
13497 See ignore_fromline_hosts above.
13499 +----------------+---------+-----------------+--------------+
13500 |keep_environment|Use: main|Type: string list|Default: unset|
13501 +----------------+---------+-----------------+--------------+
13503 This option contains a string list of environment variables to keep. You have
13504 to trust these variables or you have to be sure that these variables do not
13505 impose any security risk. Keep in mind that during the startup phase Exim is
13506 running with an effective UID 0 in most installations. As the default value is
13507 an empty list, the default environment for using libraries, running embedded
13508 Perl code, or running external binaries is empty, and does not not even contain
13511 Actually the list is interpreted as a list of patterns (10.1), except that it
13512 is not expanded first.
13514 WARNING: Macro substitution is still done first, so having a macro FOO and
13515 having FOO_HOME in your keep_environment option may have unexpected results.
13516 You may work around this using a regular expression that does not match the
13517 macro name: ^[F]OO_HOME$.
13519 Current versions of Exim issue a warning during startupif you do not mention
13520 keep_environment or add_environment in your runtime configuration file.
13522 +--------------+---------+----------+-----------+
13523 |keep_malformed|Use: main|Type: time|Default: 4d|
13524 +--------------+---------+----------+-----------+
13526 This option specifies the length of time to keep messages whose spool files
13527 have been corrupted in some way. This should, of course, never happen. At the
13528 next attempt to deliver such a message, it gets removed. The incident is
13531 +----------------+---------+------------+--------------+
13532 |ldap_ca_cert_dir|Use: main|Type: string|Default: unset|
13533 +----------------+---------+------------+--------------+
13535 This option indicates which directory contains CA certificates for verifying a
13536 TLS certificate presented by an LDAP server. While Exim does not provide a
13537 default value, your SSL library may. Analogous to tls_verify_certificates but
13538 as a client-side option for LDAP and constrained to be a directory.
13540 +-----------------+---------+------------+--------------+
13541 |ldap_ca_cert_file|Use: main|Type: string|Default: unset|
13542 +-----------------+---------+------------+--------------+
13544 This option indicates which file contains CA certificates for verifying a TLS
13545 certificate presented by an LDAP server. While Exim does not provide a default
13546 value, your SSL library may. Analogous to tls_verify_certificates but as a
13547 client-side option for LDAP and constrained to be a file.
13549 +--------------+---------+------------+--------------+
13550 |ldap_cert_file|Use: main|Type: string|Default: unset|
13551 +--------------+---------+------------+--------------+
13553 This option indicates which file contains an TLS client certificate which Exim
13554 should present to the LDAP server during TLS negotiation. Should be used
13555 together with ldap_cert_key.
13557 +-------------+---------+------------+--------------+
13558 |ldap_cert_key|Use: main|Type: string|Default: unset|
13559 +-------------+---------+------------+--------------+
13561 This option indicates which file contains the secret/private key to use to
13562 prove identity to the LDAP server during TLS negotiation. Should be used
13563 together with ldap_cert_file, which contains the identity to be proven.
13565 +-----------------+---------+------------+--------------+
13566 |ldap_cipher_suite|Use: main|Type: string|Default: unset|
13567 +-----------------+---------+------------+--------------+
13569 This controls the TLS cipher-suite negotiation during TLS negotiation with the
13570 LDAP server. See 41.4 for more details of the format of cipher-suite options
13571 with OpenSSL (as used by LDAP client libraries).
13573 +--------------------+---------+-----------------+--------------+
13574 |ldap_default_servers|Use: main|Type: string list|Default: unset|
13575 +--------------------+---------+-----------------+--------------+
13577 This option provides a list of LDAP servers which are tried in turn when an
13578 LDAP query does not contain a server. See section 9.14 for details of LDAP
13579 queries. This option is available only when Exim has been built with LDAP
13582 +-----------------+---------+------------+---------------+
13583 |ldap_require_cert|Use: main|Type: string|Default: unset.|
13584 +-----------------+---------+------------+---------------+
13586 This should be one of the values "hard", "demand", "allow", "try" or "never". A
13587 value other than one of these is interpreted as "never". See the entry
13588 "TLS_REQCERT" in your system man page for ldap.conf(5). Although Exim does not
13589 set a default, the LDAP library probably defaults to hard/demand.
13591 +--------------+---------+-------------+--------------+
13592 |ldap_start_tls|Use: main|Type: boolean|Default: false|
13593 +--------------+---------+-------------+--------------+
13595 If set, Exim will attempt to negotiate TLS with the LDAP server when connecting
13596 on a regular LDAP port. This is the LDAP equivalent of SMTP's "STARTTLS". This
13597 is distinct from using "ldaps", which is the LDAP form of SSL-on-connect. In
13598 the event of failure to negotiate TLS, the action taken is controlled by
13601 +------------+---------+-------------+--------------+
13602 |ldap_version|Use: main|Type: integer|Default: unset|
13603 +------------+---------+-------------+--------------+
13605 This option can be used to force Exim to set a specific protocol version for
13606 LDAP. If it option is unset, it is shown by the -bP command line option as -1.
13607 When this is the case, the default is 3 if LDAP_VERSION3 is defined in the LDAP
13608 headers; otherwise it is 2. This option is available only when Exim has been
13609 built with LDAP support.
13611 +----------------+---------+-------------+-------------+
13612 |local_from_check|Use: main|Type: boolean|Default: true|
13613 +----------------+---------+-------------+-------------+
13615 When a message is submitted locally (that is, not over a TCP/IP connection) by
13616 an untrusted user, Exim removes any existing Sender: header line, and checks
13617 that the From: header line matches the login of the calling user and the domain
13618 specified by qualify_domain.
13620 Note: An unqualified address (no domain) in the From: header in a locally
13621 submitted message is automatically qualified by Exim, unless the -bnq command
13622 line option is used.
13624 You can use local_from_prefix and local_from_suffix to permit affixes on the
13625 local part. If the From: header line does not match, Exim adds a Sender: header
13626 with an address constructed from the calling user's login and the default
13629 If local_from_check is set false, the From: header check is disabled, and no
13630 Sender: header is ever added. If, in addition, you want to retain Sender:
13631 header lines supplied by untrusted users, you must also set local_sender_retain
13634 These options affect only the header lines in the message. The envelope sender
13635 is still forced to be the login id at the qualify domain unless
13636 untrusted_set_sender permits the user to supply an envelope sender.
13638 For messages received over TCP/IP, an ACL can specify "submission mode" to
13639 request similar header line checking. See section 46.16, which has more details
13640 about Sender: processing.
13642 +-----------------+---------+------------+--------------+
13643 |local_from_prefix|Use: main|Type: string|Default: unset|
13644 +-----------------+---------+------------+--------------+
13646 When Exim checks the From: header line of locally submitted messages for
13647 matching the login id (see local_from_check above), it can be configured to
13648 ignore certain prefixes and suffixes in the local part of the address. This is
13649 done by setting local_from_prefix and/or local_from_suffix to appropriate
13650 lists, in the same form as the local_part_prefix and local_part_suffix router
13651 options (see chapter 15). For example, if
13653 local_from_prefix = *-
13655 is set, a From: line containing
13657 From: anything-user@your.domain.example
13659 will not cause a Sender: header to be added if user@your.domain.example matches
13660 the actual sender address that is constructed from the login name and qualify
13663 +-----------------+---------+------------+--------------+
13664 |local_from_suffix|Use: main|Type: string|Default: unset|
13665 +-----------------+---------+------------+--------------+
13667 See local_from_prefix above.
13669 +----------------+---------+-----------------+------------------+
13670 |local_interfaces|Use: main|Type: string list|Default: see below|
13671 +----------------+---------+-----------------+------------------+
13673 This option controls which network interfaces are used by the daemon for
13674 listening; they are also used to identify the local host when routing. Chapter
13675 13 contains a full description of this option and the related options
13676 daemon_smtp_ports, extra_local_interfaces, hosts_treat_as_local, and
13677 tls_on_connect_ports. The default value for local_interfaces is
13679 local_interfaces = 0.0.0.0
13681 when Exim is built without IPv6 support; otherwise it is
13683 local_interfaces = <; ::0 ; 0.0.0.0
13685 +------------------+---------+----------+-----------+
13686 |local_scan_timeout|Use: main|Type: time|Default: 5m|
13687 +------------------+---------+----------+-----------+
13689 This timeout applies to the local_scan() function (see chapter 44). Zero means
13690 "no timeout". If the timeout is exceeded, the incoming message is rejected with
13691 a temporary error if it is an SMTP message. For a non-SMTP message, the message
13692 is dropped and Exim ends with a non-zero code. The incident is logged on the
13693 main and reject logs.
13695 +-------------------+---------+-------------+--------------+
13696 |local_sender_retain|Use: main|Type: boolean|Default: false|
13697 +-------------------+---------+-------------+--------------+
13699 When a message is submitted locally (that is, not over a TCP/IP connection) by
13700 an untrusted user, Exim removes any existing Sender: header line. If you do not
13701 want this to happen, you must set local_sender_retain, and you must also set
13702 local_from_check to be false (Exim will complain if you do not). See also the
13703 ACL modifier "control = suppress_local_fixups". Section 46.16 has more details
13704 about Sender: processing.
13706 +----------------+---------+-------------+--------------+
13707 |localhost_number|Use: main|Type: string*|Default: unset|
13708 +----------------+---------+-------------+--------------+
13710 Exim's message ids are normally unique only within the local host. If
13711 uniqueness among a set of hosts is required, each host must set a different
13712 value for the localhost_number option. The string is expanded immediately after
13713 reading the configuration file (so that a number can be computed from the host
13714 name, for example) and the result of the expansion must be a number in the
13715 range 0-16 (or 0-10 on operating systems with case-insensitive file systems).
13716 This is available in subsequent string expansions via the variable
13717 $localhost_number. When localhost_number is set, the final two characters of
13718 the message id, instead of just being a fractional part of the time, are
13719 computed from the time and the local host number as described in section 3.4.
13721 +-------------+---------+------------------+----------------------------+
13722 |log_file_path|Use: main|Type: string list*|Default: set at compile time|
13723 +-------------+---------+------------------+----------------------------+
13725 This option sets the path which is used to determine the names of Exim's log
13726 files, or indicates that logging is to be to syslog, or both. It is expanded
13727 when Exim is entered, so it can, for example, contain a reference to the host
13728 name. If no specific path is set for the log files at compile or run time, they
13729 are written in a sub-directory called log in Exim's spool directory. Chapter 51
13730 contains further details about Exim's logging, and section 51.1 describes how
13731 the contents of log_file_path are used. If this string is fixed at your
13732 installation (contains no expansion variables) it is recommended that you do
13733 not set this option in the configuration file, but instead supply the path
13734 using LOG_FILE_PATH in Local/Makefile so that it is available to Exim for
13735 logging errors detected early on - in particular, failure to read the
13736 configuration file.
13738 +------------+---------+------------+--------------+
13739 |log_selector|Use: main|Type: string|Default: unset|
13740 +------------+---------+------------+--------------+
13742 This option can be used to reduce or increase the number of things that Exim
13743 writes to its log files. Its argument is made up of names preceded by plus or
13744 minus characters. For example:
13746 log_selector = +arguments -retry_defer
13748 A list of possible names and what they control is given in the chapter on
13749 logging, in section 51.15.
13751 +------------+---------+-------------+--------------+
13752 |log_timezone|Use: main|Type: boolean|Default: false|
13753 +------------+---------+-------------+--------------+
13755 By default, the timestamps on log lines are in local time without the timezone.
13756 This means that if your timezone changes twice a year, the timestamps in log
13757 lines are ambiguous for an hour when the clocks go back. One way of avoiding
13758 this problem is to set the timezone to UTC. An alternative is to set
13759 log_timezone true. This turns on the addition of the timezone offset to
13760 timestamps in log lines. Turning on this option can add quite a lot to the size
13761 of log files because each line is extended by 6 characters. Note that the
13762 $tod_log variable contains the log timestamp without the zone, but there is
13763 another variable called $tod_zone that contains just the timezone offset.
13765 +---------------+---------+-------------+-----------+
13766 |lookup_open_max|Use: main|Type: integer|Default: 25|
13767 +---------------+---------+-------------+-----------+
13769 This option limits the number of simultaneously open files for single-key
13770 lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally
13771 keeps these files open during routing, because often the same file is required
13772 several times. If the limit is reached, Exim closes the least recently used
13773 file. Note that if you are using the ndbm library, it actually opens two files
13774 for each logical DBM database, though it still counts as one for the purposes
13775 of lookup_open_max. If you are getting "too many open files" errors with NDBM,
13776 you need to reduce the value of lookup_open_max.
13778 +-------------------+---------+-------------+----------+
13779 |max_username_length|Use: main|Type: integer|Default: 0|
13780 +-------------------+---------+-------------+----------+
13782 Some operating systems are broken in that they truncate long arguments to
13783 getpwnam() to eight characters, instead of returning "no such user". If this
13784 option is set greater than zero, any attempt to call getpwnam() with an
13785 argument that is longer behaves as if getpwnam() failed.
13787 +---------------------+---------+----------+--------------+
13788 |message_body_newlines|Use: main|Type: bool|Default: false|
13789 +---------------------+---------+----------+--------------+
13791 By default, newlines in the message body are replaced by spaces when setting
13792 the $message_body and $message_body_end expansion variables. If this option is
13793 set true, this no longer happens.
13795 +--------------------+---------+-------------+------------+
13796 |message_body_visible|Use: main|Type: integer|Default: 500|
13797 +--------------------+---------+-------------+------------+
13799 This option specifies how much of a message's body is to be included in the
13800 $message_body and $message_body_end expansion variables.
13802 +------------------------+---------+-------------+--------------+
13803 |message_id_header_domain|Use: main|Type: string*|Default: unset|
13804 +------------------------+---------+-------------+--------------+
13806 If this option is set, the string is expanded and used as the right hand side
13807 (domain) of the Message-ID: header that Exim creates if a locally-originated
13808 incoming message does not have one. "Locally-originated" means "not received
13809 over TCP/IP." Otherwise, the primary host name is used. Only letters, digits,
13810 dot and hyphen are accepted; any other characters are replaced by hyphens. If
13811 the expansion is forced to fail, or if the result is an empty string, the
13814 +----------------------+---------+-------------+--------------+
13815 |message_id_header_text|Use: main|Type: string*|Default: unset|
13816 +----------------------+---------+-------------+--------------+
13818 If this variable is set, the string is expanded and used to augment the text of
13819 the Message-id: header that Exim creates if a locally-originated incoming
13820 message does not have one. The text of this header is required by RFC 2822 to
13821 take the form of an address. By default, Exim uses its internal message id as
13822 the local part, and the primary host name as the domain. If this option is set,
13823 it is expanded, and provided the expansion is not forced to fail, and does not
13824 yield an empty string, the result is inserted into the header immediately
13825 before the @, separated from the internal message id by a dot. Any characters
13826 that are illegal in an address are automatically converted into hyphens. This
13827 means that variables such as $tod_log can be used, because the spaces and
13828 colons will become hyphens.
13830 +------------+---------+-------------+-------------+
13831 |message_logs|Use: main|Type: boolean|Default: true|
13832 +------------+---------+-------------+-------------+
13834 If this option is turned off, per-message log files are not created in the
13835 msglog spool sub-directory. This reduces the amount of disk I/O required by
13836 Exim, by reducing the number of files involved in handling a message from a
13837 minimum of four (header spool file, body spool file, delivery journal, and
13838 per-message log) to three. The other major I/O activity is Exim's main log,
13839 which is not affected by this option.
13841 +------------------+---------+-------------+------------+
13842 |message_size_limit|Use: main|Type: string*|Default: 50M|
13843 +------------------+---------+-------------+------------+
13845 This option limits the maximum size of message that Exim will process. The
13846 value is expanded for each incoming connection so, for example, it can be made
13847 to depend on the IP address of the remote host for messages arriving via TCP/
13848 IP. After expansion, the value must be a sequence of decimal digits, optionally
13849 followed by K or M.
13851 Note: This limit cannot be made to depend on a message's sender or any other
13852 properties of an individual message, because it has to be advertised in the
13853 server's response to EHLO. String expansion failure causes a temporary error. A
13854 value of zero means no limit, but its use is not recommended. See also
13855 bounce_return_size_limit.
13857 Incoming SMTP messages are failed with a 552 error if the limit is exceeded;
13858 locally-generated messages either get a stderr message or a delivery failure
13859 message to the sender, depending on the -oe setting. Rejection of an oversized
13860 message is logged in both the main and the reject logs. See also the generic
13861 transport option message_size_limit, which limits the size of message that an
13862 individual transport can process.
13864 If you use a virus-scanner and set this option to to a value larger than the
13865 maximum size that your virus-scanner is configured to support, you may get
13866 failures triggered by large mails. The right size to configure for the
13867 virus-scanner depends upon what data is passed and the options in use but it's
13868 probably safest to just set it to a little larger than this value. Eg, with a
13869 default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
13870 some problems may result.
13872 A value of 0 will disable size limit checking; Exim will still advertise the
13873 SIZE extension in an EHLO response, but without a limit, so as to permit SMTP
13874 clients to still indicate the message size along with the MAIL verb.
13876 +--------------------+---------+-------------+--------------+
13877 |move_frozen_messages|Use: main|Type: boolean|Default: false|
13878 +--------------------+---------+-------------+--------------+
13880 This option, which is available only if Exim has been built with the setting
13882 SUPPORT_MOVE_FROZEN_MESSAGES=yes
13884 in Local/Makefile, causes frozen messages and their message logs to be moved
13885 from the input and msglog directories on the spool to Finput and Fmsglog,
13886 respectively. There is currently no support in Exim or the standard utilities
13887 for handling such moved messages, and they do not show up in lists generated by
13888 -bp or by the Exim monitor.
13890 +-----------+---------+-------------+--------------+
13891 |mua_wrapper|Use: main|Type: boolean|Default: false|
13892 +-----------+---------+-------------+--------------+
13894 Setting this option true causes Exim to run in a very restrictive mode in which
13895 it passes messages synchronously to a smart host. Chapter 50 contains a full
13896 description of this facility.
13898 +-------------+---------+-----------------+--------------+
13899 |mysql_servers|Use: main|Type: string list|Default: unset|
13900 +-------------+---------+-----------------+--------------+
13902 This option provides a list of MySQL servers and associated connection data, to
13903 be used in conjunction with mysql lookups (see section 9.21). The option is
13904 available only if Exim has been built with MySQL support.
13906 +-----------+---------+------------------+--------------+
13907 |never_users|Use: main|Type: string list*|Default: unset|
13908 +-----------+---------+------------------+--------------+
13910 This option is expanded just once, at the start of Exim's processing. Local
13911 message deliveries are normally run in processes that are setuid to the
13912 recipient, and remote deliveries are normally run under Exim's own uid and gid.
13913 It is usually desirable to prevent any deliveries from running as root, as a
13916 When Exim is built, an option called FIXED_NEVER_USERS can be set to a list of
13917 users that must not be used for local deliveries. This list is fixed in the
13918 binary and cannot be overridden by the configuration file. By default, it
13919 contains just the single user name "root". The never_users runtime option can
13920 be used to add more users to the fixed list.
13922 If a message is to be delivered as one of the users on the fixed list or the
13923 never_users list, an error occurs, and delivery is deferred. A common example
13926 never_users = root:daemon:bin
13928 Including root is redundant if it is also on the fixed list, but it does no
13929 harm. This option overrides the pipe_as_creator option of the pipe transport
13932 +---------------+---------+-----------------+------------------+
13933 |openssl_options|Use: main|Type: string list|Default: +no_sslv2|
13934 +---------------+---------+-----------------+------------------+
13936 This option allows an administrator to adjust the SSL options applied by
13937 OpenSSL to connections. It is given as a space-separated list of items, each
13938 one to be +added or -subtracted from the current value.
13940 This option is only available if Exim is built against OpenSSL. The values
13941 available for this option vary according to the age of your OpenSSL install.
13942 The "all" value controls a subset of flags which are available, typically the
13943 bug workaround options. The SSL_CTX_set_options man page will list the values
13944 known on your system and Exim should support all the "bug workaround" options
13945 and many of the "modifying" options. The Exim names lose the leading "SSL_OP_"
13946 and are lower-cased.
13948 Note that adjusting the options can have severe impact upon the security of SSL
13949 as used by Exim. It is possible to disable safety checks and shoot yourself in
13950 the foot in various unpleasant ways. This option should not be adjusted
13951 lightly. An unrecognised item will be detected at startup, by invoking Exim
13954 Historical note: prior to release 4.80, Exim defaulted this value to
13955 "+dont_insert_empty_fragments", which may still be needed for compatibility
13956 with some clients, but which lowers security by increasing exposure to some now
13961 # Make both old MS and old Eudora happy:
13962 openssl_options = -all +microsoft_big_sslv3_buffer \
13963 +dont_insert_empty_fragments
13965 Possible options may include:
13969 * "allow_unsafe_legacy_renegotiation"
13971 * "cipher_server_preference"
13973 * "dont_insert_empty_fragments"
13977 * "legacy_server_connect"
13979 * "microsoft_big_sslv3_buffer"
13981 * "microsoft_sess_id_bug"
13983 * "msie_sslv2_rsa_padding"
13985 * "netscape_challenge_bug"
13987 * "netscape_reuse_cipher_change_bug"
13991 * "no_session_resumption_on_renegotiation"
14005 * "safari_ecdhe_ecdsa_bug"
14009 * "single_ecdh_use"
14011 * "ssleay_080_client_dh_bug"
14013 * "sslref2_reuse_cert_type_bug"
14015 * "tls_block_padding_bug"
14019 * "tls_rollback_bug"
14021 As an aside, the "safari_ecdhe_ecdsa_bug" item is a misnomer and affects all
14022 clients connecting using the MacOS SecureTransport TLS facility prior to MacOS
14023 10.8.4, including email clients. If you see old MacOS clients failing to
14024 negotiate TLS then this option value might help, provided that your OpenSSL
14025 release is new enough to contain this work-around. This may be a situation
14026 where you have to upgrade OpenSSL to get buggy clients working.
14028 +--------------+---------+-----------------+--------------+
14029 |oracle_servers|Use: main|Type: string list|Default: unset|
14030 +--------------+---------+-----------------+--------------+
14032 This option provides a list of Oracle servers and associated connection data,
14033 to be used in conjunction with oracle lookups (see section 9.21). The option is
14034 available only if Exim has been built with Oracle support.
14036 +--------------------+---------+------------------+--------------+
14037 |percent_hack_domains|Use: main|Type: domain list*|Default: unset|
14038 +--------------------+---------+------------------+--------------+
14040 The "percent hack" is the convention whereby a local part containing a percent
14041 sign is re-interpreted as a new email address, with the percent replaced by @.
14042 This is sometimes called "source routing", though that term is also applied to
14043 RFC 2822 addresses that begin with an @ character. If this option is set, Exim
14044 implements the percent facility for those domains listed, but no others. This
14045 happens before an incoming SMTP address is tested against an ACL.
14047 Warning: The "percent hack" has often been abused by people who are trying to
14048 get round relaying restrictions. For this reason, it is best avoided if at all
14049 possible. Unfortunately, a number of less security-conscious MTAs implement it
14050 unconditionally. If you are running Exim on a gateway host, and routing mail
14051 through to internal MTAs without processing the local parts, it is a good idea
14052 to reject recipient addresses with percent characters in their local parts.
14053 Exim's default configuration does this.
14055 +-------------+---------+-------------+--------------+
14056 |perl_at_start|Use: main|Type: boolean|Default: false|
14057 +-------------+---------+-------------+--------------+
14059 This option is available only when Exim is built with an embedded Perl
14060 interpreter. See chapter 12 for details of its use.
14062 +------------+---------+------------+--------------+
14063 |perl_startup|Use: main|Type: string|Default: unset|
14064 +------------+---------+------------+--------------+
14066 This option is available only when Exim is built with an embedded Perl
14067 interpreter. See chapter 12 for details of its use.
14069 +-------------+---------+-----------------+--------------+
14070 |pgsql_servers|Use: main|Type: string list|Default: unset|
14071 +-------------+---------+-----------------+--------------+
14073 This option provides a list of PostgreSQL servers and associated connection
14074 data, to be used in conjunction with pgsql lookups (see section 9.21). The
14075 option is available only if Exim has been built with PostgreSQL support.
14077 +-------------+---------+-------------+----------------------------+
14078 |pid_file_path|Use: main|Type: string*|Default: set at compile time|
14079 +-------------+---------+-------------+----------------------------+
14081 This option sets the name of the file to which the Exim daemon writes its
14082 process id. The string is expanded, so it can contain, for example, references
14085 pid_file_path = /var/log/$primary_hostname/exim.pid
14087 If no path is set, the pid is written to the file exim-daemon.pid in Exim's
14088 spool directory. The value set by the option can be overridden by the -oP
14089 command line option. A pid file is not written if a "non-standard" daemon is
14090 run by means of the -oX option, unless a path is explicitly supplied by -oP.
14092 +--------------------------+---------+----------------+----------+
14093 |pipelining_advertise_hosts|Use: main|Type: host list*|Default: *|
14094 +--------------------------+---------+----------------+----------+
14096 This option can be used to suppress the advertisement of the SMTP PIPELINING
14097 extension to specific hosts. See also the no_pipelining control in section
14098 42.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim
14099 server enforces strict synchronization for each SMTP command and response. When
14100 PIPELINING is advertised, Exim assumes that clients will use it; "out of order"
14101 commands that are "expected" do not count as protocol errors (see
14102 smtp_max_synprot_errors).
14104 +-----------+---------+-------------+--------------+
14105 |prdr_enable|Use: main|Type: boolean|Default: false|
14106 +-----------+---------+-------------+--------------+
14108 This option can be used to enable the Per-Recipient Data Response extension to
14109 SMTP, defined by Eric Hall. If the option is set, PRDR is advertised by Exim
14110 when operating as a server. If the client requests PRDR, and more than one
14111 recipient, for a message an additional ACL is called for each recipient after
14112 the message content is recieved. See section 42.9.
14114 +---------------------+---------+-------------+--------------+
14115 |preserve_message_logs|Use: main|Type: boolean|Default: false|
14116 +---------------------+---------+-------------+--------------+
14118 If this option is set, message log files are not deleted when messages are
14119 completed. Instead, they are moved to a sub-directory of the spool directory
14120 called msglog.OLD, where they remain available for statistical or debugging
14121 purposes. This is a dangerous option to set on systems with any appreciable
14122 volume of mail. Use with care!
14124 +----------------+---------+------------+------------------+
14125 |primary_hostname|Use: main|Type: string|Default: see below|
14126 +----------------+---------+------------+------------------+
14128 This specifies the name of the current host. It is used in the default EHLO or
14129 HELO command for outgoing SMTP messages (changeable via the helo_data option in
14130 the smtp transport), and as the default for qualify_domain. The value is also
14131 used by default in some SMTP response messages from an Exim server. This can be
14132 changed dynamically by setting smtp_active_hostname.
14134 If primary_hostname is not set, Exim calls uname() to find the host name. If
14135 this fails, Exim panics and dies. If the name returned by uname() contains only
14136 one component, Exim passes it to gethostbyname() (or getipnodebyname() when
14137 available) in order to obtain the fully qualified version. The variable
14138 $primary_hostname contains the host name, whether set explicitly by this
14139 option, or defaulted.
14141 +-----------------+---------+-------------+--------------+
14142 |print_topbitchars|Use: main|Type: boolean|Default: false|
14143 +-----------------+---------+-------------+--------------+
14145 By default, Exim considers only those characters whose codes lie in the range
14146 32-126 to be printing characters. In a number of circumstances (for example,
14147 when writing log entries) non-printing characters are converted into escape
14148 sequences, primarily to avoid messing up the layout. If print_topbitchars is
14149 set, code values of 128 and above are also considered to be printing
14152 This option also affects the header syntax checks performed by the autoreply
14153 transport, and whether Exim uses RFC 2047 encoding of the user's full name when
14154 constructing From: and Sender: addresses (as described in section 46.18).
14155 Setting this option can cause Exim to generate eight bit message headers that
14156 do not conform to the standards.
14158 +----------------+---------+------------+--------------+
14159 |process_log_path|Use: main|Type: string|Default: unset|
14160 +----------------+---------+------------+--------------+
14162 This option sets the name of the file to which an Exim process writes its
14163 "process log" when sent a USR1 signal. This is used by the exiwhat utility
14164 script. If this option is unset, the file called exim-process.info in Exim's
14165 spool directory is used. The ability to specify the name explicitly can be
14166 useful in environments where two different Exims are running, using different
14169 +-------------------+---------+-------------+-------------+
14170 |prod_requires_admin|Use: main|Type: boolean|Default: true|
14171 +-------------------+---------+-------------+-------------+
14173 The -M, -R, and -q command-line options require the caller to be an admin user
14174 unless prod_requires_admin is set false. See also queue_list_requires_admin.
14176 +--------------+---------+------------+------------------+
14177 |qualify_domain|Use: main|Type: string|Default: see below|
14178 +--------------+---------+------------+------------------+
14180 This option specifies the domain name that is added to any envelope sender
14181 addresses that do not have a domain qualification. It also applies to recipient
14182 addresses if qualify_recipient is not set. Unqualified addresses are accepted
14183 by default only for locally-generated messages. Qualification is also applied
14184 to addresses in header lines such as From: and To: for locally-generated
14185 messages, unless the -bnq command line option is used.
14187 Messages from external sources must always contain fully qualified addresses,
14188 unless the sending host matches sender_unqualified_hosts or
14189 recipient_unqualified_hosts (as appropriate), in which case incoming addresses
14190 are qualified with qualify_domain or qualify_recipient as necessary.
14191 Internally, Exim always works with fully qualified envelope addresses. If
14192 qualify_domain is not set, it defaults to the primary_hostname value.
14194 +-----------------+---------+------------+------------------+
14195 |qualify_recipient|Use: main|Type: string|Default: see below|
14196 +-----------------+---------+------------+------------------+
14198 This option allows you to specify a different domain for qualifying recipient
14199 addresses to the one that is used for senders. See qualify_domain above.
14201 +-------------+---------+------------------+--------------+
14202 |queue_domains|Use: main|Type: domain list*|Default: unset|
14203 +-------------+---------+------------------+--------------+
14205 This option lists domains for which immediate delivery is not required. A
14206 delivery process is started whenever a message is received, but only those
14207 domains that do not match are processed. All other deliveries wait until the
14208 next queue run. See also hold_domains and queue_smtp_domains.
14210 +-------------------------+---------+-------------+-------------+
14211 |queue_list_requires_admin|Use: main|Type: boolean|Default: true|
14212 +-------------------------+---------+-------------+-------------+
14214 The -bp command-line option, which lists the messages that are on the queue,
14215 requires the caller to be an admin user unless queue_list_requires_admin is set
14216 false. See also prod_requires_admin.
14218 +----------+---------+-------------+--------------+
14219 |queue_only|Use: main|Type: boolean|Default: false|
14220 +----------+---------+-------------+--------------+
14222 If queue_only is set, a delivery process is not automatically started whenever
14223 a message is received. Instead, the message waits on the queue for the next
14224 queue run. Even if queue_only is false, incoming messages may not get delivered
14225 immediately when certain conditions (such as heavy load) occur.
14227 The -odq command line has the same effect as queue_only. The -odb and -odi
14228 command line options override queue_only unless queue_only_override is set
14229 false. See also queue_only_file, queue_only_load, and smtp_accept_queue.
14231 +---------------+---------+------------+--------------+
14232 |queue_only_file|Use: main|Type: string|Default: unset|
14233 +---------------+---------+------------+--------------+
14235 This option can be set to a colon-separated list of absolute path names, each
14236 one optionally preceded by "smtp". When Exim is receiving a message, it tests
14237 for the existence of each listed path using a call to stat(). For each path
14238 that exists, the corresponding queueing option is set. For paths with no
14239 prefix, queue_only is set; for paths prefixed by "smtp", queue_smtp_domains is
14240 set to match all domains. So, for example,
14242 queue_only_file = smtp/some/file
14244 causes Exim to behave as if queue_smtp_domains were set to "*" whenever /some/
14247 +---------------+---------+-----------------+--------------+
14248 |queue_only_load|Use: main|Type: fixed-point|Default: unset|
14249 +---------------+---------+-----------------+--------------+
14251 If the system load average is higher than this value, incoming messages from
14252 all sources are queued, and no automatic deliveries are started. If this
14253 happens during local or remote SMTP input, all subsequent messages received on
14254 the same SMTP connection are queued by default, whatever happens to the load in
14255 the meantime, but this can be changed by setting queue_only_load_latch false.
14257 Deliveries will subsequently be performed by queue runner processes. This
14258 option has no effect on ancient operating systems on which Exim cannot
14259 determine the load average. See also deliver_queue_load_max and
14262 +---------------------+---------+-------------+-------------+
14263 |queue_only_load_latch|Use: main|Type: boolean|Default: true|
14264 +---------------------+---------+-------------+-------------+
14266 When this option is true (the default), once one message has been queued
14267 because the load average is higher than the value set by queue_only_load, all
14268 subsequent messages received on the same SMTP connection are also queued. This
14269 is a deliberate choice; even though the load average may fall below the
14270 threshold, it doesn't seem right to deliver later messages on the same
14271 connection when not delivering earlier ones. However, there are special
14272 circumstances such as very long-lived connections from scanning appliances
14273 where this is not the best strategy. In such cases, queue_only_load_latch
14274 should be set false. This causes the value of the load average to be
14275 re-evaluated for each message.
14277 +-------------------+---------+-------------+-------------+
14278 |queue_only_override|Use: main|Type: boolean|Default: true|
14279 +-------------------+---------+-------------+-------------+
14281 When this option is true, the -odx command line options override the setting of
14282 queue_only or queue_only_file in the configuration file. If queue_only_override
14283 is set false, the -odx options cannot be used to override; they are accepted,
14286 +------------------+---------+-------------+--------------+
14287 |queue_run_in_order|Use: main|Type: boolean|Default: false|
14288 +------------------+---------+-------------+--------------+
14290 If this option is set, queue runs happen in order of message arrival instead of
14291 in an arbitrary order. For this to happen, a complete list of the entire queue
14292 must be set up before the deliveries start. When the queue is all held in a
14293 single directory (the default), a single list is created for both the ordered
14294 and the non-ordered cases. However, if split_spool_directory is set, a single
14295 list is not created when queue_run_in_order is false. In this case, the
14296 sub-directories are processed one at a time (in a random order), and this
14297 avoids setting up one huge list for the whole queue. Thus, setting
14298 queue_run_in_order with split_spool_directory may degrade performance when the
14299 queue is large, because of the extra work in setting up the single, large list.
14300 In most situations, queue_run_in_order should not be set.
14302 +-------------+---------+-------------+----------+
14303 |queue_run_max|Use: main|Type: integer|Default: 5|
14304 +-------------+---------+-------------+----------+
14306 This controls the maximum number of queue runner processes that an Exim daemon
14307 can run simultaneously. This does not mean that it starts them all at once, but
14308 rather that if the maximum number are still running when the time comes to
14309 start another one, it refrains from starting another one. This can happen with
14310 very large queues and/or very sluggish deliveries. This option does not,
14311 however, interlock with other processes, so additional queue runners can be
14312 started by other means, or by killing and restarting the daemon.
14314 Setting this option to zero does not suppress queue runs; rather, it disables
14315 the limit, allowing any number of simultaneous queue runner processes to be
14316 run. If you do not want queue runs to occur, omit the -qxx setting on the
14317 daemon's command line.
14319 +------------------+---------+------------------+--------------+
14320 |queue_smtp_domains|Use: main|Type: domain list*|Default: unset|
14321 +------------------+---------+------------------+--------------+
14323 When this option is set, a delivery process is started whenever a message is
14324 received, routing is performed, and local deliveries take place. However, if
14325 any SMTP deliveries are required for domains that match queue_smtp_domains,
14326 they are not immediately delivered, but instead the message waits on the queue
14327 for the next queue run. Since routing of the message has taken place, Exim
14328 knows to which remote hosts it must be delivered, and so when the queue run
14329 happens, multiple messages for the same host are delivered over a single SMTP
14330 connection. The -odqs command line option causes all SMTP deliveries to be
14331 queued in this way, and is equivalent to setting queue_smtp_domains to "*". See
14332 also hold_domains and queue_domains.
14334 +---------------+---------+----------+-----------+
14335 |receive_timeout|Use: main|Type: time|Default: 0s|
14336 +---------------+---------+----------+-----------+
14338 This option sets the timeout for accepting a non-SMTP message, that is, the
14339 maximum time that Exim waits when reading a message on the standard input. If
14340 the value is zero, it will wait for ever. This setting is overridden by the -or
14341 command line option. The timeout for incoming SMTP messages is controlled by
14342 smtp_receive_timeout.
14344 +--------------------+---------+-------------+------------------+
14345 |received_header_text|Use: main|Type: string*|Default: see below|
14346 +--------------------+---------+-------------+------------------+
14348 This string defines the contents of the Received: message header that is added
14349 to each message, except for the timestamp, which is automatically added on at
14350 the end (preceded by a semicolon). The string is expanded each time it is used.
14351 If the expansion yields an empty string, no Received: header line is added to
14352 the message. Otherwise, the string should start with the text "Received:" and
14353 conform to the RFC 2822 specification for Received: header lines. The default
14356 received_header_text = Received: \
14357 ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\
14358 {${if def:sender_ident \
14359 {from ${quote_local_part:$sender_ident} }}\
14360 ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
14361 by $primary_hostname \
14362 ${if def:received_protocol {with $received_protocol}} \
14363 ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\
14364 (Exim $version_number)\n\t\
14365 ${if def:sender_address \
14366 {(envelope-from <$sender_address>)\n\t}}\
14367 id $message_exim_id\
14368 ${if def:received_for {\n\tfor $received_for}}
14370 The reference to the TLS cipher is omitted when Exim is built without TLS
14371 support. The use of conditional expansions ensures that this works for both
14372 locally generated messages and messages received from remote hosts, giving
14373 header lines such as the following:
14375 Received: from scrooge.carol.example ([192.168.12.25] ident=root)
14376 by marley.carol.example with esmtp (Exim 4.00)
14377 (envelope-from <bob@carol.example>)
14378 id 16IOWa-00019l-00
14379 for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000
14380 Received: by scrooge.carol.example with local (Exim 4.00)
14381 id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000
14383 Until the body of the message has been received, the timestamp is the time when
14384 the message started to be received. Once the body has arrived, and all policy
14385 checks have taken place, the timestamp is updated to the time at which the
14386 message was accepted.
14388 +--------------------+---------+-------------+-----------+
14389 |received_headers_max|Use: main|Type: integer|Default: 30|
14390 +--------------------+---------+-------------+-----------+
14392 When a message is to be delivered, the number of Received: headers is counted,
14393 and if it is greater than this parameter, a mail loop is assumed to have
14394 occurred, the delivery is abandoned, and an error message is generated. This
14395 applies to both local and remote deliveries.
14397 +---------------------------+---------+----------------+--------------+
14398 |recipient_unqualified_hosts|Use: main|Type: host list*|Default: unset|
14399 +---------------------------+---------+----------------+--------------+
14401 This option lists those hosts from which Exim is prepared to accept unqualified
14402 recipient addresses in message envelopes. The addresses are made fully
14403 qualified by the addition of the qualify_recipient value. This option also
14404 affects message header lines. Exim does not reject unqualified recipient
14405 addresses in headers, but it qualifies them only if the message came from a
14406 host that matches recipient_unqualified_hosts, or if the message was submitted
14407 locally (not using TCP/IP), and the -bnq option was not set.
14409 +--------------+---------+-------------+----------+
14410 |recipients_max|Use: main|Type: integer|Default: 0|
14411 +--------------+---------+-------------+----------+
14413 If this option is set greater than zero, it specifies the maximum number of
14414 original recipients for any message. Additional recipients that are generated
14415 by aliasing or forwarding do not count. SMTP messages get a 452 response for
14416 all recipients over the limit; earlier recipients are delivered as normal.
14417 Non-SMTP messages with too many recipients are failed, and no deliveries are
14420 Note: The RFCs specify that an SMTP server should accept at least 100 RCPT
14421 commands in a single message.
14423 +---------------------+---------+-------------+--------------+
14424 |recipients_max_reject|Use: main|Type: boolean|Default: false|
14425 +---------------------+---------+-------------+--------------+
14427 If this option is set true, Exim rejects SMTP messages containing too many
14428 recipients by giving 552 errors to the surplus RCPT commands, and a 554 error
14429 to the eventual DATA command. Otherwise (the default) it gives a 452 error to
14430 the surplus RCPT commands and accepts the message on behalf of the initial set
14431 of recipients. The remote server should then re-send the message for the
14432 remaining recipients at a later time.
14434 +-------------------+---------+-------------+----------+
14435 |remote_max_parallel|Use: main|Type: integer|Default: 2|
14436 +-------------------+---------+-------------+----------+
14438 This option controls parallel delivery of one message to a number of remote
14439 hosts. If the value is less than 2, parallel delivery is disabled, and Exim
14440 does all the remote deliveries for a message one by one. Otherwise, if a single
14441 message has to be delivered to more than one remote host, or if several copies
14442 have to be sent to the same remote host, up to remote_max_parallel deliveries
14443 are done simultaneously. If more than remote_max_parallel deliveries are
14444 required, the maximum number of processes are started, and as each one
14445 finishes, another is begun. The order of starting processes is the same as if
14446 sequential delivery were being done, and can be controlled by the
14447 remote_sort_domains option. If parallel delivery takes place while running with
14448 debugging turned on, the debugging output from each delivery process is tagged
14449 with its process id.
14451 This option controls only the maximum number of parallel deliveries for one
14452 message in one Exim delivery process. Because Exim has no central queue
14453 manager, there is no way of controlling the total number of simultaneous
14454 deliveries if the configuration allows a delivery attempt as soon as a message
14457 If you want to control the total number of deliveries on the system, you need
14458 to set the queue_only option. This ensures that all incoming messages are added
14459 to the queue without starting a delivery process. Then set up an Exim daemon to
14460 start queue runner processes at appropriate intervals (probably fairly often,
14461 for example, every minute), and limit the total number of queue runners by
14462 setting the queue_run_max parameter. Because each queue runner delivers only
14463 one message at a time, the maximum number of deliveries that can then take
14464 place at once is queue_run_max multiplied by remote_max_parallel.
14466 If it is purely remote deliveries you want to control, use queue_smtp_domains
14467 instead of queue_only. This has the added benefit of doing the SMTP routing
14468 before queueing, so that several messages for the same host will eventually get
14469 delivered down the same connection.
14471 +-------------------+---------+------------------+--------------+
14472 |remote_sort_domains|Use: main|Type: domain list*|Default: unset|
14473 +-------------------+---------+------------------+--------------+
14475 When there are a number of remote deliveries for a message, they are sorted by
14476 domain into the order given by this list. For example,
14478 remote_sort_domains = *.cam.ac.uk:*.uk
14480 would attempt to deliver to all addresses in the cam.ac.uk domain first, then
14481 to those in the uk domain, then to any others.
14483 +-----------------+---------+----------+-----------+
14484 |retry_data_expire|Use: main|Type: time|Default: 7d|
14485 +-----------------+---------+----------+-----------+
14487 This option sets a "use before" time on retry information in Exim's hints
14488 database. Any older retry data is ignored. This means that, for example, once a
14489 host has not been tried for 7 days, Exim behaves as if it has no knowledge of
14492 +------------------+---------+----------+------------+
14493 |retry_interval_max|Use: main|Type: time|Default: 24h|
14494 +------------------+---------+----------+------------+
14496 Chapter 32 describes Exim's mechanisms for controlling the intervals between
14497 delivery attempts for messages that cannot be delivered straight away. This
14498 option sets an overall limit to the length of time between retries. It cannot
14499 be set greater than 24 hours; any attempt to do so forces the default value.
14501 +------------------+---------+-------------+-------------+
14502 |return_path_remove|Use: main|Type: boolean|Default: true|
14503 +------------------+---------+-------------+-------------+
14505 RFC 2821, section 4.4, states that an SMTP server must insert a Return-path:
14506 header line into a message when it makes a "final delivery". The Return-path:
14507 header preserves the sender address as received in the MAIL command. This
14508 description implies that this header should not be present in an incoming
14509 message. If return_path_remove is true, any existing Return-path: headers are
14510 removed from messages at the time they are received. Exim's transports have
14511 options for adding Return-path: headers at the time of delivery. They are
14512 normally used only for final local deliveries.
14514 +-----------------+---------+-------------+-------------+
14515 |return_size_limit|Use: main|Type: integer|Default: 100K|
14516 +-----------------+---------+-------------+-------------+
14518 This option is an obsolete synonym for bounce_return_size_limit.
14520 +-------------+---------+----------------+----------+
14521 |rfc1413_hosts|Use: main|Type: host list*|Default: *|
14522 +-------------+---------+----------------+----------+
14524 RFC 1413 identification calls are made to any client host which matches an item
14527 +---------------------+---------+----------+-----------+
14528 |rfc1413_query_timeout|Use: main|Type: time|Default: 5s|
14529 +---------------------+---------+----------+-----------+
14531 This sets the timeout on RFC 1413 identification calls. If it is set to zero,
14532 no RFC 1413 calls are ever made.
14534 +------------------------+---------+----------------+--------------+
14535 |sender_unqualified_hosts|Use: main|Type: host list*|Default: unset|
14536 +------------------------+---------+----------------+--------------+
14538 This option lists those hosts from which Exim is prepared to accept unqualified
14539 sender addresses. The addresses are made fully qualified by the addition of
14540 qualify_domain. This option also affects message header lines. Exim does not
14541 reject unqualified addresses in headers that contain sender addresses, but it
14542 qualifies them only if the message came from a host that matches
14543 sender_unqualified_hosts, or if the message was submitted locally (not using
14544 TCP/IP), and the -bnq option was not set.
14546 +---------------+---------+-----------------+--------------+
14547 |set_environment|Use: main|Type: string list|Default: empty|
14548 +---------------+---------+-----------------+--------------+
14550 This option allows to set individual environment variables that the currently
14551 linked libraries and programs in child processes use. The default list is
14554 +---------------------+---------+-------------+-------------+
14555 |smtp_accept_keepalive|Use: main|Type: boolean|Default: true|
14556 +---------------------+---------+-------------+-------------+
14558 This option controls the setting of the SO_KEEPALIVE option on incoming TCP/IP
14559 socket connections. When set, it causes the kernel to probe idle connections
14560 periodically, by sending packets with "old" sequence numbers. The other end of
14561 the connection should send an acknowledgment if the connection is still okay or
14562 a reset if the connection has been aborted. The reason for doing this is that
14563 it has the beneficial effect of freeing up certain types of connection that can
14564 get stuck when the remote host is disconnected without tidying up the TCP/IP
14565 call properly. The keepalive mechanism takes several hours to detect
14568 +---------------+---------+-------------+-----------+
14569 |smtp_accept_max|Use: main|Type: integer|Default: 20|
14570 +---------------+---------+-------------+-----------+
14572 This option specifies the maximum number of simultaneous incoming SMTP calls
14573 that Exim will accept. It applies only to the listening daemon; there is no
14574 control (in Exim) when incoming SMTP is being handled by inetd. If the value is
14575 set to zero, no limit is applied. However, it is required to be non-zero if
14576 either smtp_accept_max_per_host or smtp_accept_queue is set. See also
14577 smtp_accept_reserve and smtp_load_reserve.
14579 A new SMTP connection is immediately rejected if the smtp_accept_max limit has
14580 been reached. If not, Exim first checks smtp_accept_max_per_host. If that limit
14581 has not been reached for the client host, smtp_accept_reserve and
14582 smtp_load_reserve are then checked before accepting the connection.
14584 +-----------------------+---------+-------------+-----------+
14585 |smtp_accept_max_nonmail|Use: main|Type: integer|Default: 10|
14586 +-----------------------+---------+-------------+-----------+
14588 Exim counts the number of "non-mail" commands in an SMTP session, and drops the
14589 connection if there are too many. This option defines "too many". The check
14590 catches some denial-of-service attacks, repeated failing AUTHs, or a mad client
14591 looping sending EHLO, for example. The check is applied only if the client host
14592 matches smtp_accept_max_nonmail_hosts.
14594 When a new message is expected, one occurrence of RSET is not counted. This
14595 allows a client to send one RSET between messages (this is not necessary, but
14596 some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO,
14597 and one occurrence of STARTTLS between messages. After starting up a TLS
14598 session, another EHLO is expected, and so it too is not counted. The first
14599 occurrence of AUTH in a connection, or immediately following STARTTLS is not
14600 counted. Otherwise, all commands other than MAIL, RCPT, DATA, and QUIT are
14603 +-----------------------------+---------+----------------+----------+
14604 |smtp_accept_max_nonmail_hosts|Use: main|Type: host list*|Default: *|
14605 +-----------------------------+---------+----------------+----------+
14607 You can control which hosts are subject to the smtp_accept_max_nonmail check by
14608 setting this option. The default value makes it apply to all hosts. By changing
14609 the value, you can exclude any badly-behaved hosts that you have to live with.
14611 +------------------------------+---------+-------------+-------------+
14612 |smtp_accept_max_per_connection|Use: main|Type: integer|Default: 1000|
14613 +------------------------------+---------+-------------+-------------+
14615 The value of this option limits the number of MAIL commands that Exim is
14616 prepared to accept over a single SMTP connection, whether or not each command
14617 results in the transfer of a message. After the limit is reached, a 421
14618 response is given to subsequent MAIL commands. This limit is a safety
14619 precaution against a client that goes mad (incidents of this type have been
14622 +------------------------+---------+-------------+--------------+
14623 |smtp_accept_max_per_host|Use: main|Type: string*|Default: unset|
14624 +------------------------+---------+-------------+--------------+
14626 This option restricts the number of simultaneous IP connections from a single
14627 host (strictly, from a single IP address) to the Exim daemon. The option is
14628 expanded, to enable different limits to be applied to different hosts by
14629 reference to $sender_host_address. Once the limit is reached, additional
14630 connection attempts from the same host are rejected with error code 421. This
14631 is entirely independent of smtp_accept_reserve. The option's default value of
14632 zero imposes no limit. If this option is set greater than zero, it is required
14633 that smtp_accept_max be non-zero.
14635 Warning: When setting this option you should not use any expansion
14636 constructions that take an appreciable amount of time. The expansion and test
14637 happen in the main daemon loop, in order to reject additional connections
14638 without forking additional processes (otherwise a denial-of-service attack
14639 could cause a vast number or processes to be created). While the daemon is
14640 doing this processing, it cannot accept any other incoming connections.
14642 +-----------------+---------+-------------+----------+
14643 |smtp_accept_queue|Use: main|Type: integer|Default: 0|
14644 +-----------------+---------+-------------+----------+
14646 If the number of simultaneous incoming SMTP connections being handled via the
14647 listening daemon exceeds this value, messages received by SMTP are just placed
14648 on the queue; no delivery processes are started automatically. The count is
14649 fixed at the start of an SMTP connection. It cannot be updated in the
14650 subprocess that receives messages, and so the queueing or not queueing applies
14651 to all messages received in the same connection.
14653 A value of zero implies no limit, and clearly any non-zero value is useful only
14654 if it is less than the smtp_accept_max value (unless that is zero). See also
14655 queue_only, queue_only_load, queue_smtp_domains, and the various -odx command
14658 +--------------------------------+---------+-------------+-----------+
14659 |smtp_accept_queue_per_connection|Use: main|Type: integer|Default: 10|
14660 +--------------------------------+---------+-------------+-----------+
14662 This option limits the number of delivery processes that Exim starts
14663 automatically when receiving messages via SMTP, whether via the daemon or by
14664 the use of -bs or -bS. If the value of the option is greater than zero, and the
14665 number of messages received in a single SMTP session exceeds this number,
14666 subsequent messages are placed on the queue, but no delivery processes are
14667 started. This helps to limit the number of Exim processes when a server
14668 restarts after downtime and there is a lot of mail waiting for it on other
14669 systems. On large systems, the default should probably be increased, and on
14670 dial-in client systems it should probably be set to zero (that is, disabled).
14672 +-------------------+---------+-------------+----------+
14673 |smtp_accept_reserve|Use: main|Type: integer|Default: 0|
14674 +-------------------+---------+-------------+----------+
14676 When smtp_accept_max is set greater than zero, this option specifies a number
14677 of SMTP connections that are reserved for connections from the hosts that are
14678 specified in smtp_reserve_hosts. The value set in smtp_accept_max includes this
14679 reserve pool. The specified hosts are not restricted to this number of
14680 connections; the option specifies a minimum number of connection slots for
14681 them, not a maximum. It is a guarantee that this group of hosts can always get
14682 at least smtp_accept_reserve connections. However, the limit specified by
14683 smtp_accept_max_per_host is still applied to each individual host.
14685 For example, if smtp_accept_max is set to 50 and smtp_accept_reserve is set to
14686 5, once there are 45 active connections (from any hosts), new connections are
14687 accepted only from hosts listed in smtp_reserve_hosts, provided the other
14688 criteria for acceptance are met.
14690 +--------------------+---------+-------------+--------------+
14691 |smtp_active_hostname|Use: main|Type: string*|Default: unset|
14692 +--------------------+---------+-------------+--------------+
14694 This option is provided for multi-homed servers that want to masquerade as
14695 several different hosts. At the start of an incoming SMTP connection, its value
14696 is expanded and used instead of the value of $primary_hostname in SMTP
14697 responses. For example, it is used as domain name in the response to an
14698 incoming HELO or EHLO command.
14700 The active hostname is placed in the $smtp_active_hostname variable, which is
14701 saved with any messages that are received. It is therefore available for use in
14702 routers and transports when the message is later delivered.
14704 If this option is unset, or if its expansion is forced to fail, or if the
14705 expansion results in an empty string, the value of $primary_hostname is used.
14706 Other expansion failures cause a message to be written to the main and panic
14707 logs, and the SMTP command receives a temporary error. Typically, the value of
14708 smtp_active_hostname depends on the incoming interface address. For example:
14710 smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\
14711 {cox.mydomain}{box.mydomain}}
14713 Although $smtp_active_hostname is primarily concerned with incoming messages,
14714 it is also used as the default for HELO commands in callout verification if
14715 there is no remote transport from which to obtain a helo_data value.
14717 +-----------+---------+-------------+------------------+
14718 |smtp_banner|Use: main|Type: string*|Default: see below|
14719 +-----------+---------+-------------+------------------+
14721 This string, which is expanded every time it is used, is output as the initial
14722 positive response to an SMTP connection. The default setting is:
14724 smtp_banner = $smtp_active_hostname ESMTP Exim \
14725 $version_number $tod_full
14727 Failure to expand the string causes a panic error. If you want to create a
14728 multiline response to the initial SMTP connection, use "\n" in the string at
14729 appropriate points, but not at the end. Note that the 220 code is not included
14730 in this string. Exim adds it automatically (several times in the case of a
14731 multiline response).
14733 +----------------------+---------+-------------+-------------+
14734 |smtp_check_spool_space|Use: main|Type: boolean|Default: true|
14735 +----------------------+---------+-------------+-------------+
14737 When this option is set, if an incoming SMTP session encounters the SIZE option
14738 on a MAIL command, it checks that there is enough space in the spool
14739 directory's partition to accept a message of that size, while still leaving
14740 free the amount specified by check_spool_space (even if that value is zero). If
14741 there isn't enough space, a temporary error code is returned.
14743 +--------------------+---------+-------------+-----------+
14744 |smtp_connect_backlog|Use: main|Type: integer|Default: 20|
14745 +--------------------+---------+-------------+-----------+
14747 This option specifies a maximum number of waiting SMTP connections. Exim passes
14748 this value to the TCP/IP system when it sets up its listener. Once this number
14749 of connections are waiting for the daemon's attention, subsequent connection
14750 attempts are refused at the TCP/IP level. At least, that is what the manuals
14751 say; in some circumstances such connection attempts have been observed to time
14752 out instead. For large systems it is probably a good idea to increase the value
14753 (to 50, say). It also gives some protection against denial-of-service attacks
14756 +-----------------+---------+-------------+-------------+
14757 |smtp_enforce_sync|Use: main|Type: boolean|Default: true|
14758 +-----------------+---------+-------------+-------------+
14760 The SMTP protocol specification requires the client to wait for a response from
14761 the server at certain points in the dialogue. Without PIPELINING these
14762 synchronization points are after every command; with PIPELINING they are fewer,
14763 but they still exist.
14765 Some spamming sites send out a complete set of SMTP commands without waiting
14766 for any response. Exim protects against this by rejecting a message if the
14767 client has sent further input when it should not have. The error response "554
14768 SMTP synchronization error" is sent, and the connection is dropped. Testing for
14769 this error cannot be perfect because of transmission delays (unexpected input
14770 may be on its way but not yet received when Exim checks). However, it does
14771 detect many instances.
14773 The check can be globally disabled by setting smtp_enforce_sync false. If you
14774 want to disable the check selectively (for example, only for certain hosts),
14775 you can do so by an appropriate use of a control modifier in an ACL (see
14776 section 42.22). See also pipelining_advertise_hosts.
14778 +-----------------+---------+-------------+--------------+
14779 |smtp_etrn_command|Use: main|Type: string*|Default: unset|
14780 +-----------------+---------+-------------+--------------+
14782 If this option is set, the given command is run whenever an SMTP ETRN command
14783 is received from a host that is permitted to issue such commands (see chapter
14784 42). The string is split up into separate arguments which are independently
14785 expanded. The expansion variable $domain is set to the argument of the ETRN
14786 command, and no syntax checking is done on it. For example:
14788 smtp_etrn_command = /etc/etrn_command $domain \
14789 $sender_host_address
14791 A new process is created to run the command, but Exim does not wait for it to
14792 complete. Consequently, its status cannot be checked. If the command cannot be
14793 run, a line is written to the panic log, but the ETRN caller still receives a
14794 250 success response. Exim is normally running under its own uid when receiving
14795 SMTP, so it is not possible for it to change the uid before running the
14798 +-------------------+---------+-------------+-------------+
14799 |smtp_etrn_serialize|Use: main|Type: boolean|Default: true|
14800 +-------------------+---------+-------------+-------------+
14802 When this option is set, it prevents the simultaneous execution of more than
14803 one identical command as a result of ETRN in an SMTP connection. See section
14806 +-----------------+---------+-----------------+--------------+
14807 |smtp_load_reserve|Use: main|Type: fixed-point|Default: unset|
14808 +-----------------+---------+-----------------+--------------+
14810 If the system load average ever gets higher than this, incoming SMTP calls are
14811 accepted only from those hosts that match an entry in smtp_reserve_hosts. If
14812 smtp_reserve_hosts is not set, no incoming SMTP calls are accepted when the
14813 load is over the limit. The option has no effect on ancient operating systems
14814 on which Exim cannot determine the load average. See also
14815 deliver_queue_load_max and queue_only_load.
14817 +-----------------------+---------+-------------+----------+
14818 |smtp_max_synprot_errors|Use: main|Type: integer|Default: 3|
14819 +-----------------------+---------+-------------+----------+
14821 Exim rejects SMTP commands that contain syntax or protocol errors. In
14822 particular, a syntactically invalid email address, as in this command:
14824 RCPT TO:<abc xyz@a.b.c>
14826 causes immediate rejection of the command, before any other tests are done.
14827 (The ACL cannot be run if there is no valid address to set up for it.) An
14828 example of a protocol error is receiving RCPT before MAIL. If there are too
14829 many syntax or protocol errors in one SMTP session, the connection is dropped.
14830 The limit is set by this option.
14832 When the PIPELINING extension to SMTP is in use, some protocol errors are
14833 "expected", for instance, a RCPT command after a rejected MAIL command. Exim
14834 assumes that PIPELINING will be used if it advertises it (see
14835 pipelining_advertise_hosts), and in this situation, "expected" errors do not
14836 count towards the limit.
14838 +-------------------------+---------+-------------+----------+
14839 |smtp_max_unknown_commands|Use: main|Type: integer|Default: 3|
14840 +-------------------------+---------+-------------+----------+
14842 If there are too many unrecognized commands in an incoming SMTP session, an
14843 Exim server drops the connection. This is a defence against some kinds of abuse
14844 that subvert web clients into making connections to SMTP ports; in these
14845 circumstances, a number of non-SMTP command lines are sent first.
14847 +--------------------+---------+----------------+--------------+
14848 |smtp_ratelimit_hosts|Use: main|Type: host list*|Default: unset|
14849 +--------------------+---------+----------------+--------------+
14851 Some sites find it helpful to be able to limit the rate at which certain hosts
14852 can send them messages, and the rate at which an individual message can specify
14855 Exim has two rate-limiting facilities. This section describes the older
14856 facility, which can limit rates within a single connection. The newer ratelimit
14857 ACL condition can limit rates across all connections. See section 42.38 for
14858 details of the newer facility.
14860 When a host matches smtp_ratelimit_hosts, the values of smtp_ratelimit_mail and
14861 smtp_ratelimit_rcpt are used to control the rate of acceptance of MAIL and RCPT
14862 commands in a single SMTP session, respectively. Each option, if set, must
14863 contain a set of four comma-separated values:
14865 * A threshold, before which there is no rate limiting.
14867 * An initial time delay. Unlike other times in Exim, numbers with decimal
14868 fractional parts are allowed here.
14870 * A factor by which to increase the delay each time.
14872 * A maximum value for the delay. This should normally be less than 5 minutes,
14873 because after that time, the client is liable to timeout the SMTP command.
14875 For example, these settings have been used successfully at the site which first
14876 suggested this feature, for controlling mail from their customers:
14878 smtp_ratelimit_mail = 2,0.5s,1.05,4m
14879 smtp_ratelimit_rcpt = 4,0.25s,1.015,4m
14881 The first setting specifies delays that are applied to MAIL commands after two
14882 have been received over a single connection. The initial delay is 0.5 seconds,
14883 increasing by a factor of 1.05 each time. The second setting applies delays to
14884 RCPT commands when more than four occur in a single message.
14886 +-------------------+---------+------------+--------------+
14887 |smtp_ratelimit_mail|Use: main|Type: string|Default: unset|
14888 +-------------------+---------+------------+--------------+
14890 See smtp_ratelimit_hosts above.
14892 +-------------------+---------+------------+--------------+
14893 |smtp_ratelimit_rcpt|Use: main|Type: string|Default: unset|
14894 +-------------------+---------+------------+--------------+
14896 See smtp_ratelimit_hosts above.
14898 +--------------------+---------+----------+-----------+
14899 |smtp_receive_timeout|Use: main|Type: time|Default: 5m|
14900 +--------------------+---------+----------+-----------+
14902 This sets a timeout value for SMTP reception. It applies to all forms of SMTP
14903 input, including batch SMTP. If a line of input (either an SMTP command or a
14904 data line) is not received within this time, the SMTP connection is dropped and
14905 the message is abandoned. A line is written to the log containing one of the
14906 following messages:
14908 SMTP command timeout on connection from...
14909 SMTP data timeout on connection from...
14911 The former means that Exim was expecting to read an SMTP command; the latter
14912 means that it was in the DATA phase, reading the contents of a message.
14914 The value set by this option can be overridden by the -os command-line option.
14915 A setting of zero time disables the timeout, but this should never be used for
14916 SMTP over TCP/IP. (It can be useful in some cases of local input using -bs or
14917 -bS.) For non-SMTP input, the reception timeout is controlled by
14918 receive_timeout and -or.
14920 +------------------+---------+----------------+--------------+
14921 |smtp_reserve_hosts|Use: main|Type: host list*|Default: unset|
14922 +------------------+---------+----------------+--------------+
14924 This option defines hosts for which SMTP connections are reserved; see
14925 smtp_accept_reserve and smtp_load_reserve above.
14927 +-------------------------+---------+-------------+--------------+
14928 |smtp_return_error_details|Use: main|Type: boolean|Default: false|
14929 +-------------------------+---------+-------------+--------------+
14931 In the default state, Exim uses bland messages such as "Administrative
14932 prohibition" when it rejects SMTP commands for policy reasons. Many sysadmins
14933 like this because it gives away little information to spammers. However, some
14934 other sysadmins who are applying strict checking policies want to give out much
14935 fuller information about failures. Setting smtp_return_error_details true
14936 causes Exim to be more forthcoming. For example, instead of "Administrative
14937 prohibition", it might give:
14939 550-Rejected after DATA: '>' missing at end of address:
14940 550 failing address in "From" header is: <user@dom.ain
14942 +-------------+---------+------------+------------------+
14943 |spamd_address|Use: main|Type: string|Default: see below|
14944 +-------------+---------+------------+------------------+
14946 This option is available when Exim is compiled with the content-scanning
14947 extension. It specifies how Exim connects to SpamAssassin's spamd daemon. The
14952 See section 43.2 for more details.
14954 +---------------------+---------+-------------+--------------+
14955 |split_spool_directory|Use: main|Type: boolean|Default: false|
14956 +---------------------+---------+-------------+--------------+
14958 If this option is set, it causes Exim to split its input directory into 62
14959 subdirectories, each with a single alphanumeric character as its name. The
14960 sixth character of the message id is used to allocate messages to
14961 subdirectories; this is the least significant base-62 digit of the time of
14962 arrival of the message.
14964 Splitting up the spool in this way may provide better performance on systems
14965 where there are long mail queues, by reducing the number of files in any one
14966 directory. The msglog directory is also split up in a similar way to the input
14967 directory; however, if preserve_message_logs is set, all old msglog files are
14968 still placed in the single directory msglog.OLD.
14970 It is not necessary to take any special action for existing messages when
14971 changing split_spool_directory. Exim notices messages that are in the "wrong"
14972 place, and continues to process them. If the option is turned off after a
14973 period of being on, the subdirectories will eventually empty and be
14974 automatically deleted.
14976 When split_spool_directory is set, the behaviour of queue runner processes
14977 changes. Instead of creating a list of all messages in the queue, and then
14978 trying to deliver each one in turn, it constructs a list of those in one
14979 sub-directory and tries to deliver them, before moving on to the next
14980 sub-directory. The sub-directories are processed in a random order. This
14981 spreads out the scanning of the input directories, and uses less memory. It is
14982 particularly beneficial when there are lots of messages on the queue. However,
14983 if queue_run_in_order is set, none of this new processing happens. The entire
14984 queue has to be scanned and sorted before any deliveries can start.
14986 +---------------+---------+-------------+----------------------------+
14987 |spool_directory|Use: main|Type: string*|Default: set at compile time|
14988 +---------------+---------+-------------+----------------------------+
14990 This defines the directory in which Exim keeps its spool, that is, the messages
14991 it is waiting to deliver. The default value is taken from the compile-time
14992 configuration setting, if there is one. If not, this option must be set. The
14993 string is expanded, so it can contain, for example, a reference to
14996 If the spool directory name is fixed on your installation, it is recommended
14997 that you set it at build time rather than from this option, particularly if the
14998 log files are being written to the spool directory (see log_file_path).
14999 Otherwise log files cannot be used for errors that are detected early on, such
15000 as failures in the configuration file.
15002 By using this option to override the compiled-in path, it is possible to run
15003 tests of Exim without using the standard spool.
15005 +-------------------+---------+----------+-----------+
15006 |sqlite_lock_timeout|Use: main|Type: time|Default: 5s|
15007 +-------------------+---------+----------+-----------+
15009 This option controls the timeout that the sqlite lookup uses when trying to
15010 access an SQLite database. See section 9.25 for more details.
15012 +---------------+---------+-------------+--------------+
15013 |strict_acl_vars|Use: main|Type: boolean|Default: false|
15014 +---------------+---------+-------------+--------------+
15016 This option controls what happens if a syntactically valid but undefined ACL
15017 variable is referenced. If it is false (the default), an empty string is
15018 substituted; if it is true, an error is generated. See section 42.19 for
15019 details of ACL variables.
15021 +---------------------------+---------+-------------+--------------+
15022 |strip_excess_angle_brackets|Use: main|Type: boolean|Default: false|
15023 +---------------------------+---------+-------------+--------------+
15025 If this option is set, redundant pairs of angle brackets round "route-addr"
15026 items in addresses are stripped. For example, <<xxx@a.b.c.d>> is treated as
15027 <xxx@a.b.c.d>. If this is in the envelope and the message is passed on to
15028 another MTA, the excess angle brackets are not passed on. If this option is not
15029 set, multiple pairs of angle brackets cause a syntax error.
15031 +------------------+---------+-------------+--------------+
15032 |strip_trailing_dot|Use: main|Type: boolean|Default: false|
15033 +------------------+---------+-------------+--------------+
15035 If this option is set, a trailing dot at the end of a domain in an address is
15036 ignored. If this is in the envelope and the message is passed on to another
15037 MTA, the dot is not passed on. If this option is not set, a dot at the end of a
15038 domain causes a syntax error. However, addresses in header lines are checked
15039 only when an ACL requests header syntax checking.
15041 +------------------+---------+-------------+-------------+
15042 |syslog_duplication|Use: main|Type: boolean|Default: true|
15043 +------------------+---------+-------------+-------------+
15045 When Exim is logging to syslog, it writes the log lines for its three separate
15046 logs at different syslog priorities so that they can in principle be separated
15047 on the logging hosts. Some installations do not require this separation, and in
15048 those cases, the duplication of certain log lines is a nuisance. If
15049 syslog_duplication is set false, only one copy of any particular log line is
15050 written to syslog. For lines that normally go to both the main log and the
15051 reject log, the reject log version (possibly containing message header lines)
15052 is written, at LOG_NOTICE priority. Lines that normally go to both the main and
15053 the panic log are written at the LOG_ALERT priority.
15055 +---------------+---------+------------+--------------+
15056 |syslog_facility|Use: main|Type: string|Default: unset|
15057 +---------------+---------+------------+--------------+
15059 This option sets the syslog "facility" name, used when Exim is logging to
15060 syslog. The value must be one of the strings "mail", "user", "news", "uucp",
15061 "daemon", or "localx" where x is a digit between 0 and 7. If this option is
15062 unset, "mail" is used. See chapter 51 for details of Exim's logging.
15064 +------------------+---------+------------+---------------+
15065 |syslog_processname|Use: main|Type: string|Default: "exim"|
15066 +------------------+---------+------------+---------------+
15068 This option sets the syslog "ident" name, used when Exim is logging to syslog.
15069 The value must be no longer than 32 characters. See chapter 51 for details of
15072 +----------------+---------+-------------+-------------+
15073 |syslog_timestamp|Use: main|Type: boolean|Default: true|
15074 +----------------+---------+-------------+-------------+
15076 If syslog_timestamp is set false, the timestamps on Exim's log lines are
15077 omitted when these lines are sent to syslog. See chapter 51 for details of
15080 +-------------+---------+-------------+--------------+
15081 |system_filter|Use: main|Type: string*|Default: unset|
15082 +-------------+---------+-------------+--------------+
15084 This option specifies an Exim filter file that is applied to all messages at
15085 the start of each delivery attempt, before any routing is done. System filters
15086 must be Exim filters; they cannot be Sieve filters. If the system filter
15087 generates any deliveries to files or pipes, or any new mail messages, the
15088 appropriate system_filter_..._transport option(s) must be set, to define which
15089 transports are to be used. Details of this facility are given in chapter 45.
15091 +---------------------------------+---------+-------------+--------------+
15092 |system_filter_directory_transport|Use: main|Type: string*|Default: unset|
15093 +---------------------------------+---------+-------------+--------------+
15095 This sets the name of the transport driver that is to be used when the save
15096 command in a system message filter specifies a path ending in "/", implying
15097 delivery of each message into a separate file in some directory. During the
15098 delivery, the variable $address_file contains the path name.
15100 +----------------------------+---------+-------------+--------------+
15101 |system_filter_file_transport|Use: main|Type: string*|Default: unset|
15102 +----------------------------+---------+-------------+--------------+
15104 This sets the name of the transport driver that is to be used when the save
15105 command in a system message filter specifies a path not ending in "/". During
15106 the delivery, the variable $address_file contains the path name.
15108 +-------------------+---------+------------+--------------+
15109 |system_filter_group|Use: main|Type: string|Default: unset|
15110 +-------------------+---------+------------+--------------+
15112 This option is used only when system_filter_user is also set. It sets the gid
15113 under which the system filter is run, overriding any gid that is associated
15114 with the user. The value may be numerical or symbolic.
15116 +----------------------------+---------+-------------+--------------+
15117 |system_filter_pipe_transport|Use: main|Type: string*|Default: unset|
15118 +----------------------------+---------+-------------+--------------+
15120 This specifies the transport driver that is to be used when a pipe command is
15121 used in a system filter. During the delivery, the variable $address_pipe
15122 contains the pipe command.
15124 +-----------------------------+---------+-------------+--------------+
15125 |system_filter_reply_transport|Use: main|Type: string*|Default: unset|
15126 +-----------------------------+---------+-------------+--------------+
15128 This specifies the transport driver that is to be used when a mail command is
15129 used in a system filter.
15131 +------------------+---------+------------+--------------+
15132 |system_filter_user|Use: main|Type: string|Default: unset|
15133 +------------------+---------+------------+--------------+
15135 If this option is set to root, the system filter is run in the main Exim
15136 delivery process, as root. Otherwise, the system filter runs in a separate
15137 process, as the given user, defaulting to the Exim run-time user. Unless the
15138 string consists entirely of digits, it is looked up in the password data.
15139 Failure to find the named user causes a configuration error. The gid is either
15140 taken from the password data, or specified by system_filter_group. When the uid
15141 is specified numerically, system_filter_group is required to be set.
15143 If the system filter generates any pipe, file, or reply deliveries, the uid
15144 under which the filter is run is used when transporting them, unless a
15145 transport option overrides.
15147 +-----------+---------+-------------+-------------+
15148 |tcp_nodelay|Use: main|Type: boolean|Default: true|
15149 +-----------+---------+-------------+-------------+
15151 If this option is set false, it stops the Exim daemon setting the TCP_NODELAY
15152 option on its listening sockets. Setting TCP_NODELAY turns off the "Nagle
15153 algorithm", which is a way of improving network performance in interactive
15154 (character-by-character) situations. Turning it off should improve Exim's
15155 performance a bit, so that is what happens by default. However, it appears that
15156 some broken clients cannot cope, and time out. Hence this option. It affects
15157 only those sockets that are set up for listening by the daemon. Sockets created
15158 by the smtp transport for delivering mail always set TCP_NODELAY.
15160 +--------------------+---------+----------+-----------+
15161 |timeout_frozen_after|Use: main|Type: time|Default: 0s|
15162 +--------------------+---------+----------+-----------+
15164 If timeout_frozen_after is set to a time greater than zero, a frozen message of
15165 any kind that has been on the queue for longer than the given time is
15166 automatically cancelled at the next queue run. If the frozen message is a
15167 bounce message, it is just discarded; otherwise, a bounce is sent to the
15168 sender, in a similar manner to cancellation by the -Mg command line option. If
15169 you want to timeout frozen bounce messages earlier than other kinds of frozen
15170 message, see ignore_bounce_errors_after.
15172 Note: the default value of zero means no timeouts; with this setting, frozen
15173 messages remain on the queue forever (except for any frozen bounce messages
15174 that are released by ignore_bounce_errors_after).
15176 +--------+---------+------------+--------------+
15177 |timezone|Use: main|Type: string|Default: unset|
15178 +--------+---------+------------+--------------+
15180 The value of timezone is used to set the environment variable TZ while running
15181 Exim (if it is different on entry). This ensures that all timestamps created by
15182 Exim are in the required timezone. If you want all your timestamps to be in UTC
15183 (aka GMT) you should set
15187 The default value is taken from TIMEZONE_DEFAULT in Local/Makefile, or, if that
15188 is not set, from the value of the TZ environment variable when Exim is built.
15189 If timezone is set to the empty string, either at build or run time, any
15190 existing TZ variable is removed from the environment when Exim runs. This is
15191 appropriate behaviour for obtaining wall-clock time on some, but unfortunately
15192 not all, operating systems.
15194 +-------------------+---------+----------------+--------------+
15195 |tls_advertise_hosts|Use: main|Type: host list*|Default: unset|
15196 +-------------------+---------+----------------+--------------+
15198 When Exim is built with support for TLS encrypted connections, the availability
15199 of the STARTTLS command to set up an encrypted session is advertised in
15200 response to EHLO only to those client hosts that match this option. See chapter
15201 41 for details of Exim's support for TLS.
15203 +---------------+---------+-------------+--------------+
15204 |tls_certificate|Use: main|Type: string*|Default: unset|
15205 +---------------+---------+-------------+--------------+
15207 The value of this option is expanded, and must then be the absolute path to a
15208 file which contains the server's certificates. The server's private key is also
15209 assumed to be in this file if tls_privatekey is unset. See chapter 41 for
15212 Note: The certificates defined by this option are used only when Exim is
15213 receiving incoming messages as a server. If you want to supply certificates for
15214 use when sending messages as a client, you must set the tls_certificate option
15215 in the relevant smtp transport.
15217 If the option contains $tls_out_sni and Exim is built against OpenSSL, then if
15218 the OpenSSL build supports TLS extensions and the TLS client sends the Server
15219 Name Indication extension, then this option and others documented in 41.10 will
15222 +-------+---------+-------------+--------------+
15223 |tls_crl|Use: main|Type: string*|Default: unset|
15224 +-------+---------+-------------+--------------+
15226 This option specifies a certificate revocation list. The expanded value must be
15227 the name of a file that contains a CRL in PEM format.
15229 See 41.10 for discussion of when this option might be re-expanded.
15231 +---------------+---------+-------------+-------------+
15232 |tls_dh_max_bits|Use: main|Type: integer|Default: 2236|
15233 +---------------+---------+-------------+-------------+
15235 The number of bits used for Diffie-Hellman key-exchange may be suggested by the
15236 chosen TLS library. That value might prove to be too high for interoperability.
15237 This option provides a maximum clamp on the value suggested, trading off
15238 security for interoperability.
15240 The value must be at least 1024.
15242 The value 2236 was chosen because, at time of adding the option, it was the
15243 hard-coded maximum value supported by the NSS cryptographic library, as used by
15244 Thunderbird, while GnuTLS was suggesting 2432 bits as normal.
15246 If you prefer more security and are willing to break some clients, raise this
15249 Note that the value passed to GnuTLS for *generating* a new prime may be a
15250 little less than this figure, because GnuTLS is inexact and may produce a
15251 larger prime than requested.
15253 +-----------+---------+-------------+--------------+
15254 |tls_dhparam|Use: main|Type: string*|Default: unset|
15255 +-----------+---------+-------------+--------------+
15257 The value of this option is expanded and indicates the source of DH parameters
15258 to be used by Exim.
15260 If it is a filename starting with a "/", then it names a file from which DH
15261 parameters should be loaded. If the file exists, it should hold a PEM-encoded
15262 PKCS#3 representation of the DH prime. If the file does not exist, for OpenSSL
15263 it is an error. For GnuTLS, Exim will attempt to create the file and fill it
15264 with a generated DH prime. For OpenSSL, if the DH bit-count from loading the
15265 file is greater than tls_dh_max_bits then it will be ignored, and treated as
15266 though the tls_dhparam were set to "none".
15268 If this option expands to the string "none", then no DH parameters will be
15271 If this option expands to the string "historic" and Exim is using GnuTLS, then
15272 Exim will attempt to load a file from inside the spool directory. If the file
15273 does not exist, Exim will attempt to create it. See section 41.3 for further
15276 If Exim is using OpenSSL and this option is empty or unset, then Exim will load
15277 a default DH prime; the default is the 2048 bit prime described in section 2.2
15278 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which in
15279 IKE is assigned number 23.
15281 Otherwise, the option must expand to the name used by Exim for any of a number
15282 of DH primes specified in RFC 2409, RFC 3526 and RFC 5114. As names, Exim uses
15283 "ike" followed by the number used by IKE, of "default" which corresponds to
15286 The available primes are: "ike1", "ike2", "ike5", "ike14", "ike15", "ike16",
15287 "ike17", "ike18", "ike22", "ike23" (aka "default") and "ike24".
15289 Some of these will be too small to be accepted by clients. Some may be too
15290 large to be accepted by clients.
15292 The TLS protocol does not negotiate an acceptable size for this; clients tend
15293 to hard-drop connections if what is offered by the server is unacceptable,
15294 whether too large or too small, and there's no provision for the client to tell
15295 the server what these constraints are. Thus, as a server operator, you need to
15296 make an educated guess as to what is most likely to work for your userbase.
15298 Some known size constraints suggest that a bit-size in the range 2048 to 2236
15299 is most likely to maximise interoperability. The upper bound comes from
15300 applications using the Mozilla Network Security Services (NSS) library, which
15301 used to set its "DH_MAX_P_BITS" upper-bound to 2236. This affects many mail
15302 user agents (MUAs). The lower bound comes from Debian installs of Exim4 prior
15303 to the 4.80 release, as Debian used to patch Exim to raise the minimum
15304 acceptable bound from 1024 to 2048.
15306 +-------------+---------+-------------+--------------+
15307 |tls_ocsp_file|Use: main|Type: string*|Default: unset|
15308 +-------------+---------+-------------+--------------+
15310 This option must if set expand to the absolute path to a file which contains a
15311 current status proof for the server's certificate, as obtained from the
15312 Certificate Authority.
15314 +--------------------+---------+-----------------+--------------+
15315 |tls_on_connect_ports|Use: main|Type: string list|Default: unset|
15316 +--------------------+---------+-----------------+--------------+
15318 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
15319 operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately
15320 set up without waiting for the client to issue a STARTTLS command. For further
15321 details, see section 13.4.
15323 +--------------+---------+-------------+--------------+
15324 |tls_privatekey|Use: main|Type: string*|Default: unset|
15325 +--------------+---------+-------------+--------------+
15327 The value of this option is expanded, and must then be the absolute path to a
15328 file which contains the server's private key. If this option is unset, or if
15329 the expansion is forced to fail, or the result is an empty string, the private
15330 key is assumed to be in the same file as the server's certificates. See chapter
15331 41 for further details.
15333 See 41.10 for discussion of when this option might be re-expanded.
15335 +------------------+---------+-------------+--------------+
15336 |tls_remember_esmtp|Use: main|Type: boolean|Default: false|
15337 +------------------+---------+-------------+--------------+
15339 If this option is set true, Exim violates the RFCs by remembering that it is in
15340 "esmtp" state after successfully negotiating a TLS session. This provides
15341 support for broken clients that fail to send a new EHLO after starting a TLS
15344 +-------------------+---------+-------------+--------------+
15345 |tls_require_ciphers|Use: main|Type: string*|Default: unset|
15346 +-------------------+---------+-------------+--------------+
15348 This option controls which ciphers can be used for incoming TLS connections.
15349 The smtp transport has an option of the same name for controlling outgoing
15350 connections. This option is expanded for each connection, so can be varied for
15351 different clients if required. The value of this option must be a list of
15352 permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
15353 in somewhat different ways. If GnuTLS is being used, the client controls the
15354 preference order of the available ciphers. Details are given in sections 41.4
15357 +--------------------+---------+----------------+--------------+
15358 |tls_try_verify_hosts|Use: main|Type: host list*|Default: unset|
15359 +--------------------+---------+----------------+--------------+
15361 See tls_verify_hosts below.
15363 +-----------------------+---------+-------------+--------------+
15364 |tls_verify_certificates|Use: main|Type: string*|Default: unset|
15365 +-----------------------+---------+-------------+--------------+
15367 The value of this option is expanded, and must then be the absolute path to a
15368 file containing permitted certificates for clients that match tls_verify_hosts
15369 or tls_try_verify_hosts. Alternatively, if you are using OpenSSL, you can set
15370 tls_verify_certificates to the name of a directory containing certificate
15371 files. This does not work with GnuTLS; the option must be set to the name of a
15372 single file if you are using GnuTLS.
15374 These certificates should be for the certificate authorities trusted, rather
15375 than the public cert of individual clients. With both OpenSSL and GnuTLS, if
15376 the value is a file then the certificates are sent by Exim as a server to
15377 connecting clients, defining the list of accepted certificate authorities. Thus
15378 the values defined should be considered public data. To avoid this, use OpenSSL
15381 See 41.10 for discussion of when this option might be re-expanded.
15383 A forced expansion failure or setting to an empty string is equivalent to being
15386 +----------------+---------+----------------+--------------+
15387 |tls_verify_hosts|Use: main|Type: host list*|Default: unset|
15388 +----------------+---------+----------------+--------------+
15390 This option, along with tls_try_verify_hosts, controls the checking of
15391 certificates from clients. The expected certificates are defined by
15392 tls_verify_certificates, which must be set. A configuration error occurs if
15393 either tls_verify_hosts or tls_try_verify_hosts is set and
15394 tls_verify_certificates is not set.
15396 Any client that matches tls_verify_hosts is constrained by
15397 tls_verify_certificates. When the client initiates a TLS session, it must
15398 present one of the listed certificates. If it does not, the connection is
15399 aborted. Warning: Including a host in tls_verify_hosts does not require the
15400 host to use TLS. It can still send SMTP commands through unencrypted
15401 connections. Forcing a client to use TLS has to be done separately using an ACL
15402 to reject inappropriate commands when the connection is not encrypted.
15404 A weaker form of checking is provided by tls_try_verify_hosts. If a client
15405 matches this option (but not tls_verify_hosts), Exim requests a certificate and
15406 checks it against tls_verify_certificates, but does not abort the connection if
15407 there is no certificate or if it does not match. This state can be detected in
15408 an ACL, which makes it possible to implement policies such as "accept for relay
15409 only if a verified certificate has been received, but accept for local delivery
15410 if encrypted, even without a verified certificate".
15412 Client hosts that match neither of these lists are not asked to present
15415 +--------------+---------+------------------+--------------+
15416 |trusted_groups|Use: main|Type: string list*|Default: unset|
15417 +--------------+---------+------------------+--------------+
15419 This option is expanded just once, at the start of Exim's processing. If this
15420 option is set, any process that is running in one of the listed groups, or
15421 which has one of them as a supplementary group, is trusted. The groups can be
15422 specified numerically or by name. See section 5.2 for details of what trusted
15423 callers are permitted to do. If neither trusted_groups nor trusted_users is
15424 set, only root and the Exim user are trusted.
15426 +-------------+---------+------------------+--------------+
15427 |trusted_users|Use: main|Type: string list*|Default: unset|
15428 +-------------+---------+------------------+--------------+
15430 This option is expanded just once, at the start of Exim's processing. If this
15431 option is set, any process that is running as one of the listed users is
15432 trusted. The users can be specified numerically or by name. See section 5.2 for
15433 details of what trusted callers are permitted to do. If neither trusted_groups
15434 nor trusted_users is set, only root and the Exim user are trusted.
15436 +-------------+---------+-------------+--------------+
15437 |unknown_login|Use: main|Type: string*|Default: unset|
15438 +-------------+---------+-------------+--------------+
15440 This is a specialized feature for use in unusual configurations. By default, if
15441 the uid of the caller of Exim cannot be looked up using getpwuid(), Exim gives
15442 up. The unknown_login option can be used to set a login name to be used in this
15443 circumstance. It is expanded, so values like user$caller_uid can be set. When
15444 unknown_login is used, the value of unknown_username is used for the user's
15445 real name (gecos field), unless this has been set by the -F option.
15447 +----------------+---------+------------+--------------+
15448 |unknown_username|Use: main|Type: string|Default: unset|
15449 +----------------+---------+------------+--------------+
15453 +--------------------+---------+-------------------+--------------+
15454 |untrusted_set_sender|Use: main|Type: address list*|Default: unset|
15455 +--------------------+---------+-------------------+--------------+
15457 When an untrusted user submits a message to Exim using the standard input, Exim
15458 normally creates an envelope sender address from the user's login and the
15459 default qualification domain. Data from the -f option (for setting envelope
15460 senders on non-SMTP messages) or the SMTP MAIL command (if -bs or -bS is used)
15463 However, untrusted users are permitted to set an empty envelope sender address,
15464 to declare that a message should never generate any bounces. For example:
15466 exim -f '<>' user@domain.example
15468 The untrusted_set_sender option allows you to permit untrusted users to set
15469 other envelope sender addresses in a controlled way. When it is set, untrusted
15470 users are allowed to set envelope sender addresses that match any of the
15471 patterns in the list. Like all address lists, the string is expanded. The
15472 identity of the user is in $sender_ident, so you can, for example, restrict
15473 users to setting senders that start with their login ids followed by a hyphen
15474 by a setting like this:
15476 untrusted_set_sender = ^$sender_ident-
15478 If you want to allow untrusted users to set envelope sender addresses without
15479 restriction, you can use
15481 untrusted_set_sender = *
15483 The untrusted_set_sender option applies to all forms of local input, but only
15484 to the setting of the envelope sender. It does not permit untrusted users to
15485 use the other options which trusted user can use to override message
15486 parameters. Furthermore, it does not stop Exim from removing an existing
15487 Sender: header in the message, or from adding a Sender: header if necessary.
15488 See local_sender_retain and local_from_check for ways of overriding these
15489 actions. The handling of the Sender: header is also described in section 46.16.
15491 The log line for a message's arrival shows the envelope sender following "<=".
15492 For local messages, the user's login always follows, after "U=". In -bp
15493 displays, and in the Exim monitor, if an untrusted user sets an envelope sender
15494 address, the user's login is shown in parentheses after the sender address.
15496 +-----------------+---------+------------+------------------+
15497 |uucp_from_pattern|Use: main|Type: string|Default: see below|
15498 +-----------------+---------+------------+------------------+
15500 Some applications that pass messages to an MTA via a command line interface use
15501 an initial line starting with "From " to pass the envelope sender. In
15502 particular, this is used by UUCP software. Exim recognizes such a line by means
15503 of a regular expression that is set in uucp_from_pattern. When the pattern
15504 matches, the sender address is constructed by expanding the contents of
15505 uucp_from_sender, provided that the caller of Exim is a trusted user. The
15506 default pattern recognizes lines in the following two forms:
15508 From ph10 Fri Jan 5 12:35 GMT 1996
15509 From ph10 Fri, 7 Jan 97 14:00:00 GMT
15511 The pattern can be seen by running
15513 exim -bP uucp_from_pattern
15515 It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit
15516 year in the second case. The first word after "From " is matched in the regular
15517 expression by a parenthesized subpattern. The default value for
15518 uucp_from_sender is "$1", which therefore just uses this first word ("ph10" in
15519 the example above) as the message's sender. See also ignore_fromline_hosts.
15521 +----------------+---------+-------------+-------------+
15522 |uucp_from_sender|Use: main|Type: string*|Default: "$1"|
15523 +----------------+---------+-------------+-------------+
15525 See uucp_from_pattern above.
15527 +-----------------+---------+------------+--------------+
15528 |warn_message_file|Use: main|Type: string|Default: unset|
15529 +-----------------+---------+------------+--------------+
15531 This option defines a template file containing paragraphs of text to be used
15532 for constructing the warning message which is sent by Exim when a message has
15533 been on the queue for a specified amount of time, as specified by delay_warning
15534 . Details of the file's contents are given in chapter 48. See also
15535 bounce_message_file.
15537 +---------------+---------+-------------+-------------+
15538 |write_rejectlog|Use: main|Type: boolean|Default: true|
15539 +---------------+---------+-------------+-------------+
15541 If this option is set false, Exim no longer writes anything to the reject log.
15542 See chapter 51 for details of what Exim writes to its logs.
15546 ===============================================================================
15547 15. GENERIC OPTIONS FOR ROUTERS
15549 This chapter describes the generic options that apply to all routers. Those
15550 that are preconditions are marked with ** in the "use" field.
15552 For a general description of how a router operates, see sections 3.10 and 3.12.
15553 The latter specifies the order in which the preconditions are tested. The order
15554 of expansion of the options that provide data for a transport is: errors_to,
15555 headers_add, headers_remove, transport.
15557 +------------+------------+-------------+--------------+
15558 |address_data|Use: routers|Type: string*|Default: unset|
15559 +------------+------------+-------------+--------------+
15561 The string is expanded just before the router is run, that is, after all the
15562 precondition tests have succeeded. If the expansion is forced to fail, the
15563 router declines, the value of address_data remains unchanged, and the more
15564 option controls what happens next. Other expansion failures cause delivery of
15565 the address to be deferred.
15567 When the expansion succeeds, the value is retained with the address, and can be
15568 accessed using the variable $address_data in the current router, subsequent
15569 routers, and the eventual transport.
15571 Warning: If the current or any subsequent router is a redirect router that runs
15572 a user's filter file, the contents of $address_data are accessible in the
15573 filter. This is not normally a problem, because such data is usually either not
15574 confidential or it "belongs" to the current user, but if you do put
15575 confidential data into $address_data you need to remember this point.
15577 Even if the router declines or passes, the value of $address_data remains with
15578 the address, though it can be changed by another address_data setting on a
15579 subsequent router. If a router generates child addresses, the value of
15580 $address_data propagates to them. This also applies to the special kind of
15581 "child" that is generated by a router with the unseen option.
15583 The idea of address_data is that you can use it to look up a lot of data for
15584 the address once, and then pick out parts of the data later. For example, you
15585 could use a single LDAP lookup to return a string of the form
15587 uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
15589 In the transport you could pick out the mailbox by a setting such as
15591 file = ${extract{mailbox}{$address_data}}
15593 This makes the configuration file less messy, and also reduces the number of
15594 lookups (though Exim does cache lookups).
15596 The address_data facility is also useful as a means of passing information from
15597 one router to another, and from a router to a transport. In addition, if
15598 $address_data is set by a router when verifying a recipient address from an
15599 ACL, it remains available for use in the rest of the ACL statement. After
15600 verifying a sender, the value is transferred to $sender_address_data.
15602 +------------+--------------+-------------+-------------+
15603 |address_test|Use: routers**|Type: boolean|Default: true|
15604 +------------+--------------+-------------+-------------+
15606 If this option is set false, the router is skipped when routing is being tested
15607 by means of the -bt command line option. This can be a convenience when your
15608 first router sends messages to an external scanner, because it saves you having
15609 to set the "already scanned" indicator when testing real address routing.
15611 +--------------------+------------+-------------+--------------+
15612 |cannot_route_message|Use: routers|Type: string*|Default: unset|
15613 +--------------------+------------+-------------+--------------+
15615 This option specifies a text message that is used when an address cannot be
15616 routed because Exim has run out of routers. The default message is "Unrouteable
15617 address". This option is useful only on routers that have more set false, or on
15618 the very last router in a configuration, because the value that is used is
15619 taken from the last router that is considered. This includes a router that is
15620 skipped because its preconditions are not met, as well as a router that
15621 declines. For example, using the default configuration, you could put:
15623 cannot_route_message = Remote domain not found in DNS
15625 on the first router, which is a dnslookup router with more set false, and
15627 cannot_route_message = Unknown local user
15629 on the final router that checks for local users. If string expansion fails for
15630 this option, the default message is used. Unless the expansion failure was
15631 explicitly forced, a message about the failure is written to the main and panic
15632 logs, in addition to the normal message about the routing failure.
15634 +------------------+------------+-------------+--------------+
15635 |caseful_local_part|Use: routers|Type: boolean|Default: false|
15636 +------------------+------------+-------------+--------------+
15638 By default, routers handle the local parts of addresses in a case-insensitive
15639 manner, though the actual case is preserved for transmission with the message.
15640 If you want the case of letters to be significant in a router, you must set
15641 this option true. For individual router options that contain address or local
15642 part lists (for example, local_parts), case-sensitive matching can be turned on
15643 by "+caseful" as a list item. See section 10.20 for more details.
15645 The value of the $local_part variable is forced to lower case while a router is
15646 running unless caseful_local_part is set. When a router assigns an address to a
15647 transport, the value of $local_part when the transport runs is the same as it
15648 was in the router. Similarly, when a router generates child addresses by
15649 aliasing or forwarding, the values of $original_local_part and
15650 $parent_local_part are those that were used by the redirecting router.
15652 This option applies to the processing of an address by a router. When a
15653 recipient address is being processed in an ACL, there is a separate control
15654 modifier that can be used to specify case-sensitive processing within the ACL
15655 (see section 42.22).
15657 +----------------+--------------+-------------+--------------+
15658 |check_local_user|Use: routers**|Type: boolean|Default: false|
15659 +----------------+--------------+-------------+--------------+
15661 When this option is true, Exim checks that the local part of the recipient
15662 address (with affixes removed if relevant) is the name of an account on the
15663 local system. The check is done by calling the getpwnam() function rather than
15664 trying to read /etc/passwd directly. This means that other methods of holding
15665 password data (such as NIS) are supported. If the local part is a local user,
15666 $home is set from the password data, and can be tested in other preconditions
15667 that are evaluated after this one (the order of evaluation is given in section
15668 3.12). However, the value of $home can be overridden by router_home_directory.
15669 If the local part is not a local user, the router is skipped.
15671 If you want to check that the local part is either the name of a local user or
15672 matches something else, you cannot combine check_local_user with a setting of
15673 local_parts, because that specifies the logical and of the two conditions.
15674 However, you can use a passwd lookup in a local_parts setting to achieve this.
15677 local_parts = passwd;$local_part : lsearch;/etc/other/users
15679 Note, however, that the side effects of check_local_user (such as setting up a
15680 home directory) do not occur when a passwd lookup is used in a local_parts (or
15681 any other) precondition.
15683 +---------+--------------+-------------+--------------+
15684 |condition|Use: routers**|Type: string*|Default: unset|
15685 +---------+--------------+-------------+--------------+
15687 This option specifies a general precondition test that has to succeed for the
15688 router to be called. The condition option is the last precondition to be
15689 evaluated (see section 3.12). The string is expanded, and if the result is a
15690 forced failure, or an empty string, or one of the strings "0" or "no" or
15691 "false" (checked without regard to the case of the letters), the router is
15692 skipped, and the address is offered to the next one.
15694 If the result is any other value, the router is run (as this is the last
15695 precondition to be evaluated, all the other preconditions must be true).
15697 This option is unusual in that multiple condition options may be present. All
15698 condition options must succeed.
15700 The condition option provides a means of applying custom conditions to the
15701 running of routers. Note that in the case of a simple conditional expansion,
15702 the default expansion values are exactly what is wanted. For example:
15704 condition = ${if >{$message_age}{600}}
15706 Because of the default behaviour of the string expansion, this is equivalent to
15708 condition = ${if >{$message_age}{600}{true}{}}
15710 A multiple condition example, which succeeds:
15712 condition = ${if >{$message_age}{600}}
15713 condition = ${if !eq{${lc:$local_part}}{postmaster}}
15716 If the expansion fails (other than forced failure) delivery is deferred. Some
15717 of the other precondition options are common special cases that could in fact
15718 be specified using condition.
15720 +-----------+------------+-------------+--------------+
15721 |debug_print|Use: routers|Type: string*|Default: unset|
15722 +-----------+------------+-------------+--------------+
15724 If this option is set and debugging is enabled (see the -d command line option)
15725 or in address-testing mode (see the -bt command line option), the string is
15726 expanded and included in the debugging output. If expansion of the string
15727 fails, the error message is written to the debugging output, and Exim carries
15728 on processing. This option is provided to help with checking out the values of
15729 variables and so on when debugging router configurations. For example, if a
15730 condition option appears not to be working, debug_print can be used to output
15731 the variables it references. The output happens after checks for domains,
15732 local_parts, and check_local_user but before any other preconditions are
15733 tested. A newline is added to the text if it does not end with one. The
15734 variable $router_name contains the name of the router.
15736 +---------------+------------+-------------+--------------+
15737 |disable_logging|Use: routers|Type: boolean|Default: false|
15738 +---------------+------------+-------------+--------------+
15740 If this option is set true, nothing is logged for any routing errors or for any
15741 deliveries caused by this router. You should not set this option unless you
15742 really, really know what you are doing. See also the generic transport option
15745 +-------+--------------+------------------+--------------+
15746 |domains|Use: routers**|Type: domain list*|Default: unset|
15747 +-------+--------------+------------------+--------------+
15749 If this option is set, the router is skipped unless the current domain matches
15750 the list. If the match is achieved by means of a file lookup, the data that the
15751 lookup returned for the domain is placed in $domain_data for use in string
15752 expansions of the driver's private options. See section 3.12 for a list of the
15753 order in which preconditions are evaluated.
15755 +------+------------+------------+--------------+
15756 |driver|Use: routers|Type: string|Default: unset|
15757 +------+------------+------------+--------------+
15759 This option must always be set. It specifies which of the available routers is
15762 +---------+------------+-------------+--------------+
15763 |errors_to|Use: routers|Type: string*|Default: unset|
15764 +---------+------------+-------------+--------------+
15766 If a router successfully handles an address, it may assign the address to a
15767 transport for delivery or it may generate child addresses. In both cases, if
15768 there is a delivery problem during later processing, the resulting bounce
15769 message is sent to the address that results from expanding this string,
15770 provided that the address verifies successfully. The errors_to option is
15771 expanded before headers_add, headers_remove, and transport.
15773 The errors_to setting associated with an address can be overridden if it
15774 subsequently passes through other routers that have their own errors_to
15775 settings, or if the message is delivered by a transport with a return_path
15778 If errors_to is unset, or the expansion is forced to fail, or the result of the
15779 expansion fails to verify, the errors address associated with the incoming
15780 address is used. At top level, this is the envelope sender. A non-forced
15781 expansion failure causes delivery to be deferred.
15783 If an address for which errors_to has been set ends up being delivered over
15784 SMTP, the envelope sender for that delivery is the errors_to value, so that any
15785 bounces that are generated by other MTAs on the delivery route are also sent
15786 there. You can set errors_to to the empty string by either of these settings:
15791 An expansion item that yields an empty string has the same effect. If you do
15792 this, a locally detected delivery error for addresses processed by this router
15793 no longer gives rise to a bounce message; the error is discarded. If the
15794 address is delivered to a remote host, the return path is set to "<>", unless
15795 overridden by the return_path option on the transport.
15797 If for some reason you want to discard local errors, but use a non-empty MAIL
15798 command for remote delivery, you can preserve the original return path in
15799 $address_data in the router, and reinstate it in the transport by setting
15802 The most common use of errors_to is to direct mailing list bounces to the
15803 manager of the list, as described in section 49.2, or to implement VERP
15804 (Variable Envelope Return Paths) (see section 49.6).
15806 +----+--------------+-------------+-------------+
15807 |expn|Use: routers**|Type: boolean|Default: true|
15808 +----+--------------+-------------+-------------+
15810 If this option is turned off, the router is skipped when testing an address as
15811 a result of processing an SMTP EXPN command. You might, for example, want to
15812 turn it off on a router for users' .forward files, while leaving it on for the
15813 system alias file. See section 3.12 for a list of the order in which
15814 preconditions are evaluated.
15816 The use of the SMTP EXPN command is controlled by an ACL (see chapter 42). When
15817 Exim is running an EXPN command, it is similar to testing an address with -bt.
15818 Compare VRFY, whose counterpart is -bv.
15820 +-----------+------------+-------------+--------------+
15821 |fail_verify|Use: routers|Type: boolean|Default: false|
15822 +-----------+------------+-------------+--------------+
15824 Setting this option has the effect of setting both fail_verify_sender and
15825 fail_verify_recipient to the same value.
15827 +---------------------+------------+-------------+--------------+
15828 |fail_verify_recipient|Use: routers|Type: boolean|Default: false|
15829 +---------------------+------------+-------------+--------------+
15831 If this option is true and an address is accepted by this router when verifying
15832 a recipient, verification fails.
15834 +------------------+------------+-------------+--------------+
15835 |fail_verify_sender|Use: routers|Type: boolean|Default: false|
15836 +------------------+------------+-------------+--------------+
15838 If this option is true and an address is accepted by this router when verifying
15839 a sender, verification fails.
15841 +--------------+------------+-----------------+--------------+
15842 |fallback_hosts|Use: routers|Type: string list|Default: unset|
15843 +--------------+------------+-----------------+--------------+
15845 String expansion is not applied to this option. The argument must be a
15846 colon-separated list of host names or IP addresses. The list separator can be
15847 changed (see section 6.19), and a port can be specified with each name or
15848 address. In fact, the format of each item is exactly the same as defined for
15849 the list of hosts in a manualroute router (see section 20.5).
15851 If a router queues an address for a remote transport, this host list is
15852 associated with the address, and used instead of the transport's fallback host
15853 list. If hosts_randomize is set on the transport, the order of the list is
15854 randomized for each use. See the fallback_hosts option of the smtp transport
15855 for further details.
15857 +-----+------------+-------------+------------------+
15858 |group|Use: routers|Type: string*|Default: see below|
15859 +-----+------------+-------------+------------------+
15861 When a router queues an address for a transport, and the transport does not
15862 specify a group, the group given here is used when running the delivery
15863 process. The group may be specified numerically or by name. If expansion fails,
15864 the error is logged and delivery is deferred. The default is unset, unless
15865 check_local_user is set, when the default is taken from the password
15866 information. See also initgroups and user and the discussion in chapter 23.
15868 +-----------+------------+-----------+--------------+
15869 |headers_add|Use: routers|Type: list*|Default: unset|
15870 +-----------+------------+-----------+--------------+
15872 This option specifies a list of text headers, newline-separated, that is
15873 associated with any addresses that are accepted by the router. Each item is
15874 separately expanded, at routing time. However, this option has no effect when
15875 an address is just being verified. The way in which the text is used to add
15876 header lines at transport time is described in section 46.17. New header lines
15877 are not actually added until the message is in the process of being
15878 transported. This means that references to header lines in string expansions in
15879 the transport's configuration do not "see" the added header lines.
15881 The headers_add option is expanded after errors_to, but before headers_remove
15882 and transport. If an item is empty, or if an item expansion is forced to fail,
15883 the item has no effect. Other expansion failures are treated as configuration
15886 Unlike most options, headers_add can be specified multiple times for a router;
15887 all listed headers are added.
15889 Warning 1: The headers_add option cannot be used for a redirect router that has
15890 the one_time option set.
15892 Warning 2: If the unseen option is set on the router, all header additions are
15893 deleted when the address is passed on to subsequent routers. For a redirect
15894 router, if a generated address is the same as the incoming address, this can
15895 lead to duplicate addresses with different header modifications. Exim does not
15896 do duplicate deliveries (except, in certain circumstances, to pipes -- see
15897 section 22.7), but it is undefined which of the duplicates is discarded, so
15898 this ambiguous situation should be avoided. The repeat_use option of the
15899 redirect router may be of help.
15901 +--------------+------------+-----------+--------------+
15902 |headers_remove|Use: routers|Type: list*|Default: unset|
15903 +--------------+------------+-----------+--------------+
15905 This option specifies a list of text headers, colon-separated, that is
15906 associated with any addresses that are accepted by the router. Each item is
15907 separately expanded, at routing time. However, this option has no effect when
15908 an address is just being verified. The way in which the text is used to remove
15909 header lines at transport time is described in section 46.17. Header lines are
15910 not actually removed until the message is in the process of being transported.
15911 This means that references to header lines in string expansions in the
15912 transport's configuration still "see" the original header lines.
15914 The headers_remove option is expanded after errors_to and headers_add, but
15915 before transport. If an item expansion is forced to fail, the item has no
15916 effect. Other expansion failures are treated as configuration errors.
15918 Unlike most options, headers_remove can be specified multiple times for a
15919 router; all listed headers are removed.
15921 Warning 1: The headers_remove option cannot be used for a redirect router that
15922 has the one_time option set.
15924 Warning 2: If the unseen option is set on the router, all header removal
15925 requests are deleted when the address is passed on to subsequent routers, and
15926 this can lead to problems with duplicates -- see the similar warning for
15929 +-------------------+------------+----------------+--------------+
15930 |ignore_target_hosts|Use: routers|Type: host list*|Default: unset|
15931 +-------------------+------------+----------------+--------------+
15933 Although this option is a host list, it should normally contain IP address
15934 entries rather than names. If any host that is looked up by the router has an
15935 IP address that matches an item in this list, Exim behaves as if that IP
15936 address did not exist. This option allows you to cope with rogue DNS entries
15939 remote.domain.example. A 127.0.0.1
15943 ignore_target_hosts = 127.0.0.1
15945 on the relevant router. If all the hosts found by a dnslookup router are
15946 discarded in this way, the router declines. In a conventional configuration, an
15947 attempt to mail to such a domain would normally provoke the "unrouteable
15948 domain" error, and an attempt to verify an address in the domain would fail.
15949 Similarly, if ignore_target_hosts is set on an ipliteral router, the router
15950 declines if presented with one of the listed addresses.
15952 You can use this option to disable the use of IPv4 or IPv6 for mail delivery by
15953 means of the first or the second of the following settings, respectively:
15955 ignore_target_hosts = 0.0.0.0/0
15956 ignore_target_hosts = <; 0::0/0
15958 The pattern in the first line matches all IPv4 addresses, whereas the pattern
15959 in the second line matches all IPv6 addresses.
15961 This option may also be useful for ignoring link-local and site-local IPv6
15962 addresses. Because, like all host lists, the value of ignore_target_hosts is
15963 expanded before use as a list, it is possible to make it dependent on the
15964 domain that is being routed.
15966 During its expansion, $host_address is set to the IP address that is being
15969 +----------+------------+-------------+--------------+
15970 |initgroups|Use: routers|Type: boolean|Default: false|
15971 +----------+------------+-------------+--------------+
15973 If the router queues an address for a transport, and this option is true, and
15974 the uid supplied by the router is not overridden by the transport, the
15975 initgroups() function is called when running the transport to ensure that any
15976 additional groups associated with the uid are set up. See also group and user
15977 and the discussion in chapter 23.
15979 +-----------------+--------------+-----------------+--------------+
15980 |local_part_prefix|Use: routers**|Type: string list|Default: unset|
15981 +-----------------+--------------+-----------------+--------------+
15983 If this option is set, the router is skipped unless the local part starts with
15984 one of the given strings, or local_part_prefix_optional is true. See section
15985 3.12 for a list of the order in which preconditions are evaluated.
15987 The list is scanned from left to right, and the first prefix that matches is
15988 used. A limited form of wildcard is available; if the prefix begins with an
15989 asterisk, it matches the longest possible sequence of arbitrary characters at
15990 the start of the local part. An asterisk should therefore always be followed by
15991 some character that does not occur in normal local parts. Wildcarding can be
15992 used to set up multiple user mailboxes, as described in section 49.8.
15994 During the testing of the local_parts option, and while the router is running,
15995 the prefix is removed from the local part, and is available in the expansion
15996 variable $local_part_prefix. When a message is being delivered, if the router
15997 accepts the address, this remains true during subsequent delivery by a
15998 transport. In particular, the local part that is transmitted in the RCPT
15999 command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default.
16000 This behaviour can be overridden by setting rcpt_include_affixes true on the
16001 relevant transport.
16003 When an address is being verified, local_part_prefix affects only the behaviour
16004 of the router. If the callout feature of verification is in use, this means
16005 that the full address, including the prefix, will be used during the callout.
16007 The prefix facility is commonly used to handle local parts of the form
16008 owner-something. Another common use is to support local parts of the form
16009 real-username to bypass a user's .forward file - helpful when trying to tell a
16010 user their forwarding is broken - by placing a router like this one immediately
16011 before the router that handles .forward files:
16015 local_part_prefix = real-
16017 transport = local_delivery
16019 For security, it would probably be a good idea to restrict the use of this
16020 router to locally-generated messages, using a condition such as this:
16022 condition = ${if match {$sender_host_address}\
16023 {\N^(|127\.0\.0\.1)$\N}}
16025 If both local_part_prefix and local_part_suffix are set for a router, both
16026 conditions must be met if not optional. Care must be taken if wildcards are
16027 used in both a prefix and a suffix on the same router. Different separator
16028 characters must be used to avoid ambiguity.
16030 +--------------------------+------------+-------------+--------------+
16031 |local_part_prefix_optional|Use: routers|Type: boolean|Default: false|
16032 +--------------------------+------------+-------------+--------------+
16034 See local_part_prefix above.
16036 +-----------------+--------------+-----------------+--------------+
16037 |local_part_suffix|Use: routers**|Type: string list|Default: unset|
16038 +-----------------+--------------+-----------------+--------------+
16040 This option operates in the same way as local_part_prefix, except that the
16041 local part must end (rather than start) with the given string, the
16042 local_part_suffix_optional option determines whether the suffix is mandatory,
16043 and the wildcard * character, if present, must be the last character of the
16044 suffix. This option facility is commonly used to handle local parts of the form
16045 something-request and multiple user mailboxes of the form username-foo.
16047 +--------------------------+------------+-------------+--------------+
16048 |local_part_suffix_optional|Use: routers|Type: boolean|Default: false|
16049 +--------------------------+------------+-------------+--------------+
16051 See local_part_suffix above.
16053 +-----------+--------------+----------------------+--------------+
16054 |local_parts|Use: routers**|Type: local part list*|Default: unset|
16055 +-----------+--------------+----------------------+--------------+
16057 The router is run only if the local part of the address matches the list. See
16058 section 3.12 for a list of the order in which preconditions are evaluated, and
16059 section 10.21 for a discussion of local part lists. Because the string is
16060 expanded, it is possible to make it depend on the domain, for example:
16062 local_parts = dbm;/usr/local/specials/$domain
16064 If the match is achieved by a lookup, the data that the lookup returned for the
16065 local part is placed in the variable $local_part_data for use in expansions of
16066 the router's private options. You might use this option, for example, if you
16067 have a large number of local virtual domains, and you want to send all
16068 postmaster mail to the same place without having to set up an alias in each
16073 local_parts = postmaster
16074 data = postmaster@real.domain.example
16076 +------------+------------+-------------+------------------+
16077 |log_as_local|Use: routers|Type: boolean|Default: see below|
16078 +------------+------------+-------------+------------------+
16080 Exim has two logging styles for delivery, the idea being to make local
16081 deliveries stand out more visibly from remote ones. In the "local" style, the
16082 recipient address is given just as the local part, without a domain. The use of
16083 this style is controlled by this option. It defaults to true for the accept
16084 router, and false for all the others. This option applies only when a router
16085 assigns an address to a transport. It has no effect on routers that redirect
16088 +----+------------+--------------+-------------+
16089 |more|Use: routers|Type: boolean*|Default: true|
16090 +----+------------+--------------+-------------+
16092 The result of string expansion for this option must be a valid boolean value,
16093 that is, one of the strings "yes", "no", "true", or "false". Any other result
16094 causes an error, and delivery is deferred. If the expansion is forced to fail,
16095 the default value for the option (true) is used. Other failures cause delivery
16098 If this option is set false, and the router declines to handle the address, no
16099 further routers are tried, routing fails, and the address is bounced. However,
16100 if the router explicitly passes an address to the following router by means of
16105 or otherwise, the setting of more is ignored. Also, the setting of more does
16106 not affect the behaviour if one of the precondition tests fails. In that case,
16107 the address is always passed to the next router.
16109 Note that address_data is not considered to be a precondition. If its expansion
16110 is forced to fail, the router declines, and the value of more controls what
16113 +---------------+------------+-------------+--------------+
16114 |pass_on_timeout|Use: routers|Type: boolean|Default: false|
16115 +---------------+------------+-------------+--------------+
16117 If a router times out during a host lookup, it normally causes deferral of the
16118 address. If pass_on_timeout is set, the address is passed on to the next
16119 router, overriding no_more. This may be helpful for systems that are
16120 intermittently connected to the Internet, or those that want to pass to a smart
16121 host any messages that cannot immediately be delivered.
16123 There are occasional other temporary errors that can occur while doing DNS
16124 lookups. They are treated in the same way as a timeout, and this option applies
16127 +-----------+------------+------------+--------------+
16128 |pass_router|Use: routers|Type: string|Default: unset|
16129 +-----------+------------+------------+--------------+
16131 Routers that recognize the generic self option (dnslookup, ipliteral, and
16132 manualroute) are able to return "pass", forcing routing to continue, and
16133 overriding a false setting of more. When one of these routers returns "pass",
16134 the address is normally handed on to the next router in sequence. This can be
16135 changed by setting pass_router to the name of another router. However (unlike
16136 redirect_router) the named router must be below the current router, to avoid
16137 loops. Note that this option applies only to the special case of "pass". It
16138 does not apply when a router returns "decline" because it cannot handle an
16141 +---------------+------------+------------+--------------+
16142 |redirect_router|Use: routers|Type: string|Default: unset|
16143 +---------------+------------+------------+--------------+
16145 Sometimes an administrator knows that it is pointless to reprocess addresses
16146 generated from alias or forward files with the same router again. For example,
16147 if an alias file translates real names into login ids there is no point
16148 searching the alias file a second time, especially if it is a large file.
16150 The redirect_router option can be set to the name of any router instance. It
16151 causes the routing of any generated addresses to start at the named router
16152 instead of at the first router. This option has no effect if the router in
16153 which it is set does not generate new addresses.
16155 +-------------+--------------+------------------+--------------+
16156 |require_files|Use: routers**|Type: string list*|Default: unset|
16157 +-------------+--------------+------------------+--------------+
16159 This option provides a general mechanism for predicating the running of a
16160 router on the existence or non-existence of certain files or directories.
16161 Before running a router, as one of its precondition tests, Exim works its way
16162 through the require_files list, expanding each item separately.
16164 Because the list is split before expansion, any colons in expansion items must
16165 be doubled, or the facility for using a different list separator must be used.
16166 If any expansion is forced to fail, the item is ignored. Other expansion
16167 failures cause routing of the address to be deferred.
16169 If any expanded string is empty, it is ignored. Otherwise, except as described
16170 below, each string must be a fully qualified file path, optionally preceded by
16171 "!". The paths are passed to the stat() function to test for the existence of
16172 the files or directories. The router is skipped if any paths not preceded by "!
16173 " do not exist, or if any paths preceded by "!" do exist.
16175 If stat() cannot determine whether a file exists or not, delivery of the
16176 message is deferred. This can happen when NFS-mounted filesystems are
16179 This option is checked after the domains, local_parts, and senders options, so
16180 you cannot use it to check for the existence of a file in which to look up a
16181 domain, local part, or sender. (See section 3.12 for a full list of the order
16182 in which preconditions are evaluated.) However, as these options are all
16183 expanded, you can use the exists expansion condition to make such tests. The
16184 require_files option is intended for checking files that the router may be
16185 going to use internally, or which are needed by a transport (for example
16188 During delivery, the stat() function is run as root, but there is a facility
16189 for some checking of the accessibility of a file by another user. This is not a
16190 proper permissions check, but just a "rough" check that operates as follows:
16192 If an item in a require_files list does not contain any forward slash
16193 characters, it is taken to be the user (and optional group, separated by a
16194 comma) to be checked for subsequent files in the list. If no group is specified
16195 but the user is specified symbolically, the gid associated with the uid is
16198 require_files = mail:/some/file
16199 require_files = $local_part:$home/.procmailrc
16201 If a user or group name in a require_files list does not exist, the
16202 require_files condition fails.
16204 Exim performs the check by scanning along the components of the file path, and
16205 checking the access for the given uid and gid. It checks for "x" access on
16206 directories, and "r" access on the final file. Note that this means that file
16207 access control lists, if the operating system has them, are ignored.
16209 Warning 1: When the router is being run to verify addresses for an incoming
16210 SMTP message, Exim is not running as root, but under its own uid. This may
16211 affect the result of a require_files check. In particular, stat() may yield the
16212 error EACCES ("Permission denied"). This means that the Exim user is not
16213 permitted to read one of the directories on the file's path.
16215 Warning 2: Even when Exim is running as root while delivering a message, stat()
16216 can yield EACCES for a file in an NFS directory that is mounted without root
16217 access. In this case, if a check for access by a particular user is requested,
16218 Exim creates a subprocess that runs as that user, and tries the check again in
16221 The default action for handling an unresolved EACCES is to consider it to be
16222 caused by a configuration error, and routing is deferred because the existence
16223 or non-existence of the file cannot be determined. However, in some
16224 circumstances it may be desirable to treat this condition as if the file did
16225 not exist. If the file name (or the exclamation mark that precedes the file
16226 name for non-existence) is preceded by a plus sign, the EACCES error is treated
16227 as if the file did not exist. For example:
16229 require_files = +/some/file
16231 If the router is not an essential part of verification (for example, it handles
16232 users' .forward files), another solution is to set the verify option false so
16233 that the router is skipped when verifying.
16235 +--------------------+------------+-------------+------------------+
16236 |retry_use_local_part|Use: routers|Type: boolean|Default: see below|
16237 +--------------------+------------+-------------+------------------+
16239 When a delivery suffers a temporary routing failure, a retry record is created
16240 in Exim's hints database. For addresses whose routing depends only on the
16241 domain, the key for the retry record should not involve the local part, but for
16242 other addresses, both the domain and the local part should be included.
16243 Usually, remote routing is of the former kind, and local routing is of the
16246 This option controls whether the local part is used to form the key for retry
16247 hints for addresses that suffer temporary errors while being handled by this
16248 router. The default value is true for any router that has check_local_user set,
16249 and false otherwise. Note that this option does not apply to hints keys for
16250 transport delays; they are controlled by a generic transport option of the same
16253 The setting of retry_use_local_part applies only to the router on which it
16254 appears. If the router generates child addresses, they are routed
16255 independently; this setting does not become attached to them.
16257 +---------------------+------------+-------------+--------------+
16258 |router_home_directory|Use: routers|Type: string*|Default: unset|
16259 +---------------------+------------+-------------+--------------+
16261 This option sets a home directory for use while the router is running. (Compare
16262 transport_home_directory, which sets a home directory for later transporting.)
16263 In particular, if used on a redirect router, this option sets a value for $home
16264 while a filter is running. The value is expanded; forced expansion failure
16265 causes the option to be ignored - other failures cause the router to defer.
16267 Expansion of router_home_directory happens immediately after the
16268 check_local_user test (if configured), before any further expansions take
16269 place. (See section 3.12 for a list of the order in which preconditions are
16270 evaluated.) While the router is running, router_home_directory overrides the
16271 value of $home that came from check_local_user.
16273 When a router accepts an address and assigns it to a local transport (including
16274 the cases when a redirect router generates a pipe, file, or autoreply
16275 delivery), the home directory setting for the transport is taken from the first
16276 of these values that is set:
16278 * The home_directory option on the transport;
16280 * The transport_home_directory option on the router;
16282 * The password data if check_local_user is set on the router;
16284 * The router_home_directory option on the router.
16286 In other words, router_home_directory overrides the password data for the
16287 router, but not for the transport.
16289 +----+------------+------------+---------------+
16290 |self|Use: routers|Type: string|Default: freeze|
16291 +----+------------+------------+---------------+
16293 This option applies to those routers that use a recipient address to find a
16294 list of remote hosts. Currently, these are the dnslookup, ipliteral, and
16295 manualroute routers. Certain configurations of the queryprogram router can also
16296 specify a list of remote hosts. Usually such routers are configured to send the
16297 message to a remote host via an smtp transport. The self option specifies what
16298 happens when the first host on the list turns out to be the local host. The way
16299 in which Exim checks for the local host is described in section 13.8.
16301 Normally this situation indicates either an error in Exim's configuration (for
16302 example, the router should be configured not to process this domain), or an
16303 error in the DNS (for example, the MX should not point to this host). For this
16304 reason, the default action is to log the incident, defer the address, and
16305 freeze the message. The following alternatives are provided for use in special
16310 Delivery of the message is tried again later, but the message is not
16315 The domain is changed to the given domain, and the address is passed back
16316 to be reprocessed by the routers. No rewriting of headers takes place. This
16317 behaviour is essentially a redirection.
16319 reroute: rewrite: <domain>
16321 The domain is changed to the given domain, and the address is passed back
16322 to be reprocessed by the routers. Any headers that contain the original
16323 domain are rewritten.
16327 The router passes the address to the next router, or to the router named in
16328 the pass_router option if it is set. This overrides no_more. During
16329 subsequent routing and delivery, the variable $self_hostname contains the
16330 name of the local host that the router encountered. This can be used to
16331 distinguish between different cases for hosts with multiple names. The
16337 ensures that only those addresses that routed to the local host are passed
16338 on. Without no_more, addresses that were declined for other reasons would
16339 also be passed to the next router.
16343 Delivery fails and an error report is generated.
16347 The anomaly is ignored and the address is queued for the transport. This
16348 setting should be used with extreme caution. For an smtp transport, it
16349 makes sense only in cases where the program that is listening on the SMTP
16350 port is not this version of Exim. That is, it must be some other MTA, or
16351 Exim with a different configuration file that handles the domain in another
16354 +-------+--------------+-------------------+--------------+
16355 |senders|Use: routers**|Type: address list*|Default: unset|
16356 +-------+--------------+-------------------+--------------+
16358 If this option is set, the router is skipped unless the message's sender
16359 address matches something on the list. See section 3.12 for a list of the order
16360 in which preconditions are evaluated.
16362 There are issues concerning verification when the running of routers is
16363 dependent on the sender. When Exim is verifying the address in an errors_to
16364 setting, it sets the sender to the null string. When using the -bt option to
16365 check a configuration file, it is necessary also to use the -f option to set an
16366 appropriate sender. For incoming mail, the sender is unset when verifying the
16367 sender, but is available when verifying any recipients. If the SMTP VRFY
16368 command is enabled, it must be used after MAIL if the sender address matters.
16370 +--------------------+------------+-------------+--------------+
16371 |translate_ip_address|Use: routers|Type: string*|Default: unset|
16372 +--------------------+------------+-------------+--------------+
16374 There exist some rare networking situations (for example, packet radio) where
16375 it is helpful to be able to translate IP addresses generated by normal routing
16376 mechanisms into other IP addresses, thus performing a kind of manual IP
16377 routing. This should be done only if the normal IP routing of the TCP/IP stack
16378 is inadequate or broken. Because this is an extremely uncommon requirement, the
16379 code to support this option is not included in the Exim binary unless
16380 SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in Local/Makefile.
16382 The translate_ip_address string is expanded for every IP address generated by
16383 the router, with the generated address set in $host_address. If the expansion
16384 is forced to fail, no action is taken. For any other expansion error, delivery
16385 of the message is deferred. If the result of the expansion is an IP address,
16386 that replaces the original address; otherwise the result is assumed to be a
16387 host name - this is looked up using gethostbyname() (or getipnodebyname() when
16388 available) to produce one or more replacement IP addresses. For example, to
16389 subvert all IP addresses in some specific networks, this could be added to a
16392 translate_ip_address = \
16393 ${lookup{${mask:$host_address/26}}lsearch{/some/file}\
16396 The file would contain lines like
16398 10.2.3.128/26 some.host
16399 10.8.4.34/26 10.44.8.15
16401 You should not make use of this facility unless you really understand what you
16404 +---------+------------+-------------+--------------+
16405 |transport|Use: routers|Type: string*|Default: unset|
16406 +---------+------------+-------------+--------------+
16408 This option specifies the transport to be used when a router accepts an address
16409 and sets it up for delivery. A transport is never needed if a router is used
16410 only for verification. The value of the option is expanded at routing time,
16411 after the expansion of errors_to, headers_add, and headers_remove, and result
16412 must be the name of one of the configured transports. If it is not, delivery is
16415 The transport option is not used by the redirect router, but it does have some
16416 private options that set up transports for pipe and file deliveries (see
16419 +---------------------------+------------+-------------+--------------+
16420 |transport_current_directory|Use: routers|Type: string*|Default: unset|
16421 +---------------------------+------------+-------------+--------------+
16423 This option associates a current directory with any address that is routed to a
16424 local transport. This can happen either because a transport is explicitly
16425 configured for the router, or because it generates a delivery to a file or a
16426 pipe. During the delivery process (that is, at transport time), this option
16427 string is expanded and is set as the current directory, unless overridden by a
16428 setting on the transport. If the expansion fails for any reason, including
16429 forced failure, an error is logged, and delivery is deferred. See chapter 23
16430 for details of the local delivery environment.
16432 +------------------------+------------+-------------+------------------+
16433 |transport_home_directory|Use: routers|Type: string*|Default: see below|
16434 +------------------------+------------+-------------+------------------+
16436 This option associates a home directory with any address that is routed to a
16437 local transport. This can happen either because a transport is explicitly
16438 configured for the router, or because it generates a delivery to a file or a
16439 pipe. During the delivery process (that is, at transport time), the option
16440 string is expanded and is set as the home directory, unless overridden by a
16441 setting of home_directory on the transport. If the expansion fails for any
16442 reason, including forced failure, an error is logged, and delivery is deferred.
16444 If the transport does not specify a home directory, and
16445 transport_home_directory is not set for the router, the home directory for the
16446 transport is taken from the password data if check_local_user is set for the
16447 router. Otherwise it is taken from router_home_directory if that option is set;
16448 if not, no home directory is set for the transport.
16450 See chapter 23 for further details of the local delivery environment.
16452 +------+------------+--------------+--------------+
16453 |unseen|Use: routers|Type: boolean*|Default: false|
16454 +------+------------+--------------+--------------+
16456 The result of string expansion for this option must be a valid boolean value,
16457 that is, one of the strings "yes", "no", "true", or "false". Any other result
16458 causes an error, and delivery is deferred. If the expansion is forced to fail,
16459 the default value for the option (false) is used. Other failures cause delivery
16462 When this option is set true, routing does not cease if the router accepts the
16463 address. Instead, a copy of the incoming address is passed to the next router,
16464 overriding a false setting of more. There is little point in setting more false
16465 if unseen is always true, but it may be useful in cases when the value of
16466 unseen contains expansion items (and therefore, presumably, is sometimes true
16467 and sometimes false).
16469 Setting the unseen option has a similar effect to the unseen command qualifier
16470 in filter files. It can be used to cause copies of messages to be delivered to
16471 some other destination, while also carrying out a normal delivery. In effect,
16472 the current address is made into a "parent" that has two children - one that is
16473 delivered as specified by this router, and a clone that goes on to be routed
16474 further. For this reason, unseen may not be combined with the one_time option
16475 in a redirect router.
16477 Warning: Header lines added to the address (or specified for removal) by this
16478 router or by previous routers affect the "unseen" copy of the message only. The
16479 clone that continues to be processed by further routers starts with no added
16480 headers and none specified for removal. For a redirect router, if a generated
16481 address is the same as the incoming address, this can lead to duplicate
16482 addresses with different header modifications. Exim does not do duplicate
16483 deliveries (except, in certain circumstances, to pipes -- see section 22.7),
16484 but it is undefined which of the duplicates is discarded, so this ambiguous
16485 situation should be avoided. The repeat_use option of the redirect router may
16488 Unlike the handling of header modifications, any data that was set by the
16489 address_data option in the current or previous routers is passed on to
16490 subsequent routers.
16492 +----+------------+-------------+------------------+
16493 |user|Use: routers|Type: string*|Default: see below|
16494 +----+------------+-------------+------------------+
16496 When a router queues an address for a transport, and the transport does not
16497 specify a user, the user given here is used when running the delivery process.
16498 The user may be specified numerically or by name. If expansion fails, the error
16499 is logged and delivery is deferred. This user is also used by the redirect
16500 router when running a filter file. The default is unset, except when
16501 check_local_user is set. In this case, the default is taken from the password
16502 information. If the user is specified as a name, and group is not set, the
16503 group associated with the user is used. See also initgroups and group and the
16504 discussion in chapter 23.
16506 +------+--------------+-------------+-------------+
16507 |verify|Use: routers**|Type: boolean|Default: true|
16508 +------+--------------+-------------+-------------+
16510 Setting this option has the effect of setting verify_sender and
16511 verify_recipient to the same value.
16513 +-----------+--------------+-------------+--------------+
16514 |verify_only|Use: routers**|Type: boolean|Default: false|
16515 +-----------+--------------+-------------+--------------+
16517 If this option is set, the router is used only when verifying an address,
16518 delivering in cutthrough mode or testing with the -bv option, not when actually
16519 doing a delivery, testing with the -bt option, or running the SMTP EXPN
16520 command. It can be further restricted to verifying only senders or recipients
16521 by means of verify_sender and verify_recipient.
16523 Warning: When the router is being run to verify addresses for an incoming SMTP
16524 message, Exim is not running as root, but under its own uid. If the router
16525 accesses any files, you need to make sure that they are accessible to the Exim
16528 +----------------+--------------+-------------+-------------+
16529 |verify_recipient|Use: routers**|Type: boolean|Default: true|
16530 +----------------+--------------+-------------+-------------+
16532 If this option is false, the router is skipped when verifying recipient
16533 addresses, delivering in cutthrough mode or testing recipient verification
16534 using -bv. See section 3.12 for a list of the order in which preconditions are
16537 +-------------+--------------+-------------+-------------+
16538 |verify_sender|Use: routers**|Type: boolean|Default: true|
16539 +-------------+--------------+-------------+-------------+
16541 If this option is false, the router is skipped when verifying sender addresses
16542 or testing sender verification using -bvs. See section 3.12 for a list of the
16543 order in which preconditions are evaluated.
16547 ===============================================================================
16548 16. THE ACCEPT ROUTER
16550 The accept router has no private options of its own. Unless it is being used
16551 purely for verification (see verify_only) a transport is required to be defined
16552 by the generic transport option. If the preconditions that are specified by
16553 generic options are met, the router accepts the address and queues it for the
16554 given transport. The most common use of this router is for setting up
16555 deliveries to local mailboxes. For example:
16559 domains = mydomain.example
16561 transport = local_delivery
16563 The domains condition in this example checks the domain of the address, and
16564 check_local_user checks that the local part is the login of a local user. When
16565 both preconditions are met, the accept router runs, and queues the address for
16566 the local_delivery transport.
16570 ===============================================================================
16571 17. THE DNSLOOKUP ROUTER
16573 The dnslookup router looks up the hosts that handle mail for the recipient's
16574 domain in the DNS. A transport must always be set for this router, unless
16575 verify_only is set.
16577 If SRV support is configured (see check_srv below), Exim first searches for SRV
16578 records. If none are found, or if SRV support is not configured, MX records are
16579 looked up. If no MX records exist, address records are sought. However,
16580 mx_domains can be set to disable the direct use of address records.
16582 MX records of equal priority are sorted by Exim into a random order. Exim then
16583 looks for address records for the host names obtained from MX or SRV records.
16584 When a host has more than one IP address, they are sorted into a random order,
16585 except that IPv6 addresses are always sorted before IPv4 addresses. If all the
16586 IP addresses found are discarded by a setting of the ignore_target_hosts
16587 generic option, the router declines.
16589 Unless they have the highest priority (lowest MX value), MX records that point
16590 to the local host, or to any host name that matches hosts_treat_as_local, are
16591 discarded, together with any other MX records of equal or lower priority.
16593 If the host pointed to by the highest priority MX record, or looked up as an
16594 address record, is the local host, or matches hosts_treat_as_local, what
16595 happens is controlled by the generic self option.
16598 17.1 Problems with DNS lookups
16599 ------------------------------
16601 There have been problems with DNS servers when SRV records are looked up. Some
16602 mis-behaving servers return a DNS error or timeout when a non-existent SRV
16603 record is sought. Similar problems have in the past been reported for MX
16604 records. The global dns_again_means_nonexist option can help with this problem,
16605 but it is heavy-handed because it is a global option.
16607 For this reason, there are two options, srv_fail_domains and mx_fail_domains,
16608 that control what happens when a DNS lookup in a dnslookup router results in a
16609 DNS failure or a "try again" response. If an attempt to look up an SRV or MX
16610 record causes one of these results, and the domain matches the relevant list,
16611 Exim behaves as if the DNS had responded "no such record". In the case of an
16612 SRV lookup, this means that the router proceeds to look for MX records; in the
16613 case of an MX lookup, it proceeds to look for A or AAAA records, unless the
16614 domain matches mx_domains, in which case routing fails.
16617 17.2 Declining addresses by dnslookup
16618 -------------------------------------
16620 There are a few cases where a dnslookup router will decline to accept an
16621 address; if such a router is expected to handle "all remaining non-local
16622 domains", then it is important to set no_more.
16624 Reasons for a dnslookup router to decline currently include:
16626 * The domain does not exist in DNS
16628 * The domain exists but the MX record's host part is just "."; this is a
16629 common convention (borrowed from SRV) used to indicate that there is no
16630 such service for this domain and to not fall back to trying A/AAAA records.
16632 * Ditto, but for SRV records, when check_srv is set on this router.
16634 * MX record points to a non-existent host.
16636 * MX record points to an IP address and the main section option
16637 allow_mx_to_ip is not set.
16639 * MX records exist and point to valid hosts, but all hosts resolve only to
16640 addresses blocked by the ignore_target_hosts generic option on this router.
16642 * The domain is not syntactically valid (see also allow_utf8_domains and
16643 dns_check_names_pattern for handling one variant of this)
16645 * check_secondary_mx is set on this router but the local host can not be
16646 found in the MX records (see below)
16649 17.3 Private options for dnslookup
16650 ----------------------------------
16652 The private options for the dnslookup router are as follows:
16654 +------------------+--------------+-------------+--------------+
16655 |check_secondary_mx|Use: dnslookup|Type: boolean|Default: false|
16656 +------------------+--------------+-------------+--------------+
16658 If this option is set, the router declines unless the local host is found in
16659 (and removed from) the list of hosts obtained by MX lookup. This can be used to
16660 process domains for which the local host is a secondary mail exchanger
16661 differently to other domains. The way in which Exim decides whether a host is
16662 the local host is described in section 13.8.
16664 +---------+--------------+-------------+--------------+
16665 |check_srv|Use: dnslookup|Type: string*|Default: unset|
16666 +---------+--------------+-------------+--------------+
16668 The dnslookup router supports the use of SRV records (see RFC 2782) in addition
16669 to MX and address records. The support is disabled by default. To enable SRV
16670 support, set the check_srv option to the name of the service required. For
16675 looks for SRV records that refer to the normal smtp service. The option is
16676 expanded, so the service name can vary from message to message or address to
16677 address. This might be helpful if SRV records are being used for a submission
16678 service. If the expansion is forced to fail, the check_srv option is ignored,
16679 and the router proceeds to look for MX records in the normal way.
16681 When the expansion succeeds, the router searches first for SRV records for the
16682 given service (it assumes TCP protocol). A single SRV record with a host name
16683 that consists of just a single dot indicates "no such service for this domain";
16684 if this is encountered, the router declines. If other kinds of SRV record are
16685 found, they are used to construct a host list for delivery according to the
16686 rules of RFC 2782. MX records are not sought in this case.
16688 When no SRV records are found, MX records (and address records) are sought in
16689 the traditional way. In other words, SRV records take precedence over MX
16690 records, just as MX records take precedence over address records. Note that
16691 this behaviour is not sanctioned by RFC 2782, though a previous draft RFC
16692 defined it. It is apparently believed that MX records are sufficient for email
16693 and that SRV records should not be used for this purpose. However, SRV records
16694 have an additional "weight" feature which some people might find useful when
16695 trying to split an SMTP load between hosts of different power.
16697 See section 17.1 above for a discussion of Exim's behaviour when there is a DNS
16700 +----------------------+--------------+------------------+--------------+
16701 |dnssec_request_domains|Use: dnslookup|Type: domain list*|Default: unset|
16702 +----------------------+--------------+------------------+--------------+
16704 DNS lookups for domains matching dnssec_request_domains will be done with the
16705 dnssec request bit set. This applies to all of the SRV, MX A6, AAAA, A lookup
16708 +----------------------+--------------+------------------+--------------+
16709 |dnssec_require_domains|Use: dnslookup|Type: domain list*|Default: unset|
16710 +----------------------+--------------+------------------+--------------+
16712 DNS lookups for domains matching dnssec_request_domains will be done with the
16713 dnssec request bit set. Any returns not having the Authenticated Data bit (AD
16714 bit) set wil be ignored and logged as a host-lookup failure. This applies to
16715 all of the SRV, MX A6, AAAA, A lookup sequence.
16717 +----------+--------------+------------------+--------------+
16718 |mx_domains|Use: dnslookup|Type: domain list*|Default: unset|
16719 +----------+--------------+------------------+--------------+
16721 A domain that matches mx_domains is required to have either an MX or an SRV
16722 record in order to be recognized. (The name of this option could be improved.)
16723 For example, if all the mail hosts in fict.example are known to have MX
16724 records, except for those in discworld.fict.example, you could use this
16727 mx_domains = ! *.discworld.fict.example : *.fict.example
16729 This specifies that messages addressed to a domain that matches the list but
16730 has no MX record should be bounced immediately instead of being routed using
16731 the address record.
16733 +---------------+--------------+------------------+--------------+
16734 |mx_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
16735 +---------------+--------------+------------------+--------------+
16737 If the DNS lookup for MX records for one of the domains in this list causes a
16738 DNS lookup error, Exim behaves as if no MX records were found. See section 17.1
16739 for more discussion.
16741 +--------------+--------------+-------------+-------------+
16742 |qualify_single|Use: dnslookup|Type: boolean|Default: true|
16743 +--------------+--------------+-------------+-------------+
16745 When this option is true, the resolver option RES_DEFNAMES is set for DNS
16746 lookups. Typically, but not standardly, this causes the resolver to qualify
16747 single-component names with the default domain. For example, on a machine
16748 called dictionary.ref.example, the domain thesaurus would be changed to
16749 thesaurus.ref.example inside the resolver. For details of what your resolver
16750 actually does, consult your man pages for resolver and resolv.conf.
16752 +---------------+--------------+-------------+-------------+
16753 |rewrite_headers|Use: dnslookup|Type: boolean|Default: true|
16754 +---------------+--------------+-------------+-------------+
16756 If the domain name in the address that is being processed is not fully
16757 qualified, it may be expanded to its full form by a DNS lookup. For example, if
16758 an address is specified as dormouse@teaparty, the domain might be expanded to
16759 teaparty.wonderland.fict.example. Domain expansion can also occur as a result
16760 of setting the widen_domains option. If rewrite_headers is true, all
16761 occurrences of the abbreviated domain name in any Bcc:, Cc:, From:, Reply-to:,
16762 Sender:, and To: header lines of the message are rewritten with the full domain
16765 This option should be turned off only when it is known that no message is ever
16766 going to be sent outside an environment where the abbreviation makes sense.
16768 When an MX record is looked up in the DNS and matches a wildcard record, name
16769 servers normally return a record containing the name that has been looked up,
16770 making it impossible to detect whether a wildcard was present or not. However,
16771 some name servers have recently been seen to return the wildcard entry. If the
16772 name returned by a DNS lookup begins with an asterisk, it is not used for
16775 +------------------------+--------------+-------------+--------------+
16776 |same_domain_copy_routing|Use: dnslookup|Type: boolean|Default: false|
16777 +------------------------+--------------+-------------+--------------+
16779 Addresses with the same domain are normally routed by the dnslookup router to
16780 the same list of hosts. However, this cannot be presumed, because the router
16781 options and preconditions may refer to the local part of the address. By
16782 default, therefore, Exim routes each address in a message independently. DNS
16783 servers run caches, so repeated DNS lookups are not normally expensive, and in
16784 any case, personal messages rarely have more than a few recipients.
16786 If you are running mailing lists with large numbers of subscribers at the same
16787 domain, and you are using a dnslookup router which is independent of the local
16788 part, you can set same_domain_copy_routing to bypass repeated DNS lookups for
16789 identical domains in one message. In this case, when dnslookup routes an
16790 address to a remote transport, any other unrouted addresses in the message that
16791 have the same domain are automatically given the same routing without
16792 processing them independently, provided the following conditions are met:
16794 * No router that processed the address specified headers_add or
16797 * The router did not change the address in any way, for example, by
16798 "widening" the domain.
16800 +--------------+--------------+-------------+--------------+
16801 |search_parents|Use: dnslookup|Type: boolean|Default: false|
16802 +--------------+--------------+-------------+--------------+
16804 When this option is true, the resolver option RES_DNSRCH is set for DNS
16805 lookups. This is different from the qualify_single option in that it applies to
16806 domains containing dots. Typically, but not standardly, it causes the resolver
16807 to search for the name in the current domain and in parent domains. For
16808 example, on a machine in the fict.example domain, if looking up
16809 teaparty.wonderland failed, the resolver would try
16810 teaparty.wonderland.fict.example. For details of what your resolver actually
16811 does, consult your man pages for resolver and resolv.conf.
16813 Setting this option true can cause problems in domains that have a wildcard MX
16814 record, because any domain that does not have its own MX record matches the
16817 +----------------+--------------+------------------+--------------+
16818 |srv_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
16819 +----------------+--------------+------------------+--------------+
16821 If the DNS lookup for SRV records for one of the domains in this list causes a
16822 DNS lookup error, Exim behaves as if no SRV records were found. See section
16823 17.1 for more discussion.
16825 +-------------+--------------+-----------------+--------------+
16826 |widen_domains|Use: dnslookup|Type: string list|Default: unset|
16827 +-------------+--------------+-----------------+--------------+
16829 If a DNS lookup fails and this option is set, each of its strings in turn is
16830 added onto the end of the domain, and the lookup is tried again. For example,
16833 widen_domains = fict.example:ref.example
16835 is set and a lookup of klingon.dictionary fails,
16836 klingon.dictionary.fict.example is looked up, and if this fails,
16837 klingon.dictionary.ref.example is tried. Note that the qualify_single and
16838 search_parents options can cause some widening to be undertaken inside the DNS
16839 resolver. widen_domains is not applied to sender addresses when verifying,
16840 unless rewrite_headers is false (not the default).
16843 17.4 Effect of qualify_single and search_parents
16844 ------------------------------------------------
16846 When a domain from an envelope recipient is changed by the resolver as a result
16847 of the qualify_single or search_parents options, Exim rewrites the
16848 corresponding address in the message's header lines unless rewrite_headers is
16849 set false. Exim then re-routes the address, using the full domain.
16851 These two options affect only the DNS lookup that takes place inside the router
16852 for the domain of the address that is being routed. They do not affect lookups
16853 such as that implied by
16857 that may happen while processing a router precondition before the router is
16858 entered. No widening ever takes place for these lookups.
16862 ===============================================================================
16863 18. THE IPLITERAL ROUTER
16865 This router has no private options. Unless it is being used purely for
16866 verification (see verify_only) a transport is required to be defined by the
16867 generic transport option. The router accepts the address if its domain part
16868 takes the form of an RFC 2822 domain literal. For example, the ipliteral router
16869 handles the address
16873 by setting up delivery to the host with that IP address. IPv4 domain literals
16874 consist of an IPv4 address enclosed in square brackets. IPv6 domain literals
16875 are similar, but the address is preceded by "ipv6:". For example:
16877 postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678]
16879 Exim allows "ipv4:" before IPv4 addresses, for consistency, and on the grounds
16880 that sooner or later somebody will try it.
16882 If the IP address matches something in ignore_target_hosts, the router
16883 declines. If an IP literal turns out to refer to the local host, the generic
16884 self option determines what happens.
16886 The RFCs require support for domain literals; however, their use is
16887 controversial in today's Internet. If you want to use this router, you must
16888 also set the main configuration option allow_domain_literals. Otherwise, Exim
16889 will not recognize the domain literal syntax in addresses.
16893 ===============================================================================
16894 19. THE IPLOOKUP ROUTER
16896 The iplookup router was written to fulfil a specific requirement in Cambridge
16897 University (which in fact no longer exists). For this reason, it is not
16898 included in the binary of Exim by default. If you want to include it, you must
16901 ROUTER_IPLOOKUP=yes
16903 in your Local/Makefile configuration file.
16905 The iplookup router routes an address by sending it over a TCP or UDP
16906 connection to one or more specific hosts. The host can then return the same or
16907 a different address - in effect rewriting the recipient address in the
16908 message's envelope. The new address is then passed on to subsequent routers. If
16909 this process fails, the address can be passed on to other routers, or delivery
16910 can be deferred. Since iplookup is just a rewriting router, a transport must
16911 not be specified for it.
16913 +-----+-------------+------------+--------------+
16914 |hosts|Use: iplookup|Type: string|Default: unset|
16915 +-----+-------------+------------+--------------+
16917 This option must be supplied. Its value is a colon-separated list of host
16918 names. The hosts are looked up using gethostbyname() (or getipnodebyname() when
16919 available) and are tried in order until one responds to the query. If none
16920 respond, what happens is controlled by optional.
16922 +--------+-------------+-------------+--------------+
16923 |optional|Use: iplookup|Type: boolean|Default: false|
16924 +--------+-------------+-------------+--------------+
16926 If optional is true, if no response is obtained from any host, the address is
16927 passed to the next router, overriding no_more. If optional is false, delivery
16928 to the address is deferred.
16930 +----+-------------+-------------+----------+
16931 |port|Use: iplookup|Type: integer|Default: 0|
16932 +----+-------------+-------------+----------+
16934 This option must be supplied. It specifies the port number for the TCP or UDP
16937 +--------+-------------+------------+------------+
16938 |protocol|Use: iplookup|Type: string|Default: udp|
16939 +--------+-------------+------------+------------+
16941 This option can be set to "udp" or "tcp" to specify which of the two protocols
16944 +-----+-------------+-------------+------------------+
16945 |query|Use: iplookup|Type: string*|Default: see below|
16946 +-----+-------------+-------------+------------------+
16948 This defines the content of the query that is sent to the remote hosts. The
16951 $local_part@$domain $local_part@$domain
16953 The repetition serves as a way of checking that a response is to the correct
16954 query in the default case (see response_pattern below).
16956 +-------+-------------+-------------+--------------+
16957 |reroute|Use: iplookup|Type: string*|Default: unset|
16958 +-------+-------------+-------------+--------------+
16960 If this option is not set, the rerouted address is precisely the byte string
16961 returned by the remote host, up to the first white space, if any. If set, the
16962 string is expanded to form the rerouted address. It can include parts matched
16963 in the response by response_pattern by means of numeric variables such as $1,
16964 $2, etc. The variable $0 refers to the entire input string, whether or not a
16965 pattern is in use. In all cases, the rerouted address must end up in the form
16968 +----------------+-------------+------------+--------------+
16969 |response_pattern|Use: iplookup|Type: string|Default: unset|
16970 +----------------+-------------+------------+--------------+
16972 This option can be set to a regular expression that is applied to the string
16973 returned from the remote host. If the pattern does not match the response, the
16974 router declines. If response_pattern is not set, no checking of the response is
16975 done, unless the query was defaulted, in which case there is a check that the
16976 text returned after the first white space is the original address. This checks
16977 that the answer that has been received is in response to the correct question.
16978 For example, if the response is just a new domain, the following could be used:
16980 response_pattern = ^([^@]+)$
16981 reroute = $local_part@$1
16983 +-------+-------------+----------+-----------+
16984 |timeout|Use: iplookup|Type: time|Default: 5s|
16985 +-------+-------------+----------+-----------+
16987 This specifies the amount of time to wait for a response from the remote
16988 machine. The same timeout is used for the connect() function for a TCP call. It
16989 does not apply to UDP.
16993 ===============================================================================
16994 20. THE MANUALROUTE ROUTER
16996 The manualroute router is so-called because it provides a way of manually
16997 routing an address according to its domain. It is mainly used when you want to
16998 route addresses to remote hosts according to your own rules, bypassing the
16999 normal DNS routing that looks up MX records. However, manualroute can also
17000 route to local transports, a facility that may be useful if you want to save
17001 messages for dial-in hosts in local files.
17003 The manualroute router compares a list of domain patterns with the domain it is
17004 trying to route. If there is no match, the router declines. Each pattern has
17005 associated with it a list of hosts and some other optional data, which may
17006 include a transport. The combination of a pattern and its data is called a
17007 "routing rule". For patterns that do not have an associated transport, the
17008 generic transport option must specify a transport, unless the router is being
17009 used purely for verification (see verify_only).
17011 In the case of verification, matching the domain pattern is sufficient for the
17012 router to accept the address. When actually routing an address for delivery, an
17013 address that matches a domain pattern is queued for the associated transport.
17014 If the transport is not a local one, a host list must be associated with the
17015 pattern; IP addresses are looked up for the hosts, and these are passed to the
17016 transport along with the mail address. For local transports, a host list is
17017 optional. If it is present, it is passed in $host as a single text string.
17019 The list of routing rules can be provided as an inline string in route_list, or
17020 the data can be obtained by looking up the domain in a file or database by
17021 setting route_data. Only one of these settings may appear in any one instance
17022 of manualroute. The format of routing rules is described below, following the
17023 list of private options.
17026 20.1 Private options for manualroute
17027 ------------------------------------
17029 The private options for the manualroute router are as follows:
17031 +----------------+----------------+------------+--------------+
17032 |host_all_ignored|Use: manualroute|Type: string|Default: defer|
17033 +----------------+----------------+------------+--------------+
17035 See host_find_failed.
17037 +----------------+----------------+------------+---------------+
17038 |host_find_failed|Use: manualroute|Type: string|Default: freeze|
17039 +----------------+----------------+------------+---------------+
17041 This option controls what happens when manualroute tries to find an IP address
17042 for a host, and the host does not exist. The option can be set to one of the
17052 The default ("freeze") assumes that this state is a serious configuration
17053 error. The difference between "pass" and "decline" is that the former forces
17054 the address to be passed to the next router (or the router defined by
17055 pass_router), overriding no_more, whereas the latter passes the address to the
17056 next router only if more is true.
17058 The value "ignore" causes Exim to completely ignore a host whose IP address
17059 cannot be found. If all the hosts in the list are ignored, the behaviour is
17060 controlled by the host_all_ignored option. This takes the same values as
17061 host_find_failed, except that it cannot be set to "ignore".
17063 The host_find_failed option applies only to a definite "does not exist" state;
17064 if a host lookup gets a temporary error, delivery is deferred unless the
17065 generic pass_on_timeout option is set.
17067 +---------------+----------------+-------------+--------------+
17068 |hosts_randomize|Use: manualroute|Type: boolean|Default: false|
17069 +---------------+----------------+-------------+--------------+
17071 If this option is set, the order of the items in a host list in a routing rule
17072 is randomized each time the list is used, unless an option in the routing rule
17073 overrides (see below). Randomizing the order of a host list can be used to do
17074 crude load sharing. However, if more than one mail address is routed by the
17075 same router to the same host list, the host lists are considered to be the same
17076 (even though they may be randomized into different orders) for the purpose of
17077 deciding whether to batch the deliveries into a single SMTP transaction.
17079 When hosts_randomize is true, a host list may be split into groups whose order
17080 is separately randomized. This makes it possible to set up MX-like behaviour.
17081 The boundaries between groups are indicated by an item that is just "+" in the
17082 host list. For example:
17084 route_list = * host1:host2:host3:+:host4:host5
17086 The order of the first three hosts and the order of the last two hosts is
17087 randomized for each use, but the first three always end up before the last two.
17088 If hosts_randomize is not set, a "+" item in the list is ignored. If a
17089 randomized host list is passed to an smtp transport that also has
17090 hosts_randomize set, the list is not re-randomized.
17092 +----------+----------------+-------------+--------------+
17093 |route_data|Use: manualroute|Type: string*|Default: unset|
17094 +----------+----------------+-------------+--------------+
17096 If this option is set, it must expand to yield the data part of a routing rule.
17097 Typically, the expansion string includes a lookup based on the domain. For
17100 route_data = ${lookup{$domain}dbm{/etc/routes}}
17102 If the expansion is forced to fail, or the result is an empty string, the
17103 router declines. Other kinds of expansion failure cause delivery to be
17106 +----------+----------------+-----------------+--------------+
17107 |route_list|Use: manualroute|Type: string list|Default: unset|
17108 +----------+----------------+-----------------+--------------+
17110 This string is a list of routing rules, in the form defined below. Note that,
17111 unlike most string lists, the items are separated by semicolons. This is so
17112 that they may contain colon-separated host lists.
17114 +------------------------+----------------+-------------+--------------+
17115 |same_domain_copy_routing|Use: manualroute|Type: boolean|Default: false|
17116 +------------------------+----------------+-------------+--------------+
17118 Addresses with the same domain are normally routed by the manualroute router to
17119 the same list of hosts. However, this cannot be presumed, because the router
17120 options and preconditions may refer to the local part of the address. By
17121 default, therefore, Exim routes each address in a message independently. DNS
17122 servers run caches, so repeated DNS lookups are not normally expensive, and in
17123 any case, personal messages rarely have more than a few recipients.
17125 If you are running mailing lists with large numbers of subscribers at the same
17126 domain, and you are using a manualroute router which is independent of the
17127 local part, you can set same_domain_copy_routing to bypass repeated DNS lookups
17128 for identical domains in one message. In this case, when manualroute routes an
17129 address to a remote transport, any other unrouted addresses in the message that
17130 have the same domain are automatically given the same routing without
17131 processing them independently. However, this is only done if headers_add and
17132 headers_remove are unset.
17135 20.2 Routing rules in route_list
17136 --------------------------------
17138 The value of route_list is a string consisting of a sequence of routing rules,
17139 separated by semicolons. If a semicolon is needed in a rule, it can be entered
17140 as two semicolons. Alternatively, the list separator can be changed as
17141 described (for colon-separated lists) in section 6.19. Empty rules are ignored.
17142 The format of each rule is
17144 <domain pattern> <list of hosts> <options>
17146 The following example contains two rules, each with a simple domain pattern and
17150 dict.ref.example mail-1.ref.example:mail-2.ref.example ; \
17151 thes.ref.example mail-3.ref.example:mail-4.ref.example
17153 The three parts of a rule are separated by white space. The pattern and the
17154 list of hosts can be enclosed in quotes if necessary, and if they are, the
17155 usual quoting rules apply. Each rule in a route_list must start with a single
17156 domain pattern, which is the only mandatory item in the rule. The pattern is in
17157 the same format as one item in a domain list (see section 10.8), except that it
17158 may not be the name of an interpolated file. That is, it may be wildcarded, or
17159 a regular expression, or a file or database lookup (with semicolons doubled,
17160 because of the use of semicolon as a separator in a route_list).
17162 The rules in route_list are searched in order until one of the patterns matches
17163 the domain that is being routed. The list of hosts and then options are then
17164 used as described below. If there is no match, the router declines. When
17165 route_list is set, route_data must not be set.
17168 20.3 Routing rules in route_data
17169 --------------------------------
17171 The use of route_list is convenient when there are only a small number of
17172 routing rules. For larger numbers, it is easier to use a file or database to
17173 hold the routing information, and use the route_data option instead. The value
17174 of route_data is a list of hosts, followed by (optional) options. Most
17175 commonly, route_data is set as a string that contains an expansion lookup. For
17176 example, suppose we place two routing rules in a file like this:
17178 dict.ref.example: mail-1.ref.example:mail-2.ref.example
17179 thes.ref.example: mail-3.ref.example:mail-4.ref.example
17181 This data can be accessed by setting
17183 route_data = ${lookup{$domain}lsearch{/the/file/name}}
17185 Failure of the lookup results in an empty string, causing the router to
17186 decline. However, you do not have to use a lookup in route_data. The only
17187 requirement is that the result of expanding the string is a list of hosts,
17188 possibly followed by options, separated by white space. The list of hosts must
17189 be enclosed in quotes if it contains white space.
17192 20.4 Format of the list of hosts
17193 --------------------------------
17195 A list of hosts, whether obtained via route_data or route_list, is always
17196 separately expanded before use. If the expansion fails, the router declines.
17197 The result of the expansion must be a colon-separated list of names and/or IP
17198 addresses, optionally also including ports. The format of each item in the list
17199 is described in the next section. The list separator can be changed as
17200 described in section 6.19.
17202 If the list of hosts was obtained from a route_list item, the following
17203 variables are set during its expansion:
17205 * If the domain was matched against a regular expression, the numeric
17206 variables $1, $2, etc. may be set. For example:
17208 route_list = ^domain(\d+) host-$1.text.example
17210 * $0 is always set to the entire domain.
17212 * $1 is also set when partial matching is done in a file lookup.
17214 * If the pattern that matched the domain was a lookup item, the data that was
17215 looked up is available in the expansion variable $value. For example:
17217 route_list = lsearch;;/some/file.routes $value
17219 Note the doubling of the semicolon in the pattern that is necessary because
17220 semicolon is the default route list separator.
17223 20.5 Format of one host item
17224 ----------------------------
17226 Each item in the list of hosts is either a host name or an IP address,
17227 optionally with an attached port number. When no port is given, an IP address
17228 is not enclosed in brackets. When a port is specified, it overrides the port
17229 specification on the transport. The port is separated from the name or address
17230 by a colon. This leads to some complications:
17232 * Because colon is the default separator for the list of hosts, either the
17233 colon that specifies a port must be doubled, or the list separator must be
17234 changed. The following two examples have the same effect:
17236 route_list = * "host1.tld::1225 : host2.tld::1226"
17237 route_list = * "<+ host1.tld:1225 + host2.tld:1226"
17239 * When IPv6 addresses are involved, it gets worse, because they contain
17240 colons of their own. To make this case easier, it is permitted to enclose
17241 an IP address (either v4 or v6) in square brackets if a port number
17242 follows. For example:
17244 route_list = * "</ [10.1.1.1]:1225 / [::1]:1226"
17247 20.6 How the list of hosts is used
17248 ----------------------------------
17250 When an address is routed to an smtp transport by manualroute, each of the
17251 hosts is tried, in the order specified, when carrying out the SMTP delivery.
17252 However, the order can be changed by setting the hosts_randomize option, either
17253 on the router (see section 20.1 above), or on the transport.
17255 Hosts may be listed by name or by IP address. An unadorned name in the list of
17256 hosts is interpreted as a host name. A name that is followed by "/MX" is
17257 interpreted as an indirection to a sublist of hosts obtained by looking up MX
17258 records in the DNS. For example:
17260 route_list = * x.y.z:p.q.r/MX:e.f.g
17262 If this feature is used with a port specifier, the port must come last. For
17265 route_list = * dom1.tld/mx::1225
17267 If the hosts_randomize option is set, the order of the items in the list is
17268 randomized before any lookups are done. Exim then scans the list; for any name
17269 that is not followed by "/MX" it looks up an IP address. If this turns out to
17270 be an interface on the local host and the item is not the first in the list,
17271 Exim discards it and any subsequent items. If it is the first item, what
17272 happens is controlled by the self option of the router.
17274 A name on the list that is followed by "/MX" is replaced with the list of hosts
17275 obtained by looking up MX records for the name. This is always a DNS lookup;
17276 the bydns and byname options (see section 20.7 below) are not relevant here.
17277 The order of these hosts is determined by the preference values in the MX
17278 records, according to the usual rules. Because randomizing happens before the
17279 MX lookup, it does not affect the order that is defined by MX preferences.
17281 If the local host is present in the sublist obtained from MX records, but is
17282 not the most preferred host in that list, it and any equally or less preferred
17283 hosts are removed before the sublist is inserted into the main list.
17285 If the local host is the most preferred host in the MX list, what happens
17286 depends on where in the original list of hosts the "/MX" item appears. If it is
17287 not the first item (that is, there are previous hosts in the main list), Exim
17288 discards this name and any subsequent items in the main list.
17290 If the MX item is first in the list of hosts, and the local host is the most
17291 preferred host, what happens is controlled by the self option of the router.
17293 DNS failures when lookup up the MX records are treated in the same way as DNS
17294 failures when looking up IP addresses: pass_on_timeout and host_find_failed are
17295 used when relevant.
17297 The generic ignore_target_hosts option applies to all hosts in the list,
17298 whether obtained from an MX lookup or not.
17301 20.7 How the options are used
17302 -----------------------------
17304 The options are a sequence of words; in practice no more than three are ever
17305 present. One of the words can be the name of a transport; this overrides the
17306 transport option on the router for this particular routing rule only. The other
17307 words (if present) control randomization of the list of hosts on a per-rule
17308 basis, and how the IP addresses of the hosts are to be found when routing to a
17309 remote transport. These options are as follows:
17311 * randomize: randomize the order of the hosts in this list, overriding the
17312 setting of hosts_randomize for this routing rule only.
17314 * no_randomize: do not randomize the order of the hosts in this list,
17315 overriding the setting of hosts_randomize for this routing rule only.
17317 * byname: use getipnodebyname() (gethostbyname() on older systems) to find IP
17318 addresses. This function may ultimately cause a DNS lookup, but it may also
17319 look in /etc/hosts or other sources of information.
17321 * bydns: look up address records for the hosts directly in the DNS; fail if
17322 no address records are found. If there is a temporary DNS error (such as a
17323 timeout), delivery is deferred.
17327 route_list = domain1 host1:host2:host3 randomize bydns;\
17328 domain2 host4:host5
17330 If neither byname nor bydns is given, Exim behaves as follows: First, a DNS
17331 lookup is done. If this yields anything other than HOST_NOT_FOUND, that result
17332 is used. Otherwise, Exim goes on to try a call to getipnodebyname() or
17333 gethostbyname(), and the result of the lookup is the result of that call.
17335 Warning: It has been discovered that on some systems, if a DNS lookup called
17336 via getipnodebyname() times out, HOST_NOT_FOUND is returned instead of
17337 TRY_AGAIN. That is why the default action is to try a DNS lookup first. Only if
17338 that gives a definite "no such host" is the local function called.
17340 If no IP address for a host can be found, what happens is controlled by the
17341 host_find_failed option.
17343 When an address is routed to a local transport, IP addresses are not looked up.
17344 The host list is passed to the transport in the $host variable.
17347 20.8 Manualroute examples
17348 -------------------------
17350 In some of the examples that follow, the presence of the remote_smtp transport,
17351 as defined in the default configuration file, is assumed:
17353 * The manualroute router can be used to forward all external mail to a smart
17354 host. If you have set up, in the main part of the configuration, a named
17355 domain list that contains your local domains, for example:
17357 domainlist local_domains = my.domain.example
17359 You can arrange for all other domains to be routed to a smart host by
17360 making your first router something like this:
17363 driver = manualroute
17364 domains = !+local_domains
17365 transport = remote_smtp
17366 route_list = * smarthost.ref.example
17368 This causes all non-local addresses to be sent to the single host
17369 smarthost.ref.example. If a colon-separated list of smart hosts is given,
17370 they are tried in order (but you can use hosts_randomize to vary the order
17371 each time). Another way of configuring the same thing is this:
17374 driver = manualroute
17375 transport = remote_smtp
17376 route_list = !+local_domains smarthost.ref.example
17378 There is no difference in behaviour between these two routers as they
17379 stand. However, they behave differently if no_more is added to them. In the
17380 first example, the router is skipped if the domain does not match the
17381 domains precondition; the following router is always tried. If the router
17382 runs, it always matches the domain and so can never decline. Therefore,
17383 no_more would have no effect. In the second case, the router is never
17384 skipped; it always runs. However, if it doesn't match the domain, it
17385 declines. In this case no_more would prevent subsequent routers from
17388 * A mail hub is a host which receives mail for a number of domains via MX
17389 records in the DNS and delivers it via its own private routing mechanism.
17390 Often the final destinations are behind a firewall, with the mail hub being
17391 the one machine that can connect to machines both inside and outside the
17392 firewall. The manualroute router is usually used on a mail hub to route
17393 incoming messages to the correct hosts. For a small number of domains, the
17394 routing can be inline, using the route_list option, but for a larger number
17395 a file or database lookup is easier to manage.
17397 If the domain names are in fact the names of the machines to which the mail
17398 is to be sent by the mail hub, the configuration can be quite simple. For
17402 driver = manualroute
17403 transport = remote_smtp
17404 route_list = *.rhodes.tvs.example $domain
17406 This configuration routes domains that match "*.rhodes.tvs.example" to
17407 hosts whose names are the same as the mail domains. A similar approach can
17408 be taken if the host name can be obtained from the domain name by a string
17409 manipulation that the expansion facilities can handle. Otherwise, a lookup
17410 based on the domain can be used to find the host:
17413 driver = manualroute
17414 transport = remote_smtp
17415 route_data = ${lookup {$domain} cdb {/internal/host/routes}}
17417 The result of the lookup must be the name or IP address of the host (or
17418 hosts) to which the address is to be routed. If the lookup fails, the route
17419 data is empty, causing the router to decline. The address then passes to
17422 * You can use manualroute to deliver messages to pipes or files in batched
17423 SMTP format for onward transportation by some other means. This is one way
17424 of storing mail for a dial-up host when it is not connected. The route list
17425 entry can be as simple as a single domain name in a configuration like
17429 driver = manualroute
17430 transport = batchsmtp_appendfile
17431 route_list = saved.domain.example
17433 though often a pattern is used to pick up more than one domain. If there
17434 are several domains or groups of domains with different transport
17435 requirements, different transports can be listed in the routing
17439 driver = manualroute
17441 *.saved.domain1.example $domain batch_appendfile; \
17442 *.saved.domain2.example \
17443 ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \
17446 The first of these just passes the domain in the $host variable, which
17447 doesn't achieve much (since it is also in $domain), but the second does a
17448 file lookup to find a value to pass, causing the router to decline to
17449 handle the address if the lookup fails.
17451 * Routing mail directly to UUCP software is a specific case of the use of
17452 manualroute in a gateway to another mail environment. This is an example of
17453 one way it can be done:
17459 command = /usr/local/bin/uux -r - \
17460 ${substr_-5:$host}!rmail ${local_part}
17461 return_fail_output = true
17466 driver = manualroute
17468 ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}}
17470 The file /usr/local/exim/uucphosts contains entries like
17472 darksite.ethereal.example: darksite.UUCP
17474 It can be set up more simply without adding and removing ".UUCP" but this
17475 way makes clear the distinction between the domain name
17476 darksite.ethereal.example and the UUCP host name darksite.
17480 ===============================================================================
17481 21. THE QUERYPROGRAM ROUTER
17483 The queryprogram router routes an address by running an external command and
17484 acting on its output. This is an expensive way to route, and is intended mainly
17485 for use in lightly-loaded systems, or for performing experiments. However, if
17486 it is possible to use the precondition options (domains, local_parts, etc) to
17487 skip this router for most addresses, it could sensibly be used in special
17488 cases, even on a busy host. There are the following private options:
17490 +-------+-----------------+-------------+--------------+
17491 |command|Use: queryprogram|Type: string*|Default: unset|
17492 +-------+-----------------+-------------+--------------+
17494 This option must be set. It specifies the command that is to be run. The
17495 command is split up into a command name and arguments, and then each is
17496 expanded separately (exactly as for a pipe transport, described in chapter 29).
17498 +-------------+-----------------+------------+--------------+
17499 |command_group|Use: queryprogram|Type: string|Default: unset|
17500 +-------------+-----------------+------------+--------------+
17502 This option specifies a gid to be set when running the command while routing an
17503 address for deliver. It must be set if command_user specifies a numerical uid.
17504 If it begins with a digit, it is interpreted as the numerical value of the gid.
17505 Otherwise it is looked up using getgrnam().
17507 +------------+-----------------+------------+--------------+
17508 |command_user|Use: queryprogram|Type: string|Default: unset|
17509 +------------+-----------------+------------+--------------+
17511 This option must be set. It specifies the uid which is set when running the
17512 command while routing an address for delivery. If the value begins with a
17513 digit, it is interpreted as the numerical value of the uid. Otherwise, it is
17514 looked up using getpwnam() to obtain a value for the uid and, if command_group
17515 is not set, a value for the gid also.
17517 Warning: Changing uid and gid is possible only when Exim is running as root,
17518 which it does during a normal delivery in a conventional configuration.
17519 However, when an address is being verified during message reception, Exim is
17520 usually running as the Exim user, not as root. If the queryprogram router is
17521 called from a non-root process, Exim cannot change uid or gid before running
17522 the command. In this circumstance the command runs under the current uid and
17525 +-----------------+-----------------+------------+----------+
17526 |current_directory|Use: queryprogram|Type: string|Default: /|
17527 +-----------------+-----------------+------------+----------+
17529 This option specifies an absolute path which is made the current directory
17530 before running the command.
17532 +-------+-----------------+----------+-----------+
17533 |timeout|Use: queryprogram|Type: time|Default: 1h|
17534 +-------+-----------------+----------+-----------+
17536 If the command does not complete within the timeout period, its process group
17537 is killed and the message is frozen. A value of zero time specifies no timeout.
17539 The standard output of the command is connected to a pipe, which is read when
17540 the command terminates. It should consist of a single line of output,
17541 containing up to five fields, separated by white space. The maximum length of
17542 the line is 1023 characters. Longer lines are silently truncated. The first
17543 field is one of the following words (case-insensitive):
17545 * Accept: routing succeeded; the remaining fields specify what to do (see
17548 * Decline: the router declines; pass the address to the next router, unless
17551 * Fail: routing failed; do not pass the address to any more routers. Any
17552 subsequent text on the line is an error message. If the router is run as
17553 part of address verification during an incoming SMTP message, the message
17554 is included in the SMTP response.
17556 * Defer: routing could not be completed at this time; try again later. Any
17557 subsequent text on the line is an error message which is logged. It is not
17558 included in any SMTP response.
17560 * Freeze: the same as defer, except that the message is frozen.
17562 * Pass: pass the address to the next router (or the router specified by
17563 pass_router), overriding no_more.
17565 * Redirect: the message is redirected. The remainder of the line is a list of
17566 new addresses, which are routed independently, starting with the first
17567 router, or the router specified by redirect_router, if set.
17569 When the first word is accept, the remainder of the line consists of a number
17570 of keyed data values, as follows (split into two lines here, to fit on the
17573 ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts>
17574 LOOKUP=byname|bydns DATA=<text>
17576 The data items can be given in any order, and all are optional. If no transport
17577 is included, the transport specified by the generic transport option is used.
17578 The list of hosts and the lookup type are needed only if the transport is an
17579 smtp transport that does not itself supply a list of hosts.
17581 The format of the list of hosts is the same as for the manualroute router. As
17582 well as host names and IP addresses with optional port numbers, as described in
17583 section 20.5, it may contain names followed by "/MX" to specify sublists of
17584 hosts that are obtained by looking up MX records (see section 20.6).
17586 If the lookup type is not specified, Exim behaves as follows when trying to
17587 find an IP address for each host: First, a DNS lookup is done. If this yields
17588 anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim goes
17589 on to try a call to getipnodebyname() or gethostbyname(), and the result of the
17590 lookup is the result of that call.
17592 If the DATA field is set, its value is placed in the $address_data variable.
17593 For example, this return line
17595 accept hosts=x1.y.example:x2.y.example data="rule1"
17597 routes the address to the default transport, passing a list of two hosts. When
17598 the transport runs, the string "rule1" is in $address_data.
17602 ===============================================================================
17603 22. THE REDIRECT ROUTER
17605 The redirect router handles several kinds of address redirection. Its most
17606 common uses are for resolving local part aliases from a central alias file
17607 (usually called /etc/aliases) and for handling users' personal .forward files,
17608 but it has many other potential uses. The incoming address can be redirected in
17609 several different ways:
17611 * It can be replaced by one or more new addresses which are themselves routed
17614 * It can be routed to be delivered to a given file or directory.
17616 * It can be routed to be delivered to a specified pipe command.
17618 * It can cause an automatic reply to be generated.
17620 * It can be forced to fail, optionally with a custom error message.
17622 * It can be temporarily deferred, optionally with a custom message.
17624 * It can be discarded.
17626 The generic transport option must not be set for redirect routers. However,
17627 there are some private options which define transports for delivery to files
17628 and pipes, and for generating autoreplies. See the file_transport,
17629 pipe_transport and reply_transport descriptions below.
17632 22.1 Redirection data
17633 ---------------------
17635 The router operates by interpreting a text string which it obtains either by
17636 expanding the contents of the data option, or by reading the entire contents of
17637 a file whose name is given in the file option. These two options are mutually
17638 exclusive. The first is commonly used for handling system aliases, in a
17639 configuration like this:
17643 data = ${lookup{$local_part}lsearch{/etc/aliases}}
17645 If the lookup fails, the expanded string in this example is empty. When the
17646 expansion of data results in an empty string, the router declines. A forced
17647 expansion failure also causes the router to decline; other expansion failures
17648 cause delivery to be deferred.
17650 A configuration using file is commonly used for handling users' .forward files,
17656 file = $home/.forward
17659 If the file does not exist, or causes no action to be taken (for example, it is
17660 empty or consists only of comments), the router declines. Warning: This is not
17661 the case when the file contains syntactically valid items that happen to yield
17662 empty addresses, for example, items containing only RFC 2822 address comments.
17665 22.2 Forward files and address verification
17666 -------------------------------------------
17668 It is usual to set no_verify on redirect routers which handle users' .forward
17669 files, as in the example above. There are two reasons for this:
17671 * When Exim is receiving an incoming SMTP message from a remote host, it is
17672 running under the Exim uid, not as root. Exim is unable to change uid to
17673 read the file as the user, and it may not be able to read it as the Exim
17674 user. So in practice the router may not be able to operate.
17676 * However, even when the router can operate, the existence of a .forward file
17677 is unimportant when verifying an address. What should be checked is whether
17678 the local part is a valid user name or not. Cutting out the redirection
17679 processing saves some resources.
17682 22.3 Interpreting redirection data
17683 ----------------------------------
17685 The contents of the data string, whether obtained from data or file, can be
17686 interpreted in two different ways:
17688 * If the allow_filter option is set true, and the data begins with the text "
17689 #Exim filter" or "#Sieve filter", it is interpreted as a list of filtering
17690 instructions in the form of an Exim or Sieve filter file, respectively.
17691 Details of the syntax and semantics of filter files are described in a
17692 separate document entitled Exim's interfaces to mail filtering; this
17693 document is intended for use by end users.
17695 * Otherwise, the data must be a comma-separated list of redirection items, as
17696 described in the next section.
17698 When a message is redirected to a file (a "mail folder"), the file name given
17699 in a non-filter redirection list must always be an absolute path. A filter may
17700 generate a relative path - how this is handled depends on the transport's
17701 configuration. See section 26.1 for a discussion of this issue for the
17702 appendfile transport.
17705 22.4 Items in a non-filter redirection list
17706 -------------------------------------------
17708 When the redirection data is not an Exim or Sieve filter, for example, if it
17709 comes from a conventional alias or forward file, it consists of a list of
17710 addresses, file names, pipe commands, or certain special items (see section
17711 22.6 below). The special items can be individually enabled or disabled by means
17712 of options whose names begin with allow_ or forbid_, depending on their default
17713 values. The items in the list are separated by commas or newlines. If a comma
17714 is required in an item, the entire item must be enclosed in double quotes.
17716 Lines starting with a # character are comments, and are ignored, and # may also
17717 appear following a comma, in which case everything between the # and the next
17718 newline character is ignored.
17720 If an item is entirely enclosed in double quotes, these are removed. Otherwise
17721 double quotes are retained because some forms of mail address require their use
17722 (but never to enclose the entire address). In the following description, "item"
17723 refers to what remains after any surrounding double quotes have been removed.
17725 Warning: If you use an Exim expansion to construct a redirection address, and
17726 the expansion contains a reference to $local_part, you should make use of the
17727 quote_local_part expansion operator, in case the local part contains special
17728 characters. For example, to redirect all mail for the domain obsolete.example,
17729 retaining the existing local part, you could use this setting:
17731 data = ${quote_local_part:$local_part}@newdomain.example
17734 22.5 Redirecting to a local mailbox
17735 -----------------------------------
17737 A redirection item may safely be the same as the address currently under
17738 consideration. This does not cause a routing loop, because a router is
17739 automatically skipped if any ancestor of the address that is being processed is
17740 the same as the current address and was processed by the current router. Such
17741 an address is therefore passed to the following routers, so it is handled as if
17742 there were no redirection. When making this loop-avoidance test, the complete
17743 local part, including any prefix or suffix, is used.
17745 Specifying the same local part without a domain is a common usage in personal
17746 filter files when the user wants to have messages delivered to the local
17747 mailbox and also forwarded elsewhere. For example, the user whose login is cleo
17748 might have a .forward file containing this:
17750 cleo, cleopatra@egypt.example
17752 For compatibility with other MTAs, such unqualified local parts may be preceded
17753 by "\", but this is not a requirement for loop prevention. However, it does
17754 make a difference if more than one domain is being handled synonymously.
17756 If an item begins with "\" and the rest of the item parses as a valid RFC 2822
17757 address that does not include a domain, the item is qualified using the domain
17758 of the incoming address. In the absence of a leading "\", unqualified addresses
17759 are qualified using the value in qualify_recipient, but you can force the
17760 incoming domain to be used by setting qualify_preserve_domain.
17762 Care must be taken if there are alias names for local users. Consider an MTA
17763 handling a single local domain where the system alias file contains:
17767 Now suppose that Sam (whose login id is spqr) wants to save copies of messages
17768 in the local mailbox, and also forward copies elsewhere. He creates this
17771 Sam.Reman, spqr@reme.elsewhere.example
17773 With these settings, an incoming message addressed to Sam.Reman fails. The
17774 redirect router for system aliases does not process Sam.Reman the second time
17775 round, because it has previously routed it, and the following routers
17776 presumably cannot handle the alias. The forward file should really contain
17778 spqr, spqr@reme.elsewhere.example
17780 but because this is such a common error, the check_ancestor option (see below)
17781 exists to provide a way to get round it. This is normally set on a redirect
17782 router that is handling users' .forward files.
17785 22.6 Special items in redirection lists
17786 ---------------------------------------
17788 In addition to addresses, the following types of item may appear in redirection
17789 lists (that is, in non-filter redirection data):
17791 * An item is treated as a pipe command if it begins with "|" and does not
17792 parse as a valid RFC 2822 address that includes a domain. A transport for
17793 running the command must be specified by the pipe_transport option.
17794 Normally, either the router or the transport specifies a user and a group
17795 under which to run the delivery. The default is to use the Exim user and
17798 Single or double quotes can be used for enclosing the individual arguments
17799 of the pipe command; no interpretation of escapes is done for single
17800 quotes. If the command contains a comma character, it is necessary to put
17801 the whole item in double quotes, for example:
17803 "|/some/command ready,steady,go"
17805 since items in redirection lists are terminated by commas. Do not, however,
17806 quote just the command. An item such as
17808 |"/some/command ready,steady,go"
17810 is interpreted as a pipe with a rather strange command name, and no
17813 Note that the above example assumes that the text comes from a lookup
17814 source of some sort, so that the quotes are part of the data. If composing
17815 a redirect router with a data option directly specifying this command, the
17816 quotes will be used by the configuration parser to define the extent of one
17817 string, but will not be passed down into the redirect router itself. There
17818 are two main approaches to get around this: escape quotes to be part of the
17819 data itself, or avoid using this mechanism and instead create a custom
17820 transport with the command option set and reference that transport from an
17823 * An item is interpreted as a path name if it begins with "/" and does not
17824 parse as a valid RFC 2822 address that includes a domain. For example,
17826 /home/world/minbari
17828 is treated as a file name, but
17830 /s=molari/o=babylon/@x400gate.way
17832 is treated as an address. For a file name, a transport must be specified
17833 using the file_transport option. However, if the generated path name ends
17834 with a forward slash character, it is interpreted as a directory name
17835 rather than a file name, and directory_transport is used instead.
17837 Normally, either the router or the transport specifies a user and a group
17838 under which to run the delivery. The default is to use the Exim user and
17841 However, if a redirection item is the path /dev/null, delivery to it is
17842 bypassed at a high level, and the log entry shows "**bypassed**" instead of
17843 a transport name. In this case the user and group are not used.
17845 * If an item is of the form
17847 :include:<path name>
17849 a list of further items is taken from the given file and included at that
17850 point. Note: Such a file can not be a filter file; it is just an
17851 out-of-line addition to the list. The items in the included list are
17852 separated by commas or newlines and are not subject to expansion. If this
17853 is the first item in an alias list in an lsearch file, a colon must be used
17854 to terminate the alias name. This example is incorrect:
17856 list1 :include:/opt/lists/list1
17858 It must be given as
17860 list1: :include:/opt/lists/list1
17862 * Sometimes you want to throw away mail to a particular local part. Making
17863 the data option expand to an empty string does not work, because that
17864 causes the router to decline. Instead, the alias item :blackhole: can be
17865 used. It does what its name implies. No delivery is done, and no error
17866 message is generated. This has the same effect as specifing /dev/null as a
17867 destination, but it can be independently disabled.
17869 Warning: If :blackhole: appears anywhere in a redirection list, no delivery
17870 is done for the original local part, even if other redirection items are
17871 present. If you are generating a multi-item list (for example, by reading a
17872 database) and need the ability to provide a no-op item, you must use /dev/
17875 * An attempt to deliver a particular address can be deferred or forced to
17876 fail by redirection items of the form
17881 respectively. When a redirection list contains such an item, it applies to
17882 the entire redirection; any other items in the list are ignored. Any text
17883 following :fail: or :defer: is placed in the error text associated with the
17884 failure. For example, an alias file might contain:
17886 X.Employee: :fail: Gone away, no forwarding address
17888 In the case of an address that is being verified from an ACL or as the
17889 subject of a VRFY command, the text is included in the SMTP error response
17890 by default. The text is not included in the response to an EXPN command. In
17891 non-SMTP cases the text is included in the error message that Exim
17894 By default, Exim sends a 451 SMTP code for a :defer:, and 550 for :fail:.
17895 However, if the message starts with three digits followed by a space,
17896 optionally followed by an extended code of the form n.n.n, also followed by
17897 a space, and the very first digit is the same as the default error code,
17898 the code from the message is used instead. If the very first digit is
17899 incorrect, a panic error is logged, and the default code is used. You can
17900 suppress the use of the supplied code in a redirect router by setting the
17901 forbid_smtp_code option true. In this case, any SMTP code is quietly
17904 In an ACL, an explicitly provided message overrides the default, but the
17905 default message is available in the variable $acl_verify_message and can
17906 therefore be included in a custom message if this is desired.
17908 Normally the error text is the rest of the redirection list - a comma does
17909 not terminate it - but a newline does act as a terminator. Newlines are not
17910 normally present in alias expansions. In lsearch lookups they are removed
17911 as part of the continuation process, but they may exist in other kinds of
17912 lookup and in :include: files.
17914 During routing for message delivery (as opposed to verification), a
17915 redirection containing :fail: causes an immediate failure of the incoming
17916 address, whereas :defer: causes the message to remain on the queue so that
17917 a subsequent delivery attempt can happen at a later time. If an address is
17918 deferred for too long, it will ultimately fail, because the normal retry
17921 * Sometimes it is useful to use a single-key search type with a default (see
17922 chapter 9) to look up aliases. However, there may be a need for exceptions
17923 to the default. These can be handled by aliasing them to :unknown:. This
17924 differs from :fail: in that it causes the redirect router to decline,
17925 whereas :fail: forces routing to fail. A lookup which results in an empty
17926 redirection list has the same effect.
17929 22.7 Duplicate addresses
17930 ------------------------
17932 Exim removes duplicate addresses from the list to which it is delivering, so as
17933 to deliver just one copy to each address. This does not apply to deliveries
17934 routed to pipes by different immediate parent addresses, but an indirect
17935 aliasing scheme of the type
17937 pipe: |/some/command $local_part
17941 does not work with a message that is addressed to both local parts, because
17942 when the second is aliased to the intermediate local part "pipe" it gets
17943 discarded as being the same as a previously handled address. However, a scheme
17946 localpart1: |/some/command $local_part
17947 localpart2: |/some/command $local_part
17949 does result in two different pipe deliveries, because the immediate parents of
17950 the pipes are distinct.
17953 22.8 Repeated redirection expansion
17954 -----------------------------------
17956 When a message cannot be delivered to all of its recipients immediately,
17957 leading to two or more delivery attempts, redirection expansion is carried out
17958 afresh each time for those addresses whose children were not all previously
17959 delivered. If redirection is being used as a mailing list, this can lead to new
17960 members of the list receiving copies of old messages. The one_time option can
17961 be used to avoid this.
17964 22.9 Errors in redirection lists
17965 --------------------------------
17967 If skip_syntax_errors is set, a malformed address that causes a parsing error
17968 is skipped, and an entry is written to the main log. This may be useful for
17969 mailing lists that are automatically managed. Otherwise, if an error is
17970 detected while generating the list of new addresses, the original address is
17971 deferred. See also syntax_errors_to.
17974 22.10 Private options for the redirect router
17975 ---------------------------------------------
17977 The private options for the redirect router are as follows:
17979 +-----------+-------------+-------------+--------------+
17980 |allow_defer|Use: redirect|Type: boolean|Default: false|
17981 +-----------+-------------+-------------+--------------+
17983 Setting this option allows the use of :defer: in non-filter redirection data,
17984 or the defer command in an Exim filter file.
17986 +----------+-------------+-------------+--------------+
17987 |allow_fail|Use: redirect|Type: boolean|Default: false|
17988 +----------+-------------+-------------+--------------+
17990 If this option is true, the :fail: item can be used in a redirection list, and
17991 the fail command may be used in an Exim filter file.
17993 +------------+-------------+-------------+--------------+
17994 |allow_filter|Use: redirect|Type: boolean|Default: false|
17995 +------------+-------------+-------------+--------------+
17997 Setting this option allows Exim to interpret redirection data that starts with
17998 "#Exim filter" or "#Sieve filter" as a set of filtering instructions. There are
17999 some features of Exim filter files that some administrators may wish to lock
18000 out; see the forbid_filter_xxx options below.
18002 It is also possible to lock out Exim filters or Sieve filters while allowing
18003 the other type; see forbid_exim_filter and forbid_sieve_filter.
18005 The filter is run using the uid and gid set by the generic user and group
18006 options. These take their defaults from the password data if check_local_user
18007 is set, so in the normal case of users' personal filter files, the filter is
18008 run as the relevant user. When allow_filter is set true, Exim insists that
18009 either check_local_user or user is set.
18011 +------------+-------------+-------------+--------------+
18012 |allow_freeze|Use: redirect|Type: boolean|Default: false|
18013 +------------+-------------+-------------+--------------+
18015 Setting this option allows the use of the freeze command in an Exim filter.
18016 This command is more normally encountered in system filters, and is disabled by
18017 default for redirection filters because it isn't something you usually want to
18018 let ordinary users do.
18020 +--------------+-------------+-------------+--------------+
18021 |check_ancestor|Use: redirect|Type: boolean|Default: false|
18022 +--------------+-------------+-------------+--------------+
18024 This option is concerned with handling generated addresses that are the same as
18025 some address in the list of redirection ancestors of the current address.
18026 Although it is turned off by default in the code, it is set in the default
18027 configuration file for handling users' .forward files. It is recommended for
18028 this use of the redirect router.
18030 When check_ancestor is set, if a generated address (including the domain) is
18031 the same as any ancestor of the current address, it is replaced by a copy of
18032 the current address. This helps in the case where local part A is aliased to B,
18033 and B has a .forward file pointing back to A. For example, within a single
18034 domain, the local part "Joe.Bloggs" is aliased to "jb" and jb/.forward
18037 \Joe.Bloggs, <other item(s)>
18039 Without the check_ancestor setting, either local part ("jb" or "joe.bloggs")
18040 gets processed once by each router and so ends up as it was originally. If "jb"
18041 is the real mailbox name, mail to "jb" gets delivered (having been turned into
18042 "joe.bloggs" by the .forward file and back to "jb" by the alias), but mail to
18043 "joe.bloggs" fails. Setting check_ancestor on the redirect router that handles
18044 the .forward file prevents it from turning "jb" back into "joe.bloggs" when
18045 that was the original address. See also the repeat_use option below.
18047 +-----------+-------------+-------------+------------------+
18048 |check_group|Use: redirect|Type: boolean|Default: see below|
18049 +-----------+-------------+-------------+------------------+
18051 When the file option is used, the group owner of the file is checked only when
18052 this option is set. The permitted groups are those listed in the owngroups
18053 option, together with the user's default group if check_local_user is set. If
18054 the file has the wrong group, routing is deferred. The default setting for this
18055 option is true if check_local_user is set and the modemask option permits the
18056 group write bit, or if the owngroups option is set. Otherwise it is false, and
18057 no group check occurs.
18059 +-----------+-------------+-------------+------------------+
18060 |check_owner|Use: redirect|Type: boolean|Default: see below|
18061 +-----------+-------------+-------------+------------------+
18063 When the file option is used, the owner of the file is checked only when this
18064 option is set. If check_local_user is set, the local user is permitted;
18065 otherwise the owner must be one of those listed in the owners option. The
18066 default value for this option is true if check_local_user or owners is set.
18067 Otherwise the default is false, and no owner check occurs.
18069 +----+-------------+-------------+--------------+
18070 |data|Use: redirect|Type: string*|Default: unset|
18071 +----+-------------+-------------+--------------+
18073 This option is mutually exclusive with file. One or other of them must be set,
18074 but not both. The contents of data are expanded, and then used as the list of
18075 forwarding items, or as a set of filtering instructions. If the expansion is
18076 forced to fail, or the result is an empty string or a string that has no effect
18077 (consists entirely of comments), the router declines.
18079 When filtering instructions are used, the string must begin with "#Exim
18080 filter", and all comments in the string, including this initial one, must be
18081 terminated with newline characters. For example:
18083 data = #Exim filter\n\
18084 if $h_to: contains Exim then save $home/mail/exim endif
18086 If you are reading the data from a database where newlines cannot be included,
18087 you can use the ${sg} expansion item to turn the escape string of your choice
18090 +-------------------+-------------+-------------+--------------+
18091 |directory_transport|Use: redirect|Type: string*|Default: unset|
18092 +-------------------+-------------+-------------+--------------+
18094 A redirect router sets up a direct delivery to a directory when a path name
18095 ending with a slash is specified as a new "address". The transport used is
18096 specified by this option, which, after expansion, must be the name of a
18097 configured transport. This should normally be an appendfile transport.
18099 +----+-------------+-------------+--------------+
18100 |file|Use: redirect|Type: string*|Default: unset|
18101 +----+-------------+-------------+--------------+
18103 This option specifies the name of a file that contains the redirection data. It
18104 is mutually exclusive with the data option. The string is expanded before use;
18105 if the expansion is forced to fail, the router declines. Other expansion
18106 failures cause delivery to be deferred. The result of a successful expansion
18107 must be an absolute path. The entire file is read and used as the redirection
18108 data. If the data is an empty string or a string that has no effect (consists
18109 entirely of comments), the router declines.
18111 If the attempt to open the file fails with a "does not exist" error, Exim runs
18112 a check on the containing directory, unless ignore_enotdir is true (see below).
18113 If the directory does not appear to exist, delivery is deferred. This can
18114 happen when users' .forward files are in NFS-mounted directories, and there is
18115 a mount problem. If the containing directory does exist, but the file does not,
18116 the router declines.
18118 +--------------+-------------+-------------+--------------+
18119 |file_transport|Use: redirect|Type: string*|Default: unset|
18120 +--------------+-------------+-------------+--------------+
18122 A redirect router sets up a direct delivery to a file when a path name not
18123 ending in a slash is specified as a new "address". The transport used is
18124 specified by this option, which, after expansion, must be the name of a
18125 configured transport. This should normally be an appendfile transport. When it
18126 is running, the file name is in $address_file.
18128 +-------------------+-------------+-------------+-------------+
18129 |filter_prepend_home|Use: redirect|Type: boolean|Default: true|
18130 +-------------------+-------------+-------------+-------------+
18132 When this option is true, if a save command in an Exim filter specifies a
18133 relative path, and $home is defined, it is automatically prepended to the
18134 relative path. If this option is set false, this action does not happen. The
18135 relative path is then passed to the transport unmodified.
18137 +----------------+-------------+-------------+--------------+
18138 |forbid_blackhole|Use: redirect|Type: boolean|Default: false|
18139 +----------------+-------------+-------------+--------------+
18141 If this option is true, the :blackhole: item may not appear in a redirection
18144 +------------------+-------------+-------------+--------------+
18145 |forbid_exim_filter|Use: redirect|Type: boolean|Default: false|
18146 +------------------+-------------+-------------+--------------+
18148 If this option is set true, only Sieve filters are permitted when allow_filter
18151 +-----------+-------------+-------------+--------------+
18152 |forbid_file|Use: redirect|Type: boolean|Default: false|
18153 +-----------+-------------+-------------+--------------+
18155 If this option is true, this router may not generate a new address that
18156 specifies delivery to a local file or directory, either from a filter or from a
18157 conventional forward file. This option is forced to be true if one_time is set.
18158 It applies to Sieve filters as well as to Exim filters, but if true, it locks
18159 out the Sieve's "keep" facility.
18161 +--------------------+-------------+-------------+--------------+
18162 |forbid_filter_dlfunc|Use: redirect|Type: boolean|Default: false|
18163 +--------------------+-------------+-------------+--------------+
18165 If this option is true, string expansions in Exim filters are not allowed to
18166 make use of the dlfunc expansion facility to run dynamically loaded functions.
18168 +------------------------+-------------+-------------+--------------+
18169 |forbid_filter_existstest|Use: redirect|Type: boolean|Default: false|
18170 +------------------------+-------------+-------------+--------------+
18172 If this option is true, string expansions in Exim filters are not allowed to
18173 make use of the exists condition or the stat expansion item.
18175 +----------------------+-------------+-------------+--------------+
18176 |forbid_filter_logwrite|Use: redirect|Type: boolean|Default: false|
18177 +----------------------+-------------+-------------+--------------+
18179 If this option is true, use of the logging facility in Exim filters is not
18180 permitted. Logging is in any case available only if the filter is being run
18181 under some unprivileged uid (which is normally the case for ordinary users'
18184 +--------------------+-------------+-------------+--------------+
18185 |forbid_filter_lookup|Use: redirect|Type: boolean|Default: false|
18186 +--------------------+-------------+-------------+--------------+
18188 If this option is true, string expansions in Exim filter files are not allowed
18189 to make use of lookup items.
18191 +------------------+-------------+-------------+--------------+
18192 |forbid_filter_perl|Use: redirect|Type: boolean|Default: false|
18193 +------------------+-------------+-------------+--------------+
18195 This option has an effect only if Exim is built with embedded Perl support. If
18196 it is true, string expansions in Exim filter files are not allowed to make use
18197 of the embedded Perl support.
18199 +----------------------+-------------+-------------+--------------+
18200 |forbid_filter_readfile|Use: redirect|Type: boolean|Default: false|
18201 +----------------------+-------------+-------------+--------------+
18203 If this option is true, string expansions in Exim filter files are not allowed
18204 to make use of readfile items.
18206 +------------------------+-------------+-------------+--------------+
18207 |forbid_filter_readsocket|Use: redirect|Type: boolean|Default: false|
18208 +------------------------+-------------+-------------+--------------+
18210 If this option is true, string expansions in Exim filter files are not allowed
18211 to make use of readsocket items.
18213 +-------------------+-------------+-------------+--------------+
18214 |forbid_filter_reply|Use: redirect|Type: boolean|Default: false|
18215 +-------------------+-------------+-------------+--------------+
18217 If this option is true, this router may not generate an automatic reply
18218 message. Automatic replies can be generated only from Exim or Sieve filter
18219 files, not from traditional forward files. This option is forced to be true if
18222 +-----------------+-------------+-------------+--------------+
18223 |forbid_filter_run|Use: redirect|Type: boolean|Default: false|
18224 +-----------------+-------------+-------------+--------------+
18226 If this option is true, string expansions in Exim filter files are not allowed
18227 to make use of run items.
18229 +--------------+-------------+-------------+--------------+
18230 |forbid_include|Use: redirect|Type: boolean|Default: false|
18231 +--------------+-------------+-------------+--------------+
18233 If this option is true, items of the form
18235 :include:<path name>
18237 are not permitted in non-filter redirection lists.
18239 +-----------+-------------+-------------+--------------+
18240 |forbid_pipe|Use: redirect|Type: boolean|Default: false|
18241 +-----------+-------------+-------------+--------------+
18243 If this option is true, this router may not generate a new address which
18244 specifies delivery to a pipe, either from an Exim filter or from a conventional
18245 forward file. This option is forced to be true if one_time is set.
18247 +-------------------+-------------+-------------+--------------+
18248 |forbid_sieve_filter|Use: redirect|Type: boolean|Default: false|
18249 +-------------------+-------------+-------------+--------------+
18251 If this option is set true, only Exim filters are permitted when allow_filter
18254 +----------------+-------------+-------------+--------------+
18255 |forbid_smtp_code|Use: redirect|Type: boolean|Default: false|
18256 +----------------+-------------+-------------+--------------+
18258 If this option is set true, any SMTP error codes that are present at the start
18259 of messages specified for ":defer:" or ":fail:" are quietly ignored, and the
18260 default codes (451 and 550, respectively) are always used.
18262 +--------------------+-------------+-------------+--------------+
18263 |hide_child_in_errmsg|Use: redirect|Type: boolean|Default: false|
18264 +--------------------+-------------+-------------+--------------+
18266 If this option is true, it prevents Exim from quoting a child address if it
18267 generates a bounce or delay message for it. Instead it says "an address
18268 generated from <the top level address>". Of course, this applies only to
18269 bounces generated locally. If a message is forwarded to another host, its
18270 bounce may well quote the generated address.
18272 +-------------+-------------+-------------+--------------+
18273 |ignore_eacces|Use: redirect|Type: boolean|Default: false|
18274 +-------------+-------------+-------------+--------------+
18276 If this option is set and an attempt to open a redirection file yields the
18277 EACCES error (permission denied), the redirect router behaves as if the file
18280 +--------------+-------------+-------------+--------------+
18281 |ignore_enotdir|Use: redirect|Type: boolean|Default: false|
18282 +--------------+-------------+-------------+--------------+
18284 If this option is set and an attempt to open a redirection file yields the
18285 ENOTDIR error (something on the path is not a directory), the redirect router
18286 behaves as if the file did not exist.
18288 Setting ignore_enotdir has another effect as well: When a redirect router that
18289 has the file option set discovers that the file does not exist (the ENOENT
18290 error), it tries to stat() the parent directory, as a check against unmounted
18291 NFS directories. If the parent can not be statted, delivery is deferred.
18292 However, it seems wrong to do this check when ignore_enotdir is set, because
18293 that option tells Exim to ignore "something on the path is not a directory"
18294 (the ENOTDIR error). This is a confusing area, because it seems that some
18295 operating systems give ENOENT where others give ENOTDIR.
18297 +-----------------+-------------+------------+--------------+
18298 |include_directory|Use: redirect|Type: string|Default: unset|
18299 +-----------------+-------------+------------+--------------+
18301 If this option is set, the path names of any :include: items in a redirection
18302 list must start with this directory.
18304 +--------+-------------+-------------------+------------+
18305 |modemask|Use: redirect|Type: octal integer|Default: 022|
18306 +--------+-------------+-------------------+------------+
18308 This specifies mode bits which must not be set for a file specified by the file
18309 option. If any of the forbidden bits are set, delivery is deferred.
18311 +--------+-------------+-------------+--------------+
18312 |one_time|Use: redirect|Type: boolean|Default: false|
18313 +--------+-------------+-------------+--------------+
18315 Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
18316 files each time it tries to deliver a message causes a problem when one or more
18317 of the generated addresses fails be delivered at the first attempt. The problem
18318 is not one of duplicate delivery - Exim is clever enough to handle that - but
18319 of what happens when the redirection list changes during the time that the
18320 message is on Exim's queue. This is particularly true in the case of mailing
18321 lists, where new subscribers might receive copies of messages that were posted
18322 before they subscribed.
18324 If one_time is set and any addresses generated by the router fail to deliver at
18325 the first attempt, the failing addresses are added to the message as "top
18326 level" addresses, and the parent address that generated them is marked
18327 "delivered". Thus, redirection does not happen again at the next delivery
18330 Warning 1: Any header line addition or removal that is specified by this router
18331 would be lost if delivery did not succeed at the first attempt. For this
18332 reason, the headers_add and headers_remove generic options are not permitted
18333 when one_time is set.
18335 Warning 2: To ensure that the router generates only addresses (as opposed to
18336 pipe or file deliveries or auto-replies) forbid_file, forbid_pipe, and
18337 forbid_filter_reply are forced to be true when one_time is set.
18339 Warning 3: The unseen generic router option may not be set with one_time.
18341 The original top-level address is remembered with each of the generated
18342 addresses, and is output in any log messages. However, any intermediate parent
18343 addresses are not recorded. This makes a difference to the log only if
18344 all_parents log selector is set. It is expected that one_time will typically be
18345 used for mailing lists, where there is normally just one level of expansion.
18347 +------+-------------+-----------------+--------------+
18348 |owners|Use: redirect|Type: string list|Default: unset|
18349 +------+-------------+-----------------+--------------+
18351 This specifies a list of permitted owners for the file specified by file. This
18352 list is in addition to the local user when check_local_user is set. See
18355 +---------+-------------+-----------------+--------------+
18356 |owngroups|Use: redirect|Type: string list|Default: unset|
18357 +---------+-------------+-----------------+--------------+
18359 This specifies a list of permitted groups for the file specified by file. The
18360 list is in addition to the local user's primary group when check_local_user is
18361 set. See check_group above.
18363 +--------------+-------------+-------------+--------------+
18364 |pipe_transport|Use: redirect|Type: string*|Default: unset|
18365 +--------------+-------------+-------------+--------------+
18367 A redirect router sets up a direct delivery to a pipe when a string starting
18368 with a vertical bar character is specified as a new "address". The transport
18369 used is specified by this option, which, after expansion, must be the name of a
18370 configured transport. This should normally be a pipe transport. When the
18371 transport is run, the pipe command is in $address_pipe.
18373 +--------------+-------------+-------------+--------------+
18374 |qualify_domain|Use: redirect|Type: string*|Default: unset|
18375 +--------------+-------------+-------------+--------------+
18377 If this option is set, and an unqualified address (one without a domain) is
18378 generated, and that address would normally be qualified by the global setting
18379 in qualify_recipient, it is instead qualified with the domain specified by
18380 expanding this string. If the expansion fails, the router declines. If you want
18381 to revert to the default, you can have the expansion generate
18382 $qualify_recipient.
18384 This option applies to all unqualified addresses generated by Exim filters, but
18385 for traditional .forward files, it applies only to addresses that are not
18386 preceded by a backslash. Sieve filters cannot generate unqualified addresses.
18388 +-----------------------+-------------+-------------+--------------+
18389 |qualify_preserve_domain|Use: redirect|Type: boolean|Default: false|
18390 +-----------------------+-------------+-------------+--------------+
18392 If this option is set, the router's local qualify_domain option must not be set
18393 (a configuration error occurs if it is). If an unqualified address (one without
18394 a domain) is generated, it is qualified with the domain of the parent address
18395 (the immediately preceding ancestor) instead of the global qualify_recipient
18396 value. In the case of a traditional .forward file, this applies whether or not
18397 the address is preceded by a backslash.
18399 +----------+-------------+-------------+-------------+
18400 |repeat_use|Use: redirect|Type: boolean|Default: true|
18401 +----------+-------------+-------------+-------------+
18403 If this option is set false, the router is skipped for a child address that has
18404 any ancestor that was routed by this router. This test happens before any of
18405 the other preconditions are tested. Exim's default anti-looping rules skip only
18406 when the ancestor is the same as the current address. See also check_ancestor
18407 above and the generic redirect_router option.
18409 +---------------+-------------+-------------+--------------+
18410 |reply_transport|Use: redirect|Type: string*|Default: unset|
18411 +---------------+-------------+-------------+--------------+
18413 A redirect router sets up an automatic reply when a mail or vacation command is
18414 used in a filter file. The transport used is specified by this option, which,
18415 after expansion, must be the name of a configured transport. This should
18416 normally be an autoreply transport. Other transports are unlikely to do
18417 anything sensible or useful.
18419 +-------+-------------+-------------+-------------+
18420 |rewrite|Use: redirect|Type: boolean|Default: true|
18421 +-------+-------------+-------------+-------------+
18423 If this option is set false, addresses generated by the router are not subject
18424 to address rewriting. Otherwise, they are treated like new addresses and are
18425 rewritten according to the global rewriting rules.
18427 +----------------+-------------+-------------+--------------+
18428 |sieve_subaddress|Use: redirect|Type: string*|Default: unset|
18429 +----------------+-------------+-------------+--------------+
18431 The value of this option is passed to a Sieve filter to specify the :subaddress
18432 part of an address.
18434 +-----------------+-------------+-------------+--------------+
18435 |sieve_useraddress|Use: redirect|Type: string*|Default: unset|
18436 +-----------------+-------------+-------------+--------------+
18438 The value of this option is passed to a Sieve filter to specify the :user part
18439 of an address. However, if it is unset, the entire original local part
18440 (including any prefix or suffix) is used for :user.
18442 +------------------------+-------------+-------------+--------------+
18443 |sieve_vacation_directory|Use: redirect|Type: string*|Default: unset|
18444 +------------------------+-------------+-------------+--------------+
18446 To enable the "vacation" extension for Sieve filters, you must set
18447 sieve_vacation_directory to the directory where vacation databases are held (do
18448 not put anything else in that directory), and ensure that the reply_transport
18449 option refers to an autoreply transport. Each user needs their own directory;
18450 Exim will create it if necessary.
18452 +------------------+-------------+-------------+--------------+
18453 |skip_syntax_errors|Use: redirect|Type: boolean|Default: false|
18454 +------------------+-------------+-------------+--------------+
18456 If skip_syntax_errors is set, syntactically malformed addresses in non-filter
18457 redirection data are skipped, and each failing address is logged. If
18458 syntax_errors_to is set, a message is sent to the address it defines, giving
18459 details of the failures. If syntax_errors_text is set, its contents are
18460 expanded and placed at the head of the error message generated by
18461 syntax_errors_to. Usually it is appropriate to set syntax_errors_to to be the
18462 same address as the generic errors_to option. The skip_syntax_errors option is
18463 often used when handling mailing lists.
18465 If all the addresses in a redirection list are skipped because of syntax
18466 errors, the router declines to handle the original address, and it is passed to
18467 the following routers.
18469 If skip_syntax_errors is set when an Exim filter is interpreted, any syntax
18470 error in the filter causes filtering to be abandoned without any action being
18471 taken. The incident is logged, and the router declines to handle the address,
18472 so it is passed to the following routers.
18474 Syntax errors in a Sieve filter file cause the "keep" action to occur. This
18475 action is specified by RFC 3028. The values of skip_syntax_errors,
18476 syntax_errors_to, and syntax_errors_text are not used.
18478 skip_syntax_errors can be used to specify that errors in users' forward lists
18479 or filter files should not prevent delivery. The syntax_errors_to option, used
18480 with an address that does not get redirected, can be used to notify users of
18481 these errors, by means of a router like this:
18487 file = $home/.forward
18488 file_transport = address_file
18489 pipe_transport = address_pipe
18490 reply_transport = address_reply
18493 syntax_errors_to = real-$local_part@$domain
18494 syntax_errors_text = \
18495 This is an automatically generated message. An error has\n\
18496 been found in your .forward file. Details of the error are\n\
18497 reported below. While this error persists, you will receive\n\
18498 a copy of this message for every message that is addressed\n\
18499 to you. If your .forward file is a filter file, or if it is\n\
18500 a non-filter file containing no valid forwarding addresses,\n\
18501 a copy of each incoming message will be put in your normal\n\
18502 mailbox. If a non-filter file contains at least one valid\n\
18503 forwarding address, forwarding to the valid addresses will\n\
18504 happen, and those will be the only deliveries that occur.
18506 You also need a router to ensure that local addresses that are prefixed by
18507 "real-" are recognized, but not forwarded or filtered. For example, you could
18508 put this immediately before the userforward router:
18513 local_part_prefix = real-
18514 transport = local_delivery
18516 For security, it would probably be a good idea to restrict the use of this
18517 router to locally-generated messages, using a condition such as this:
18519 condition = ${if match {$sender_host_address}\
18520 {\N^(|127\.0\.0\.1)$\N}}
18522 +------------------+-------------+-------------+--------------+
18523 |syntax_errors_text|Use: redirect|Type: string*|Default: unset|
18524 +------------------+-------------+-------------+--------------+
18526 See skip_syntax_errors above.
18528 +----------------+-------------+------------+--------------+
18529 |syntax_errors_to|Use: redirect|Type: string|Default: unset|
18530 +----------------+-------------+------------+--------------+
18532 See skip_syntax_errors above.
18536 ===============================================================================
18537 23. ENVIRONMENT FOR RUNNING LOCAL TRANSPORTS
18539 Local transports handle deliveries to files and pipes. (The autoreply transport
18540 can be thought of as similar to a pipe.) Exim always runs transports in
18541 subprocesses, under specified uids and gids. Typical deliveries to local
18542 mailboxes run under the uid and gid of the local user.
18544 Exim also sets a specific current directory while running the transport; for
18545 some transports a home directory setting is also relevant. The pipe transport
18546 is the only one that sets up environment variables; see section 29.4 for
18549 The values used for the uid, gid, and the directories may come from several
18550 different places. In many cases, the router that handles the address associates
18551 settings with that address as a result of its check_local_user, group, or user
18552 options. However, values may also be given in the transport's own
18553 configuration, and these override anything that comes from the router.
18556 23.1 Concurrent deliveries
18557 --------------------------
18559 If two different messages for the same local recipient arrive more or less
18560 simultaneously, the two delivery processes are likely to run concurrently. When
18561 the appendfile transport is used to write to a file, Exim applies locking rules
18562 to stop concurrent processes from writing to the same file at the same time.
18564 However, when you use a pipe transport, it is up to you to arrange any locking
18565 that is needed. Here is a silly example:
18569 command = /bin/sh -c 'cat >>/some/file'
18571 This is supposed to write the message at the end of the file. However, if two
18572 messages arrive at the same time, the file will be scrambled. You can use the
18573 exim_lock utility program (see section 52.15) to lock a file using the same
18574 algorithm that Exim itself uses.
18580 All transports have the options group and user. If group is set, it overrides
18581 any group that the router set in the address, even if user is not set for the
18582 transport. This makes it possible, for example, to run local mail delivery
18583 under the uid of the recipient (set by the router), but in a special group (set
18584 by the transport). For example:
18587 # User/group are set by check_local_user in this router
18591 transport = group_delivery
18594 # This transport overrides the group
18596 driver = appendfile
18597 file = /var/spool/mail/$local_part
18600 If user is set for a transport, its value overrides what is set in the address
18601 by the router. If user is non-numeric and group is not set, the gid associated
18602 with the user is used. If user is numeric, group must be set.
18604 When the uid is taken from the transport's configuration, the initgroups()
18605 function is called for the groups associated with that uid if the initgroups
18606 option is set for the transport. When the uid is not specified by the
18607 transport, but is associated with the address by a router, the option for
18608 calling initgroups() is taken from the router configuration.
18610 The pipe transport contains the special option pipe_as_creator. If this is set
18611 and user is not set, the uid of the process that called Exim to receive the
18612 message is used, and if group is not set, the corresponding original gid is
18615 This is the detailed preference order for obtaining a gid; the first of the
18616 following that is set is used:
18618 * A group setting of the transport;
18620 * A group setting of the router;
18622 * A gid associated with a user setting of the router, either as a result of
18623 check_local_user or an explicit non-numeric user setting;
18625 * The group associated with a non-numeric user setting of the transport;
18627 * In a pipe transport, the creator's gid if deliver_as_creator is set and the
18628 uid is the creator's uid;
18630 * The Exim gid if the Exim uid is being used as a default.
18632 If, for example, the user is specified numerically on the router and there are
18633 no group settings, no gid is available. In this situation, an error occurs.
18634 This is different for the uid, for which there always is an ultimate default.
18635 The first of the following that is set is used:
18637 * A user setting of the transport;
18639 * In a pipe transport, the creator's uid if deliver_as_creator is set;
18641 * A user setting of the router;
18643 * A check_local_user setting of the router;
18647 Of course, an error will still occur if the uid that is chosen is on the
18651 23.3 Current and home directories
18652 ---------------------------------
18654 Routers may set current and home directories for local transports by means of
18655 the transport_current_directory and transport_home_directory options. However,
18656 if the transport's current_directory or home_directory options are set, they
18657 override the router's values. In detail, the home directory for a local
18658 transport is taken from the first of these values that is set:
18660 * The home_directory option on the transport;
18662 * The transport_home_directory option on the router;
18664 * The password data if check_local_user is set on the router;
18666 * The router_home_directory option on the router.
18668 The current directory is taken from the first of these values that is set:
18670 * The current_directory option on the transport;
18672 * The transport_current_directory option on the router.
18674 If neither the router nor the transport sets a current directory, Exim uses the
18675 value of the home directory, if it is set. Otherwise it sets the current
18676 directory to / before running a local transport.
18679 23.4 Expansion variables derived from the address
18680 -------------------------------------------------
18682 Normally a local delivery is handling a single address, and in that case the
18683 variables such as $domain and $local_part are set during local deliveries.
18684 However, in some circumstances more than one address may be handled at once
18685 (for example, while writing batch SMTP for onward transmission by some other
18686 means). In this case, the variables associated with the local part are never
18687 set, $domain is set only if all the addresses have the same domain, and
18688 $original_domain is never set.
18692 ===============================================================================
18693 24. GENERIC OPTIONS FOR TRANSPORTS
18695 The following generic options apply to all transports:
18697 +---------+---------------+-------------+--------------+
18698 |body_only|Use: transports|Type: boolean|Default: false|
18699 +---------+---------------+-------------+--------------+
18701 If this option is set, the message's headers are not transported. It is
18702 mutually exclusive with headers_only. If it is used with the appendfile or pipe
18703 transports, the settings of message_prefix and message_suffix should be
18704 checked, because this option does not automatically suppress them.
18706 +-----------------+---------------+-------------+--------------+
18707 |current_directory|Use: transports|Type: string*|Default: unset|
18708 +-----------------+---------------+-------------+--------------+
18710 This specifies the current directory that is to be set while running the
18711 transport, overriding any value that may have been set by the router. If the
18712 expansion fails for any reason, including forced failure, an error is logged,
18713 and delivery is deferred.
18715 +---------------+---------------+-------------+--------------+
18716 |disable_logging|Use: transports|Type: boolean|Default: false|
18717 +---------------+---------------+-------------+--------------+
18719 If this option is set true, nothing is logged for any deliveries by the
18720 transport or for any transport errors. You should not set this option unless
18721 you really, really know what you are doing.
18723 +-----------+---------------+-------------+--------------+
18724 |debug_print|Use: transports|Type: string*|Default: unset|
18725 +-----------+---------------+-------------+--------------+
18727 If this option is set and debugging is enabled (see the -d command line
18728 option), the string is expanded and included in the debugging output when the
18729 transport is run. If expansion of the string fails, the error message is
18730 written to the debugging output, and Exim carries on processing. This facility
18731 is provided to help with checking out the values of variables and so on when
18732 debugging driver configurations. For example, if a headers_add option is not
18733 working properly, debug_print could be used to output the variables it
18734 references. A newline is added to the text if it does not end with one. The
18735 variables $transport_name and $router_name contain the name of the transport
18736 and the router that called it.
18738 +-----------------+---------------+-------------+--------------+
18739 |delivery_date_add|Use: transports|Type: boolean|Default: false|
18740 +-----------------+---------------+-------------+--------------+
18742 If this option is true, a Delivery-date: header is added to the message. This
18743 gives the actual time the delivery was made. As this is not a standard header,
18744 Exim has a configuration option (delivery_date_remove) which requests its
18745 removal from incoming messages, so that delivered messages can safely be resent
18746 to other recipients.
18748 +------+---------------+------------+--------------+
18749 |driver|Use: transports|Type: string|Default: unset|
18750 +------+---------------+------------+--------------+
18752 This specifies which of the available transport drivers is to be used. There is
18753 no default, and this option must be set for every transport.
18755 +---------------+---------------+-------------+--------------+
18756 |envelope_to_add|Use: transports|Type: boolean|Default: false|
18757 +---------------+---------------+-------------+--------------+
18759 If this option is true, an Envelope-to: header is added to the message. This
18760 gives the original address(es) in the incoming envelope that caused this
18761 delivery to happen. More than one address may be present if the transport is
18762 configured to handle several addresses at once, or if more than one original
18763 address was redirected to the same final address. As this is not a standard
18764 header, Exim has a configuration option (envelope_to_remove) which requests its
18765 removal from incoming messages, so that delivered messages can safely be resent
18766 to other recipients.
18768 +-----+---------------+-------------+-------------------+
18769 |group|Use: transports|Type: string*|Default: Exim group|
18770 +-----+---------------+-------------+-------------------+
18772 This option specifies a gid for running the transport process, overriding any
18773 value that the router supplies, and also overriding any value associated with
18776 +-----------+---------------+-----------+--------------+
18777 |headers_add|Use: transports|Type: list*|Default: unset|
18778 +-----------+---------------+-----------+--------------+
18780 This option specifies a list of text headers, newline-separated, which are
18781 (separately) expanded and added to the header portion of a message as it is
18782 transported, as described in section 46.17. Additional header lines can also be
18783 specified by routers. If the result of the expansion is an empty string, or if
18784 the expansion is forced to fail, no action is taken. Other expansion failures
18785 are treated as errors and cause the delivery to be deferred.
18787 Unlike most options, headers_add can be specified multiple times for a
18788 transport; all listed headers are added.
18790 +------------+---------------+-------------+--------------+
18791 |headers_only|Use: transports|Type: boolean|Default: false|
18792 +------------+---------------+-------------+--------------+
18794 If this option is set, the message's body is not transported. It is mutually
18795 exclusive with body_only. If it is used with the appendfile or pipe transports,
18796 the settings of message_prefix and message_suffix should be checked, since this
18797 option does not automatically suppress them.
18799 +--------------+---------------+-----------+--------------+
18800 |headers_remove|Use: transports|Type: list*|Default: unset|
18801 +--------------+---------------+-----------+--------------+
18803 This option specifies a list of header names, colon-separated; these headers
18804 are omitted from the message as it is transported, as described in section
18805 46.17. Header removal can also be specified by routers. Each list item is
18806 separately expanded. If the result of the expansion is an empty string, or if
18807 the expansion is forced to fail, no action is taken. Other expansion failures
18808 are treated as errors and cause the delivery to be deferred.
18810 Unlike most options, headers_remove can be specified multiple times for a
18811 router; all listed headers are removed.
18813 +---------------+---------------+------------+--------------+
18814 |headers_rewrite|Use: transports|Type: string|Default: unset|
18815 +---------------+---------------+------------+--------------+
18817 This option allows addresses in header lines to be rewritten at transport time,
18818 that is, as the message is being copied to its destination. The contents of the
18819 option are a colon-separated list of rewriting rules. Each rule is in exactly
18820 the same form as one of the general rewriting rules that are applied when a
18821 message is received. These are described in chapter 31. For example,
18823 headers_rewrite = a@b c@d f : \
18826 changes a@b into c@d in From: header lines, and x@y into w@z in all
18827 address-bearing header lines. The rules are applied to the header lines just
18828 before they are written out at transport time, so they affect only those copies
18829 of the message that pass through the transport. However, only the message's
18830 original header lines, and any that were added by a system filter, are
18831 rewritten. If a router or transport adds header lines, they are not affected by
18832 this option. These rewriting rules are not applied to the envelope. You can
18833 change the return path using return_path, but you cannot change envelope
18834 recipients at this time.
18836 +--------------+---------------+-------------+--------------+
18837 |home_directory|Use: transports|Type: string*|Default: unset|
18838 +--------------+---------------+-------------+--------------+
18840 This option specifies a home directory setting for a local transport,
18841 overriding any value that may be set by the router. The home directory is
18842 placed in $home while expanding the transport's private options. It is also
18843 used as the current directory if no current directory is set by the
18844 current_directory option on the transport or the transport_current_directory
18845 option on the router. If the expansion fails for any reason, including forced
18846 failure, an error is logged, and delivery is deferred.
18848 +----------+---------------+-------------+--------------+
18849 |initgroups|Use: transports|Type: boolean|Default: false|
18850 +----------+---------------+-------------+--------------+
18852 If this option is true and the uid for the delivery process is provided by the
18853 transport, the initgroups() function is called when running the transport to
18854 ensure that any additional groups associated with the uid are set up.
18856 +------------------+---------------+-------------+----------+
18857 |message_size_limit|Use: transports|Type: string*|Default: 0|
18858 +------------------+---------------+-------------+----------+
18860 This option controls the size of messages passed through the transport. It is
18861 expanded before use; the result of the expansion must be a sequence of decimal
18862 digits, optionally followed by K or M. If the expansion fails for any reason,
18863 including forced failure, or if the result is not of the required form,
18864 delivery is deferred. If the value is greater than zero and the size of a
18865 message exceeds this limit, the address is failed. If there is any chance that
18866 the resulting bounce message could be routed to the same transport, you should
18867 ensure that return_size_limit is less than the transport's message_size_limit,
18868 as otherwise the bounce message will fail to get delivered.
18870 +--------------------+---------------+-------------+--------------+
18871 |rcpt_include_affixes|Use: transports|Type: boolean|Default: false|
18872 +--------------------+---------------+-------------+--------------+
18874 When this option is false (the default), and an address that has had any
18875 affixes (prefixes or suffixes) removed from the local part is delivered by any
18876 form of SMTP or LMTP, the affixes are not included. For example, if a router
18879 local_part_prefix = *-
18881 routes the address abc-xyz@some.domain to an SMTP transport, the envelope is
18884 RCPT TO:<xyz@some.domain>
18886 This is also the case when an ACL-time callout is being used to verify a
18887 recipient address. However, if rcpt_include_affixes is set true, the whole
18888 local part is included in the RCPT command. This option applies to BSMTP
18889 deliveries by the appendfile and pipe transports as well as to the lmtp and
18892 +--------------------+---------------+-------------+------------------+
18893 |retry_use_local_part|Use: transports|Type: boolean|Default: see below|
18894 +--------------------+---------------+-------------+------------------+
18896 When a delivery suffers a temporary failure, a retry record is created in
18897 Exim's hints database. For remote deliveries, the key for the retry record is
18898 based on the name and/or IP address of the failing remote host. For local
18899 deliveries, the key is normally the entire address, including both the local
18900 part and the domain. This is suitable for most common cases of local delivery
18901 temporary failure - for example, exceeding a mailbox quota should delay only
18902 deliveries to that mailbox, not to the whole domain.
18904 However, in some special cases you may want to treat a temporary local delivery
18905 as a failure associated with the domain, and not with a particular local part.
18906 (For example, if you are storing all mail for some domain in files.) You can do
18907 this by setting retry_use_local_part false.
18909 For all the local transports, its default value is true. For remote transports,
18910 the default value is false for tidiness, but changing the value has no effect
18911 on a remote transport in the current implementation.
18913 +-----------+---------------+-------------+--------------+
18914 |return_path|Use: transports|Type: string*|Default: unset|
18915 +-----------+---------------+-------------+--------------+
18917 If this option is set, the string is expanded at transport time and replaces
18918 the existing return path (envelope sender) value in the copy of the message
18919 that is being delivered. An empty return path is permitted. This feature is
18920 designed for remote deliveries, where the value of this option is used in the
18921 SMTP MAIL command. If you set return_path for a local transport, the only
18922 effect is to change the address that is placed in the Return-path: header line,
18923 if one is added to the message (see the next option).
18925 Note: A changed return path is not logged unless you add
18926 return_path_on_delivery to the log selector.
18928 The expansion can refer to the existing value via $return_path. This is either
18929 the message's envelope sender, or an address set by the errors_to option on a
18930 router. If the expansion is forced to fail, no replacement occurs; if it fails
18931 for another reason, delivery is deferred. This option can be used to support
18932 VERP (Variable Envelope Return Paths) - see section 49.6.
18934 Note: If a delivery error is detected locally, including the case when a remote
18935 server rejects a message at SMTP time, the bounce message is not sent to the
18936 value of this option. It is sent to the previously set errors address. This
18937 defaults to the incoming sender address, but can be changed by setting
18938 errors_to in a router.
18940 +---------------+---------------+-------------+--------------+
18941 |return_path_add|Use: transports|Type: boolean|Default: false|
18942 +---------------+---------------+-------------+--------------+
18944 If this option is true, a Return-path: header is added to the message. Although
18945 the return path is normally available in the prefix line of BSD mailboxes, this
18946 is commonly not displayed by MUAs, and so the user does not have easy access to
18949 RFC 2821 states that the Return-path: header is added to a message "when the
18950 delivery SMTP server makes the final delivery". This implies that this header
18951 should not be present in incoming messages. Exim has a configuration option,
18952 return_path_remove, which requests removal of this header from incoming
18953 messages, so that delivered messages can safely be resent to other recipients.
18955 +----------------+---------------+-------------+--------------+
18956 |shadow_condition|Use: transports|Type: string*|Default: unset|
18957 +----------------+---------------+-------------+--------------+
18959 See shadow_transport below.
18961 +----------------+---------------+------------+--------------+
18962 |shadow_transport|Use: transports|Type: string|Default: unset|
18963 +----------------+---------------+------------+--------------+
18965 A local transport may set the shadow_transport option to the name of another
18966 local transport. Shadow remote transports are not supported.
18968 Whenever a delivery to the main transport succeeds, and either shadow_condition
18969 is unset, or its expansion does not result in the empty string or one of the
18970 strings "0" or "no" or "false", the message is also passed to the shadow
18971 transport, with the same delivery address or addresses. If expansion fails, no
18972 action is taken except that non-forced expansion failures cause a log line to
18975 The result of the shadow transport is discarded and does not affect the
18976 subsequent processing of the message. Only a single level of shadowing is
18977 provided; the shadow_transport option is ignored on any transport when it is
18978 running as a shadow. Options concerned with output from pipes are also ignored.
18979 The log line for the successful delivery has an item added on the end, of the
18982 ST=<shadow transport name>
18984 If the shadow transport did not succeed, the error message is put in
18985 parentheses afterwards. Shadow transports can be used for a number of different
18986 purposes, including keeping more detailed log information than Exim normally
18987 provides, and implementing automatic acknowledgment policies based on message
18988 headers that some sites insist on.
18990 +----------------+---------------+-------------+--------------+
18991 |transport_filter|Use: transports|Type: string*|Default: unset|
18992 +----------------+---------------+-------------+--------------+
18994 This option sets up a filtering (in the Unix shell sense) process for messages
18995 at transport time. It should not be confused with mail filtering as set up by
18996 individual users or via a system filter.
18998 When the message is about to be written out, the command specified by
18999 transport_filter is started up in a separate, parallel process, and the entire
19000 message, including the header lines, is passed to it on its standard input
19001 (this in fact is done from a third process, to avoid deadlock). The command
19002 must be specified as an absolute path.
19004 The lines of the message that are written to the transport filter are
19005 terminated by newline ("\n"). The message is passed to the filter before any
19006 SMTP-specific processing, such as turning "\n" into "\r\n" and escaping lines
19007 beginning with a dot, and also before any processing implied by the settings of
19008 check_string and escape_string in the appendfile or pipe transports.
19010 The standard error for the filter process is set to the same destination as its
19011 standard output; this is read and written to the message's ultimate
19012 destination. The process that writes the message to the filter, the filter
19013 itself, and the original process that reads the result and delivers it are all
19014 run in parallel, like a shell pipeline.
19016 The filter can perform any transformations it likes, but of course should take
19017 care not to break RFC 2822 syntax. Exim does not check the result, except to
19018 test for a final newline when SMTP is in use. All messages transmitted over
19019 SMTP must end with a newline, so Exim supplies one if it is missing.
19021 A transport filter can be used to provide content-scanning on a per-user basis
19022 at delivery time if the only required effect of the scan is to modify the
19023 message. For example, a content scan could insert a new header line containing
19024 a spam score. This could be interpreted by a filter in the user's MUA. It is
19025 not possible to discard a message at this stage.
19027 A problem might arise if the filter increases the size of a message that is
19028 being sent down an SMTP connection. If the receiving SMTP server has indicated
19029 support for the SIZE parameter, Exim will have sent the size of the message at
19030 the start of the SMTP session. If what is actually sent is substantially more,
19031 the server might reject the message. This can be worked round by setting the
19032 size_addition option on the smtp transport, either to allow for additions to
19033 the message, or to disable the use of SIZE altogether.
19035 The value of the transport_filter option is the command string for starting the
19036 filter, which is run directly from Exim, not under a shell. The string is
19037 parsed by Exim in the same way as a command string for the pipe transport: Exim
19038 breaks it up into arguments and then expands each argument separately (see
19039 section 29.3). Any kind of expansion failure causes delivery to be deferred.
19040 The special argument $pipe_addresses is replaced by a number of arguments, one
19041 for each address that applies to this delivery. (This isn't an ideal name for
19042 this feature here, but as it was already implemented for the pipe transport, it
19043 seemed sensible not to change it.)
19045 The expansion variables $host and $host_address are available when the
19046 transport is a remote one. They contain the name and IP address of the host to
19047 which the message is being sent. For example:
19049 transport_filter = /some/directory/transport-filter.pl \
19050 $host $host_address $sender_address $pipe_addresses
19052 Two problems arise if you want to use more complicated expansion items to
19053 generate transport filter commands, both of which due to the fact that the
19054 command is split up before expansion.
19056 * If an expansion item contains white space, you must quote it, so that it is
19057 all part of the same command item. If the entire option setting is one such
19058 expansion item, you have to take care what kind of quoting you use. For
19061 transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
19063 This runs the command /bin/cmd1 if the host name is a.b.c, and /bin/cmd2
19064 otherwise. If double quotes had been used, they would have been stripped by
19065 Exim when it read the option's value. When the value is used, if the single
19066 quotes were missing, the line would be split into two items, "/bin/cmd${if"
19067 and "eq{$host}{a.b.c}{1}{2}", and an error would occur when Exim tried to
19068 expand the first one.
19070 * Except for the special case of $pipe_addresses that is mentioned above, an
19071 expansion cannot generate multiple arguments, or a command name followed by
19072 arguments. Consider this example:
19074 transport_filter = ${lookup{$host}lsearch{/a/file}\
19075 {$value}{/bin/cat}}
19077 The result of the lookup is interpreted as the name of the command, even if
19078 it contains white space. The simplest way round this is to use a shell:
19080 transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\
19081 {$value}{/bin/cat}}
19083 The filter process is run under the same uid and gid as the normal delivery.
19084 For remote deliveries this is the Exim uid/gid by default. The command should
19085 normally yield a zero return code. Transport filters are not supposed to fail.
19086 A non-zero code is taken to mean that the transport filter encountered some
19087 serious problem. Delivery of the message is deferred; the message remains on
19088 the queue and is tried again later. It is not possible to cause a message to be
19089 bounced from a transport filter.
19091 If a transport filter is set on an autoreply transport, the original message is
19092 passed through the filter as it is being copied into the newly generated
19093 message, which happens if the return_message option is set.
19095 +------------------------+---------------+----------+-----------+
19096 |transport_filter_timeout|Use: transports|Type: time|Default: 5m|
19097 +------------------------+---------------+----------+-----------+
19099 When Exim is reading the output of a transport filter, it applies a timeout
19100 that can be set by this option. Exceeding the timeout is normally treated as a
19101 temporary delivery failure. However, if a transport filter is used with a pipe
19102 transport, a timeout in the transport filter is treated in the same way as a
19103 timeout in the pipe command itself. By default, a timeout is a hard error, but
19104 if the pipe transport's timeout_defer option is set true, it becomes a
19107 +----+---------------+-------------+------------------+
19108 |user|Use: transports|Type: string*|Default: Exim user|
19109 +----+---------------+-------------+------------------+
19111 This option specifies the user under whose uid the delivery process is to be
19112 run, overriding any uid that may have been set by the router. If the user is
19113 given as a name, the uid is looked up from the password data, and the
19114 associated group is taken as the value of the gid to be used if the group
19117 For deliveries that use local transports, a user and group are normally
19118 specified explicitly or implicitly (for example, as a result of
19119 check_local_user) by the router or transport.
19121 For remote transports, you should leave this option unset unless you really are
19122 sure you know what you are doing. When a remote transport is running, it needs
19123 to be able to access Exim's hints databases, because each host may have its own
19128 ===============================================================================
19129 25. ADDRESS BATCHING IN LOCAL TRANSPORTS
19131 The only remote transport (smtp) is normally configured to handle more than one
19132 address at a time, so that when several addresses are routed to the same remote
19133 host, just one copy of the message is sent. Local transports, however, normally
19134 handle one address at a time. That is, a separate instance of the transport is
19135 run for each address that is routed to the transport. A separate copy of the
19136 message is delivered each time.
19138 In special cases, it may be desirable to handle several addresses at once in a
19139 local transport, for example:
19141 * In an appendfile transport, when storing messages in files for later
19142 delivery by some other means, a single copy of the message with multiple
19143 recipients saves space.
19145 * In an lmtp transport, when delivering over "local SMTP" to some process, a
19146 single copy saves time, and is the normal way LMTP is expected to work.
19148 * In a pipe transport, when passing the message to a scanner program or to
19149 some other delivery mechanism such as UUCP, multiple recipients may be
19152 These three local transports all have the same options for controlling multiple
19153 ("batched") deliveries, namely batch_max and batch_id. To save repeating the
19154 information for each transport, these options are described here.
19156 The batch_max option specifies the maximum number of addresses that can be
19157 delivered together in a single run of the transport. Its default value is one
19158 (no batching). When more than one address is routed to a transport that has a
19159 batch_max value greater than one, the addresses are delivered in a batch (that
19160 is, in a single run of the transport with multiple recipients), subject to
19161 certain conditions:
19163 * If any of the transport's options contain a reference to $local_part, no
19164 batching is possible.
19166 * If any of the transport's options contain a reference to $domain, only
19167 addresses with the same domain are batched.
19169 * If batch_id is set, it is expanded for each address, and only those
19170 addresses with the same expanded value are batched. This allows you to
19171 specify customized batching conditions. Failure of the expansion for any
19172 reason, including forced failure, disables batching, but it does not stop
19173 the delivery from taking place.
19175 * Batched addresses must also have the same errors address (where to send
19176 delivery errors), the same header additions and removals, the same user and
19177 group for the transport, and if a host list is present, the first host must
19180 In the case of the appendfile and pipe transports, batching applies both when
19181 the file or pipe command is specified in the transport, and when it is
19182 specified by a redirect router, but all the batched addresses must of course be
19183 routed to the same file or pipe command. These two transports have an option
19184 called use_bsmtp, which causes them to deliver the message in "batched SMTP"
19185 format, with the envelope represented as SMTP commands. The check_string and
19186 escape_string options are forced to the values
19189 escape_string = ".."
19191 when batched SMTP is in use. A full description of the batch SMTP mechanism is
19192 given in section 47.10. The lmtp transport does not have a use_bsmtp option,
19193 because it always delivers using the SMTP protocol.
19195 If the generic envelope_to_add option is set for a batching transport, the
19196 Envelope-to: header that is added to the message contains all the addresses
19197 that are being processed together. If you are using a batching appendfile
19198 transport without use_bsmtp, the only way to preserve the recipient addresses
19199 is to set the envelope_to_add option.
19201 If you are using a pipe transport without BSMTP, and setting the transport's
19202 command option, you can include $pipe_addresses as part of the command. This is
19203 not a true variable; it is a bit of magic that causes each of the recipient
19204 addresses to be inserted into the command as a separate argument. This provides
19205 a way of accessing all the addresses that are being delivered in the batch.
19206 Note: This is not possible for pipe commands that are specified by a redirect
19211 ===============================================================================
19212 26. THE APPENDFILE TRANSPORT
19214 The appendfile transport delivers a message by appending it to an existing
19215 file, or by creating an entirely new file in a specified directory. Single
19216 files to which messages are appended can be in the traditional Unix mailbox
19217 format, or optionally in the MBX format supported by the Pine MUA and
19218 University of Washington IMAP daemon, inter alia. When each message is being
19219 delivered as a separate file, "maildir" format can optionally be used to give
19220 added protection against failures that happen part-way through the delivery. A
19221 third form of separate-file delivery known as "mailstore" is also supported.
19222 For all file formats, Exim attempts to create as many levels of directory as
19223 necessary, provided that create_directory is set.
19225 The code for the optional formats is not included in the Exim binary by
19226 default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or
19227 SUPPORT_MAILSTORE in Local/Makefile to have the appropriate code included.
19229 Exim recognizes system quota errors, and generates an appropriate message. Exim
19230 also supports its own quota control within the transport, for use when the
19231 system facility is unavailable or cannot be used for some reason.
19233 If there is an error while appending to a file (for example, quota exceeded or
19234 partition filled), Exim attempts to reset the file's length and last
19235 modification time back to what they were before. If there is an error while
19236 creating an entirely new file, the new file is removed.
19238 Before appending to a file, a number of security checks are made, and the file
19239 is locked. A detailed description is given below, after the list of private
19242 The appendfile transport is most commonly used for local deliveries to users'
19243 mailboxes. However, it can also be used as a pseudo-remote transport for
19244 putting messages into files for remote delivery by some means other than Exim.
19245 "Batch SMTP" format is often used in this case (see the use_bsmtp option).
19248 26.1 The file and directory options
19249 -----------------------------------
19251 The file option specifies a single file, to which the message is appended; the
19252 directory option specifies a directory, in which a new file containing the
19253 message is created. Only one of these two options can be set, and for normal
19254 deliveries to mailboxes, one of them must be set.
19256 However, appendfile is also used for delivering messages to files or
19257 directories whose names (or parts of names) are obtained from alias,
19258 forwarding, or filtering operations (for example, a save command in a user's
19259 Exim filter). When such a transport is running, $local_part contains the local
19260 part that was aliased or forwarded, and $address_file contains the name (or
19261 partial name) of the file or directory generated by the redirection operation.
19262 There are two cases:
19264 * If neither file nor directory is set, the redirection operation must
19265 specify an absolute path (one that begins with "/"). This is the most
19266 common case when users with local accounts use filtering to sort mail into
19267 different folders. See for example, the address_file transport in the
19268 default configuration. If the path ends with a slash, it is assumed to be
19269 the name of a directory. A delivery to a directory can also be forced by
19270 setting maildir_format or mailstore_format.
19272 * If file or directory is set for a delivery from a redirection, it is used
19273 to determine the file or directory name for the delivery. Normally, the
19274 contents of $address_file are used in some way in the string expansion.
19276 As an example of the second case, consider an environment where users do not
19277 have home directories. They may be permitted to use Exim filter commands of the
19282 or Sieve filter commands of the form:
19284 require "fileinto";
19285 fileinto "folder23";
19287 In this situation, the expansion of file or directory in the transport must
19288 transform the relative path into an appropriate absolute file name. In the case
19289 of Sieve filters, the name inbox must be handled. It is the name that is used
19290 as a result of a "keep" action in the filter. This example shows one way of
19291 handling this requirement:
19293 file = ${if eq{$address_file}{inbox} \
19294 {/var/mail/$local_part} \
19295 {${if eq{${substr_0_1:$address_file}}{/} \
19297 {$home/mail/$address_file} \
19301 With this setting of file, inbox refers to the standard mailbox location,
19302 absolute paths are used without change, and other folders are in the mail
19303 directory within the home directory.
19305 Note 1: While processing an Exim filter, a relative path such as folder23 is
19306 turned into an absolute path if a home directory is known to the router. In
19307 particular, this is the case if check_local_user is set. If you want to prevent
19308 this happening at routing time, you can set router_home_directory empty. This
19309 forces the router to pass the relative path to the transport.
19311 Note 2: An absolute path in $address_file is not treated specially; the file or
19312 directory option is still used if it is set.
19315 26.2 Private options for appendfile
19316 -----------------------------------
19318 +----------+---------------+-------------+--------------+
19319 |allow_fifo|Use: appendfile|Type: boolean|Default: false|
19320 +----------+---------------+-------------+--------------+
19322 Setting this option permits delivery to named pipes (FIFOs) as well as to
19323 regular files. If no process is reading the named pipe at delivery time, the
19324 delivery is deferred.
19326 +-------------+---------------+-------------+--------------+
19327 |allow_symlink|Use: appendfile|Type: boolean|Default: false|
19328 +-------------+---------------+-------------+--------------+
19330 By default, appendfile will not deliver if the path name for the file is that
19331 of a symbolic link. Setting this option relaxes that constraint, but there are
19332 security issues involved in the use of symbolic links. Be sure you know what
19333 you are doing if you set this. Details of exactly what this option affects are
19334 included in the discussion which follows this list of options.
19336 +--------+---------------+-------------+--------------+
19337 |batch_id|Use: appendfile|Type: string*|Default: unset|
19338 +--------+---------------+-------------+--------------+
19340 See the description of local delivery batching in chapter 25. However, batching
19341 is automatically disabled for appendfile deliveries that happen as a result of
19342 forwarding or aliasing or other redirection directly to a file.
19344 +---------+---------------+-------------+----------+
19345 |batch_max|Use: appendfile|Type: integer|Default: 1|
19346 +---------+---------------+-------------+----------+
19348 See the description of local delivery batching in chapter 25.
19350 +-----------+---------------+-------------+--------------+
19351 |check_group|Use: appendfile|Type: boolean|Default: false|
19352 +-----------+---------------+-------------+--------------+
19354 When this option is set, the group owner of the file defined by the file option
19355 is checked to see that it is the same as the group under which the delivery
19356 process is running. The default setting is false because the default file mode
19357 is 0600, which means that the group is irrelevant.
19359 +-----------+---------------+-------------+-------------+
19360 |check_owner|Use: appendfile|Type: boolean|Default: true|
19361 +-----------+---------------+-------------+-------------+
19363 When this option is set, the owner of the file defined by the file option is
19364 checked to ensure that it is the same as the user under which the delivery
19365 process is running.
19367 +------------+---------------+------------+------------------+
19368 |check_string|Use: appendfile|Type: string|Default: see below|
19369 +------------+---------------+------------+------------------+
19371 As appendfile writes the message, the start of each line is tested for matching
19372 check_string, and if it does, the initial matching characters are replaced by
19373 the contents of escape_string. The value of check_string is a literal string,
19374 not a regular expression, and the case of any letters it contains is
19377 If use_bsmtp is set the values of check_string and escape_string are forced to
19378 "." and ".." respectively, and any settings in the configuration are ignored.
19379 Otherwise, they default to "From " and ">From " when the file option is set,
19380 and unset when any of the directory, maildir, or mailstore options are set.
19382 The default settings, along with message_prefix and message_suffix, are
19383 suitable for traditional "BSD" mailboxes, where a line beginning with "From "
19384 indicates the start of a new message. All four options need changing if another
19385 format is used. For example, to deliver to mailboxes in MMDF format:
19387 check_string = "\1\1\1\1\n"
19388 escape_string = "\1\1\1\1 \n"
19389 message_prefix = "\1\1\1\1\n"
19390 message_suffix = "\1\1\1\1\n"
19392 +----------------+---------------+-------------+-------------+
19393 |create_directory|Use: appendfile|Type: boolean|Default: true|
19394 +----------------+---------------+-------------+-------------+
19396 When this option is true, Exim attempts to create any missing superior
19397 directories for the file that it is about to write. A created directory's mode
19398 is given by the directory_mode option.
19400 The group ownership of a newly created directory is highly dependent on the
19401 operating system (and possibly the file system) that is being used. For
19402 example, in Solaris, if the parent directory has the setgid bit set, its group
19403 is propagated to the child; if not, the currently set group is used. However,
19404 in FreeBSD, the parent's group is always used.
19406 +-----------+---------------+------------+-----------------+
19407 |create_file|Use: appendfile|Type: string|Default: anywhere|
19408 +-----------+---------------+------------+-----------------+
19410 This option constrains the location of files and directories that are created
19411 by this transport. It applies to files defined by the file option and
19412 directories defined by the directory option. In the case of maildir delivery,
19413 it applies to the top level directory, not the maildir directories beneath.
19415 The option must be set to one of the words "anywhere", "inhome", or
19416 "belowhome". In the second and third cases, a home directory must have been set
19417 for the transport. This option is not useful when an explicit file name is
19418 given for normal mailbox deliveries. It is intended for the case when file
19419 names are generated from users' .forward files. These are usually handled by an
19420 appendfile transport called address_file. See also file_must_exist.
19422 +---------+---------------+-------------+--------------+
19423 |directory|Use: appendfile|Type: string*|Default: unset|
19424 +---------+---------------+-------------+--------------+
19426 This option is mutually exclusive with the file option, but one of file or
19427 directory must be set, unless the delivery is the direct result of a
19428 redirection (see section 26.1).
19430 When directory is set, the string is expanded, and the message is delivered
19431 into a new file or files in or below the given directory, instead of being
19432 appended to a single mailbox file. A number of different formats are provided
19433 (see maildir_format and mailstore_format), and see section 26.4 for further
19434 details of this form of delivery.
19436 +--------------+---------------+-------------+------------------+
19437 |directory_file|Use: appendfile|Type: string*|Default: see below|
19438 +--------------+---------------+-------------+------------------+
19440 When directory is set, but neither maildir_format nor mailstore_format is set,
19441 appendfile delivers each message into a file whose name is obtained by
19442 expanding this string. The default value is:
19444 q${base62:$tod_epoch}-$inode
19446 This generates a unique name from the current time, in base 62 form, and the
19447 inode of the file. The variable $inode is available only when expanding this
19450 +--------------+---------------+-------------------+-------------+
19451 |directory_mode|Use: appendfile|Type: octal integer|Default: 0700|
19452 +--------------+---------------+-------------------+-------------+
19454 If appendfile creates any directories as a result of the create_directory
19455 option, their mode is specified by this option.
19457 +-------------+---------------+------------+------------------------+
19458 |escape_string|Use: appendfile|Type: string|Default: see description|
19459 +-------------+---------------+------------+------------------------+
19461 See check_string above.
19463 +----+---------------+-------------+--------------+
19464 |file|Use: appendfile|Type: string*|Default: unset|
19465 +----+---------------+-------------+--------------+
19467 This option is mutually exclusive with the directory option, but one of file or
19468 directory must be set, unless the delivery is the direct result of a
19469 redirection (see section 26.1). The file option specifies a single file, to
19470 which the message is appended. One or more of use_fcntl_lock, use_flock_lock,
19471 or use_lockfile must be set with file.
19473 If you are using more than one host to deliver over NFS into the same
19474 mailboxes, you should always use lock files.
19476 The string value is expanded for each delivery, and must yield an absolute
19477 path. The most common settings of this option are variations on one of these
19480 file = /var/spool/mail/$local_part
19481 file = /home/$local_part/inbox
19484 In the first example, all deliveries are done into the same directory. If Exim
19485 is configured to use lock files (see use_lockfile below) it must be able to
19486 create a file in the directory, so the "sticky" bit must be turned on for
19487 deliveries to be possible, or alternatively the group option can be used to run
19488 the delivery under a group id which has write access to the directory.
19490 +-----------+---------------+------------+--------------+
19491 |file_format|Use: appendfile|Type: string|Default: unset|
19492 +-----------+---------------+------------+--------------+
19494 This option requests the transport to check the format of an existing file
19495 before adding to it. The check consists of matching a specific string at the
19496 start of the file. The value of the option consists of an even number of
19497 colon-separated strings. The first of each pair is the test string, and the
19498 second is the name of a transport. If the transport associated with a matched
19499 string is not the current transport, control is passed over to the other
19500 transport. For example, suppose the standard local_delivery transport has this
19503 file_format = "From : local_delivery :\
19504 \1\1\1\1\n : local_mmdf_delivery"
19506 Mailboxes that begin with "From" are still handled by this transport, but if a
19507 mailbox begins with four binary ones followed by a newline, control is passed
19508 to a transport called local_mmdf_delivery, which presumably is configured to do
19509 the delivery in MMDF format. If a mailbox does not exist or is empty, it is
19510 assumed to match the current transport. If the start of a mailbox doesn't match
19511 any string, or if the transport named for a given string is not defined,
19512 delivery is deferred.
19514 +---------------+---------------+-------------+--------------+
19515 |file_must_exist|Use: appendfile|Type: boolean|Default: false|
19516 +---------------+---------------+-------------+--------------+
19518 If this option is true, the file specified by the file option must exist. A
19519 temporary error occurs if it does not, causing delivery to be deferred. If this
19520 option is false, the file is created if it does not exist.
19522 +------------------+---------------+----------+-----------+
19523 |lock_fcntl_timeout|Use: appendfile|Type: time|Default: 0s|
19524 +------------------+---------------+----------+-----------+
19526 By default, the appendfile transport uses non-blocking calls to fcntl() when
19527 locking an open mailbox file. If the call fails, the delivery process sleeps
19528 for lock_interval and tries again, up to lock_retries times. Non-blocking calls
19529 are used so that the file is not kept open during the wait for the lock; the
19530 reason for this is to make it as safe as possible for deliveries over NFS in
19531 the case when processes might be accessing an NFS mailbox without using a lock
19532 file. This should not be done, but misunderstandings and hence
19533 misconfigurations are not unknown.
19535 On a busy system, however, the performance of a non-blocking lock approach is
19536 not as good as using a blocking lock with a timeout. In this case, the waiting
19537 is done inside the system call, and Exim's delivery process acquires the lock
19538 and can proceed as soon as the previous lock holder releases it.
19540 If lock_fcntl_timeout is set to a non-zero time, blocking locks, with that
19541 timeout, are used. There may still be some retrying: the maximum number of
19544 (lock_retries * lock_interval) / lock_fcntl_timeout
19546 rounded up to the next whole number. In other words, the total time during
19547 which appendfile is trying to get a lock is roughly the same, unless
19548 lock_fcntl_timeout is set very large.
19550 You should consider setting this option if you are getting a lot of delayed
19551 local deliveries because of errors of the form
19553 failed to lock mailbox /some/file (fcntl)
19555 +------------------+---------------+----------+-----------+
19556 |lock_flock_timeout|Use: appendfile|Type: time|Default: 0s|
19557 +------------------+---------------+----------+-----------+
19559 This timeout applies to file locking when using flock() (see use_flock); the
19560 timeout operates in a similar manner to lock_fcntl_timeout.
19562 +-------------+---------------+----------+-----------+
19563 |lock_interval|Use: appendfile|Type: time|Default: 3s|
19564 +-------------+---------------+----------+-----------+
19566 This specifies the time to wait between attempts to lock the file. See below
19567 for details of locking.
19569 +------------+---------------+-------------+-----------+
19570 |lock_retries|Use: appendfile|Type: integer|Default: 10|
19571 +------------+---------------+-------------+-----------+
19573 This specifies the maximum number of attempts to lock the file. A value of zero
19574 is treated as 1. See below for details of locking.
19576 +-------------+---------------+-------------------+-------------+
19577 |lockfile_mode|Use: appendfile|Type: octal integer|Default: 0600|
19578 +-------------+---------------+-------------------+-------------+
19580 This specifies the mode of the created lock file, when a lock file is being
19581 used (see use_lockfile and use_mbx_lock).
19583 +----------------+---------------+----------+------------+
19584 |lockfile_timeout|Use: appendfile|Type: time|Default: 30m|
19585 +----------------+---------------+----------+------------+
19587 When a lock file is being used (see use_lockfile), if a lock file already
19588 exists and is older than this value, it is assumed to have been left behind by
19589 accident, and Exim attempts to remove it.
19591 +-----------------+---------------+-------------+--------------+
19592 |mailbox_filecount|Use: appendfile|Type: string*|Default: unset|
19593 +-----------------+---------------+-------------+--------------+
19595 If this option is set, it is expanded, and the result is taken as the current
19596 number of files in the mailbox. It must be a decimal number, optionally
19597 followed by K or M. This provides a way of obtaining this information from an
19598 external source that maintains the data.
19600 +------------+---------------+-------------+--------------+
19601 |mailbox_size|Use: appendfile|Type: string*|Default: unset|
19602 +------------+---------------+-------------+--------------+
19604 If this option is set, it is expanded, and the result is taken as the current
19605 size the mailbox. It must be a decimal number, optionally followed by K or M.
19606 This provides a way of obtaining this information from an external source that
19607 maintains the data. This is likely to be helpful for maildir deliveries where
19608 it is computationally expensive to compute the size of a mailbox.
19610 +--------------+---------------+-------------+--------------+
19611 |maildir_format|Use: appendfile|Type: boolean|Default: false|
19612 +--------------+---------------+-------------+--------------+
19614 If this option is set with the directory option, the delivery is into a new
19615 file, in the "maildir" format that is used by other mail software. When the
19616 transport is activated directly from a redirect router (for example, the
19617 address_file transport in the default configuration), setting maildir_format
19618 causes the path received from the router to be treated as a directory, whether
19619 or not it ends with "/". This option is available only if SUPPORT_MAILDIR is
19620 present in Local/Makefile. See section 26.5 below for further details.
19622 +-----------------------------+---------------+------------+------------------+
19623 |maildir_quota_directory_regex|Use: appendfile|Type: string|Default: See below|
19624 +-----------------------------+---------------+------------+------------------+
19626 This option is relevant only when maildir_use_size_file is set. It defines a
19627 regular expression for specifying directories, relative to the quota directory
19628 (see quota_directory), that should be included in the quota calculation. The
19631 maildir_quota_directory_regex = ^(?:cur|new|\..*)$
19633 This includes the cur and new directories, and any maildir++ folders
19634 (directories whose names begin with a dot). If you want to exclude the Trash
19635 folder from the count (as some sites do), you need to change this setting to
19637 maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
19639 This uses a negative lookahead in the regular expression to exclude the
19640 directory whose name is .Trash. When a directory is excluded from quota
19641 calculations, quota processing is bypassed for any messages that are delivered
19642 directly into that directory.
19644 +---------------+---------------+-------------+-----------+
19645 |maildir_retries|Use: appendfile|Type: integer|Default: 10|
19646 +---------------+---------------+-------------+-----------+
19648 This option specifies the number of times to retry when writing a file in
19649 "maildir" format. See section 26.5 below.
19651 +-----------+---------------+-------------+--------------+
19652 |maildir_tag|Use: appendfile|Type: string*|Default: unset|
19653 +-----------+---------------+-------------+--------------+
19655 This option applies only to deliveries in maildir format, and is described in
19656 section 26.5 below.
19658 +---------------------+----------------+-------------+--------------+
19659 |maildir_use_size_file|Use: appendfile*|Type: boolean|Default: false|
19660 +---------------------+----------------+-------------+--------------+
19662 The result of string expansion for this option must be a valid boolean value.
19663 If it is true, it enables support for maildirsize files. Exim creates a
19664 maildirsize file in a maildir if one does not exist, taking the quota from the
19665 quota option of the transport. If quota is unset, the value is zero. See
19666 maildir_quota_directory_regex above and section 26.5 below for further details.
19668 +--------------------------+---------------+------------+--------------+
19669 |maildirfolder_create_regex|Use: appendfile|Type: string|Default: unset|
19670 +--------------------------+---------------+------------+--------------+
19672 The value of this option is a regular expression. If it is unset, it has no
19673 effect. Otherwise, before a maildir delivery takes place, the pattern is
19674 matched against the name of the maildir directory, that is, the directory
19675 containing the new and tmp subdirectories that will be used for the delivery.
19676 If there is a match, Exim checks for the existence of a file called
19677 maildirfolder in the directory, and creates it if it does not exist. See
19678 section 26.5 for more details.
19680 +----------------+---------------+-------------+--------------+
19681 |mailstore_format|Use: appendfile|Type: boolean|Default: false|
19682 +----------------+---------------+-------------+--------------+
19684 If this option is set with the directory option, the delivery is into two new
19685 files in "mailstore" format. The option is available only if SUPPORT_MAILSTORE
19686 is present in Local/Makefile. See section 26.4 below for further details.
19688 +----------------+---------------+-------------+--------------+
19689 |mailstore_prefix|Use: appendfile|Type: string*|Default: unset|
19690 +----------------+---------------+-------------+--------------+
19692 This option applies only to deliveries in mailstore format, and is described in
19693 section 26.4 below.
19695 +----------------+---------------+-------------+--------------+
19696 |mailstore_suffix|Use: appendfile|Type: string*|Default: unset|
19697 +----------------+---------------+-------------+--------------+
19699 This option applies only to deliveries in mailstore format, and is described in
19700 section 26.4 below.
19702 +----------+---------------+-------------+--------------+
19703 |mbx_format|Use: appendfile|Type: boolean|Default: false|
19704 +----------+---------------+-------------+--------------+
19706 This option is available only if Exim has been compiled with SUPPORT_MBX set in
19707 Local/Makefile. If mbx_format is set with the file option, the message is
19708 appended to the mailbox file in MBX format instead of traditional Unix format.
19709 This format is supported by Pine4 and its associated IMAP and POP daemons, by
19710 means of the c-client library that they all use.
19712 Note: The message_prefix and message_suffix options are not automatically
19713 changed by the use of mbx_format. They should normally be set empty when using
19714 MBX format, so this option almost always appears in this combination:
19720 If none of the locking options are mentioned in the configuration, use_mbx_lock
19721 is assumed and the other locking options default to false. It is possible to
19722 specify the other kinds of locking with mbx_format, but use_fcntl_lock and
19723 use_mbx_lock are mutually exclusive. MBX locking interworks with c-client,
19724 providing for shared access to the mailbox. It should not be used if any
19725 program that does not use this form of locking is going to access the mailbox,
19726 nor should it be used if the mailbox file is NFS mounted, because it works only
19727 when the mailbox is accessed from a single host.
19729 If you set use_fcntl_lock with an MBX-format mailbox, you cannot use the
19730 standard version of c-client, because as long as it has a mailbox open (this
19731 means for the whole of a Pine or IMAP session), Exim will not be able to append
19734 +--------------+---------------+-------------+------------------+
19735 |message_prefix|Use: appendfile|Type: string*|Default: see below|
19736 +--------------+---------------+-------------+------------------+
19738 The string specified here is expanded and output at the start of every message.
19739 The default is unset unless file is specified and use_bsmtp is not set, in
19742 message_prefix = "From ${if def:return_path{$return_path}\
19743 {MAILER-DAEMON}} $tod_bsdinbox\n"
19745 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
19746 n" in message_prefix.
19748 +--------------+---------------+-------------+------------------+
19749 |message_suffix|Use: appendfile|Type: string*|Default: see below|
19750 +--------------+---------------+-------------+------------------+
19752 The string specified here is expanded and output at the end of every message.
19753 The default is unset unless file is specified and use_bsmtp is not set, in
19754 which case it is a single newline character. The suffix can be suppressed by
19759 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
19760 n" in message_suffix.
19762 +----+---------------+-------------------+-------------+
19763 |mode|Use: appendfile|Type: octal integer|Default: 0600|
19764 +----+---------------+-------------------+-------------+
19766 If the output file is created, it is given this mode. If it already exists and
19767 has wider permissions, they are reduced to this mode. If it has narrower
19768 permissions, an error occurs unless mode_fail_narrower is false. However, if
19769 the delivery is the result of a save command in a filter file specifying a
19770 particular mode, the mode of the output file is always forced to take that
19771 value, and this option is ignored.
19773 +------------------+---------------+-------------+-------------+
19774 |mode_fail_narrower|Use: appendfile|Type: boolean|Default: true|
19775 +------------------+---------------+-------------+-------------+
19777 This option applies in the case when an existing mailbox file has a narrower
19778 mode than that specified by the mode option. If mode_fail_narrower is true, the
19779 delivery is deferred ("mailbox has the wrong mode"); otherwise Exim continues
19780 with the delivery attempt, using the existing mode of the file.
19782 +-------------+---------------+-------------+--------------+
19783 |notify_comsat|Use: appendfile|Type: boolean|Default: false|
19784 +-------------+---------------+-------------+--------------+
19786 If this option is true, the comsat daemon is notified after every successful
19787 delivery to a user mailbox. This is the daemon that notifies logged on users
19788 about incoming mail.
19790 +-----+---------------+-------------+--------------+
19791 |quota|Use: appendfile|Type: string*|Default: unset|
19792 +-----+---------------+-------------+--------------+
19794 This option imposes a limit on the size of the file to which Exim is appending,
19795 or to the total space used in the directory tree when the directory option is
19796 set. In the latter case, computation of the space used is expensive, because
19797 all the files in the directory (and any sub-directories) have to be
19798 individually inspected and their sizes summed. (See quota_size_regex and
19799 maildir_use_size_file for ways to avoid this in environments where users have
19800 no shell access to their mailboxes).
19802 As there is no interlock against two simultaneous deliveries into a multi-file
19803 mailbox, it is possible for the quota to be overrun in this case. For
19804 single-file mailboxes, of course, an interlock is a necessity.
19806 A file's size is taken as its used value. Because of blocking effects, this may
19807 be a lot less than the actual amount of disk space allocated to the file. If
19808 the sizes of a number of files are being added up, the rounding effect can
19809 become quite noticeable, especially on systems that have large block sizes.
19810 Nevertheless, it seems best to stick to the used figure, because this is the
19811 obvious value which users understand most easily.
19813 The value of the option is expanded, and must then be a numerical value
19814 (decimal point allowed), optionally followed by one of the letters K, M, or G,
19815 for kilobytes, megabytes, or gigabytes. If Exim is running on a system with
19816 large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
19819 Note: A value of zero is interpreted as "no quota".
19821 The expansion happens while Exim is running as root, before it changes uid for
19822 the delivery. This means that files that are inaccessible to the end user can
19823 be used to hold quota values that are looked up in the expansion. When delivery
19824 fails because this quota is exceeded, the handling of the error is as for
19825 system quota failures.
19827 By default, Exim's quota checking mimics system quotas, and restricts the
19828 mailbox to the specified maximum size, though the value is not accurate to the
19829 last byte, owing to separator lines and additional headers that may get added
19830 during message delivery. When a mailbox is nearly full, large messages may get
19831 refused even though small ones are accepted, because the size of the current
19832 message is added to the quota when the check is made. This behaviour can be
19833 changed by setting quota_is_inclusive false. When this is done, the check for
19834 exceeding the quota does not include the current message. Thus, deliveries
19835 continue until the quota has been exceeded; thereafter, no further messages are
19836 delivered. See also quota_warn_threshold.
19838 +---------------+---------------+-------------+--------------+
19839 |quota_directory|Use: appendfile|Type: string*|Default: unset|
19840 +---------------+---------------+-------------+--------------+
19842 This option defines the directory to check for quota purposes when delivering
19843 into individual files. The default is the delivery directory, or, if a file
19844 called maildirfolder exists in a maildir directory, the parent of the delivery
19847 +---------------+---------------+-------------+----------+
19848 |quota_filecount|Use: appendfile|Type: string*|Default: 0|
19849 +---------------+---------------+-------------+----------+
19851 This option applies when the directory option is set. It limits the total
19852 number of files in the directory (compare the inode limit in system quotas). It
19853 can only be used if quota is also set. The value is expanded; an expansion
19854 failure causes delivery to be deferred. A value of zero is interpreted as "no
19857 +------------------+---------------+-------------+-------------+
19858 |quota_is_inclusive|Use: appendfile|Type: boolean|Default: true|
19859 +------------------+---------------+-------------+-------------+
19863 +----------------+---------------+------------+--------------+
19864 |quota_size_regex|Use: appendfile|Type: string|Default: unset|
19865 +----------------+---------------+------------+--------------+
19867 This option applies when one of the delivery modes that writes a separate file
19868 for each message is being used. When Exim wants to find the size of one of
19869 these files in order to test the quota, it first checks quota_size_regex. If
19870 this is set to a regular expression that matches the file name, and it captures
19871 one string, that string is interpreted as a representation of the file's size.
19872 The value of quota_size_regex is not expanded.
19874 This feature is useful only when users have no shell access to their mailboxes
19875 - otherwise they could defeat the quota simply by renaming the files. This
19876 facility can be used with maildir deliveries, by setting maildir_tag to add the
19877 file length to the file name. For example:
19879 maildir_tag = ,S=$message_size
19880 quota_size_regex = ,S=(\d+)
19882 An alternative to $message_size is $message_linecount, which contains the
19883 number of lines in the message.
19885 The regular expression should not assume that the length is at the end of the
19886 file name (even though maildir_tag puts it there) because maildir MUAs
19887 sometimes add other information onto the ends of message file names.
19889 Section 26.7 contains further information.
19891 +------------------+---------------+-------------+------------------+
19892 |quota_warn_message|Use: appendfile|Type: string*|Default: see below|
19893 +------------------+---------------+-------------+------------------+
19895 See below for the use of this option. If it is not set when
19896 quota_warn_threshold is set, it defaults to
19898 quota_warn_message = "\
19899 To: $local_part@$domain\n\
19900 Subject: Your mailbox\n\n\
19901 This message is automatically created \
19902 by mail delivery software.\n\n\
19903 The size of your mailbox has exceeded \
19904 a warning threshold that is\n\
19905 set by the system administrator.\n"
19907 +--------------------+---------------+-------------+----------+
19908 |quota_warn_threshold|Use: appendfile|Type: string*|Default: 0|
19909 +--------------------+---------------+-------------+----------+
19911 This option is expanded in the same way as quota (see above). If the resulting
19912 value is greater than zero, and delivery of the message causes the size of the
19913 file or total space in the directory tree to cross the given threshold, a
19914 warning message is sent. If quota is also set, the threshold may be specified
19915 as a percentage of it by following the value with a percent sign. For example:
19918 quota_warn_threshold = 75%
19920 If quota is not set, a setting of quota_warn_threshold that ends with a percent
19923 The warning message itself is specified by the quota_warn_message option, and
19924 it must start with a To: header line containing the recipient(s) of the warning
19925 message. These do not necessarily have to include the recipient(s) of the
19926 original message. A Subject: line should also normally be supplied. You can
19927 include any other header lines that you want. If you do not include a From:
19928 line, the default is:
19930 From: Mail Delivery System <mailer-daemon@$qualify_domain_sender>
19932 If you supply a Reply-To: line, it overrides the global errors_reply_to option.
19934 The quota option does not have to be set in order to use this option; they are
19935 independent of one another except when the threshold is specified as a
19938 +---------+---------------+-------------+--------------+
19939 |use_bsmtp|Use: appendfile|Type: boolean|Default: false|
19940 +---------+---------------+-------------+--------------+
19942 If this option is set true, appendfile writes messages in "batch SMTP" format,
19943 with the envelope sender and recipient(s) included as SMTP commands. If you
19944 want to include a leading HELO command with such messages, you can do so by
19945 setting the message_prefix option. See section 47.10 for details of batch SMTP.
19947 +--------+---------------+-------------+--------------+
19948 |use_crlf|Use: appendfile|Type: boolean|Default: false|
19949 +--------+---------------+-------------+--------------+
19951 This option causes lines to be terminated with the two-character CRLF sequence
19952 (carriage return, linefeed) instead of just a linefeed character. In the case
19953 of batched SMTP, the byte sequence written to the file is then an exact image
19954 of what would be sent down a real SMTP connection.
19956 Note: The contents of the message_prefix and message_suffix options (which are
19957 used to supply the traditional "From " and blank line separators in
19958 Berkeley-style mailboxes) are written verbatim, so must contain their own
19959 carriage return characters if these are needed. In cases where these options
19960 have non-empty defaults, the values end with a single linefeed, so they must be
19961 changed to end with "\r\n" if use_crlf is set.
19963 +--------------+---------------+-------------+------------------+
19964 |use_fcntl_lock|Use: appendfile|Type: boolean|Default: see below|
19965 +--------------+---------------+-------------+------------------+
19967 This option controls the use of the fcntl() function to lock a file for
19968 exclusive use when a message is being appended. It is set by default unless
19969 use_flock_lock is set. Otherwise, it should be turned off only if you know that
19970 all your MUAs use lock file locking. When both use_fcntl_lock and
19971 use_flock_lock are unset, use_lockfile must be set.
19973 +--------------+---------------+-------------+--------------+
19974 |use_flock_lock|Use: appendfile|Type: boolean|Default: false|
19975 +--------------+---------------+-------------+--------------+
19977 This option is provided to support the use of flock() for file locking, for the
19978 few situations where it is needed. Most modern operating systems support fcntl
19979 () and lockf() locking, and these two functions interwork with each other. Exim
19980 uses fcntl() locking by default.
19982 This option is required only if you are using an operating system where flock()
19983 is used by programs that access mailboxes (typically MUAs), and where flock()
19984 does not correctly interwork with fcntl(). You can use both fcntl() and flock()
19985 locking simultaneously if you want.
19987 Not all operating systems provide flock(). Some versions of Solaris do not have
19988 it (and some, I think, provide a not quite right version built on top of lockf
19989 ()). If the OS does not have flock(), Exim will be built without the ability to
19990 use it, and any attempt to do so will cause a configuration error.
19992 Warning: flock() locks do not work on NFS files (unless flock() is just being
19993 mapped onto fcntl() by the OS).
19995 +------------+---------------+-------------+------------------+
19996 |use_lockfile|Use: appendfile|Type: boolean|Default: see below|
19997 +------------+---------------+-------------+------------------+
19999 If this option is turned off, Exim does not attempt to create a lock file when
20000 appending to a mailbox file. In this situation, the only locking is by fcntl().
20001 You should only turn use_lockfile off if you are absolutely sure that every MUA
20002 that is ever going to look at your users' mailboxes uses fcntl() rather than a
20003 lock file, and even then only when you are not delivering over NFS from more
20006 In order to append to an NFS file safely from more than one host, it is
20007 necessary to take out a lock before opening the file, and the lock file
20008 achieves this. Otherwise, even with fcntl() locking, there is a risk of file
20011 The use_lockfile option is set by default unless use_mbx_lock is set. It is not
20012 possible to turn both use_lockfile and use_fcntl_lock off, except when
20015 +------------+---------------+-------------+------------------+
20016 |use_mbx_lock|Use: appendfile|Type: boolean|Default: see below|
20017 +------------+---------------+-------------+------------------+
20019 This option is available only if Exim has been compiled with SUPPORT_MBX set in
20020 Local/Makefile. Setting the option specifies that special MBX locking rules be
20021 used. It is set by default if mbx_format is set and none of the locking options
20022 are mentioned in the configuration. The locking rules are the same as are used
20023 by the c-client library that underlies Pine and the IMAP4 and POP daemons that
20024 come with it (see the discussion below). The rules allow for shared access to
20025 the mailbox. However, this kind of locking does not work when the mailbox is
20028 You can set use_mbx_lock with either (or both) of use_fcntl_lock and
20029 use_flock_lock to control what kind of locking is used in implementing the MBX
20030 locking rules. The default is to use fcntl() if use_mbx_lock is set without
20031 use_fcntl_lock or use_flock_lock.
20034 26.3 Operational details for appending
20035 --------------------------------------
20037 Before appending to a file, the following preparations are made:
20039 * If the name of the file is /dev/null, no action is taken, and a success
20042 * If any directories on the file's path are missing, Exim creates them if the
20043 create_directory option is set. A created directory's mode is given by the
20044 directory_mode option.
20046 * If file_format is set, the format of an existing file is checked. If this
20047 indicates that a different transport should be used, control is passed to
20050 * If use_lockfile is set, a lock file is built in a way that will work
20051 reliably over NFS, as follows:
20053 1. Create a "hitching post" file whose name is that of the lock file with
20054 the current time, primary host name, and process id added, by opening
20055 for writing as a new file. If this fails with an access error, delivery
20058 2. Close the hitching post file, and hard link it to the lock file name.
20060 3. If the call to link() succeeds, creation of the lock file has
20061 succeeded. Unlink the hitching post name.
20063 4. Otherwise, use stat() to get information about the hitching post file,
20064 and then unlink hitching post name. If the number of links is exactly
20065 two, creation of the lock file succeeded but something (for example, an
20066 NFS server crash and restart) caused this fact not to be communicated
20067 to the link() call.
20069 5. If creation of the lock file failed, wait for lock_interval and try
20070 again, up to lock_retries times. However, since any program that writes
20071 to a mailbox should complete its task very quickly, it is reasonable to
20072 time out old lock files that are normally the result of user agent and
20073 system crashes. If an existing lock file is older than lockfile_timeout
20074 Exim attempts to unlink it before trying again.
20076 * A call is made to lstat() to discover whether the main file exists, and if
20077 so, what its characteristics are. If lstat() fails for any reason other
20078 than non-existence, delivery is deferred.
20080 * If the file does exist and is a symbolic link, delivery is deferred, unless
20081 the allow_symlink option is set, in which case the ownership of the link is
20082 checked, and then stat() is called to find out about the real file, which
20083 is then subjected to the checks below. The check on the top-level link
20084 ownership prevents one user creating a link for another's mailbox in a
20085 sticky directory, though allowing symbolic links in this case is definitely
20086 not a good idea. If there is a chain of symbolic links, the intermediate
20087 ones are not checked.
20089 * If the file already exists but is not a regular file, or if the file's
20090 owner and group (if the group is being checked - see check_group above) are
20091 different from the user and group under which the delivery is running,
20092 delivery is deferred.
20094 * If the file's permissions are more generous than specified, they are
20095 reduced. If they are insufficient, delivery is deferred, unless
20096 mode_fail_narrower is set false, in which case the delivery is tried using
20097 the existing permissions.
20099 * The file's inode number is saved, and the file is then opened for
20100 appending. If this fails because the file has vanished, appendfile behaves
20101 as if it hadn't existed (see below). For any other failures, delivery is
20104 * If the file is opened successfully, check that the inode number hasn't
20105 changed, that it is still a regular file, and that the owner and
20106 permissions have not changed. If anything is wrong, defer delivery and
20107 freeze the message.
20109 * If the file did not exist originally, defer delivery if the file_must_exist
20110 option is set. Otherwise, check that the file is being created in a
20111 permitted directory if the create_file option is set (deferring on
20112 failure), and then open for writing as a new file, with the O_EXCL and
20113 O_CREAT options, except when dealing with a symbolic link (the
20114 allow_symlink option must be set). In this case, which can happen if the
20115 link points to a non-existent file, the file is opened for writing using
20116 O_CREAT but not O_EXCL, because that prevents link following.
20118 * If opening fails because the file exists, obey the tests given above for
20119 existing files. However, to avoid looping in a situation where the file is
20120 being continuously created and destroyed, the exists/not-exists loop is
20121 broken after 10 repetitions, and the message is then frozen.
20123 * If opening fails with any other error, defer delivery.
20125 * Once the file is open, unless both use_fcntl_lock and use_flock_lock are
20126 false, it is locked using fcntl() or flock() or both. If use_mbx_lock is
20127 false, an exclusive lock is requested in each case. However, if
20128 use_mbx_lock is true, Exim takes out a shared lock on the open file, and an
20129 exclusive lock on the file whose name is
20131 /tmp/.<device-number>.<inode-number>
20133 using the device and inode numbers of the open mailbox file, in accordance
20134 with the MBX locking rules. This file is created with a mode that is
20135 specified by the lockfile_mode option.
20137 If Exim fails to lock the file, there are two possible courses of action,
20138 depending on the value of the locking timeout. This is obtained from
20139 lock_fcntl_timeout or lock_flock_timeout, as appropriate.
20141 If the timeout value is zero, the file is closed, Exim waits for
20142 lock_interval, and then goes back and re-opens the file as above and tries
20143 to lock it again. This happens up to lock_retries times, after which the
20144 delivery is deferred.
20146 If the timeout has a value greater than zero, blocking calls to fcntl() or
20147 flock() are used (with the given timeout), so there has already been some
20148 waiting involved by the time locking fails. Nevertheless, Exim does not
20149 give up immediately. It retries up to
20151 (lock_retries * lock_interval) / <timeout>
20153 times (rounded up).
20155 At the end of delivery, Exim closes the file (which releases the fcntl() and/or
20156 flock() locks) and then deletes the lock file if one was created.
20159 26.4 Operational details for delivery to a new file
20160 ---------------------------------------------------
20162 When the directory option is set instead of file, each message is delivered
20163 into a newly-created file or set of files. When appendfile is activated
20164 directly from a redirect router, neither file nor directory is normally set,
20165 because the path for delivery is supplied by the router. (See for example, the
20166 address_file transport in the default configuration.) In this case, delivery is
20167 to a new file if either the path name ends in "/", or the maildir_format or
20168 mailstore_format option is set.
20170 No locking is required while writing the message to a new file, so the various
20171 locking options of the transport are ignored. The "From" line that by default
20172 separates messages in a single file is not normally needed, nor is the escaping
20173 of message lines that start with "From", and there is no need to ensure a
20174 newline at the end of each message. Consequently, the default values for
20175 check_string, message_prefix, and message_suffix are all unset when any of
20176 directory, maildir_format, or mailstore_format is set.
20178 If Exim is required to check a quota setting, it adds up the sizes of all the
20179 files in the delivery directory by default. However, you can specify a
20180 different directory by setting quota_directory. Also, for maildir deliveries
20181 (see below) the maildirfolder convention is honoured.
20183 There are three different ways in which delivery to individual files can be
20184 done, controlled by the settings of the maildir_format and mailstore_format
20185 options. Note that code to support maildir or mailstore formats is not included
20186 in the binary unless SUPPORT_MAILDIR or SUPPORT_MAILSTORE, respectively, is set
20189 In all three cases an attempt is made to create the directory and any necessary
20190 sub-directories if they do not exist, provided that the create_directory option
20191 is set (the default). The location of a created directory can be constrained by
20192 setting create_file. A created directory's mode is given by the directory_mode
20193 option. If creation fails, or if the create_directory option is not set when
20194 creation is required, delivery is deferred.
20197 26.5 Maildir delivery
20198 ---------------------
20200 If the maildir_format option is true, Exim delivers each message by writing it
20201 to a file whose name is tmp/<stime>.H<mtime>P<pid>.<host> in the directory that
20202 is defined by the directory option (the "delivery directory"). If the delivery
20203 is successful, the file is renamed into the new subdirectory.
20205 In the file name, <stime> is the current time of day in seconds, and <mtime> is
20206 the microsecond fraction of the time. After a maildir delivery, Exim checks
20207 that the time-of-day clock has moved on by at least one microsecond before
20208 terminating the delivery process. This guarantees uniqueness for the file name.
20209 However, as a precaution, Exim calls stat() for the file before opening it. If
20210 any response other than ENOENT (does not exist) is given, Exim waits 2 seconds
20211 and tries again, up to maildir_retries times.
20213 Before Exim carries out a maildir delivery, it ensures that subdirectories
20214 called new, cur, and tmp exist in the delivery directory. If they do not exist,
20215 Exim tries to create them and any superior directories in their path, subject
20216 to the create_directory and create_file options. If the
20217 maildirfolder_create_regex option is set, and the regular expression it
20218 contains matches the delivery directory, Exim also ensures that a file called
20219 maildirfolder exists in the delivery directory. If a missing directory or
20220 maildirfolder file cannot be created, delivery is deferred.
20222 These features make it possible to use Exim to create all the necessary files
20223 and directories in a maildir mailbox, including subdirectories for maildir++
20224 folders. Consider this example:
20226 maildir_format = true
20227 directory = /var/mail/$local_part\
20228 ${if eq{$local_part_suffix}{}{}\
20229 {/.${substr_1:$local_part_suffix}}}
20230 maildirfolder_create_regex = /\.[^/]+$
20232 If $local_part_suffix is empty (there was no suffix for the local part),
20233 delivery is into a toplevel maildir with a name like /var/mail/pimbo (for the
20234 user called pimbo). The pattern in maildirfolder_create_regex does not match
20235 this name, so Exim will not look for or create the file /var/mail/pimbo/
20236 maildirfolder, though it will create /var/mail/pimbo/{cur,new,tmp} if
20239 However, if $local_part_suffix contains "-eximusers" (for example), delivery is
20240 into the maildir++ folder /var/mail/pimbo/.eximusers, which does match
20241 maildirfolder_create_regex. In this case, Exim will create /var/mail/pimbo
20242 /.eximusers/maildirfolder as well as the three maildir directories /var/mail/
20243 pimbo/.eximusers/{cur,new,tmp}.
20245 Warning: Take care when setting maildirfolder_create_regex that it does not
20246 inadvertently match the toplevel maildir directory, because a maildirfolder
20247 file at top level would completely break quota calculations.
20249 If Exim is required to check a quota setting before a maildir delivery, and
20250 quota_directory is not set, it looks for a file called maildirfolder in the
20251 maildir directory (alongside new, cur, tmp). If this exists, Exim assumes the
20252 directory is a maildir++ folder directory, which is one level down from the
20253 user's top level mailbox directory. This causes it to start at the parent
20254 directory instead of the current directory when calculating the amount of space
20257 One problem with delivering into a multi-file mailbox is that it is
20258 computationally expensive to compute the size of the mailbox for quota
20259 checking. Various approaches have been taken to reduce the amount of work
20260 needed. The next two sections describe two of them. A third alternative is to
20261 use some external process for maintaining the size data, and use the expansion
20262 of the mailbox_size option as a way of importing it into Exim.
20265 26.6 Using tags to record message sizes
20266 ---------------------------------------
20268 If maildir_tag is set, the string is expanded for each delivery. When the
20269 maildir file is renamed into the new sub-directory, the tag is added to its
20270 name. However, if adding the tag takes the length of the name to the point
20271 where the test stat() call fails with ENAMETOOLONG, the tag is dropped and the
20272 maildir file is created with no tag.
20274 Tags can be used to encode the size of files in their names; see
20275 quota_size_regex above for an example. The expansion of maildir_tag happens
20276 after the message has been written. The value of the $message_size variable is
20277 set to the number of bytes actually written. If the expansion is forced to
20278 fail, the tag is ignored, but a non-forced failure causes delivery to be
20279 deferred. The expanded tag may contain any printing characters except "/".
20280 Non-printing characters in the string are ignored; if the resulting string is
20281 empty, it is ignored. If it starts with an alphanumeric character, a leading
20282 colon is inserted; this default has not proven to be the path that popular
20283 maildir implementations have chosen (but changing it in Exim would break
20284 backwards compatibility).
20286 For one common implementation, you might set:
20288 maildir_tag = ,S=${message_size}
20290 but you should check the documentation of the other software to be sure.
20292 It is advisable to also set quota_size_regex when setting maildir_tag as this
20293 allows Exim to extract the size from your tag, instead of having to stat() each
20297 26.7 Using a maildirsize file
20298 -----------------------------
20300 If maildir_use_size_file is true, Exim implements the maildir++ rules for
20301 storing quota and message size information in a file called maildirsize within
20302 the toplevel maildir directory. If this file does not exist, Exim creates it,
20303 setting the quota from the quota option of the transport. If the maildir
20304 directory itself does not exist, it is created before any attempt to write a
20307 The maildirsize file is used to hold information about the sizes of messages in
20308 the maildir, thus speeding up quota calculations. The quota value in the file
20309 is just a cache; if the quota is changed in the transport, the new value
20310 overrides the cached value when the next message is delivered. The cache is
20311 maintained for the benefit of other programs that access the maildir and need
20314 If the quota option in the transport is unset or zero, the maildirsize file is
20315 maintained (with a zero quota setting), but no quota is imposed.
20317 A regular expression is available for controlling which directories in the
20318 maildir participate in quota calculations when a maildirsizefile is in use. See
20319 the description of the maildir_quota_directory_regex option above for details.
20322 26.8 Mailstore delivery
20323 -----------------------
20325 If the mailstore_format option is true, each message is written as two files in
20326 the given directory. A unique base name is constructed from the message id and
20327 the current delivery process, and the files that are written use this base name
20328 plus the suffixes .env and .msg. The .env file contains the message's envelope,
20329 and the .msg file contains the message itself. The base name is placed in the
20330 variable $mailstore_basename.
20332 During delivery, the envelope is first written to a file with the suffix .tmp.
20333 The .msg file is then written, and when it is complete, the .tmp file is
20334 renamed as the .env file. Programs that access messages in mailstore format
20335 should wait for the presence of both a .msg and a .env file before accessing
20336 either of them. An alternative approach is to wait for the absence of a .tmp
20339 The envelope file starts with any text defined by the mailstore_prefix option,
20340 expanded and terminated by a newline if there isn't one. Then follows the
20341 sender address on one line, then all the recipient addresses, one per line.
20342 There can be more than one recipient only if the batch_max option is set
20343 greater than one. Finally, mailstore_suffix is expanded and the result appended
20344 to the file, followed by a newline if it does not end with one.
20346 If expansion of mailstore_prefix or mailstore_suffix ends with a forced
20347 failure, it is ignored. Other expansion errors are treated as serious
20348 configuration errors, and delivery is deferred. The variable
20349 $mailstore_basename is available for use during these expansions.
20352 26.9 Non-special new file delivery
20353 ----------------------------------
20355 If neither maildir_format nor mailstore_format is set, a single new file is
20356 created directly in the named directory. For example, when delivering messages
20357 into files in batched SMTP format for later delivery to some host (see section
20358 47.10), a setting such as
20360 directory = /var/bsmtp/$host
20362 might be used. A message is written to a file with a temporary name, which is
20363 then renamed when the delivery is complete. The final name is obtained by
20364 expanding the contents of the directory_file option.
20368 ===============================================================================
20369 27. THE AUTOREPLY TRANSPORT
20371 The autoreply transport is not a true transport in that it does not cause the
20372 message to be transmitted. Instead, it generates a new mail message as an
20373 automatic reply to the incoming message. References: and Auto-Submitted: header
20374 lines are included. These are constructed according to the rules in RFCs 2822
20375 and 3834, respectively.
20377 If the router that passes the message to this transport does not have the
20378 unseen option set, the original message (for the current recipient) is not
20379 delivered anywhere. However, when the unseen option is set on the router that
20380 passes the message to this transport, routing of the address continues, so
20381 another router can set up a normal message delivery.
20383 The autoreply transport is usually run as the result of mail filtering, a
20384 "vacation" message being the standard example. However, it can also be run
20385 directly from a router like any other transport. To reduce the possibility of
20386 message cascades, messages created by the autoreply transport always have empty
20387 envelope sender addresses, like bounce messages.
20389 The parameters of the message to be sent can be specified in the configuration
20390 by options described below. However, these are used only when the address
20391 passed to the transport does not contain its own reply information. When the
20392 transport is run as a consequence of a mail or vacation command in a filter
20393 file, the parameters of the message are supplied by the filter, and passed with
20394 the address. The transport's options that define the message are then ignored
20395 (so they are not usually set in this case). The message is specified entirely
20396 by the filter or by the transport; it is never built from a mixture of options.
20397 However, the file_optional, mode, and return_message options apply in all
20400 Autoreply is implemented as a local transport. When used as a result of a
20401 command in a user's filter file, autoreply normally runs under the uid and gid
20402 of the user, and with appropriate current and home directories (see chapter 23
20405 There is a subtle difference between routing a message to a pipe transport that
20406 generates some text to be returned to the sender, and routing it to an
20407 autoreply transport. This difference is noticeable only if more than one
20408 address from the same message is so handled. In the case of a pipe, the
20409 separate outputs from the different addresses are gathered up and returned to
20410 the sender in a single message, whereas if autoreply is used, a separate
20411 message is generated for each address that is passed to it.
20413 Non-printing characters are not permitted in the header lines generated for the
20414 message that autoreply creates, with the exception of newlines that are
20415 immediately followed by white space. If any non-printing characters are found,
20416 the transport defers. Whether characters with the top bit set count as printing
20417 characters or not is controlled by the print_topbitchars global option.
20419 If any of the generic options for manipulating headers (for example,
20420 headers_add) are set on an autoreply transport, they apply to the copy of the
20421 original message that is included in the generated message when return_message
20422 is set. They do not apply to the generated message itself.
20424 If the autoreply transport receives return code 2 from Exim when it submits the
20425 message, indicating that there were no recipients, it does not treat this as an
20426 error. This means that autoreplies sent to $sender_address when this is empty
20427 (because the incoming message is a bounce message) do not cause problems. They
20428 are just discarded.
20431 27.1 Private options for autoreply
20432 ----------------------------------
20434 +---+--------------+-------------+--------------+
20435 |bcc|Use: autoreply|Type: string*|Default: unset|
20436 +---+--------------+-------------+--------------+
20438 This specifies the addresses that are to receive "blind carbon copies" of the
20439 message when the message is specified by the transport.
20441 +--+--------------+-------------+--------------+
20442 |cc|Use: autoreply|Type: string*|Default: unset|
20443 +--+--------------+-------------+--------------+
20445 This specifies recipients of the message and the contents of the Cc: header
20446 when the message is specified by the transport.
20448 +----+--------------+-------------+--------------+
20449 |file|Use: autoreply|Type: string*|Default: unset|
20450 +----+--------------+-------------+--------------+
20452 The contents of the file are sent as the body of the message when the message
20453 is specified by the transport. If both file and text are set, the text string
20456 +-----------+--------------+-------------+--------------+
20457 |file_expand|Use: autoreply|Type: boolean|Default: false|
20458 +-----------+--------------+-------------+--------------+
20460 If this is set, the contents of the file named by the file option are subjected
20461 to string expansion as they are added to the message.
20463 +-------------+--------------+-------------+--------------+
20464 |file_optional|Use: autoreply|Type: boolean|Default: false|
20465 +-------------+--------------+-------------+--------------+
20467 If this option is true, no error is generated if the file named by the file
20468 option or passed with the address does not exist or cannot be read.
20470 +----+--------------+-------------+--------------+
20471 |from|Use: autoreply|Type: string*|Default: unset|
20472 +----+--------------+-------------+--------------+
20474 This specifies the contents of the From: header when the message is specified
20477 +-------+--------------+-------------+--------------+
20478 |headers|Use: autoreply|Type: string*|Default: unset|
20479 +-------+--------------+-------------+--------------+
20481 This specifies additional RFC 2822 headers that are to be added to the message
20482 when the message is specified by the transport. Several can be given by using "
20483 \n" to separate them. There is no check on the format.
20485 +---+--------------+-------------+--------------+
20486 |log|Use: autoreply|Type: string*|Default: unset|
20487 +---+--------------+-------------+--------------+
20489 This option names a file in which a record of every message sent is logged when
20490 the message is specified by the transport.
20492 +----+--------------+-------------------+-------------+
20493 |mode|Use: autoreply|Type: octal integer|Default: 0600|
20494 +----+--------------+-------------------+-------------+
20496 If either the log file or the "once" file has to be created, this mode is used.
20498 +----------+--------------+-------------------+--------------+
20499 |never_mail|Use: autoreply|Type: address list*|Default: unset|
20500 +----------+--------------+-------------------+--------------+
20502 If any run of the transport creates a message with a recipient that matches any
20503 item in the list, that recipient is quietly discarded. If all recipients are
20504 discarded, no message is created. This applies both when the recipients are
20505 generated by a filter and when they are specified in the transport.
20507 +----+--------------+-------------+--------------+
20508 |once|Use: autoreply|Type: string*|Default: unset|
20509 +----+--------------+-------------+--------------+
20511 This option names a file or DBM database in which a record of each To:
20512 recipient is kept when the message is specified by the transport. Note: This
20513 does not apply to Cc: or Bcc: recipients.
20515 If once is unset, or is set to an empty string, the message is always sent. By
20516 default, if once is set to a non-empty file name, the message is not sent if a
20517 potential recipient is already listed in the database. However, if the
20518 once_repeat option specifies a time greater than zero, the message is sent if
20519 that much time has elapsed since a message was last sent to this recipient. A
20520 setting of zero time for once_repeat (the default) prevents a message from
20521 being sent a second time - in this case, zero means infinity.
20523 If once_file_size is zero, a DBM database is used to remember recipients, and
20524 it is allowed to grow as large as necessary. If once_file_size is set greater
20525 than zero, it changes the way Exim implements the once option. Instead of using
20526 a DBM file to record every recipient it sends to, it uses a regular file, whose
20527 size will never get larger than the given value.
20529 In the file, Exim keeps a linear list of recipient addresses and the times at
20530 which they were sent messages. If the file is full when a new address needs to
20531 be added, the oldest address is dropped. If once_repeat is not set, this means
20532 that a given recipient may receive multiple messages, but at unpredictable
20533 intervals that depend on the rate of turnover of addresses in the file. If
20534 once_repeat is set, it specifies a maximum time between repeats.
20536 +--------------+--------------+-------------+----------+
20537 |once_file_size|Use: autoreply|Type: integer|Default: 0|
20538 +--------------+--------------+-------------+----------+
20542 +-----------+--------------+-----------+-----------+
20543 |once_repeat|Use: autoreply|Type: time*|Default: 0s|
20544 +-----------+--------------+-----------+-----------+
20546 See once above. After expansion, the value of this option must be a valid time
20549 +--------+--------------+-------------+--------------+
20550 |reply_to|Use: autoreply|Type: string*|Default: unset|
20551 +--------+--------------+-------------+--------------+
20553 This specifies the contents of the Reply-To: header when the message is
20554 specified by the transport.
20556 +--------------+--------------+-------------+--------------+
20557 |return_message|Use: autoreply|Type: boolean|Default: false|
20558 +--------------+--------------+-------------+--------------+
20560 If this is set, a copy of the original message is returned with the new
20561 message, subject to the maximum size set in the return_size_limit global
20562 configuration option.
20564 +-------+--------------+-------------+--------------+
20565 |subject|Use: autoreply|Type: string*|Default: unset|
20566 +-------+--------------+-------------+--------------+
20568 This specifies the contents of the Subject: header when the message is
20569 specified by the transport. It is tempting to quote the original subject in
20570 automatic responses. For example:
20572 subject = Re: $h_subject:
20574 There is a danger in doing this, however. It may allow a third party to
20575 subscribe your users to an opt-in mailing list, provided that the list accepts
20576 bounce messages as subscription confirmations. Well-managed lists require a
20577 non-bounce message to confirm a subscription, so the danger is relatively
20580 +----+--------------+-------------+--------------+
20581 |text|Use: autoreply|Type: string*|Default: unset|
20582 +----+--------------+-------------+--------------+
20584 This specifies a single string to be used as the body of the message when the
20585 message is specified by the transport. If both text and file are set, the text
20588 +--+--------------+-------------+--------------+
20589 |to|Use: autoreply|Type: string*|Default: unset|
20590 +--+--------------+-------------+--------------+
20592 This specifies recipients of the message and the contents of the To: header
20593 when the message is specified by the transport.
20597 ===============================================================================
20598 28. THE LMTP TRANSPORT
20600 The lmtp transport runs the LMTP protocol (RFC 2033) over a pipe to a specified
20601 command or by interacting with a Unix domain socket. This transport is
20602 something of a cross between the pipe and smtp transports. Exim also has
20603 support for using LMTP over TCP/IP; this is implemented as an option for the
20604 smtp transport. Because LMTP is expected to be of minority interest, the
20605 default build-time configure in src/EDITME has it commented out. You need to
20610 is present in your Local/Makefile in order to have the lmtp transport included
20611 in the Exim binary. The private options of the lmtp transport are as follows:
20613 +--------+---------+-------------+--------------+
20614 |batch_id|Use: lmtp|Type: string*|Default: unset|
20615 +--------+---------+-------------+--------------+
20617 See the description of local delivery batching in chapter 25.
20619 +---------+---------+-------------+----------+
20620 |batch_max|Use: lmtp|Type: integer|Default: 1|
20621 +---------+---------+-------------+----------+
20623 This limits the number of addresses that can be handled in a single delivery.
20624 Most LMTP servers can handle several addresses at once, so it is normally a
20625 good idea to increase this value. See the description of local delivery
20626 batching in chapter 25.
20628 +-------+---------+-------------+--------------+
20629 |command|Use: lmtp|Type: string*|Default: unset|
20630 +-------+---------+-------------+--------------+
20632 This option must be set if socket is not set. The string is a command which is
20633 run in a separate process. It is split up into a command name and list of
20634 arguments, each of which is separately expanded (so expansion cannot change the
20635 number of arguments). The command is run directly, not via a shell. The message
20636 is passed to the new process using the standard input and output to operate the
20639 +------------+---------+-------------+--------------+
20640 |ignore_quota|Use: lmtp|Type: boolean|Default: false|
20641 +------------+---------+-------------+--------------+
20643 If this option is set true, the string "IGNOREQUOTA" is added to RCPT commands,
20644 provided that the LMTP server has advertised support for IGNOREQUOTA in its
20645 response to the LHLO command.
20647 +------+---------+-------------+--------------+
20648 |socket|Use: lmtp|Type: string*|Default: unset|
20649 +------+---------+-------------+--------------+
20651 This option must be set if command is not set. The result of expansion must be
20652 the name of a Unix domain socket. The transport connects to the socket and
20653 delivers the message to it using the LMTP protocol.
20655 +-------+---------+----------+-----------+
20656 |timeout|Use: lmtp|Type: time|Default: 5m|
20657 +-------+---------+----------+-----------+
20659 The transport is aborted if the created process or Unix domain socket does not
20660 respond to LMTP commands or message input within this timeout. Delivery is
20661 deferred, and will be tried again later. Here is an example of a typical LMTP
20666 command = /some/local/lmtp/delivery/program
20670 This delivers up to 20 addresses at a time, in a mixture of domains if
20671 necessary, running as the user exim.
20675 ===============================================================================
20676 29. THE PIPE TRANSPORT
20678 The pipe transport is used to deliver messages via a pipe to a command running
20679 in another process. One example is the use of pipe as a pseudo-remote transport
20680 for passing messages to some other delivery mechanism (such as UUCP). Another
20681 is the use by individual users to automatically process their incoming
20682 messages. The pipe transport can be used in one of the following ways:
20684 * A router routes one address to a transport in the normal way, and the
20685 transport is configured as a pipe transport. In this case, $local_part
20686 contains the local part of the address (as usual), and the command that is
20687 run is specified by the command option on the transport.
20689 * If the batch_max option is set greater than 1 (the default is 1), the
20690 transport can handle more than one address in a single run. In this case,
20691 when more than one address is routed to the transport, $local_part is not
20692 set (because it is not unique). However, the pseudo-variable
20693 $pipe_addresses (described in section 29.3 below) contains all the
20694 addresses that are routed to the transport.
20696 * A router redirects an address directly to a pipe command (for example, from
20697 an alias or forward file). In this case, $address_pipe contains the text of
20698 the pipe command, and the command option on the transport is ignored unless
20699 force_command is set. If only one address is being transported (batch_max
20700 is not greater than one, or only one address was redirected to this pipe
20701 command), $local_part contains the local part that was redirected.
20703 The pipe transport is a non-interactive delivery method. Exim can also deliver
20704 messages over pipes using the LMTP interactive protocol. This is implemented by
20705 the lmtp transport.
20707 In the case when pipe is run as a consequence of an entry in a local user's
20708 .forward file, the command runs under the uid and gid of that user. In other
20709 cases, the uid and gid have to be specified explicitly, either on the transport
20710 or on the router that handles the address. Current and "home" directories are
20711 also controllable. See chapter 23 for details of the local delivery environment
20712 and chapter 25 for a discussion of local delivery batching.
20715 29.1 Concurrent delivery
20716 ------------------------
20718 If two messages arrive at almost the same time, and both are routed to a pipe
20719 delivery, the two pipe transports may be run concurrently. You must ensure that
20720 any pipe commands you set up are robust against this happening. If the commands
20721 write to a file, the exim_lock utility might be of use.
20724 29.2 Returned status and data
20725 -----------------------------
20727 If the command exits with a non-zero return code, the delivery is deemed to
20728 have failed, unless either the ignore_status option is set (in which case the
20729 return code is treated as zero), or the return code is one of those listed in
20730 the temp_errors option, which are interpreted as meaning "try again later". In
20731 this case, delivery is deferred. Details of a permanent failure are logged, but
20732 are not included in the bounce message, which merely contains "local delivery
20735 If the command exits on a signal and the freeze_signal option is set then the
20736 message will be frozen in the queue. If that option is not set, a bounce will
20739 If the return code is greater than 128 and the command being run is a shell
20740 script, it normally means that the script was terminated by a signal whose
20741 value is the return code minus 128. The freeze_signal option does not apply in
20744 If Exim is unable to run the command (that is, if execve() fails), the return
20745 code is set to 127. This is the value that a shell returns if it is asked to
20746 run a non-existent command. The wording for the log line suggests that a
20747 non-existent command may be the problem.
20749 The return_output option can affect the result of a pipe delivery. If it is set
20750 and the command produces any output on its standard output or standard error
20751 streams, the command is considered to have failed, even if it gave a zero
20752 return code or if ignore_status is set. The output from the command is included
20753 as part of the bounce message. The return_fail_output option is similar, except
20754 that output is returned only when the command exits with a failure return code,
20755 that is, a value other than zero or a code that matches temp_errors.
20758 29.3 How the command is run
20759 ---------------------------
20761 The command line is (by default) broken down into a command name and arguments
20762 by the pipe transport itself. The allow_commands and restrict_to_path options
20763 can be used to restrict the commands that may be run.
20765 Unquoted arguments are delimited by white space. If an argument appears in
20766 double quotes, backslash is interpreted as an escape character in the usual
20767 way. If an argument appears in single quotes, no escaping is done.
20769 String expansion is applied to the command line except when it comes from a
20770 traditional .forward file (commands from a filter file are expanded). The
20771 expansion is applied to each argument in turn rather than to the whole line.
20772 For this reason, any string expansion item that contains white space must be
20773 quoted so as to be contained within a single argument. A setting such as
20775 command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}}
20777 will not work, because the expansion item gets split between several arguments.
20780 command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}"
20782 to ensure that it is all in one argument. The expansion is done in this way,
20783 argument by argument, so that the number of arguments cannot be changed as a
20784 result of expansion, and quotes or backslashes in inserted variables do not
20785 interact with external quoting. However, this leads to problems if you want to
20786 generate multiple arguments (or the command name plus arguments) from a single
20787 expansion. In this situation, the simplest solution is to use a shell. For
20790 command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}}
20792 Special handling takes place when an argument consists of precisely the text
20793 "$pipe_addresses". This is not a general expansion variable; the only place
20794 this string is recognized is when it appears as an argument for a pipe or
20795 transport filter command. It causes each address that is being handled to be
20796 inserted in the argument list at that point as a separate argument. This avoids
20797 any problems with spaces or shell metacharacters, and is of use when a pipe
20798 transport is handling groups of addresses in a batch.
20800 If force_command is enabled on the transport, Special handling takes place for
20801 an argument that consists of precisely the text "$address_pipe". It is handled
20802 similarly to $pipe_addresses above. It is expanded and each argument is
20803 inserted in the argument list at that point as a separate argument. The
20804 "$address_pipe" item does not need to be the only item in the argument; in
20805 fact, if it were then force_command should behave as a no-op. Rather, it should
20806 be used to adjust the command run while preserving the argument vector
20809 After splitting up into arguments and expansion, the resulting command is run
20810 in a subprocess directly from the transport, not under a shell. The message
20811 that is being delivered is supplied on the standard input, and the standard
20812 output and standard error are both connected to a single pipe that is read by
20813 Exim. The max_output option controls how much output the command may produce,
20814 and the return_output and return_fail_output options control what is done with
20817 Not running the command under a shell (by default) lessens the security risks
20818 in cases when a command from a user's filter file is built out of data that was
20819 taken from an incoming message. If a shell is required, it can of course be
20820 explicitly specified as the command to be run. However, there are circumstances
20821 where existing commands (for example, in .forward files) expect to be run under
20822 a shell and cannot easily be modified. To allow for these cases, there is an
20823 option called use_shell, which changes the way the pipe transport works.
20824 Instead of breaking up the command line as just described, it expands it as a
20825 single string and passes the result to /bin/sh. The restrict_to_path option and
20826 the $pipe_addresses facility cannot be used with use_shell, and the whole
20827 mechanism is inherently less secure.
20830 29.4 Environment variables
20831 --------------------------
20833 The environment variables listed below are set up when the command is invoked.
20834 This list is a compromise for maximum compatibility with other MTAs. Note that
20835 the environment option can be used to add additional variables to this
20838 DOMAIN the domain of the address
20839 HOME the home directory, if set
20840 HOST the host name when called from a router (see below)
20841 LOCAL_PART see below
20842 LOCAL_PART_PREFIX see below
20843 LOCAL_PART_SUFFIX see below
20845 MESSAGE_ID Exim's local ID for the message
20846 PATH as specified by the path option below
20847 QUALIFY_DOMAIN the sender qualification domain
20848 RECIPIENT the complete recipient address
20849 SENDER the sender of the message (empty if a bounce)
20851 TZ the value of the timezone option, if set
20854 When a pipe transport is called directly from (for example) an accept router,
20855 LOCAL_PART is set to the local part of the address. When it is called as a
20856 result of a forward or alias expansion, LOCAL_PART is set to the local part of
20857 the address that was expanded. In both cases, any affixes are removed from the
20858 local part, and made available in LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX,
20859 respectively. LOGNAME and USER are set to the same value as LOCAL_PART for
20860 compatibility with other MTAs.
20862 HOST is set only when a pipe transport is called from a router that associates
20863 hosts with an address, typically when using pipe as a pseudo-remote transport.
20864 HOST is set to the first host name specified by the router.
20866 If the transport's generic home_directory option is set, its value is used for
20867 the HOME environment variable. Otherwise, a home directory may be set by the
20868 router's transport_home_directory option, which defaults to the user's home
20869 directory if check_local_user is set.
20872 29.5 Private options for pipe
20873 -----------------------------
20875 +--------------+---------+------------------+--------------+
20876 |allow_commands|Use: pipe|Type: string list*|Default: unset|
20877 +--------------+---------+------------------+--------------+
20879 The string is expanded, and is then interpreted as a colon-separated list of
20880 permitted commands. If restrict_to_path is not set, the only commands permitted
20881 are those in the allow_commands list. They need not be absolute paths; the path
20882 option is still used for relative paths. If restrict_to_path is set with
20883 allow_commands, the command must either be in the allow_commands list, or a
20884 name without any slashes that is found on the path. In other words, if neither
20885 allow_commands nor restrict_to_path is set, there is no restriction on the
20886 command, but otherwise only commands that are permitted by one or the other are
20887 allowed. For example, if
20889 allow_commands = /usr/bin/vacation
20891 and restrict_to_path is not set, the only permitted command is /usr/bin/
20892 vacation. The allow_commands option may not be set if use_shell is set.
20894 +--------+---------+-------------+--------------+
20895 |batch_id|Use: pipe|Type: string*|Default: unset|
20896 +--------+---------+-------------+--------------+
20898 See the description of local delivery batching in chapter 25.
20900 +---------+---------+-------------+----------+
20901 |batch_max|Use: pipe|Type: integer|Default: 1|
20902 +---------+---------+-------------+----------+
20904 This limits the number of addresses that can be handled in a single delivery.
20905 See the description of local delivery batching in chapter 25.
20907 +------------+---------+------------+--------------+
20908 |check_string|Use: pipe|Type: string|Default: unset|
20909 +------------+---------+------------+--------------+
20911 As pipe writes the message, the start of each line is tested for matching
20912 check_string, and if it does, the initial matching characters are replaced by
20913 the contents of escape_string, provided both are set. The value of check_string
20914 is a literal string, not a regular expression, and the case of any letters it
20915 contains is significant. When use_bsmtp is set, the contents of check_string
20916 and escape_string are forced to values that implement the SMTP escaping
20917 protocol. Any settings made in the configuration file are ignored.
20919 +-------+---------+-------------+--------------+
20920 |command|Use: pipe|Type: string*|Default: unset|
20921 +-------+---------+-------------+--------------+
20923 This option need not be set when pipe is being used to deliver to pipes
20924 obtained directly from address redirections. In other cases, the option must be
20925 set, to provide a command to be run. It need not yield an absolute path (see
20926 the path option below). The command is split up into separate arguments by
20927 Exim, and each argument is separately expanded, as described in section 29.3
20930 +-----------+---------+-------------+--------------+
20931 |environment|Use: pipe|Type: string*|Default: unset|
20932 +-----------+---------+-------------+--------------+
20934 This option is used to add additional variables to the environment in which the
20935 command runs (see section 29.4 for the default list). Its value is a string
20936 which is expanded, and then interpreted as a colon-separated list of
20937 environment settings of the form <name>=<value>.
20939 +-------------+---------+------------+--------------+
20940 |escape_string|Use: pipe|Type: string|Default: unset|
20941 +-------------+---------+------------+--------------+
20943 See check_string above.
20945 +----------------+---------+-------------+--------------+
20946 |freeze_exec_fail|Use: pipe|Type: boolean|Default: false|
20947 +----------------+---------+-------------+--------------+
20949 Failure to exec the command in a pipe transport is by default treated like any
20950 other failure while running the command. However, if freeze_exec_fail is set,
20951 failure to exec is treated specially, and causes the message to be frozen,
20952 whatever the setting of ignore_status.
20954 +-------------+---------+-------------+--------------+
20955 |freeze_signal|Use: pipe|Type: boolean|Default: false|
20956 +-------------+---------+-------------+--------------+
20958 Normally if the process run by a command in a pipe transport exits on a signal,
20959 a bounce message is sent. If freeze_signal is set, the message will be frozen
20960 in Exim's queue instead.
20962 +-------------+---------+-------------+--------------+
20963 |force_command|Use: pipe|Type: boolean|Default: false|
20964 +-------------+---------+-------------+--------------+
20966 Normally when a router redirects an address directly to a pipe command the
20967 command option on the transport is ignored. If force_command is set, the
20968 command option will used. This is especially useful for forcing a wrapper or
20969 additional argument to be added to the command. For example:
20971 command = /usr/bin/remote_exec myhost -- $address_pipe
20974 Note that $address_pipe is handled specially in command when force_command is
20975 set, expanding out to the original argument vector as separate items, similarly
20976 to a Unix shell ""$@"" construct.
20978 +-------------+---------+-------------+--------------+
20979 |ignore_status|Use: pipe|Type: boolean|Default: false|
20980 +-------------+---------+-------------+--------------+
20982 If this option is true, the status returned by the subprocess that is set up to
20983 run the command is ignored, and Exim behaves as if zero had been returned.
20984 Otherwise, a non-zero status or termination by signal causes an error return
20985 from the transport unless the status value is one of those listed in
20986 temp_errors; these cause the delivery to be deferred and tried again later.
20988 Note: This option does not apply to timeouts, which do not return a status. See
20989 the timeout_defer option for how timeouts are handled.
20991 +----------------+---------+-------------+--------------+
20992 |log_defer_output|Use: pipe|Type: boolean|Default: false|
20993 +----------------+---------+-------------+--------------+
20995 If this option is set, and the status returned by the command is one of the
20996 codes listed in temp_errors (that is, delivery was deferred), and any output
20997 was produced, the first line of it is written to the main log.
20999 +---------------+---------+-------------+--------------+
21000 |log_fail_output|Use: pipe|Type: boolean|Default: false|
21001 +---------------+---------+-------------+--------------+
21003 If this option is set, and the command returns any output, and also ends with a
21004 return code that is neither zero nor one of the return codes listed in
21005 temp_errors (that is, the delivery failed), the first line of output is written
21006 to the main log. This option and log_output are mutually exclusive. Only one of
21009 +----------+---------+-------------+--------------+
21010 |log_output|Use: pipe|Type: boolean|Default: false|
21011 +----------+---------+-------------+--------------+
21013 If this option is set and the command returns any output, the first line of
21014 output is written to the main log, whatever the return code. This option and
21015 log_fail_output are mutually exclusive. Only one of them may be set.
21017 +----------+---------+-------------+------------+
21018 |max_output|Use: pipe|Type: integer|Default: 20K|
21019 +----------+---------+-------------+------------+
21021 This specifies the maximum amount of output that the command may produce on its
21022 standard output and standard error file combined. If the limit is exceeded, the
21023 process running the command is killed. This is intended as a safety measure to
21024 catch runaway processes. The limit is applied independently of the settings of
21025 the options that control what is done with such output (for example,
21026 return_output). Because of buffering effects, the amount of output may exceed
21027 the limit by a small amount before Exim notices.
21029 +--------------+---------+-------------+------------------+
21030 |message_prefix|Use: pipe|Type: string*|Default: see below|
21031 +--------------+---------+-------------+------------------+
21033 The string specified here is expanded and output at the start of every message.
21034 The default is unset if use_bsmtp is set. Otherwise it is
21037 From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
21040 This is required by the commonly used /usr/bin/vacation program. However, it
21041 must not be present if delivery is to the Cyrus IMAP server, or to the tmail
21042 local delivery agent. The prefix can be suppressed by setting
21046 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
21047 n" in message_prefix.
21049 +--------------+---------+-------------+------------------+
21050 |message_suffix|Use: pipe|Type: string*|Default: see below|
21051 +--------------+---------+-------------+------------------+
21053 The string specified here is expanded and output at the end of every message.
21054 The default is unset if use_bsmtp is set. Otherwise it is a single newline. The
21055 suffix can be suppressed by setting
21059 Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
21060 n" in message_suffix.
21062 +----+---------+------------+------------------+
21063 |path|Use: pipe|Type: string|Default: see below|
21064 +----+---------+------------+------------------+
21066 This option specifies the string that is set up in the PATH environment
21067 variable of the subprocess. The default is:
21071 If the command option does not yield an absolute path name, the command is
21072 sought in the PATH directories, in the usual way. Warning: This does not apply
21073 to a command specified as a transport filter.
21075 +---------------+---------+-------------+--------------+
21076 |permit_coredump|Use: pipe|Type: boolean|Default: false|
21077 +---------------+---------+-------------+--------------+
21079 Normally Exim inhibits core-dumps during delivery. If you have a need to get a
21080 core-dump of a pipe command, enable this command. This enables core-dumps
21081 during delivery and affects both the Exim binary and the pipe command run. It
21082 is recommended that this option remain off unless and until you have a need for
21083 it and that this only be enabled when needed, as the risk of excessive resource
21084 consumption can be quite high. Note also that Exim is typically installed as a
21085 setuid binary and most operating systems will inhibit coredumps of these by
21086 default, so further OS-specific action may be required.
21088 +---------------+---------+-------------+--------------+
21089 |pipe_as_creator|Use: pipe|Type: boolean|Default: false|
21090 +---------------+---------+-------------+--------------+
21092 If the generic user option is not set and this option is true, the delivery
21093 process is run under the uid that was in force when Exim was originally called
21094 to accept the message. If the group id is not otherwise set (via the generic
21095 group option), the gid that was in force when Exim was originally called to
21096 accept the message is used.
21098 +----------------+---------+-------------+--------------+
21099 |restrict_to_path|Use: pipe|Type: boolean|Default: false|
21100 +----------------+---------+-------------+--------------+
21102 When this option is set, any command name not listed in allow_commands must
21103 contain no slashes. The command is searched for only in the directories listed
21104 in the path option. This option is intended for use in the case when a pipe
21105 command has been generated from a user's .forward file. This is usually handled
21106 by a pipe transport called address_pipe.
21108 +------------------+---------+-------------+--------------+
21109 |return_fail_output|Use: pipe|Type: boolean|Default: false|
21110 +------------------+---------+-------------+--------------+
21112 If this option is true, and the command produced any output and ended with a
21113 return code other than zero or one of the codes listed in temp_errors (that is,
21114 the delivery failed), the output is returned in the bounce message. However, if
21115 the message has a null sender (that is, it is itself a bounce message), output
21116 from the command is discarded. This option and return_output are mutually
21117 exclusive. Only one of them may be set.
21119 +-------------+---------+-------------+--------------+
21120 |return_output|Use: pipe|Type: boolean|Default: false|
21121 +-------------+---------+-------------+--------------+
21123 If this option is true, and the command produced any output, the delivery is
21124 deemed to have failed whatever the return code from the command, and the output
21125 is returned in the bounce message. Otherwise, the output is just discarded.
21126 However, if the message has a null sender (that is, it is a bounce message),
21127 output from the command is always discarded, whatever the setting of this
21128 option. This option and return_fail_output are mutually exclusive. Only one of
21131 +-----------+---------+-----------------+------------------+
21132 |temp_errors|Use: pipe|Type: string list|Default: see below|
21133 +-----------+---------+-----------------+------------------+
21135 This option contains either a colon-separated list of numbers, or a single
21136 asterisk. If ignore_status is false and return_output is not set, and the
21137 command exits with a non-zero return code, the failure is treated as temporary
21138 and the delivery is deferred if the return code matches one of the numbers, or
21139 if the setting is a single asterisk. Otherwise, non-zero return codes are
21140 treated as permanent errors. The default setting contains the codes defined by
21141 EX_TEMPFAIL and EX_CANTCREAT in sysexits.h. If Exim is compiled on a system
21142 that does not define these macros, it assumes values of 75 and 73,
21145 +-------+---------+----------+-----------+
21146 |timeout|Use: pipe|Type: time|Default: 1h|
21147 +-------+---------+----------+-----------+
21149 If the command fails to complete within this time, it is killed. This normally
21150 causes the delivery to fail (but see timeout_defer). A zero time interval
21151 specifies no timeout. In order to ensure that any subprocesses created by the
21152 command are also killed, Exim makes the initial process a process group leader,
21153 and kills the whole process group on a timeout. However, this can be defeated
21154 if one of the processes starts a new process group.
21156 +-------------+---------+-------------+--------------+
21157 |timeout_defer|Use: pipe|Type: boolean|Default: false|
21158 +-------------+---------+-------------+--------------+
21160 A timeout in a pipe transport, either in the command that the transport runs,
21161 or in a transport filter that is associated with it, is by default treated as a
21162 hard error, and the delivery fails. However, if timeout_defer is set true, both
21163 kinds of timeout become temporary errors, causing the delivery to be deferred.
21165 +-----+---------+-------------------+------------+
21166 |umask|Use: pipe|Type: octal integer|Default: 022|
21167 +-----+---------+-------------------+------------+
21169 This specifies the umask setting for the subprocess that runs the command.
21171 +---------+---------+-------------+--------------+
21172 |use_bsmtp|Use: pipe|Type: boolean|Default: false|
21173 +---------+---------+-------------+--------------+
21175 If this option is set true, the pipe transport writes messages in "batch SMTP"
21176 format, with the envelope sender and recipient(s) included as SMTP commands. If
21177 you want to include a leading HELO command with such messages, you can do so by
21178 setting the message_prefix option. See section 47.10 for details of batch SMTP.
21180 +------------------+---------+-------------+--------------+
21181 |use_classresources|Use: pipe|Type: boolean|Default: false|
21182 +------------------+---------+-------------+--------------+
21184 This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/
21185 OS. If it is set true, the setclassresources() function is used to set resource
21186 limits when a pipe transport is run to perform a delivery. The limits for the
21187 uid under which the pipe is to run are obtained from the login class database.
21189 +--------+---------+-------------+--------------+
21190 |use_crlf|Use: pipe|Type: boolean|Default: false|
21191 +--------+---------+-------------+--------------+
21193 This option causes lines to be terminated with the two-character CRLF sequence
21194 (carriage return, linefeed) instead of just a linefeed character. In the case
21195 of batched SMTP, the byte sequence written to the pipe is then an exact image
21196 of what would be sent down a real SMTP connection.
21198 The contents of the message_prefix and message_suffix options are written
21199 verbatim, so must contain their own carriage return characters if these are
21200 needed. When use_bsmtp is not set, the default values for both message_prefix
21201 and message_suffix end with a single linefeed, so their values must be changed
21202 to end with "\r\n" if use_crlf is set.
21204 +---------+---------+-------------+--------------+
21205 |use_shell|Use: pipe|Type: boolean|Default: false|
21206 +---------+---------+-------------+--------------+
21208 If this option is set, it causes the command to be passed to /bin/sh instead of
21209 being run directly from the transport, as described in section 29.3. This is
21210 less secure, but is needed in some situations where the command is expected to
21211 be run under a shell and cannot easily be modified. The allow_commands and
21212 restrict_to_path options, and the "$pipe_addresses" facility are incompatible
21213 with use_shell. The command is expanded as a single string, and handed to /bin/
21214 sh as data for its -c option.
21217 29.6 Using an external local delivery agent
21218 -------------------------------------------
21220 The pipe transport can be used to pass all messages that require local delivery
21221 to a separate local delivery agent such as procmail. When doing this, care must
21222 be taken to ensure that the pipe is run under an appropriate uid and gid. In
21223 some configurations one wants this to be a uid that is trusted by the delivery
21224 agent to supply the correct sender of the message. It may be necessary to
21225 recompile or reconfigure the delivery agent so that it trusts an appropriate
21226 user. The following is an example transport and router configuration for
21232 command = /usr/local/bin/procmail -d $local_part
21236 check_string = "From "
21237 escape_string = ">From "
21246 transport = procmail_pipe
21248 In this example, the pipe is run as the local user, but with the group set to
21249 mail. An alternative is to run the pipe as a specific user such as mail or exim
21250 , but in this case you must arrange for procmail to trust that user to supply a
21251 correct sender address. If you do not specify either a group or a user option,
21252 the pipe command is run as the local user. The home directory is the user's
21253 home directory by default.
21255 Note: The command that the pipe transport runs does not begin with
21259 as shown in some procmail documentation, because Exim does not by default use a
21260 shell to run pipe commands.
21262 The next example shows a transport and a router for a system where local
21263 deliveries are handled by the Cyrus IMAP server.
21266 local_delivery_cyrus:
21268 command = /usr/cyrus/bin/deliver \
21269 -m ${substr_1:$local_part_suffix} -- $local_part
21281 local_part_suffix = .*
21282 transport = local_delivery_cyrus
21284 Note the unsetting of message_prefix and message_suffix, and the use of
21285 return_output to cause any text written by Cyrus to be returned to the sender.
21289 ===============================================================================
21290 30. THE SMTP TRANSPORT
21292 The smtp transport delivers messages over TCP/IP connections using the SMTP or
21293 LMTP protocol. The list of hosts to try can either be taken from the address
21294 that is being processed (having been set up by the router), or specified
21295 explicitly for the transport. Timeout and retry processing (see chapter 32) is
21296 applied to each IP address independently.
21299 30.1 Multiple messages on a single connection
21300 ---------------------------------------------
21302 The sending of multiple messages over a single TCP/IP connection can arise in
21305 * If a message contains more than max_rcpt (see below) addresses that are
21306 routed to the same host, more than one copy of the message has to be sent
21307 to that host. In this situation, multiple copies may be sent in a single
21308 run of the smtp transport over a single TCP/IP connection. (What Exim
21309 actually does when it has too many addresses to send in one message also
21310 depends on the value of the global remote_max_parallel option. Details are
21311 given in section 47.1.)
21313 * When a message has been successfully delivered over a TCP/IP connection,
21314 Exim looks in its hints database to see if there are any other messages
21315 awaiting a connection to the same host. If there are, a new delivery
21316 process is started for one of them, and the current TCP/IP connection is
21317 passed on to it. The new process may in turn send multiple copies and
21318 possibly create yet another process.
21320 For each copy sent over the same TCP/IP connection, a sequence counter is
21321 incremented, and if it ever gets to the value of connection_max_messages, no
21322 further messages are sent over that connection.
21325 30.2 Use of the $host and $host_address variables
21326 -------------------------------------------------
21328 At the start of a run of the smtp transport, the values of $host and
21329 $host_address are the name and IP address of the first host on the host list
21330 passed by the router. However, when the transport is about to connect to a
21331 specific host, and while it is connected to that host, $host and $host_address
21332 are set to the values for that host. These are the values that are in force
21333 when the helo_data, hosts_try_auth, interface, serialize_hosts, and the various
21334 TLS options are expanded.
21337 30.3 Use of $tls_cipher and $tls_peerdn
21338 ---------------------------------------
21340 At the start of a run of the smtp transport, the values of $tls_bits,
21341 $tls_cipher, $tls_peerdn and $tls_sni are the values that were set when the
21342 message was received. These are the values that are used for options that are
21343 expanded before any SMTP connections are made. Just before each connection is
21344 made, these four variables are emptied. If TLS is subsequently started, they
21345 are set to the appropriate values for the outgoing connection, and these are
21346 the values that are in force when any authenticators are run and when the
21347 authenticated_sender option is expanded.
21349 These variables are deprecated in favour of $tls_in_cipher et. al. and will be
21350 removed in a future release.
21353 30.4 Private options for smtp
21354 -----------------------------
21356 The private options of the smtp transport are as follows:
21358 +----------------------------+---------+-------------+-------------+
21359 |address_retry_include_sender|Use: smtp|Type: boolean|Default: true|
21360 +----------------------------+---------+-------------+-------------+
21362 When an address is delayed because of a 4xx response to a RCPT command, it is
21363 the combination of sender and recipient that is delayed in subsequent queue
21364 runs until the retry time is reached. You can delay the recipient without
21365 reference to the sender (which is what earlier versions of Exim did), by
21366 setting address_retry_include_sender false. However, this can lead to problems
21367 with servers that regularly issue 4xx responses to RCPT commands.
21369 +---------------+---------+-------------+--------------+
21370 |allow_localhost|Use: smtp|Type: boolean|Default: false|
21371 +---------------+---------+-------------+--------------+
21373 When a host specified in hosts or fallback_hosts (see below) turns out to be
21374 the local host, or is listed in hosts_treat_as_local, delivery is deferred by
21375 default. However, if allow_localhost is set, Exim goes on to do the delivery
21376 anyway. This should be used only in special cases when the configuration
21377 ensures that no looping will result (for example, a differently configured Exim
21378 is listening on the port to which the message is sent).
21380 +--------------------+---------+-------------+--------------+
21381 |authenticated_sender|Use: smtp|Type: string*|Default: unset|
21382 +--------------------+---------+-------------+--------------+
21384 When Exim has authenticated as a client, or if authenticated_sender_force is
21385 true, this option sets a value for the AUTH= item on outgoing MAIL commands,
21386 overriding any existing authenticated sender value. If the string expansion is
21387 forced to fail, the option is ignored. Other expansion failures cause delivery
21388 to be deferred. If the result of expansion is an empty string, that is also
21391 The expansion happens after the outgoing connection has been made and TLS
21392 started, if required. This means that the $host, $host_address, $tls_out_cipher
21393 , and $tls_out_peerdn variables are set according to the particular connection.
21395 If the SMTP session is not authenticated, the expansion of authenticated_sender
21396 still happens (and can cause the delivery to be deferred if it fails), but no
21397 AUTH= item is added to MAIL commands unless authenticated_sender_force is true.
21399 This option allows you to use the smtp transport in LMTP mode to deliver mail
21400 to Cyrus IMAP and provide the proper local part as the "authenticated sender",
21401 via a setting such as:
21403 authenticated_sender = $local_part
21405 This removes the need for IMAP subfolders to be assigned special ACLs to allow
21406 direct delivery to those subfolders.
21408 Because of expected uses such as that just described for Cyrus (when no domain
21409 is involved), there is no checking on the syntax of the provided value.
21411 +--------------------------+---------+-------------+--------------+
21412 |authenticated_sender_force|Use: smtp|Type: boolean|Default: false|
21413 +--------------------------+---------+-------------+--------------+
21415 If this option is set true, the authenticated_sender option's value is used for
21416 the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as
21419 +---------------+---------+----------+-----------+
21420 |command_timeout|Use: smtp|Type: time|Default: 5m|
21421 +---------------+---------+----------+-----------+
21423 This sets a timeout for receiving a response to an SMTP command that has been
21424 sent out. It is also used when waiting for the initial banner line from the
21425 remote host. Its value must not be zero.
21427 +---------------+---------+----------+-----------+
21428 |connect_timeout|Use: smtp|Type: time|Default: 5m|
21429 +---------------+---------+----------+-----------+
21431 This sets a timeout for the connect() function, which sets up a TCP/IP call to
21432 a remote host. A setting of zero allows the system timeout (typically several
21433 minutes) to act. To have any effect, the value of this option must be less than
21434 the system timeout. However, it has been observed that on some systems there is
21435 no system timeout, which is why the default value for this option is 5 minutes,
21436 a value recommended by RFC 1123.
21438 +-----------------------+---------+-------------+------------+
21439 |connection_max_messages|Use: smtp|Type: integer|Default: 500|
21440 +-----------------------+---------+-------------+------------+
21442 This controls the maximum number of separate message deliveries that are sent
21443 over a single TCP/IP connection. If the value is zero, there is no limit. For
21444 testing purposes, this value can be overridden by the -oB command line option.
21446 +------------+---------+----------+-----------+
21447 |data_timeout|Use: smtp|Type: time|Default: 5m|
21448 +------------+---------+----------+-----------+
21450 This sets a timeout for the transmission of each block in the data portion of
21451 the message. As a result, the overall timeout for a message depends on the size
21452 of the message. Its value must not be zero. See also final_timeout.
21454 +------------------+---------+-------------+-------------+
21455 |delay_after_cutoff|Use: smtp|Type: boolean|Default: true|
21456 +------------------+---------+-------------+-------------+
21458 This option controls what happens when all remote IP addresses for a given
21459 domain have been inaccessible for so long that they have passed their retry
21462 In the default state, if the next retry time has not been reached for any of
21463 them, the address is bounced without trying any deliveries. In other words,
21464 Exim delays retrying an IP address after the final cutoff time until a new
21465 retry time is reached, and can therefore bounce an address without ever trying
21466 a delivery, when machines have been down for a long time. Some people are
21467 unhappy at this prospect, so...
21469 If delay_after_cutoff is set false, Exim behaves differently. If all IP
21470 addresses are past their final cutoff time, Exim tries to deliver to those IP
21471 addresses that have not been tried since the message arrived. If there are
21472 none, of if they all fail, the address is bounced. In other words, it does not
21473 delay when a new message arrives, but immediately tries those expired IP
21474 addresses that haven't been tried since the message arrived. If there is a
21475 continuous stream of messages for the dead hosts, unsetting delay_after_cutoff
21476 means that there will be many more attempts to deliver to them.
21478 +------------------+---------+-------------+-------------+
21479 |dns_qualify_single|Use: smtp|Type: boolean|Default: true|
21480 +------------------+---------+-------------+-------------+
21482 If the hosts or fallback_hosts option is being used, and the gethostbyname
21483 option is false, the RES_DEFNAMES resolver option is set. See the
21484 qualify_single option in chapter 17 for more details.
21486 +------------------+---------+-------------+--------------+
21487 |dns_search_parents|Use: smtp|Type: boolean|Default: false|
21488 +------------------+---------+-------------+--------------+
21490 If the hosts or fallback_hosts option is being used, and the gethostbyname
21491 option is false, the RES_DNSRCH resolver option is set. See the search_parents
21492 option in chapter 17 for more details.
21494 +----------------------+---------+------------------+--------------+
21495 |dnssec_request_domains|Use: smtp|Type: domain list*|Default: unset|
21496 +----------------------+---------+------------------+--------------+
21498 DNS lookups for domains matching dnssec_request_domains will be done with the
21499 dnssec request bit set. This applies to all of the SRV, MX A6, AAAA, A lookup
21502 +----------------------+---------+------------------+--------------+
21503 |dnssec_require_domains|Use: smtp|Type: domain list*|Default: unset|
21504 +----------------------+---------+------------------+--------------+
21506 DNS lookups for domains matching dnssec_request_domains will be done with the
21507 dnssec request bit set. Any returns not having the Authenticated Data bit (AD
21508 bit) set wil be ignored and logged as a host-lookup failure. This applies to
21509 all of the SRV, MX A6, AAAA, A lookup sequence.
21511 +----+---------+-------------+--------------+
21512 |dscp|Use: smtp|Type: string*|Default: unset|
21513 +----+---------+-------------+--------------+
21515 This option causes the DSCP value associated with a socket to be set to one of
21516 a number of fixed strings or to numeric value. The -bI:dscp option may be used
21517 to ask Exim which names it knows of. Common values include "throughput",
21518 "mincost", and on newer systems "ef", "af41", etc. Numeric values may be in the
21521 The outbound packets from Exim will be marked with this value in the header
21522 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee
21523 that these values will have any effect, not be stripped by networking
21524 equipment, or do much of anything without cooperation with your Network
21525 Engineer and those of all network operators between the source and destination.
21527 +--------------+---------+-----------------+--------------+
21528 |fallback_hosts|Use: smtp|Type: string list|Default: unset|
21529 +--------------+---------+-----------------+--------------+
21531 String expansion is not applied to this option. The argument must be a
21532 colon-separated list of host names or IP addresses, optionally also including
21533 port numbers, though the separator can be changed, as described in section 6.19
21534 . Each individual item in the list is the same as an item in a route_list
21535 setting for the manualroute router, as described in section 20.5.
21537 Fallback hosts can also be specified on routers, which associate them with the
21538 addresses they process. As for the hosts option without hosts_override,
21539 fallback_hosts specified on the transport is used only if the address does not
21540 have its own associated fallback host list. Unlike hosts, a setting of
21541 fallback_hosts on an address is not overridden by hosts_override. However,
21542 hosts_randomize does apply to fallback host lists.
21544 If Exim is unable to deliver to any of the hosts for a particular address, and
21545 the errors are not permanent rejections, the address is put on a separate
21546 transport queue with its host list replaced by the fallback hosts, unless the
21547 address was routed via MX records and the current host was in the original MX
21548 list. In that situation, the fallback host list is not used.
21550 Once normal deliveries are complete, the fallback queue is delivered by
21551 re-running the same transports with the new host lists. If several failing
21552 addresses have the same fallback hosts (and max_rcpt permits it), a single copy
21553 of the message is sent.
21555 The resolution of the host names on the fallback list is controlled by the
21556 gethostbyname option, as for the hosts option. Fallback hosts apply both to
21557 cases when the host list comes with the address and when it is taken from hosts
21558 . This option provides a "use a smart host only if delivery fails" facility.
21560 +-------------+---------+----------+------------+
21561 |final_timeout|Use: smtp|Type: time|Default: 10m|
21562 +-------------+---------+----------+------------+
21564 This is the timeout that applies while waiting for the response to the final
21565 line containing just "." that terminates a message. Its value must not be zero.
21567 +-------------+---------+-------------+--------------+
21568 |gethostbyname|Use: smtp|Type: boolean|Default: false|
21569 +-------------+---------+-------------+--------------+
21571 If this option is true when the hosts and/or fallback_hosts options are being
21572 used, names are looked up using gethostbyname() (or getipnodebyname() when
21573 available) instead of using the DNS. Of course, that function may in fact use
21574 the DNS, but it may also consult other sources of information such as /etc/
21577 +------------------+---------+-------------+--------------+
21578 |gnutls_compat_mode|Use: smtp|Type: boolean|Default: unset|
21579 +------------------+---------+-------------+--------------+
21581 This option controls whether GnuTLS is used in compatibility mode in an Exim
21582 server. This reduces security slightly, but improves interworking with older
21583 implementations of TLS.
21585 +---------+---------+-------------+------------------+
21586 |helo_data|Use: smtp|Type: string*|Default: see below|
21587 +---------+---------+-------------+------------------+
21589 The value of this option is expanded after a connection to a another host has
21590 been set up. The result is used as the argument for the EHLO, HELO, or LHLO
21591 command that starts the outgoing SMTP or LMTP session. The default value of the
21596 During the expansion, the variables $host and $host_address are set to the
21597 identity of the remote host, and the variables $sending_ip_address and
21598 $sending_port are set to the local IP address and port number that are being
21599 used. These variables can be used to generate different values for different
21600 servers or different local IP addresses. For example, if you want the string
21601 that is used for helo_data to be obtained by a DNS lookup of the outgoing
21602 interface address, you could use this:
21604 helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
21605 {$primary_hostname}}
21607 The use of helo_data applies both to sending messages and when doing callouts.
21609 +-----+---------+------------------+--------------+
21610 |hosts|Use: smtp|Type: string list*|Default: unset|
21611 +-----+---------+------------------+--------------+
21613 Hosts are associated with an address by a router such as dnslookup, which finds
21614 the hosts by looking up the address domain in the DNS, or by manualroute, which
21615 has lists of hosts in its configuration. However, email addresses can be passed
21616 to the smtp transport by any router, and not all of them can provide an
21617 associated list of hosts.
21619 The hosts option specifies a list of hosts to be used if the address being
21620 processed does not have any hosts associated with it. The hosts specified by
21621 hosts are also used, whether or not the address has its own hosts, if
21622 hosts_override is set.
21624 The string is first expanded, before being interpreted as a colon-separated
21625 list of host names or IP addresses, possibly including port numbers. The
21626 separator may be changed to something other than colon, as described in section
21627 6.19. Each individual item in the list is the same as an item in a route_list
21628 setting for the manualroute router, as described in section 20.5. However, note
21629 that the "/MX" facility of the manualroute router is not available here.
21631 If the expansion fails, delivery is deferred. Unless the failure was caused by
21632 the inability to complete a lookup, the error is logged to the panic log as
21633 well as the main log. Host names are looked up either by searching directly for
21634 address records in the DNS or by calling gethostbyname() (or getipnodebyname()
21635 when available), depending on the setting of the gethostbyname option. When
21636 Exim is compiled with IPv6 support, if a host that is looked up in the DNS has
21637 both IPv4 and IPv6 addresses, both types of address are used.
21639 During delivery, the hosts are tried in order, subject to their retry status,
21640 unless hosts_randomize is set.
21642 +-----------------+---------+----------------+--------------+
21643 |hosts_avoid_esmtp|Use: smtp|Type: host list*|Default: unset|
21644 +-----------------+---------+----------------+--------------+
21646 This option is for use with broken hosts that announce ESMTP facilities (for
21647 example, PIPELINING) and then fail to implement them properly. When a host
21648 matches hosts_avoid_esmtp, Exim sends HELO rather than EHLO at the start of the
21649 SMTP session. This means that it cannot use any of the ESMTP facilities such as
21650 AUTH, PIPELINING, SIZE, and STARTTLS.
21652 +----------------------+---------+----------------+--------------+
21653 |hosts_avoid_pipelining|Use: smtp|Type: host list*|Default: unset|
21654 +----------------------+---------+----------------+--------------+
21656 Exim will not use the SMTP PIPELINING extension when delivering to any host
21657 that matches this list, even if the server host advertises PIPELINING support.
21659 +---------------+---------+----------------+--------------+
21660 |hosts_avoid_tls|Use: smtp|Type: host list*|Default: unset|
21661 +---------------+---------+----------------+--------------+
21663 Exim will not try to start a TLS session when delivering to any host that
21664 matches this list. See chapter 41 for details of TLS.
21666 +----------------------+---------+----------------+----------+
21667 |hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: *|
21668 +----------------------+---------+----------------+----------+
21670 Exim will not try to start a TLS session for a verify callout, or when
21671 delivering in cutthrough mode, to any host that matches this list. Note that
21672 the default is to not use TLS.
21674 +-------------+---------+-------------+----------+
21675 |hosts_max_try|Use: smtp|Type: integer|Default: 5|
21676 +-------------+---------+-------------+----------+
21678 This option limits the number of IP addresses that are tried for any one
21679 delivery in cases where there are temporary delivery errors. Section 30.5
21680 describes in detail how the value of this option is used.
21682 +-----------------------+---------+-------------+-----------+
21683 |hosts_max_try_hardlimit|Use: smtp|Type: integer|Default: 50|
21684 +-----------------------+---------+-------------+-----------+
21686 This is an additional check on the maximum number of IP addresses that Exim
21687 tries for any one delivery. Section 30.5 describes its use and why it exists.
21689 +----------------+---------+----------------+--------------+
21690 |hosts_nopass_tls|Use: smtp|Type: host list*|Default: unset|
21691 +----------------+---------+----------------+--------------+
21693 For any host that matches this list, a connection on which a TLS session has
21694 been started will not be passed to a new delivery process for sending another
21695 message on the same connection. See section 41.11 for an explanation of when
21696 this might be needed.
21698 +--------------+---------+-------------+--------------+
21699 |hosts_override|Use: smtp|Type: boolean|Default: false|
21700 +--------------+---------+-------------+--------------+
21702 If this option is set and the hosts option is also set, any hosts that are
21703 attached to the address are ignored, and instead the hosts specified by the
21704 hosts option are always used. This option does not apply to fallback_hosts.
21706 +---------------+---------+-------------+--------------+
21707 |hosts_randomize|Use: smtp|Type: boolean|Default: false|
21708 +---------------+---------+-------------+--------------+
21710 If this option is set, and either the list of hosts is taken from the hosts or
21711 the fallback_hosts option, or the hosts supplied by the router were not
21712 obtained from MX records (this includes fallback hosts from the router), and
21713 were not randomized by the router, the order of trying the hosts is randomized
21714 each time the transport runs. Randomizing the order of a host list can be used
21715 to do crude load sharing.
21717 When hosts_randomize is true, a host list may be split into groups whose order
21718 is separately randomized. This makes it possible to set up MX-like behaviour.
21719 The boundaries between groups are indicated by an item that is just "+" in the
21720 host list. For example:
21722 hosts = host1:host2:host3:+:host4:host5
21724 The order of the first three hosts and the order of the last two hosts is
21725 randomized for each use, but the first three always end up before the last two.
21726 If hosts_randomize is not set, a "+" item in the list is ignored.
21728 +------------------+---------+----------------+--------------+
21729 |hosts_require_auth|Use: smtp|Type: host list*|Default: unset|
21730 +------------------+---------+----------------+--------------+
21732 This option provides a list of servers for which authentication must succeed
21733 before Exim will try to transfer a message. If authentication fails for servers
21734 which are not in this list, Exim tries to send unauthenticated. If
21735 authentication fails for one of these servers, delivery is deferred. This
21736 temporary error is detectable in the retry rules, so it can be turned into a
21737 hard failure if required. See also hosts_try_auth, and chapter 33 for details
21740 +------------------+---------+----------------+----------+
21741 |hosts_request_ocsp|Use: smtp|Type: host list*|Default: *|
21742 +------------------+---------+----------------+----------+
21744 Exim will request a Certificate Status on a TLS session for any host that
21745 matches this list. tls_verify_certificates should also be set for the
21748 +------------------+---------+----------------+--------------+
21749 |hosts_require_ocsp|Use: smtp|Type: host list*|Default: unset|
21750 +------------------+---------+----------------+--------------+
21752 Exim will request, and check for a valid Certificate Status being given, on a
21753 TLS session for any host that matches this list. tls_verify_certificates should
21754 also be set for the transport.
21756 +-----------------+---------+----------------+--------------+
21757 |hosts_require_tls|Use: smtp|Type: host list*|Default: unset|
21758 +-----------------+---------+----------------+--------------+
21760 Exim will insist on using a TLS session when delivering to any host that
21761 matches this list. See chapter 41 for details of TLS. Note: This option affects
21762 outgoing mail only. To insist on TLS for incoming messages, use an appropriate
21765 +--------------+---------+----------------+--------------+
21766 |hosts_try_auth|Use: smtp|Type: host list*|Default: unset|
21767 +--------------+---------+----------------+--------------+
21769 This option provides a list of servers to which, provided they announce
21770 authentication support, Exim will attempt to authenticate as a client when it
21771 connects. If authentication fails, Exim will try to transfer the message
21772 unauthenticated. See also hosts_require_auth, and chapter 33 for details of
21775 +--------------+---------+----------------+--------------+
21776 |hosts_try_prdr|Use: smtp|Type: host list*|Default: unset|
21777 +--------------+---------+----------------+--------------+
21779 This option provides a list of servers to which, provided they announce PRDR
21780 support, Exim will attempt to negotiate PRDR for multi-recipient messages.
21782 +---------+---------+------------------+--------------+
21783 |interface|Use: smtp|Type: string list*|Default: unset|
21784 +---------+---------+------------------+--------------+
21786 This option specifies which interface to bind to when making an outgoing SMTP
21787 call. The value is an IP address, not an interface name such as "eth0". Do not
21788 confuse this with the interface address that was used when a message was
21789 received, which is in $received_ip_address, formerly known as
21790 $interface_address. The name was changed to minimize confusion with the
21791 outgoing interface address. There is no variable that contains an outgoing
21792 interface address because, unless it is set by this option, its value is
21795 During the expansion of the interface option the variables $host and
21796 $host_address refer to the host to which a connection is about to be made
21797 during the expansion of the string. Forced expansion failure, or an empty
21798 string result causes the option to be ignored. Otherwise, after expansion, the
21799 string must be a list of IP addresses, colon-separated by default, but the
21800 separator can be changed in the usual way. For example:
21802 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
21804 The first interface of the correct type (IPv4 or IPv6) is used for the outgoing
21805 connection. If none of them are the correct type, the option is ignored. If
21806 interface is not set, or is ignored, the system's IP functions choose which
21807 interface to use if the host has more than one.
21809 +---------+---------+-------------+-------------+
21810 |keepalive|Use: smtp|Type: boolean|Default: true|
21811 +---------+---------+-------------+-------------+
21813 This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket
21814 connections. When set, it causes the kernel to probe idle connections
21815 periodically, by sending packets with "old" sequence numbers. The other end of
21816 the connection should send a acknowledgment if the connection is still okay or
21817 a reset if the connection has been aborted. The reason for doing this is that
21818 it has the beneficial effect of freeing up certain types of connection that can
21819 get stuck when the remote host is disconnected without tidying up the TCP/IP
21820 call properly. The keepalive mechanism takes several hours to detect
21823 +-----------------+---------+-------------+--------------+
21824 |lmtp_ignore_quota|Use: smtp|Type: boolean|Default: false|
21825 +-----------------+---------+-------------+--------------+
21827 If this option is set true when the protocol option is set to "lmtp", the
21828 string "IGNOREQUOTA" is added to RCPT commands, provided that the LMTP server
21829 has advertised support for IGNOREQUOTA in its response to the LHLO command.
21831 +--------+---------+-------------+------------+
21832 |max_rcpt|Use: smtp|Type: integer|Default: 100|
21833 +--------+---------+-------------+------------+
21835 This option limits the number of RCPT commands that are sent in a single SMTP
21836 message transaction. Each set of addresses is treated independently, and so can
21837 cause parallel connections to the same host if remote_max_parallel permits
21840 +------------+---------+-------------+-------------+
21841 |multi_domain|Use: smtp|Type: boolean|Default: true|
21842 +------------+---------+-------------+-------------+
21844 When this option is set, the smtp transport can handle a number of addresses
21845 containing a mixture of different domains provided they all resolve to the same
21846 list of hosts. Turning the option off restricts the transport to handling only
21847 one domain at a time. This is useful if you want to use $domain in an expansion
21848 for the transport, because it is set only when there is a single domain
21849 involved in a remote delivery.
21851 +----+---------+-------------+------------------+
21852 |port|Use: smtp|Type: string*|Default: see below|
21853 +----+---------+-------------+------------------+
21855 This option specifies the TCP/IP port on the server to which Exim connects.
21856 Note: Do not confuse this with the port that was used when a message was
21857 received, which is in $received_port, formerly known as $interface_port. The
21858 name was changed to minimize confusion with the outgoing port. There is no
21859 variable that contains an outgoing port.
21861 If the value of this option begins with a digit it is taken as a port number;
21862 otherwise it is looked up using getservbyname(). The default value is normally
21863 "smtp", but if protocol is set to "lmtp", the default is "lmtp". If the
21864 expansion fails, or if a port number cannot be found, delivery is deferred.
21866 +--------+---------+------------+-------------+
21867 |protocol|Use: smtp|Type: string|Default: smtp|
21868 +--------+---------+------------+-------------+
21870 If this option is set to "lmtp" instead of "smtp", the default value for the
21871 port option changes to "lmtp", and the transport operates the LMTP protocol
21872 (RFC 2033) instead of SMTP. This protocol is sometimes used for local
21873 deliveries into closed message stores. Exim also has support for running LMTP
21874 over a pipe to a local process - see chapter 28.
21876 If this option is set to "smtps", the default vaule for the port option changes
21877 to "smtps", and the transport initiates TLS immediately after connecting, as an
21878 outbound SSL-on-connect, instead of using STARTTLS to upgrade. The Internet
21879 standards bodies strongly discourage use of this mode.
21881 +------------------------+---------+-------------+-------------+
21882 |retry_include_ip_address|Use: smtp|Type: boolean|Default: true|
21883 +------------------------+---------+-------------+-------------+
21885 Exim normally includes both the host name and the IP address in the key it
21886 constructs for indexing retry data after a temporary delivery failure. This
21887 means that when one of several IP addresses for a host is failing, it gets
21888 tried periodically (controlled by the retry rules), but use of the other IP
21889 addresses is not affected.
21891 However, in some dialup environments hosts are assigned a different IP address
21892 each time they connect. In this situation the use of the IP address as part of
21893 the retry key leads to undesirable behaviour. Setting this option false causes
21894 Exim to use only the host name. This should normally be done on a separate
21895 instance of the smtp transport, set up specially to handle the dialup hosts.
21897 +---------------+---------+----------------+--------------+
21898 |serialize_hosts|Use: smtp|Type: host list*|Default: unset|
21899 +---------------+---------+----------------+--------------+
21901 Because Exim operates in a distributed manner, if several messages for the same
21902 host arrive at around the same time, more than one simultaneous connection to
21903 the remote host can occur. This is not usually a problem except when there is a
21904 slow link between the hosts. In that situation it may be helpful to restrict
21905 Exim to one connection at a time. This can be done by setting serialize_hosts
21906 to match the relevant hosts.
21908 Exim implements serialization by means of a hints database in which a record is
21909 written whenever a process connects to one of the restricted hosts. The record
21910 is deleted when the connection is completed. Obviously there is scope for
21911 records to get left lying around if there is a system or program crash. To
21912 guard against this, Exim ignores any records that are more than six hours old.
21914 If you set up this kind of serialization, you should also arrange to delete the
21915 relevant hints database whenever your system reboots. The names of the files
21916 start with misc and they are kept in the spool/db directory. There may be one
21917 or two files, depending on the type of DBM in use. The same files are used for
21918 ETRN serialization.
21920 +-------------+---------+-------------+-------------+
21921 |size_addition|Use: smtp|Type: integer|Default: 1024|
21922 +-------------+---------+-------------+-------------+
21924 If a remote SMTP server indicates that it supports the SIZE option of the MAIL
21925 command, Exim uses this to pass over the message size at the start of an SMTP
21926 transaction. It adds the value of size_addition to the value it sends, to allow
21927 for headers and other text that may be added during delivery by configuration
21928 options or in a transport filter. It may be necessary to increase this if a lot
21929 of text is added to messages.
21931 Alternatively, if the value of size_addition is set negative, it disables the
21932 use of the SIZE option altogether.
21934 +---------------+---------+-------------+--------------+
21935 |tls_certificate|Use: smtp|Type: string*|Default: unset|
21936 +---------------+---------+-------------+--------------+
21938 The value of this option must be the absolute path to a file which contains the
21939 client's certificate, for possible use when sending a message over an encrypted
21940 connection. The values of $host and $host_address are set to the name and
21941 address of the server during the expansion. See chapter 41 for details of TLS.
21943 Note: This option must be set if you want Exim to be able to use a TLS
21944 certificate when sending messages as a client. The global option of the same
21945 name specifies the certificate for Exim as a server; it is not automatically
21946 assumed that the same certificate should be used when Exim is operating as a
21949 +-------+---------+-------------+--------------+
21950 |tls_crl|Use: smtp|Type: string*|Default: unset|
21951 +-------+---------+-------------+--------------+
21953 This option specifies a certificate revocation list. The expanded value must be
21954 the name of a file that contains a CRL in PEM format.
21956 +---------------+---------+-------------+-------------+
21957 |tls_dh_min_bits|Use: smtp|Type: integer|Default: 1024|
21958 +---------------+---------+-------------+-------------+
21960 When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman key
21961 agreement is negotiated, the server will provide a large prime number for use.
21962 This option establishes the minimum acceptable size of that number. If the
21963 parameter offered by the server is too small, then the TLS handshake will fail.
21965 Only supported when using GnuTLS.
21967 +--------------+---------+-------------+--------------+
21968 |tls_privatekey|Use: smtp|Type: string*|Default: unset|
21969 +--------------+---------+-------------+--------------+
21971 The value of this option must be the absolute path to a file which contains the
21972 client's private key. This is used when sending a message over an encrypted
21973 connection using a client certificate. The values of $host and $host_address
21974 are set to the name and address of the server during the expansion. If this
21975 option is unset, or the expansion is forced to fail, or the result is an empty
21976 string, the private key is assumed to be in the same file as the certificate.
21977 See chapter 41 for details of TLS.
21979 +-------------------+---------+-------------+--------------+
21980 |tls_require_ciphers|Use: smtp|Type: string*|Default: unset|
21981 +-------------------+---------+-------------+--------------+
21983 The value of this option must be a list of permitted cipher suites, for use
21984 when setting up an outgoing encrypted connection. (There is a global option of
21985 the same name for controlling incoming connections.) The values of $host and
21986 $host_address are set to the name and address of the server during the
21987 expansion. See chapter 41 for details of TLS; note that this option is used in
21988 different ways by OpenSSL and GnuTLS (see sections 41.4 and 41.5). For GnuTLS,
21989 the order of the ciphers is a preference order.
21991 +-------+---------+-------------+--------------+
21992 |tls_sni|Use: smtp|Type: string*|Default: unset|
21993 +-------+---------+-------------+--------------+
21995 If this option is set then it sets the $tls_out_sni variable and causes any TLS
21996 session to pass this value as the Server Name Indication extension to the
21997 remote side, which can be used by the remote side to select an appropriate
21998 certificate and private key for the session.
22000 See 41.10 for more information.
22002 Note that for OpenSSL, this feature requires a build of OpenSSL that supports
22005 +---------------------+---------+-------------+-------------+
22006 |tls_tempfail_tryclear|Use: smtp|Type: boolean|Default: true|
22007 +---------------------+---------+-------------+-------------+
22009 When the server host is not in hosts_require_tls, and there is a problem in
22010 setting up a TLS session, this option determines whether or not Exim should try
22011 to deliver the message unencrypted. If it is set false, delivery to the current
22012 host is deferred; if there are other hosts, they are tried. If this option is
22013 set true, Exim attempts to deliver unencrypted after a 4xx response to
22014 STARTTLS. Also, if STARTTLS is accepted, but the subsequent TLS negotiation
22015 fails, Exim closes the current connection (because it is in an unknown state),
22016 opens a new one to the same host, and then tries the delivery in clear.
22018 +--------------------+---------+----------------------+--------+
22019 |tls_try_verify_hosts|Use: smtp|Type: host list* unset|Default:|
22020 +--------------------+---------+----------------------+--------+
22022 This option gives a list of hosts for which, on encrypted connections,
22023 certificate verification will be tried but need not succeed. The
22024 tls_verify_certificates option must also be set. Note that unless the host is
22025 in this list TLS connections will be denied to hosts using self-signed
22026 certificates when tls_verify_certificates is set. The
22027 $tls_out_certificate_verified variable is set when certificate verification
22030 +-----------------------+---------+-------------+--------------+
22031 |tls_verify_certificates|Use: smtp|Type: string*|Default: unset|
22032 +-----------------------+---------+-------------+--------------+
22034 The value of this option must be the absolute path to a file containing
22035 permitted server certificates, for use when setting up an encrypted connection.
22036 Alternatively, if you are using OpenSSL, you can set tls_verify_certificates to
22037 the name of a directory containing certificate files. This does not work with
22038 GnuTLS; the option must be set to the name of a single file if you are using
22039 GnuTLS. The values of $host and $host_address are set to the name and address
22040 of the server during the expansion of this option. See chapter 41 for details
22043 For back-compatability, if neither tls_verify_hosts nor tls_try_verify_hosts
22044 are set and certificate verification fails the TLS connection is closed.
22046 +----------------+---------+----------------------+--------+
22047 |tls_verify_hosts|Use: smtp|Type: host list* unset|Default:|
22048 +----------------+---------+----------------------+--------+
22050 This option gives a list of hosts for which. on encrypted connections,
22051 certificate verification must succeed. The tls_verify_certificates option must
22052 also be set. If both this option and tls_try_verify_hosts are unset operation
22053 is as if this option selected all hosts.
22056 30.5 How the limits for the number of hosts to try are used
22057 -----------------------------------------------------------
22059 There are two options that are concerned with the number of hosts that are
22060 tried when an SMTP delivery takes place. They are hosts_max_try and
22061 hosts_max_try_hardlimit.
22063 The hosts_max_try option limits the number of hosts that are tried for a single
22064 delivery. However, despite the term "host" in its name, the option actually
22065 applies to each IP address independently. In other words, a multihomed host is
22066 treated as several independent hosts, just as it is for retrying.
22068 Many of the larger ISPs have multiple MX records which often point to
22069 multihomed hosts. As a result, a list of a dozen or more IP addresses may be
22070 created as a result of routing one of these domains.
22072 Trying every single IP address on such a long list does not seem sensible; if
22073 several at the top of the list fail, it is reasonable to assume there is some
22074 problem that is likely to affect all of them. Roughly speaking, the value of
22075 hosts_max_try is the maximum number that are tried before deferring the
22076 delivery. However, the logic cannot be quite that simple.
22078 Firstly, IP addresses that are skipped because their retry times have not
22079 arrived do not count, and in addition, addresses that are past their retry
22080 limits are also not counted, even when they are tried. This means that when
22081 some IP addresses are past their retry limits, more than the value of
22082 hosts_max_retry may be tried. The reason for this behaviour is to ensure that
22083 all IP addresses are considered before timing out an email address (but see
22084 below for an exception).
22086 Secondly, when the hosts_max_try limit is reached, Exim looks down the host
22087 list to see if there is a subsequent host with a different (higher valued) MX.
22088 If there is, that host is considered next, and the current IP address is used
22089 but not counted. This behaviour helps in the case of a domain with a retry rule
22090 that hardly ever delays any hosts, as is now explained:
22092 Consider the case of a long list of hosts with one MX value, and a few with a
22093 higher MX value. If hosts_max_try is small (the default is 5) only a few hosts
22094 at the top of the list are tried at first. With the default retry rule, which
22095 specifies increasing retry times, the higher MX hosts are eventually tried when
22096 those at the top of the list are skipped because they have not reached their
22099 However, it is common practice to put a fixed short retry time on domains for
22100 large ISPs, on the grounds that their servers are rarely down for very long.
22101 Unfortunately, these are exactly the domains that tend to resolve to long lists
22102 of hosts. The short retry time means that the lowest MX hosts are tried every
22103 time. The attempts may be in a different order because of random sorting, but
22104 without the special MX check, the higher MX hosts would never be tried until
22105 all the lower MX hosts had timed out (which might be several days), because
22106 there are always some lower MX hosts that have reached their retry times. With
22107 the special check, Exim considers at least one IP address from each MX value at
22108 every delivery attempt, even if the hosts_max_try limit has already been
22111 The above logic means that hosts_max_try is not a hard limit, and in
22112 particular, Exim normally eventually tries all the IP addresses before timing
22113 out an email address. When hosts_max_try was implemented, this seemed a
22114 reasonable thing to do. Recently, however, some lunatic DNS configurations have
22115 been set up with hundreds of IP addresses for some domains. It can take a very
22116 long time indeed for an address to time out in these cases.
22118 The hosts_max_try_hardlimit option was added to help with this problem. Exim
22119 never tries more than this number of IP addresses; if it hits this limit and
22120 they are all timed out, the email address is bounced, even though not all
22121 possible IP addresses have been tried.
22125 ===============================================================================
22126 31. ADDRESS REWRITING
22128 There are some circumstances in which Exim automatically rewrites domains in
22129 addresses. The two most common are when an address is given without a domain
22130 (referred to as an "unqualified address") or when an address contains an
22131 abbreviated domain that is expanded by DNS lookup.
22133 Unqualified envelope addresses are accepted only for locally submitted
22134 messages, or for messages that are received from hosts matching
22135 sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.
22136 Unqualified addresses in header lines are qualified if they are in locally
22137 submitted messages, or messages from hosts that are permitted to send
22138 unqualified envelope addresses. Otherwise, unqualified addresses in header
22139 lines are neither qualified nor rewritten.
22141 One situation in which Exim does not automatically rewrite a domain is when it
22142 is the name of a CNAME record in the DNS. The older RFCs suggest that such a
22143 domain should be rewritten using the "canonical" name, and some MTAs do this.
22144 The new RFCs do not contain this suggestion.
22147 31.1 Explicitly configured address rewriting
22148 --------------------------------------------
22150 This chapter describes the rewriting rules that can be used in the main rewrite
22151 section of the configuration file, and also in the generic headers_rewrite
22152 option that can be set on any transport.
22154 Some people believe that configured address rewriting is a Mortal Sin. Others
22155 believe that life is not possible without it. Exim provides the facility; you
22156 do not have to use it.
22158 The main rewriting rules that appear in the "rewrite" section of the
22159 configuration file are applied to addresses in incoming messages, both envelope
22160 addresses and addresses in header lines. Each rule specifies the types of
22161 address to which it applies.
22163 Whether or not addresses in header lines are rewritten depends on the origin of
22164 the headers and the type of rewriting. Global rewriting, that is, rewriting
22165 rules from the rewrite section of the configuration file, is applied only to
22166 those headers that were received with the message. Header lines that are added
22167 by ACLs or by a system filter or by individual routers or transports (which are
22168 specific to individual recipient addresses) are not rewritten by the global
22171 Rewriting at transport time, by means of the headers_rewrite option, applies
22172 all headers except those added by routers and transports. That is, as well as
22173 the headers that were received with the message, it also applies to headers
22174 that were added by an ACL or a system filter.
22176 In general, rewriting addresses from your own system or domain has some
22177 legitimacy. Rewriting other addresses should be done only with great care and
22178 in special circumstances. The author of Exim believes that rewriting should be
22179 used sparingly, and mainly for "regularizing" addresses in your own domains.
22180 Although it can sometimes be used as a routing tool, this is very strongly
22183 There are two commonly encountered circumstances where rewriting is used, as
22184 illustrated by these examples:
22186 * The company whose domain is hitch.fict.example has a number of hosts that
22187 exchange mail with each other behind a firewall, but there is only a single
22188 gateway to the outer world. The gateway rewrites *.hitch.fict.example as
22189 hitch.fict.example when sending mail off-site.
22191 * A host rewrites the local parts of its own users so that, for example,
22192 fp42@hitch.fict.example becomes Ford.Prefect@hitch.fict.example.
22195 31.2 When does rewriting happen?
22196 --------------------------------
22198 Configured address rewriting can take place at several different stages of a
22199 message's processing.
22201 At the start of an ACL for MAIL, the sender address may have been rewritten by
22202 a special SMTP-time rewrite rule (see section 31.9), but no ordinary rewrite
22203 rules have yet been applied. If, however, the sender address is verified in the
22204 ACL, it is rewritten before verification, and remains rewritten thereafter. The
22205 subsequent value of $sender_address is the rewritten address. This also applies
22206 if sender verification happens in a RCPT ACL. Otherwise, when the sender
22207 address is not verified, it is rewritten as soon as a message's header lines
22208 have been received.
22210 Similarly, at the start of an ACL for RCPT, the current recipient's address may
22211 have been rewritten by a special SMTP-time rewrite rule, but no ordinary
22212 rewrite rules have yet been applied to it. However, the behaviour is different
22213 from the sender address when a recipient is verified. The address is rewritten
22214 for the verification, but the rewriting is not remembered at this stage. The
22215 value of $local_part and $domain after verification are always the same as they
22216 were before (that is, they contain the unrewritten - except for SMTP-time
22217 rewriting - address).
22219 As soon as a message's header lines have been received, all the envelope
22220 recipient addresses are permanently rewritten, and rewriting is also applied to
22221 the addresses in the header lines (if configured). This happens before adding
22222 any header lines that were specified in MAIL or RCPT ACLs, and before the DATA
22223 ACL and local_scan() functions are run.
22225 When an address is being routed, either for delivery or for verification,
22226 rewriting is applied immediately to child addresses that are generated by
22227 redirection, unless no_rewrite is set on the router.
22229 At transport time, additional rewriting of addresses in header lines can be
22230 specified by setting the generic headers_rewrite option on a transport. This
22231 option contains rules that are identical in form to those in the rewrite
22232 section of the configuration file. They are applied to the original message
22233 header lines and any that were added by ACLs or a system filter. They are not
22234 applied to header lines that are added by routers or the transport.
22236 The outgoing envelope sender can be rewritten by means of the return_path
22237 transport option. However, it is not possible to rewrite envelope recipients at
22241 31.3 Testing the rewriting rules that apply on input
22242 ----------------------------------------------------
22244 Exim's input rewriting configuration appears in a part of the run time
22245 configuration file headed by "begin rewrite". It can be tested by the -brw
22246 command line option. This takes an address (which can be a full RFC 2822
22247 address) as its argument. The output is a list of how the address would be
22248 transformed by the rewriting rules for each of the different places it might
22249 appear in an incoming message, that is, for each different header and for the
22250 envelope sender and recipient fields. For example,
22252 exim -brw ph10@exim.workshop.example
22254 might produce the output
22256 sender: Philip.Hazel@exim.workshop.example
22257 from: Philip.Hazel@exim.workshop.example
22258 to: ph10@exim.workshop.example
22259 cc: ph10@exim.workshop.example
22260 bcc: ph10@exim.workshop.example
22261 reply-to: Philip.Hazel@exim.workshop.example
22262 env-from: Philip.Hazel@exim.workshop.example
22263 env-to: ph10@exim.workshop.example
22265 which shows that rewriting has been set up for that address when used in any of
22266 the source fields, but not when it appears as a recipient address. At the
22267 present time, there is no equivalent way of testing rewriting rules that are
22268 set for a particular transport.
22271 31.4 Rewriting rules
22272 --------------------
22274 The rewrite section of the configuration file consists of lines of rewriting
22277 <source pattern> <replacement> <flags>
22279 Rewriting rules that are specified for the headers_rewrite generic transport
22280 option are given as a colon-separated list. Each item in the list takes the
22281 same form as a line in the main rewriting configuration (except that any colons
22282 must be doubled, of course).
22284 The formats of source patterns and replacement strings are described below.
22285 Each is terminated by white space, unless enclosed in double quotes, in which
22286 case normal quoting conventions apply inside the quotes. The flags are single
22287 characters which may appear in any order. Spaces and tabs between them are
22290 For each address that could potentially be rewritten, the rules are scanned in
22291 order, and replacements for the address from earlier rules can themselves be
22292 replaced by later rules (but see the "q" and "R" flags).
22294 The order in which addresses are rewritten is undefined, may change between
22295 releases, and must not be relied on, with one exception: when a message is
22296 received, the envelope sender is always rewritten first, before any header
22297 lines are rewritten. For example, the replacement string for a rewrite of an
22298 address in To: must not assume that the message's address in From: has (or has
22299 not) already been rewritten. However, a rewrite of From: may assume that the
22300 envelope sender has already been rewritten.
22302 The variables $local_part and $domain can be used in the replacement string to
22303 refer to the address that is being rewritten. Note that lookup-driven rewriting
22304 can be done by a rule of the form
22308 where the lookup key uses $1 and $2 or $local_part and $domain to refer to the
22309 address that is being rewritten.
22312 31.5 Rewriting patterns
22313 -----------------------
22315 The source pattern in a rewriting rule is any item which may appear in an
22316 address list (see section 10.19). It is in fact processed as a single-item
22317 address list, which means that it is expanded before being tested against the
22318 address. As always, if you use a regular expression as a pattern, you must take
22319 care to escape dollar and backslash characters, or use the "\N" facility to
22320 suppress string expansion within the regular expression.
22322 Domains in patterns should be given in lower case. Local parts in patterns are
22323 case-sensitive. If you want to do case-insensitive matching of local parts, you
22324 can use a regular expression that starts with "^(?i)".
22326 After matching, the numerical variables $1, $2, etc. may be set, depending on
22327 the type of match which occurred. These can be used in the replacement string
22328 to insert portions of the incoming address. $0 always refers to the complete
22329 incoming address. When a regular expression is used, the numerical variables
22330 are set from its capturing subexpressions. For other types of pattern they are
22333 * If a local part or domain starts with an asterisk, the numerical variables
22334 refer to the character strings matched by asterisks, with $1 associated
22335 with the first asterisk, and $2 with the second, if present. For example,
22338 *queen@*.fict.example
22340 is matched against the address hearts-queen@wonderland.fict.example then
22342 $0 = hearts-queen@wonderland.fict.example
22346 Note that if the local part does not start with an asterisk, but the domain
22347 does, it is $1 that contains the wild part of the domain.
22349 * If the domain part of the pattern is a partial lookup, the wild and fixed
22350 parts of the domain are placed in the next available numerical variables.
22351 Suppose, for example, that the address foo@bar.baz.example is processed by
22352 a rewriting rule of the form
22354 *@partial-dbm;/some/dbm/file <replacement string>
22356 and the key in the file that matches the domain is "*.baz.example". Then
22362 If the address foo@baz.example is looked up, this matches the same wildcard
22363 file entry, and in this case $2 is set to the empty string, but $3 is still
22364 set to baz.example. If a non-wild key is matched in a partial lookup, $2 is
22365 again set to the empty string and $3 is set to the whole domain. For
22366 non-partial domain lookups, no numerical variables are set.
22369 31.6 Rewriting replacements
22370 ---------------------------
22372 If the replacement string for a rule is a single asterisk, addresses that match
22373 the pattern and the flags are not rewritten, and no subsequent rewriting rules
22374 are scanned. For example,
22376 hatta@lookingglass.fict.example * f
22378 specifies that hatta@lookingglass.fict.example is never to be rewritten in
22381 If the replacement string is not a single asterisk, it is expanded, and must
22382 yield a fully qualified address. Within the expansion, the variables
22383 $local_part and $domain refer to the address that is being rewritten. Any
22384 letters they contain retain their original case - they are not lower cased. The
22385 numerical variables are set up according to the type of pattern that matched
22386 the address, as described above. If the expansion is forced to fail by the
22387 presence of "fail" in a conditional or lookup item, rewriting by the current
22388 rule is abandoned, but subsequent rules may take effect. Any other expansion
22389 failure causes the entire rewriting operation to be abandoned, and an entry
22390 written to the panic log.
22393 31.7 Rewriting flags
22394 --------------------
22396 There are three different kinds of flag that may appear on rewriting rules:
22398 * Flags that specify which headers and envelope addresses to rewrite: E, F,
22399 T, b, c, f, h, r, s, t.
22401 * A flag that specifies rewriting at SMTP time: S.
22403 * Flags that control the rewriting process: Q, q, R, w.
22405 For rules that are part of the headers_rewrite generic transport option, E, F,
22406 T, and S are not permitted.
22409 31.8 Flags specifying which headers and envelope addresses to rewrite
22410 ---------------------------------------------------------------------
22412 If none of the following flag letters, nor the "S" flag (see section 31.9) are
22413 present, a main rewriting rule applies to all headers and to both the sender
22414 and recipient fields of the envelope, whereas a transport-time rewriting rule
22415 just applies to all headers. Otherwise, the rewriting rule is skipped unless
22416 the relevant addresses are being processed.
22418 E rewrite all envelope fields
22419 F rewrite the envelope From field
22420 T rewrite the envelope To field
22421 b rewrite the Bcc: header
22422 c rewrite the Cc: header
22423 f rewrite the From: header
22424 h rewrite all headers
22425 r rewrite the Reply-To: header
22426 s rewrite the Sender: header
22427 t rewrite the To: header
22429 "All headers" means all of the headers listed above that can be selected
22430 individually, plus their Resent- versions. It does not include other headers
22431 such as Subject: etc.
22433 You should be particularly careful about rewriting Sender: headers, and
22434 restrict this to special known cases in your own domains.
22437 31.9 The SMTP-time rewriting flag
22438 ---------------------------------
22440 The rewrite flag "S" specifies a rewrite of incoming envelope addresses at SMTP
22441 time, as soon as an address is received in a MAIL or RCPT command, and before
22442 any other processing; even before syntax checking. The pattern is required to
22443 be a regular expression, and it is matched against the whole of the data for
22444 the command, including any surrounding angle brackets.
22446 This form of rewrite rule allows for the handling of addresses that are not
22447 compliant with RFCs 2821 and 2822 (for example, "bang paths" in batched SMTP
22448 input). Because the input is not required to be a syntactically valid address,
22449 the variables $local_part and $domain are not available during the expansion of
22450 the replacement string. The result of rewriting replaces the original address
22451 in the MAIL or RCPT command.
22454 31.10 Flags controlling the rewriting process
22455 ---------------------------------------------
22457 There are four flags which control the way the rewriting process works. These
22458 take effect only when a rule is invoked, that is, when the address is of the
22459 correct type (matches the flags) and matches the pattern:
22461 * If the "Q" flag is set on a rule, the rewritten address is permitted to be
22462 an unqualified local part. It is qualified with qualify_recipient. In the
22463 absence of "Q" the rewritten address must always include a domain.
22465 * If the "q" flag is set on a rule, no further rewriting rules are
22466 considered, even if no rewriting actually takes place because of a "fail"
22467 in the expansion. The "q" flag is not effective if the address is of the
22468 wrong type (does not match the flags) or does not match the pattern.
22470 * The "R" flag causes a successful rewriting rule to be re-applied to the new
22471 address, up to ten times. It can be combined with the "q" flag, to stop
22472 rewriting once it fails to match (after at least one successful rewrite).
22474 * When an address in a header is rewritten, the rewriting normally applies
22475 only to the working part of the address, with any comments and RFC 2822
22476 "phrase" left unchanged. For example, rewriting might change
22478 From: Ford Prefect <fp42@restaurant.hitch.fict.example>
22482 From: Ford Prefect <prefectf@hitch.fict.example>
22484 Sometimes there is a need to replace the whole address item, and this can
22485 be done by adding the flag letter "w" to a rule. If this is set on a rule
22486 that causes an address in a header line to be rewritten, the entire address
22487 is replaced, not just the working part. The replacement must be a complete
22488 RFC 2822 address, including the angle brackets if necessary. If text
22489 outside angle brackets contains a character whose value is greater than 126
22490 or less than 32 (except for tab), the text is encoded according to RFC
22491 2047. The character set is taken from headers_charset, which defaults to
22494 When the "w" flag is set on a rule that causes an envelope address to be
22495 rewritten, all but the working part of the replacement address is
22499 31.11 Rewriting examples
22500 ------------------------
22502 Here is an example of the two common rewriting paradigms:
22504 *@*.hitch.fict.example $1@hitch.fict.example
22505 *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\
22506 {$value}fail}@hitch.fict.example bctfrF
22508 Note the use of "fail" in the lookup expansion in the second rule, forcing the
22509 string expansion to fail if the lookup does not succeed. In this context it has
22510 the effect of leaving the original address unchanged, but Exim goes on to
22511 consider subsequent rewriting rules, if any, because the "q" flag is not
22512 present in that rule. An alternative to "fail" would be to supply $1
22513 explicitly, which would cause the rewritten address to be the same as before,
22514 at the cost of a small bit of processing. Not supplying either of these is an
22515 error, since the rewritten address would then contain no local part.
22517 The first example above replaces the domain with a superior, more general
22518 domain. This may not be desirable for certain local parts. If the rule
22520 root@*.hitch.fict.example *
22522 were inserted before the first rule, rewriting would be suppressed for the
22523 local part root at any domain ending in hitch.fict.example.
22525 Rewriting can be made conditional on a number of tests, by making use of ${if
22526 in the expansion item. For example, to apply a rewriting rule only to messages
22527 that originate outside the local host:
22529 *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\
22530 {$1@hitch.fict.example}fail}"
22532 The replacement string is quoted in this example because it contains white
22535 Exim does not handle addresses in the form of "bang paths". If it sees such an
22536 address it treats it as an unqualified local part which it qualifies with the
22537 local qualification domain (if the source of the message is local or if the
22538 remote host is permitted to send unqualified addresses). Rewriting can
22539 sometimes be used to handle simple bang paths with a fixed number of
22540 components. For example, the rule
22542 \N^([^!]+)!(.*)@your.domain.example$\N $2@$1
22544 rewrites a two-component bang path host.name!user as the domain address
22545 user@host.name. However, there is a security implication in using this as a
22546 global rewriting rule for envelope addresses. It can provide a backdoor method
22547 for using your system as a relay, because the incoming addresses appear to be
22548 local. If the bang path addresses are received via SMTP, it is safer to use the
22549 "S" flag to rewrite them as they are received, so that relay checking can be
22550 done on the rewritten addresses.
22554 ===============================================================================
22555 32. RETRY CONFIGURATION
22557 The "retry" section of the runtime configuration file contains a list of retry
22558 rules that control how often Exim tries to deliver messages that cannot be
22559 delivered at the first attempt. If there are no retry rules (the section is
22560 empty or not present), there are no retries. In this situation, temporary
22561 errors are treated as permanent. The default configuration contains a single,
22562 general-purpose retry rule (see section 7.5). The -brt command line option can
22563 be used to test which retry rule will be used for a given address, domain and
22566 The most common cause of retries is temporary failure to deliver to a remote
22567 host because the host is down, or inaccessible because of a network problem.
22568 Exim's retry processing in this case is applied on a per-host (strictly, per IP
22569 address) basis, not on a per-message basis. Thus, if one message has recently
22570 been delayed, delivery of a new message to the same host is not immediately
22571 tried, but waits for the host's retry time to arrive. If the retry_defer log
22572 selector is set, the message "retry time not reached" is written to the main
22573 log whenever a delivery is skipped for this reason. Section 47.2 contains more
22574 details of the handling of errors during remote deliveries.
22576 Retry processing applies to routing as well as to delivering, except as covered
22577 in the next paragraph. The retry rules do not distinguish between these
22578 actions. It is not possible, for example, to specify different behaviour for
22579 failures to route the domain snark.fict.example and failures to deliver to the
22580 host snark.fict.example. I didn't think anyone would ever need this added
22581 complication, so did not implement it. However, although they share the same
22582 retry rule, the actual retry times for routing and transporting a given domain
22583 are maintained independently.
22585 When a delivery is not part of a queue run (typically an immediate delivery on
22586 receipt of a message), the routers are always run, and local deliveries are
22587 always attempted, even if retry times are set for them. This makes for better
22588 behaviour if one particular message is causing problems (for example, causing
22589 quota overflow, or provoking an error in a filter file). If such a delivery
22590 suffers a temporary failure, the retry data is updated as normal, and
22591 subsequent delivery attempts from queue runs occur only when the retry time for
22592 the local address is reached.
22595 32.1 Changing retry rules
22596 -------------------------
22598 If you change the retry rules in your configuration, you should consider
22599 whether or not to delete the retry data that is stored in Exim's spool area in
22600 files with names like db/retry. Deleting any of Exim's hints files is always
22601 safe; that is why they are called "hints".
22603 The hints retry data contains suggested retry times based on the previous
22604 rules. In the case of a long-running problem with a remote host, it might
22605 record the fact that the host has timed out. If your new rules increase the
22606 timeout time for such a host, you should definitely remove the old retry data
22607 and let Exim recreate it, based on the new rules. Otherwise Exim might bounce
22608 messages that it should now be retaining.
22611 32.2 Format of retry rules
22612 --------------------------
22614 Each retry rule occupies one line and consists of three or four parts,
22615 separated by white space: a pattern, an error name, an optional list of sender
22616 addresses, and a list of retry parameters. The pattern and sender lists must be
22617 enclosed in double quotes if they contain white space. The rules are searched
22618 in order until one is found where the pattern, error name, and sender list (if
22619 present) match the failing host or address, the error that occurred, and the
22620 message's sender, respectively.
22622 The pattern is any single item that may appear in an address list (see section
22623 10.19). It is in fact processed as a one-item address list, which means that it
22624 is expanded before being tested against the address that has been delayed. A
22625 negated address list item is permitted. Address list processing treats a plain
22626 domain name as if it were preceded by "*@", which makes it possible for many
22627 retry rules to start with just a domain. For example,
22629 lookingglass.fict.example * F,24h,30m;
22631 provides a rule for any address in the lookingglass.fict.example domain,
22634 alice@lookingglass.fict.example * F,24h,30m;
22636 applies only to temporary failures involving the local part alice. In practice,
22637 almost all rules start with a domain name pattern without a local part.
22639 Warning: If you use a regular expression in a retry rule pattern, it must match
22640 a complete address, not just a domain, because that is how regular expressions
22641 work in address lists.
22643 ^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2 Wrong
22644 ^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2 Right
22647 32.3 Choosing which retry rule to use for address errors
22648 --------------------------------------------------------
22650 When Exim is looking for a retry rule after a routing attempt has failed (for
22651 example, after a DNS timeout), each line in the retry configuration is tested
22652 against the complete address only if retry_use_local_part is set for the
22653 router. Otherwise, only the domain is used, except when matching against a
22654 regular expression, when the local part of the address is replaced with "*". A
22655 domain on its own can match a domain pattern, or a pattern that starts with
22656 "*@". By default, retry_use_local_part is true for routers where
22657 check_local_user is true, and false for other routers.
22659 Similarly, when Exim is looking for a retry rule after a local delivery has
22660 failed (for example, after a mailbox full error), each line in the retry
22661 configuration is tested against the complete address only if
22662 retry_use_local_part is set for the transport (it defaults true for all local
22665 However, when Exim is looking for a retry rule after a remote delivery attempt
22666 suffers an address error (a 4xx SMTP response for a recipient address), the
22667 whole address is always used as the key when searching the retry rules. The
22668 rule that is found is used to create a retry time for the combination of the
22669 failing address and the message's sender. It is the combination of sender and
22670 recipient that is delayed in subsequent queue runs until its retry time is
22671 reached. You can delay the recipient without regard to the sender by setting
22672 address_retry_include_sender false in the smtp transport but this can lead to
22673 problems with servers that regularly issue 4xx responses to RCPT commands.
22676 32.4 Choosing which retry rule to use for host and message errors
22677 -----------------------------------------------------------------
22679 For a temporary error that is not related to an individual address (for
22680 example, a connection timeout), each line in the retry configuration is checked
22681 twice. First, the name of the remote host is used as a domain name (preceded by
22682 "*@" when matching a regular expression). If this does not match the line, the
22683 domain from the email address is tried in a similar fashion. For example,
22684 suppose the MX records for a.b.c.example are
22686 a.b.c.example MX 5 x.y.z.example
22690 and the retry rules are
22692 p.q.r.example * F,24h,30m;
22693 a.b.c.example * F,4d,45m;
22695 and a delivery to the host x.y.z.example suffers a connection failure. The
22696 first rule matches neither the host nor the domain, so Exim looks at the second
22697 rule. This does not match the host, but it does match the domain, so it is used
22698 to calculate the retry time for the host x.y.z.example. Meanwhile, Exim tries
22699 to deliver to p.q.r.example. If this also suffers a host error, the first retry
22700 rule is used, because it matches the host.
22702 In other words, temporary failures to deliver to host p.q.r.example use the
22703 first rule to determine retry times, but for all the other hosts for the domain
22704 a.b.c.example, the second rule is used. The second rule is also used if routing
22705 to a.b.c.example suffers a temporary failure.
22707 Note: The host name is used when matching the patterns, not its IP address.
22708 However, if a message is routed directly to an IP address without the use of a
22709 host name, for example, if a manualroute router contains a setting such as:
22711 route_list = *.a.example 192.168.34.23
22713 then the "host name" that is used when searching for a retry rule is the
22714 textual form of the IP address.
22717 32.5 Retry rules for specific errors
22718 ------------------------------------
22720 The second field in a retry rule is the name of a particular error, or an
22721 asterisk, which matches any error. The errors that can be tested for are:
22725 Authentication failed when trying to send to a host in the
22726 hosts_require_auth list in an smtp transport.
22730 A 4xx error was received for an outgoing DATA command, either immediately
22731 after the command, or after sending the message's data.
22735 A 4xx error was received for an outgoing MAIL command.
22739 A 4xx error was received for an outgoing RCPT command.
22741 For the three 4xx errors, either the first or both of the x's can be given as
22742 specific digits, for example: "mail_45x" or "rcpt_436". For example, to
22743 recognize 452 errors given to RCPT commands for addresses in a certain domain,
22744 and have retries every ten minutes with a one-hour timeout, you could set up a
22745 retry rule of this form:
22747 the.domain.name rcpt_452 F,1h,10m
22749 These errors apply to both outgoing SMTP (the smtp transport) and outgoing LMTP
22750 (either the lmtp transport, or the smtp transport in LMTP mode).
22754 A server unexpectedly closed the SMTP connection. There may, of course,
22755 legitimate reasons for this (host died, network died), but if it repeats a
22756 lot for the same host, it indicates something odd.
22760 A connection to a host obtained from an MX record was refused.
22764 A connection to a host not obtained from an MX record was refused.
22768 A connection was refused.
22772 A connection attempt to a host obtained from an MX record timed out.
22776 A connection attempt to a host not obtained from an MX record timed out.
22780 A connection attempt timed out.
22784 There was a timeout while connecting or during an SMTP session with a host
22785 obtained from an MX record.
22789 There was a timeout while connecting or during an SMTP session with a host
22790 not obtained from an MX record.
22794 There was a timeout while connecting or during an SMTP session.
22798 The server was required to use TLS (it matched hosts_require_tls in the
22799 smtp transport), but either did not offer TLS, or it responded with 4xx to
22800 STARTTLS, or there was a problem setting up the TLS connection.
22804 A mailbox quota was exceeded in a local delivery by the appendfile
22809 A mailbox quota was exceeded in a local delivery by the appendfile
22810 transport, and the mailbox has not been accessed for <time>. For example,
22811 quota_4d applies to a quota error when the mailbox has not been accessed
22814 The idea of quota_<time> is to make it possible to have shorter timeouts when
22815 the mailbox is full and is not being read by its owner. Ideally, it should be
22816 based on the last time that the user accessed the mailbox. However, it is not
22817 always possible to determine this. Exim uses the following heuristic rules:
22819 * If the mailbox is a single file, the time of last access (the "atime") is
22820 used. As no new messages are being delivered (because the mailbox is over
22821 quota), Exim does not access the file, so this is the time of last user
22824 * For a maildir delivery, the time of last modification of the new
22825 subdirectory is used. As the mailbox is over quota, no new files are
22826 created in the new subdirectory, because no new messages are being
22827 delivered. Any change to the new subdirectory is therefore assumed to be
22828 the result of an MUA moving a new message to the cur directory when it is
22829 first read. The time that is used is therefore the last time that the user
22830 read a new message.
22832 * For other kinds of multi-file mailbox, the time of last access cannot be
22833 obtained, so a retry rule that uses this type of error field is never
22836 The quota errors apply both to system-enforced quotas and to Exim's own quota
22837 mechanism in the appendfile transport. The quota error also applies when a
22838 local delivery is deferred because a partition is full (the ENOSPC error).
22841 32.6 Retry rules for specified senders
22842 --------------------------------------
22844 You can specify retry rules that apply only when the failing message has a
22845 specific sender. In particular, this can be used to define retry rules that
22846 apply only to bounce messages. The third item in a retry rule can be of this
22849 senders=<address list>
22851 The retry timings themselves are then the fourth item. For example:
22853 * rcpt_4xx senders=: F,1h,30m
22855 matches recipient 4xx errors for bounce messages sent to any address at any
22856 host. If the address list contains white space, it must be enclosed in quotes.
22859 a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5
22861 Warning: This facility can be unhelpful if it is used for host errors (which do
22862 not depend on the recipient). The reason is that the sender is used only to
22863 match the retry rule. Once the rule has been found for a host error, its
22864 contents are used to set a retry time for the host, and this will apply to all
22865 messages, not just those with specific senders.
22867 When testing retry rules using -brt, you can supply a sender using the -f
22868 command line option, like this:
22870 exim -f "" -brt user@dom.ain
22872 If you do not set -f with -brt, a retry rule that contains a senders list is
22876 32.7 Retry parameters
22877 ---------------------
22879 The third (or fourth, if a senders list is present) field in a retry rule is a
22880 sequence of retry parameter sets, separated by semicolons. Each set consists of
22882 <letter>,<cutoff time>,<arguments>
22884 The letter identifies the algorithm for computing a new retry time; the cutoff
22885 time is the time beyond which this algorithm no longer applies, and the
22886 arguments vary the algorithm's action. The cutoff time is measured from the
22887 time that the first failure for the domain (combined with the local part if
22888 relevant) was detected, not from the time the message was received.
22890 The available algorithms are:
22892 * F: retry at fixed intervals. There is a single time parameter specifying
22895 * G: retry at geometrically increasing intervals. The first argument
22896 specifies a starting value for the interval, and the second a multiplier,
22897 which is used to increase the size of the interval at each retry.
22899 * H: retry at randomized intervals. The arguments are as for G. For each
22900 retry, the previous interval is multiplied by the factor in order to get a
22901 maximum for the next interval. The minimum interval is the first argument
22902 of the parameter, and an actual interval is chosen randomly between them.
22903 Such a rule has been found to be helpful in cluster configurations when all
22904 the members of the cluster restart at once, and may therefore synchronize
22905 their queue processing times.
22907 When computing the next retry time, the algorithm definitions are scanned in
22908 order until one whose cutoff time has not yet passed is reached. This is then
22909 used to compute a new retry time that is later than the current time. In the
22910 case of fixed interval retries, this simply means adding the interval to the
22911 current time. For geometrically increasing intervals, retry intervals are
22912 computed from the rule's parameters until one that is greater than the previous
22913 interval is found. The main configuration variable retry_interval_max limits
22914 the maximum interval between retries. It cannot be set greater than "24h",
22915 which is its default value.
22917 A single remote domain may have a number of hosts associated with it, and each
22918 host may have more than one IP address. Retry algorithms are selected on the
22919 basis of the domain name, but are applied to each IP address independently. If,
22920 for example, a host has two IP addresses and one is unusable, Exim will
22921 generate retry times for it and will not try to use it until its next retry
22922 time comes. Thus the good IP address is likely to be tried first most of the
22925 Retry times are hints rather than promises. Exim does not make any attempt to
22926 run deliveries exactly at the computed times. Instead, a queue runner process
22927 starts delivery processes for delayed messages periodically, and these attempt
22928 new deliveries only for those addresses that have passed their next retry time.
22929 If a new message arrives for a deferred address, an immediate delivery attempt
22930 occurs only if the address has passed its retry time. In the absence of new
22931 messages, the minimum time between retries is the interval between queue runner
22932 processes. There is not much point in setting retry times of five minutes if
22933 your queue runners happen only once an hour, unless there are a significant
22934 number of incoming messages (which might be the case on a system that is
22935 sending everything to a smart host, for example).
22937 The data in the retry hints database can be inspected by using the exim_dumpdb
22938 or exim_fixdb utility programs (see chapter 52). The latter utility can also be
22939 used to change the data. The exinext utility script can be used to find out
22940 what the next retry times are for the hosts associated with a particular mail
22941 domain, and also for local deliveries that have been deferred.
22944 32.8 Retry rule examples
22945 ------------------------
22947 Here are some example retry rules:
22949 alice@wonderland.fict.example quota_5d F,7d,3h
22950 wonderland.fict.example quota_5d
22951 wonderland.fict.example * F,1h,15m; G,2d,1h,2;
22952 lookingglass.fict.example * F,24h,30m;
22953 * refused_A F,2h,20m;
22954 * * F,2h,15m; G,16h,1h,1.5; F,5d,8h
22956 The first rule sets up special handling for mail to
22957 alice@wonderland.fict.example when there is an over-quota error and the mailbox
22958 has not been read for at least 5 days. Retries continue every three hours for 7
22959 days. The second rule handles over-quota errors for all other local parts at
22960 wonderland.fict.example; the absence of a local part has the same effect as
22961 supplying "*@". As no retry algorithms are supplied, messages that fail are
22962 bounced immediately if the mailbox has not been read for at least 5 days.
22964 The third rule handles all other errors at wonderland.fict.example; retries
22965 happen every 15 minutes for an hour, then with geometrically increasing
22966 intervals until two days have passed since a delivery first failed. After the
22967 first hour there is a delay of one hour, then two hours, then four hours, and
22968 so on (this is a rather extreme example).
22970 The fourth rule controls retries for the domain lookingglass.fict.example. They
22971 happen every 30 minutes for 24 hours only. The remaining two rules handle all
22972 other domains, with special action for connection refusal from hosts that were
22973 not obtained from an MX record.
22975 The final rule in a retry configuration should always have asterisks in the
22976 first two fields so as to provide a general catch-all for any addresses that do
22977 not have their own special handling. This example tries every 15 minutes for 2
22978 hours, then with intervals starting at one hour and increasing by a factor of
22979 1.5 up to 16 hours, then every 8 hours up to 5 days.
22982 32.9 Timeout of retry data
22983 --------------------------
22985 Exim timestamps the data that it writes to its retry hints database. When it
22986 consults the data during a delivery it ignores any that is older than the value
22987 set in retry_data_expire (default 7 days). If, for example, a host hasn't been
22988 tried for 7 days, Exim will try to deliver to it immediately a message arrives,
22989 and if that fails, it will calculate a retry time as if it were failing for the
22992 This improves the behaviour for messages routed to rarely-used hosts such as MX
22993 backups. If such a host was down at one time, and happens to be down again when
22994 Exim tries a month later, using the old retry data would imply that it had been
22995 down all the time, which is not a justified assumption.
22997 If a host really is permanently dead, this behaviour causes a burst of retries
22998 every now and again, but only if messages routed to it are rare. If there is a
22999 message at least once every 7 days the retry data never expires.
23002 32.10 Long-term failures
23003 ------------------------
23005 Special processing happens when an email address has been failing for so long
23006 that the cutoff time for the last algorithm is reached. For example, using the
23007 default retry rule:
23009 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
23011 the cutoff time is four days. Reaching the retry cutoff is independent of how
23012 long any specific message has been failing; it is the length of continuous
23013 failure for the recipient address that counts.
23015 When the cutoff time is reached for a local delivery, or for all the IP
23016 addresses associated with a remote delivery, a subsequent delivery failure
23017 causes Exim to give up on the address, and a bounce message is generated. In
23018 order to cater for new messages that use the failing address, a next retry time
23019 is still computed from the final algorithm, and is used as follows:
23021 For local deliveries, one delivery attempt is always made for any subsequent
23022 messages. If this delivery fails, the address fails immediately. The
23023 post-cutoff retry time is not used.
23025 If the delivery is remote, there are two possibilities, controlled by the
23026 delay_after_cutoff option of the smtp transport. The option is true by default.
23027 Until the post-cutoff retry time for one of the IP addresses is reached, the
23028 failing email address is bounced immediately, without a delivery attempt taking
23029 place. After that time, one new delivery attempt is made to those IP addresses
23030 that are past their retry times, and if that still fails, the address is
23031 bounced and new retry times are computed.
23033 In other words, when all the hosts for a given email address have been failing
23034 for a long time, Exim bounces rather then defers until one of the hosts' retry
23035 times is reached. Then it tries once, and bounces if that attempt fails. This
23036 behaviour ensures that few resources are wasted in repeatedly trying to deliver
23037 to a broken destination, but if the host does recover, Exim will eventually
23040 If delay_after_cutoff is set false, Exim behaves differently. If all IP
23041 addresses are past their final cutoff time, Exim tries to deliver to those IP
23042 addresses that have not been tried since the message arrived. If there are no
23043 suitable IP addresses, or if they all fail, the address is bounced. In other
23044 words, it does not delay when a new message arrives, but tries the expired
23045 addresses immediately, unless they have been tried since the message arrived.
23046 If there is a continuous stream of messages for the failing domains, setting
23047 delay_after_cutoff false means that there will be many more attempts to deliver
23048 to permanently failing IP addresses than when delay_after_cutoff is true.
23051 32.11 Deliveries that work intermittently
23052 -----------------------------------------
23054 Some additional logic is needed to cope with cases where a host is
23055 intermittently available, or when a message has some attribute that prevents
23056 its delivery when others to the same address get through. In this situation,
23057 because some messages are successfully delivered, the "retry clock" for the
23058 host or address keeps getting reset by the successful deliveries, and so
23059 failing messages remain on the queue for ever because the cutoff time is never
23062 Two exceptional actions are applied to prevent this happening. The first
23063 applies to errors that are related to a message rather than a remote host.
23064 Section 47.2 has a discussion of the different kinds of error; examples of
23065 message-related errors are 4xx responses to MAIL or DATA commands, and quota
23066 failures. For this type of error, if a message's arrival time is earlier than
23067 the "first failed" time for the error, the earlier time is used when scanning
23068 the retry rules to decide when to try next and when to time out the address.
23070 The exceptional second action applies in all cases. If a message has been on
23071 the queue for longer than the cutoff time of any applicable retry rule for a
23072 given address, a delivery is attempted for that address, even if it is not yet
23073 time, and if this delivery fails, the address is timed out. A new retry time is
23074 not computed in this case, so that other messages for the same address are
23075 considered immediately.
23079 ===============================================================================
23080 33. SMTP AUTHENTICATION
23082 The "authenticators" section of Exim's run time configuration is concerned with
23083 SMTP authentication. This facility is an extension to the SMTP protocol,
23084 described in RFC 2554, which allows a client SMTP host to authenticate itself
23085 to a server. This is a common way for a server to recognize clients that are
23086 permitted to use it as a relay. SMTP authentication is not of relevance to the
23087 transfer of mail between servers that have no managerial connection with each
23090 Very briefly, the way SMTP authentication works is as follows:
23092 * The server advertises a number of authentication mechanisms in response to
23093 the client's EHLO command.
23095 * The client issues an AUTH command, naming a specific mechanism. The command
23096 may, optionally, contain some authentication data.
23098 * The server may issue one or more challenges, to which the client must send
23099 appropriate responses. In simple authentication mechanisms, the challenges
23100 are just prompts for user names and passwords. The server does not have to
23101 issue any challenges - in some mechanisms the relevant data may all be
23102 transmitted with the AUTH command.
23104 * The server either accepts or denies authentication.
23106 * If authentication succeeds, the client may optionally make use of the AUTH
23107 option on the MAIL command to pass an authenticated sender in subsequent
23108 mail transactions. Authentication lasts for the remainder of the SMTP
23111 * If authentication fails, the client may give up, or it may try a different
23112 authentication mechanism, or it may try transferring mail over the
23113 unauthenticated connection.
23115 If you are setting up a client, and want to know which authentication
23116 mechanisms the server supports, you can use Telnet to connect to port 25 (the
23117 SMTP port) on the server, and issue an EHLO command. The response to this
23118 includes the list of supported mechanisms. For example:
23120 $ telnet server.example 25
23121 Trying 192.168.34.25...
23122 Connected to server.example.
23123 Escape character is '^]'.
23124 220 server.example ESMTP Exim 4.20 ...
23125 ehlo client.example
23126 250-server.example Hello client.example [10.8.4.5]
23132 The second-last line of this example output shows that the server supports
23133 authentication using the PLAIN mechanism. In Exim, the different authentication
23134 mechanisms are configured by specifying authenticator drivers. Like the routers
23135 and transports, which authenticators are included in the binary is controlled
23136 by build-time definitions. The following are currently available, included by
23140 AUTH_CYRUS_SASL=yes
23143 AUTH_HEIMDAL_GSSAPI=yes
23147 in Local/Makefile, respectively. The first of these supports the CRAM-MD5
23148 authentication mechanism (RFC 2195), and the second provides an interface to
23149 the Cyrus SASL authentication library. The third is an interface to Dovecot's
23150 authentication system, delegating the work via a socket interface. The fourth
23151 provides an interface to the GNU SASL authentication library, which provides
23152 mechanisms but typically not data sources. The fifth provides direct access to
23153 Heimdal GSSAPI, geared for Kerberos, but supporting setting a server keytab.
23154 The sixth can be configured to support the PLAIN authentication mechanism (RFC
23155 2595) or the LOGIN mechanism, which is not formally documented, but used by
23156 several MUAs. The seventh authenticator supports Microsoft's Secure Password
23157 Authentication mechanism.
23159 The authenticators are configured using the same syntax as other drivers (see
23160 section 6.22). If no authenticators are required, no authentication section
23161 need be present in the configuration file. Each authenticator can in principle
23162 have both server and client functions. When Exim is receiving SMTP mail, it is
23163 acting as a server; when it is sending out messages over SMTP, it is acting as
23164 a client. Authenticator configuration options are provided for use in both
23165 these circumstances.
23167 To make it clear which options apply to which situation, the prefixes server_
23168 and client_ are used on option names that are specific to either the server or
23169 the client function, respectively. Server and client functions are disabled if
23170 none of their options are set. If an authenticator is to be used for both
23171 server and client functions, a single definition, using both sets of options,
23172 is required. For example:
23176 public_name = CRAM-MD5
23177 server_secret = ${if eq{$auth1}{ph10}{secret1}fail}
23179 client_secret = secret2
23181 The server_ option is used when Exim is acting as a server, and the client_
23182 options when it is acting as a client.
23184 Descriptions of the individual authenticators are given in subsequent chapters.
23185 The remainder of this chapter covers the generic options for the
23186 authenticators, followed by general discussion of the way authentication works
23189 Beware: the meaning of $auth1, $auth2, ... varies on a per-driver and
23190 per-mechanism basis. Please read carefully to determine which variables hold
23191 account labels such as usercodes and which hold passwords or other
23192 authenticating data.
23194 Note that some mechanisms support two different identifiers for accounts: the
23195 authentication id and the authorization id. The contractions authn and authz
23196 are commonly encountered. The American spelling is standard here. Conceptually,
23197 authentication data such as passwords are tied to the identifier used to
23198 authenticate; servers may have rules to permit one user to act as a second
23199 user, so that after login the session is treated as though that second user had
23200 logged in. That second user is the authorization id. A robust configuration
23201 might confirm that the authz field is empty or matches the authn field. Often
23202 this is just ignored. The authn can be considered as verified data, the authz
23203 as an unverified request which the server might choose to honour.
23205 A realm is a text string, typically a domain name, presented by a server to a
23206 client to help it select an account and credentials to use. In some mechanisms,
23207 the client and server provably agree on the realm, but clients typically can
23208 not treat the realm as secure data to be blindly trusted.
23211 33.1 Generic options for authenticators
23212 ---------------------------------------
23214 +----------------+-------------------+-------------+--------------+
23215 |client_condition|Use: authenticators|Type: string*|Default: unset|
23216 +----------------+-------------------+-------------+--------------+
23218 When Exim is authenticating as a client, it skips any authenticator whose
23219 client_condition expansion yields "0", "no", or "false". This can be used, for
23220 example, to skip plain text authenticators when the connection is not encrypted
23221 by a setting such as:
23223 client_condition = ${if !eq{$tls_out_cipher}{}}
23225 +-------------+-------------------+-------------+--------------+
23226 |client_set_id|Use: authenticators|Type: string*|Default: unset|
23227 +-------------+-------------------+-------------+--------------+
23229 When client authentication succeeds, this condition is expanded; the result is
23230 used in the log lines for outbound messasges. Typically it will be the user
23231 name used for authentication.
23233 +------+-------------------+------------+--------------+
23234 |driver|Use: authenticators|Type: string|Default: unset|
23235 +------+-------------------+------------+--------------+
23237 This option must always be set. It specifies which of the available
23238 authenticators is to be used.
23240 +-----------+-------------------+------------+--------------+
23241 |public_name|Use: authenticators|Type: string|Default: unset|
23242 +-----------+-------------------+------------+--------------+
23244 This option specifies the name of the authentication mechanism that the driver
23245 implements, and by which it is known to the outside world. These names should
23246 contain only upper case letters, digits, underscores, and hyphens (RFC 2222),
23247 but Exim in fact matches them caselessly. If public_name is not set, it
23248 defaults to the driver's instance name.
23250 +--------------------------+-------------------+-------------+--------------+
23251 |server_advertise_condition|Use: authenticators|Type: string*|Default: unset|
23252 +--------------------------+-------------------+-------------+--------------+
23254 When a server is about to advertise an authentication mechanism, the condition
23255 is expanded. If it yields the empty string, "0", "no", or "false", the
23256 mechanism is not advertised. If the expansion fails, the mechanism is not
23257 advertised. If the failure was not forced, and was not caused by a lookup
23258 defer, the incident is logged. See section 33.3 below for further discussion.
23260 +----------------+-------------------+-------------+--------------+
23261 |server_condition|Use: authenticators|Type: string*|Default: unset|
23262 +----------------+-------------------+-------------+--------------+
23264 This option must be set for a plaintext server authenticator, where it is used
23265 directly to control authentication. See section 34.2 for details.
23267 For the gsasl authenticator, this option is required for various mechanisms;
23268 see chapter 38 for details.
23270 For the other authenticators, server_condition can be used as an additional
23271 authentication or authorization mechanism that is applied after the other
23272 authenticator conditions succeed. If it is set, it is expanded when the
23273 authenticator would otherwise return a success code. If the expansion is forced
23274 to fail, authentication fails. Any other expansion failure causes a temporary
23275 error code to be returned. If the result of a successful expansion is an empty
23276 string, "0", "no", or "false", authentication fails. If the result of the
23277 expansion is "1", "yes", or "true", authentication succeeds. For any other
23278 result, a temporary error code is returned, with the expanded string as the
23281 +------------------+-------------------+-------------+--------------+
23282 |server_debug_print|Use: authenticators|Type: string*|Default: unset|
23283 +------------------+-------------------+-------------+--------------+
23285 If this option is set and authentication debugging is enabled (see the -d
23286 command line option), the string is expanded and included in the debugging
23287 output when the authenticator is run as a server. This can help with checking
23288 out the values of variables. If expansion of the string fails, the error
23289 message is written to the debugging output, and Exim carries on processing.
23291 +-------------+-------------------+-------------+--------------+
23292 |server_set_id|Use: authenticators|Type: string*|Default: unset|
23293 +-------------+-------------------+-------------+--------------+
23295 When an Exim server successfully authenticates a client, this string is
23296 expanded using data from the authentication, and preserved for any incoming
23297 messages in the variable $authenticated_id. It is also included in the log
23298 lines for incoming messages. For example, a user/password authenticator
23299 configuration might preserve the user name that was used to authenticate, and
23300 refer to it subsequently during delivery of the message. If expansion fails,
23301 the option is ignored.
23303 +--------------------------+-------------------+-------------+--------------+
23304 |server_mail_auth_condition|Use: authenticators|Type: string*|Default: unset|
23305 +--------------------------+-------------------+-------------+--------------+
23307 This option allows a server to discard authenticated sender addresses supplied
23308 as part of MAIL commands in SMTP connections that are authenticated by the
23309 driver on which server_mail_auth_condition is set. The option is not used as
23310 part of the authentication process; instead its (unexpanded) value is
23311 remembered for later use. How it is used is described in the following section.
23314 33.2 The AUTH parameter on MAIL commands
23315 ----------------------------------------
23317 When a client supplied an AUTH= item on a MAIL command, Exim applies the
23318 following checks before accepting it as the authenticated sender of the
23321 * If the connection is not using extended SMTP (that is, HELO was used rather
23322 than EHLO), the use of AUTH= is a syntax error.
23324 * If the value of the AUTH= parameter is "<>", it is ignored.
23326 * If acl_smtp_mailauth is defined, the ACL it specifies is run. While it is
23327 running, the value of $authenticated_sender is set to the value obtained
23328 from the AUTH= parameter. If the ACL does not yield "accept", the value of
23329 $authenticated_sender is deleted. The acl_smtp_mailauth ACL may not return
23330 "drop" or "discard". If it defers, a temporary error code (451) is given
23331 for the MAIL command.
23333 * If acl_smtp_mailauth is not defined, the value of the AUTH= parameter is
23334 accepted and placed in $authenticated_sender only if the client has
23337 * If the AUTH= value was accepted by either of the two previous rules, and
23338 the client has authenticated, and the authenticator has a setting for the
23339 server_mail_auth_condition, the condition is checked at this point. The
23340 valued that was saved from the authenticator is expanded. If the expansion
23341 fails, or yields an empty string, "0", "no", or "false", the value of
23342 $authenticated_sender is deleted. If the expansion yields any other value,
23343 the value of $authenticated_sender is retained and passed on with the
23346 When $authenticated_sender is set for a message, it is passed on to other hosts
23347 to which Exim authenticates as a client. Do not confuse this value with
23348 $authenticated_id, which is a string obtained from the authentication process,
23349 and which is not usually a complete email address.
23351 Whenever an AUTH= value is ignored, the incident is logged. The ACL for MAIL,
23352 if defined, is run after AUTH= is accepted or ignored. It can therefore make
23353 use of $authenticated_sender. The converse is not true: the value of
23354 $sender_address is not yet set up when the acl_smtp_mailauth ACL is run.
23357 33.3 Authentication on an Exim server
23358 -------------------------------------
23360 When Exim receives an EHLO command, it advertises the public names of those
23361 authenticators that are configured as servers, subject to the following
23364 * The client host must match auth_advertise_hosts (default *).
23366 * It the server_advertise_condition option is set, its expansion must not
23367 yield the empty string, "0", "no", or "false".
23369 The order in which the authenticators are defined controls the order in which
23370 the mechanisms are advertised.
23372 Some mail clients (for example, some versions of Netscape) require the user to
23373 provide a name and password for authentication whenever AUTH is advertised,
23374 even though authentication may not in fact be needed (for example, Exim may be
23375 set up to allow unconditional relaying from the client by an IP address check).
23376 You can make such clients more friendly by not advertising AUTH to them. For
23377 example, if clients on the 10.9.8.0/24 network are permitted (by the ACL that
23378 runs for RCPT) to relay without authentication, you should set
23380 auth_advertise_hosts = ! 10.9.8.0/24
23382 so that no authentication mechanisms are advertised to them.
23384 The server_advertise_condition controls the advertisement of individual
23385 authentication mechanisms. For example, it can be used to restrict the
23386 advertisement of a particular mechanism to encrypted connections, by a setting
23389 server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}}
23391 If the session is encrypted, $tls_in_cipher is not empty, and so the expansion
23392 yields "yes", which allows the advertisement to happen.
23394 When an Exim server receives an AUTH command from a client, it rejects it
23395 immediately if AUTH was not advertised in response to an earlier EHLO command.
23396 This is the case if
23398 * The client host does not match auth_advertise_hosts; or
23400 * No authenticators are configured with server options; or
23402 * Expansion of server_advertise_condition blocked the advertising of all the
23403 server authenticators.
23405 Otherwise, Exim runs the ACL specified by acl_smtp_auth in order to decide
23406 whether to accept the command. If acl_smtp_auth is not set, AUTH is accepted
23407 from any client host.
23409 If AUTH is not rejected by the ACL, Exim searches its configuration for a
23410 server authentication mechanism that was advertised in response to EHLO and
23411 that matches the one named in the AUTH command. If it finds one, it runs the
23412 appropriate authentication protocol, and authentication either succeeds or
23413 fails. If there is no matching advertised mechanism, the AUTH command is
23414 rejected with a 504 error.
23416 When a message is received from an authenticated host, the value of
23417 $received_protocol is set to "esmtpa" or "esmtpsa" instead of "esmtp" or
23418 "esmtps", and $sender_host_authenticated contains the name (not the public
23419 name) of the authenticator driver that successfully authenticated the client
23420 from which the message was received. This variable is empty if there was no
23421 successful authentication.
23424 33.4 Testing server authentication
23425 ----------------------------------
23427 Exim's -bh option can be useful for testing server authentication
23428 configurations. The data for the AUTH command has to be sent using base64
23429 encoding. A quick way to produce such data for testing is the following Perl
23433 printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
23435 This interprets its argument as a Perl string, and then encodes it. The
23436 interpretation as a Perl string allows binary zeros, which are required for
23437 some kinds of authentication, to be included in the data. For example, a
23438 command line to run this script on such data might be
23440 encode '\0user\0password'
23442 Note the use of single quotes to prevent the shell interpreting the
23443 backslashes, so that they can be interpreted by Perl to specify characters
23444 whose code value is zero.
23446 Warning 1: If either of the user or password strings starts with an octal
23447 digit, you must use three zeros instead of one after the leading backslash. If
23448 you do not, the octal digit that starts your string will be incorrectly
23449 interpreted as part of the code for the first character.
23451 Warning 2: If there are characters in the strings that Perl interprets
23452 specially, you must use a Perl escape to prevent them being misinterpreted. For
23453 example, a command such as
23455 encode '\0user@domain.com\0pas$$word'
23457 gives an incorrect answer because of the unescaped "@" and "$" characters.
23459 If you have the mimencode command installed, another way to do produce
23460 base64-encoded strings is to run the command
23462 echo -e -n `\0user\0password' | mimencode
23464 The -e option of echo enables the interpretation of backslash escapes in the
23465 argument, and the -n option specifies no newline at the end of its output.
23466 However, not all versions of echo recognize these options, so you should check
23467 your version before relying on this suggestion.
23470 33.5 Authentication by an Exim client
23471 -------------------------------------
23473 The smtp transport has two options called hosts_require_auth and hosts_try_auth
23474 . When the smtp transport connects to a server that announces support for
23475 authentication, and the host matches an entry in either of these options, Exim
23476 (as a client) tries to authenticate as follows:
23478 * For each authenticator that is configured as a client, in the order in
23479 which they are defined in the configuration, it searches the authentication
23480 mechanisms announced by the server for one whose name matches the public
23481 name of the authenticator.
23483 * When it finds one that matches, it runs the authenticator's client code.
23484 The variables $host and $host_address are available for any string
23485 expansions that the client might do. They are set to the server's name and
23486 IP address. If any expansion is forced to fail, the authentication attempt
23487 is abandoned, and Exim moves on to the next authenticator. Otherwise an
23488 expansion failure causes delivery to be deferred.
23490 * If the result of the authentication attempt is a temporary error or a
23491 timeout, Exim abandons trying to send the message to the host for the
23492 moment. It will try again later. If there are any backup hosts available,
23493 they are tried in the usual way.
23495 * If the response to authentication is a permanent error (5xx code), Exim
23496 carries on searching the list of authenticators and tries another one if
23497 possible. If all authentication attempts give permanent errors, or if there
23498 are no attempts because no mechanisms match (or option expansions force
23499 failure), what happens depends on whether the host matches
23500 hosts_require_auth or hosts_try_auth. In the first case, a temporary error
23501 is generated, and delivery is deferred. The error can be detected in the
23502 retry rules, and thereby turned into a permanent error if you wish. In the
23503 second case, Exim tries to deliver the message unauthenticated.
23505 When Exim has authenticated itself to a remote server, it adds the AUTH
23506 parameter to the MAIL commands it sends, if it has an authenticated sender for
23507 the message. If the message came from a remote host, the authenticated sender
23508 is the one that was receiving on an incoming MAIL command, provided that the
23509 incoming connection was authenticated and the server_mail_auth condition
23510 allowed the authenticated sender to be retained. If a local process calls Exim
23511 to send a message, the sender address that is built from the login name and
23512 qualify_domain is treated as authenticated. However, if the
23513 authenticated_sender option is set on the smtp transport, it overrides the
23514 authenticated sender that was received with the message.
23518 ===============================================================================
23519 34. THE PLAINTEXT AUTHENTICATOR
23521 The plaintext authenticator can be configured to support the PLAIN and LOGIN
23522 authentication mechanisms, both of which transfer authentication data as plain
23523 (unencrypted) text (though base64 encoded). The use of plain text is a security
23524 risk; you are strongly advised to insist on the use of SMTP encryption (see
23525 chapter 41) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted
23526 plain text, you should not use the same passwords for SMTP connections as you
23527 do for login accounts.
23530 34.1 Plaintext options
23531 ----------------------
23533 When configured as a server, plaintext uses the following options:
23535 +----------------+-------------------+-------------+--------------+
23536 |server_condition|Use: authenticators|Type: string*|Default: unset|
23537 +----------------+-------------------+-------------+--------------+
23539 This is actually a global authentication option, but it must be set in order to
23540 configure the plaintext driver as a server. Its use is described below.
23542 +--------------+--------------+-------------+--------------+
23543 |server_prompts|Use: plaintext|Type: string*|Default: unset|
23544 +--------------+--------------+-------------+--------------+
23546 The contents of this option, after expansion, must be a colon-separated list of
23547 prompt strings. If expansion fails, a temporary authentication rejection is
23551 34.2 Using plaintext in a server
23552 --------------------------------
23554 When running as a server, plaintext performs the authentication test by
23555 expanding a string. The data sent by the client with the AUTH command, or in
23556 response to subsequent prompts, is base64 encoded, and so may contain any byte
23557 values when decoded. If any data is supplied with the command, it is treated as
23558 a list of strings, separated by NULs (binary zeros), the first three of which
23559 are placed in the expansion variables $auth1, $auth2, and $auth3 (neither LOGIN
23560 nor PLAIN uses more than three strings).
23562 For compatibility with previous releases of Exim, the values are also placed in
23563 the expansion variables $1, $2, and $3. However, the use of these variables for
23564 this purpose is now deprecated, as it can lead to confusion in string
23565 expansions that also use them for other things.
23567 If there are more strings in server_prompts than the number of strings supplied
23568 with the AUTH command, the remaining prompts are used to obtain more data. Each
23569 response from the client may be a list of NUL-separated strings.
23571 Once a sufficient number of data strings have been received, server_condition
23572 is expanded. If the expansion is forced to fail, authentication fails. Any
23573 other expansion failure causes a temporary error code to be returned. If the
23574 result of a successful expansion is an empty string, "0", "no", or "false",
23575 authentication fails. If the result of the expansion is "1", "yes", or "true",
23576 authentication succeeds and the generic server_set_id option is expanded and
23577 saved in $authenticated_id. For any other result, a temporary error code is
23578 returned, with the expanded string as the error text
23580 Warning: If you use a lookup in the expansion to find the user's password, be
23581 sure to make the authentication fail if the user is unknown. There are good and
23582 bad examples at the end of the next section.
23585 34.3 The PLAIN authentication mechanism
23586 ---------------------------------------
23588 The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
23589 sent as one item of data (that is, one combined string containing two NUL
23590 separators). The data is sent either as part of the AUTH command, or
23591 subsequently in response to an empty prompt from the server.
23593 The second and third strings are a user name and a corresponding password.
23594 Using a single fixed user name and password as an example, this could be
23595 configured as follows:
23599 public_name = PLAIN
23601 server_condition = \
23602 ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}}
23603 server_set_id = $auth2
23605 Note that the default result strings from if ("true" or an empty string) are
23606 exactly what we want here, so they need not be specified. Obviously, if the
23607 password contains expansion-significant characters such as dollar, backslash,
23608 or closing brace, they have to be escaped.
23610 The server_prompts setting specifies a single, empty prompt (empty items at the
23611 end of a string list are ignored). If all the data comes as part of the AUTH
23612 command, as is commonly the case, the prompt is not used. This authenticator is
23613 advertised in the response to EHLO as
23617 and a client host can authenticate itself by sending the command
23619 AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0
23621 As this contains three strings (more than the number of prompts), no further
23622 data is required from the client. Alternatively, the client may just send
23626 to initiate authentication, in which case the server replies with an empty
23627 prompt. The client must respond with the combined data string.
23629 The data string is base64 encoded, as required by the RFC. This example, when
23630 decoded, is <NUL>"username"<NUL>"mysecret", where <NUL> represents a zero byte.
23631 This is split up into three strings, the first of which is empty. The
23632 server_condition option in the authenticator checks that the second two are
23633 "username" and "mysecret" respectively.
23635 Having just one fixed user name and password, as in this example, is not very
23636 realistic, though for a small organization with only a handful of
23637 authenticating clients it could make sense.
23639 A more sophisticated instance of this authenticator could use the user name in
23640 $auth2 to look up a password in a file or database, and maybe do an encrypted
23641 comparison (see crypteq in chapter 11). Here is a example of this approach,
23642 where the passwords are looked up in a DBM file. Warning: This is an incorrect
23645 server_condition = \
23646 ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}}
23648 The expansion uses the user name ($auth2) as the key to look up a password,
23649 which it then compares to the supplied password ($auth3). Why is this example
23650 incorrect? It works fine for existing users, but consider what happens if a
23651 non-existent user name is given. The lookup fails, but as no success/failure
23652 strings are given for the lookup, it yields an empty string. Thus, to defeat
23653 the authentication, all a client has to do is to supply a non-existent user
23654 name and an empty password. The correct way of writing this test is:
23656 server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
23657 {${if eq{$value}{$auth3}}} {false}}
23659 In this case, if the lookup succeeds, the result is checked; if the lookup
23660 fails, "false" is returned and authentication fails. If crypteq is being used
23661 instead of eq, the first example is in fact safe, because crypteq always fails
23662 if its second argument is empty. However, the second way of writing the test
23663 makes the logic clearer.
23666 34.4 The LOGIN authentication mechanism
23667 ---------------------------------------
23669 The LOGIN authentication mechanism is not documented in any RFC, but is in use
23670 in a number of programs. No data is sent with the AUTH command. Instead, a user
23671 name and password are supplied separately, in response to prompts. The
23672 plaintext authenticator can be configured to support this as in this example:
23676 public_name = LOGIN
23677 server_prompts = User Name : Password
23678 server_condition = \
23679 ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}}
23680 server_set_id = $auth1
23682 Because of the way plaintext operates, this authenticator accepts data supplied
23683 with the AUTH command (in contravention of the specification of LOGIN), but if
23684 the client does not supply it (as is the case for LOGIN clients), the prompt
23685 strings are used to obtain two data items.
23687 Some clients are very particular about the precise text of the prompts. For
23688 example, Outlook Express is reported to recognize only "Username:" and
23689 "Password:". Here is an example of a LOGIN authenticator that uses those
23690 strings. It uses the ldapauth expansion condition to check the user name and
23691 password by binding to an LDAP server:
23695 public_name = LOGIN
23696 server_prompts = Username:: : Password::
23697 server_condition = ${if and{{ \
23700 user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
23701 pass=${quote:$auth2} \
23702 ldap://ldap.example.org/} }} }
23703 server_set_id = uid=$auth1,ou=people,o=example.org
23705 We have to check that the username is not empty before using it, because LDAP
23706 does not permit empty DN components. We must also use the quote_ldap_dn
23707 operator to correctly quote the DN for authentication. However, the basic quote
23708 operator, rather than any of the LDAP quoting operators, is the correct one to
23709 use for the password, because quoting is needed only to make the password
23710 conform to the Exim syntax. At the LDAP level, the password is an uninterpreted
23714 34.5 Support for different kinds of authentication
23715 --------------------------------------------------
23717 A number of string expansion features are provided for the purpose of
23718 interfacing to different ways of user authentication. These include checking
23719 traditionally encrypted passwords from /etc/passwd (or equivalent), PAM,
23720 Radius, ldapauth, pwcheck, and saslauthd. For details see section 11.7.
23723 34.6 Using plaintext in a client
23724 --------------------------------
23726 The plaintext authenticator has two client options:
23728 +----------------------------+--------------+-------------+--------------+
23729 |client_ignore_invalid_base64|Use: plaintext|Type: boolean|Default: false|
23730 +----------------------------+--------------+-------------+--------------+
23732 If the client receives a server prompt that is not a valid base64 string,
23733 authentication is abandoned by default. However, if this option is set true,
23734 the error in the challenge is ignored and the client sends the response as
23737 +-----------+--------------+-------------+--------------+
23738 |client_send|Use: plaintext|Type: string*|Default: unset|
23739 +-----------+--------------+-------------+--------------+
23741 The string is a colon-separated list of authentication data strings. Each
23742 string is independently expanded before being sent to the server. The first
23743 string is sent with the AUTH command; any more strings are sent in response to
23744 prompts from the server. Before each string is expanded, the value of the most
23745 recent prompt is placed in the next $auth<n> variable, starting with $auth1 for
23746 the first prompt. Up to three prompts are stored in this way. Thus, the prompt
23747 that is received in response to sending the first string (with the AUTH
23748 command) can be used in the expansion of the second string, and so on. If an
23749 invalid base64 string is received when client_ignore_invalid_base64 is set, an
23750 empty string is put in the $auth<n> variable.
23752 Note: You cannot use expansion to create multiple strings, because splitting
23753 takes priority and happens first.
23755 Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in
23756 the data, further processing is applied to each string before it is sent. If
23757 there are any single circumflex characters in the string, they are converted to
23758 NULs. Should an actual circumflex be required as data, it must be doubled in
23761 This is an example of a client configuration that implements the PLAIN
23762 authentication mechanism with a fixed user name and password:
23766 public_name = PLAIN
23767 client_send = ^username^mysecret
23769 The lack of colons means that the entire text is sent with the AUTH command,
23770 with the circumflex characters converted to NULs. A similar example that uses
23771 the LOGIN mechanism is:
23775 public_name = LOGIN
23776 client_send = : username : mysecret
23778 The initial colon means that the first string is empty, so no data is sent with
23779 the AUTH command itself. The remaining strings are sent in response to prompts.
23783 ===============================================================================
23784 35. THE CRAM_MD5 AUTHENTICATOR
23786 The CRAM-MD5 authentication mechanism is described in RFC 2195. The server
23787 sends a challenge string to the client, and the response consists of a user
23788 name and the CRAM-MD5 digest of the challenge string combined with a secret
23789 string (password) which is known to both server and client. Thus, the secret is
23790 not sent over the network as plain text, which makes this authenticator more
23791 secure than plaintext. However, the downside is that the secret has to be
23792 available in plain text at either end.
23795 35.1 Using cram_md5 as a server
23796 -------------------------------
23798 This authenticator has one server option, which must be set to configure the
23799 authenticator as a server:
23801 +-------------+-------------+-------------+--------------+
23802 |server_secret|Use: cram_md5|Type: string*|Default: unset|
23803 +-------------+-------------+-------------+--------------+
23805 When the server receives the client's response, the user name is placed in the
23806 expansion variable $auth1, and server_secret is expanded to obtain the password
23807 for that user. The server then computes the CRAM-MD5 digest that the client
23808 should have sent, and checks that it received the correct string. If the
23809 expansion of server_secret is forced to fail, authentication fails. If the
23810 expansion fails for some other reason, a temporary error code is returned to
23813 For compatibility with previous releases of Exim, the user name is also placed
23814 in $1. However, the use of this variables for this purpose is now deprecated,
23815 as it can lead to confusion in string expansions that also use numeric
23816 variables for other things.
23818 For example, the following authenticator checks that the user name given by the
23819 client is "ph10", and if so, uses "secret" as the password. For any other user
23820 name, authentication fails.
23824 public_name = CRAM-MD5
23825 server_secret = ${if eq{$auth1}{ph10}{secret}fail}
23826 server_set_id = $auth1
23828 If authentication succeeds, the setting of server_set_id preserves the user
23829 name in $authenticated_id. A more typical configuration might look up the
23830 secret string in a file, using the user name as the key. For example:
23834 public_name = CRAM-MD5
23835 server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\
23837 server_set_id = $auth1
23839 Note that this expansion explicitly forces failure if the lookup fails because
23840 $auth1 contains an unknown user name.
23842 As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
23843 using the relevant libraries, you need to know the realm to specify in the
23844 lookup and then ask for the "userPassword" attribute for that user in that
23849 public_name = CRAM-MD5
23850 server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
23851 dbmjz{/etc/sasldb2}}
23852 server_set_id = $auth1
23855 35.2 Using cram_md5 as a client
23856 -------------------------------
23858 When used as a client, the cram_md5 authenticator has two options:
23860 +-----------+-------------+-------------+------------------------------+
23861 |client_name|Use: cram_md5|Type: string*|Default: the primary host name|
23862 +-----------+-------------+-------------+------------------------------+
23864 This string is expanded, and the result used as the user name data when
23865 computing the response to the server's challenge.
23867 +-------------+-------------+-------------+--------------+
23868 |client_secret|Use: cram_md5|Type: string*|Default: unset|
23869 +-------------+-------------+-------------+--------------+
23871 This option must be set for the authenticator to work as a client. Its value is
23872 expanded and the result used as the secret string when computing the response.
23874 Different user names and secrets can be used for different servers by referring
23875 to $host or $host_address in the options. Forced failure of either expansion
23876 string is treated as an indication that this authenticator is not prepared to
23877 handle this case. Exim moves on to the next configured client authenticator.
23878 Any other expansion failure causes Exim to give up trying to send the message
23879 to the current server.
23881 A simple example configuration of a cram_md5 authenticator, using fixed
23886 public_name = CRAM-MD5
23888 client_secret = secret
23892 ===============================================================================
23893 36. THE CYRUS_SASL AUTHENTICATOR
23895 The code for this authenticator was provided by Matthew Byng-Maddick of A L
23896 Digital Ltd (http://www.aldigital.co.uk).
23898 The cyrus_sasl authenticator provides server support for the Cyrus SASL library
23899 implementation of the RFC 2222 ("Simple Authentication and Security Layer").
23900 This library supports a number of authentication mechanisms, including PLAIN
23901 and LOGIN, but also several others that Exim does not support directly. In
23902 particular, there is support for Kerberos authentication.
23904 The cyrus_sasl authenticator provides a gatewaying mechanism directly to the
23905 Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, then
23906 so can the cyrus_sasl authenticator. By default it uses the public name of the
23907 driver to determine which mechanism to support.
23909 Where access to some kind of secret file is required, for example in GSSAPI or
23910 CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and
23911 that the Cyrus SASL library has no way of escalating privileges by default. You
23912 may also find you need to set environment variables, depending on the driver
23915 The application name provided by Exim is "exim", so various SASL options may be
23916 set in exim.conf in your SASL directory. If you are using GSSAPI for Kerberos,
23917 note that because of limitations in the GSSAPI interface, changing the server
23918 keytab might need to be communicated down to the Kerberos layer independently.
23919 The mechanism for doing so is dependent upon the Kerberos implementation.
23921 For example, for older releases of Heimdal, the environment variable
23922 KRB5_KTNAME may be set to point to an alternative keytab file. Exim will pass
23923 this variable through from its own inherited environment when started as root
23924 or the Exim user. The keytab file needs to be readable by the Exim user. With
23925 newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
23926 environment variable. In practice, for those releases, the Cyrus authenticator
23927 is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider
23928 the heimdal_gssapi authenticator, described in chapter 39
23931 36.1 Using cyrus_sasl as a server
23932 ---------------------------------
23934 The cyrus_sasl authenticator has four private options. It puts the username (on
23935 a successful authentication) into $auth1. For compatibility with previous
23936 releases of Exim, the username is also placed in $1. However, the use of this
23937 variable for this purpose is now deprecated, as it can lead to confusion in
23938 string expansions that also use numeric variables for other things.
23940 +---------------+---------------+-------------+------------------+
23941 |server_hostname|Use: cyrus_sasl|Type: string*|Default: see below|
23942 +---------------+---------------+-------------+------------------+
23944 This option selects the hostname that is used when communicating with the
23945 library. The default value is "$primary_hostname". It is up to the underlying
23946 SASL plug-in what it does with this data.
23948 +-----------+---------------+------------+------------------+
23949 |server_mech|Use: cyrus_sasl|Type: string|Default: see below|
23950 +-----------+---------------+------------+------------------+
23952 This option selects the authentication mechanism this driver should use. The
23953 default is the value of the generic public_name option. This option allows you
23954 to use a different underlying mechanism from the advertised name. For example:
23957 driver = cyrus_sasl
23958 public_name = X-ANYTHING
23959 server_mech = CRAM-MD5
23960 server_set_id = $auth1
23962 +------------+---------------+-------------+--------------+
23963 |server_realm|Use: cyrus_sasl|Type: string*|Default: unset|
23964 +------------+---------------+-------------+--------------+
23966 This specifies the SASL realm that the server claims to be in.
23968 +--------------+---------------+------------+---------------+
23969 |server_service|Use: cyrus_sasl|Type: string|Default: "smtp"|
23970 +--------------+---------------+------------+---------------+
23972 This is the SASL service that the server claims to implement.
23974 For straightforward cases, you do not need to set any of the authenticator's
23975 private options. All you need to do is to specify an appropriate mechanism as
23976 the public name. Thus, if you have a SASL library that supports CRAM-MD5 and
23977 PLAIN, you could have two authenticators as follows:
23980 driver = cyrus_sasl
23981 public_name = CRAM-MD5
23982 server_set_id = $auth1
23985 driver = cyrus_sasl
23986 public_name = PLAIN
23987 server_set_id = $auth2
23989 Cyrus SASL does implement the LOGIN authentication method, even though it is
23990 not a standard method. It is disabled by default in the source distribution,
23991 but it is present in many binary distributions.
23995 ===============================================================================
23996 37. THE DOVECOT AUTHENTICATOR
23998 This authenticator is an interface to the authentication facility of the
23999 Dovecot POP/IMAP server, which can support a number of authentication methods.
24001 Note that Dovecot must be configured to use auth-client not auth-userdb.
24003 If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
24004 to use the same mechanisms for SMTP authentication. This is a server
24005 authenticator only. There is only one option:
24007 +-------------+------------+------------+--------------+
24008 |server_socket|Use: dovecot|Type: string|Default: unset|
24009 +-------------+------------+------------+--------------+
24011 This option must specify the socket that is the interface to Dovecot
24012 authentication. The public_name option must specify an authentication mechanism
24013 that Dovecot is configured to support. You can have several authenticators for
24014 different mechanisms. For example:
24018 public_name = PLAIN
24019 server_socket = /var/run/dovecot/auth-client
24020 server_set_id = $auth1
24025 server_socket = /var/run/dovecot/auth-client
24026 server_set_id = $auth1
24028 If the SMTP connection is encrypted, or if $sender_host_address is equal to
24029 $received_ip_address (that is, the connection is local), the "secured" option
24030 is passed in the Dovecot authentication command. If, for a TLS connection, a
24031 client certificate has been verified, the "valid-client-cert" option is passed.
24032 When authentication succeeds, the identity of the user who authenticated is
24037 ===============================================================================
24038 38. THE GSASL AUTHENTICATOR
24040 The gsasl authenticator provides server integration for the GNU SASL library
24041 and the mechanisms it provides. This is new as of the 4.80 release and there
24042 are a few areas where the library does not let Exim smoothly scale to handle
24043 future authentication mechanisms, so no guarantee can be made that any
24044 particular new authentication mechanism will be supported without code changes
24047 +---------------------+----------+-------------+--------------+
24048 |server_channelbinding|Use: gsasl|Type: boolean|Default: false|
24049 +---------------------+----------+-------------+--------------+
24051 Some authentication mechanisms are able to use external context at both ends of
24052 the session to bind the authentication to that context, and fail the
24053 authentication process if that context differs. Specifically, some TLS
24054 ciphersuites can provide identifying information about the cryptographic
24057 This means that certificate identity and verification becomes a non-issue, as a
24058 man-in-the-middle attack will cause the correct client and server to see
24059 different identifiers and authentication will fail.
24061 This is currently only supported when using the GnuTLS library. This is only
24062 usable by mechanisms which support "channel binding"; at time of writing,
24063 that's the SCRAM family.
24065 This defaults off to ensure smooth upgrade across Exim releases, in case this
24066 option causes some clients to start failing. Some future release of Exim may
24067 switch the default to be true.
24069 +---------------+----------+-------------+------------------+
24070 |server_hostname|Use: gsasl|Type: string*|Default: see below|
24071 +---------------+----------+-------------+------------------+
24073 This option selects the hostname that is used when communicating with the
24074 library. The default value is "$primary_hostname". Some mechanisms will use
24077 +-----------+----------+------------+------------------+
24078 |server_mech|Use: gsasl|Type: string|Default: see below|
24079 +-----------+----------+------------+------------------+
24081 This option selects the authentication mechanism this driver should use. The
24082 default is the value of the generic public_name option. This option allows you
24083 to use a different underlying mechanism from the advertised name. For example:
24087 public_name = X-ANYTHING
24088 server_mech = CRAM-MD5
24089 server_set_id = $auth1
24091 +---------------+----------+-------------+--------------+
24092 |server_password|Use: gsasl|Type: string*|Default: unset|
24093 +---------------+----------+-------------+--------------+
24095 Various mechanisms need access to the cleartext password on the server, so that
24096 proof-of-possession can be demonstrated on the wire, without sending the
24099 The data available for lookup varies per mechanism. In all cases, $auth1 is set
24100 to the authentication id. The $auth2 variable will always be the authorization
24101 id (authz) if available, else the empty string. The $auth3 variable will always
24102 be the realm if available, else the empty string.
24104 A forced failure will cause authentication to defer.
24106 If using this option, it may make sense to set the server_condition option to
24109 +------------+----------+-------------+--------------+
24110 |server_realm|Use: gsasl|Type: string*|Default: unset|
24111 +------------+----------+-------------+--------------+
24113 This specifies the SASL realm that the server claims to be in. Some mechanisms
24114 will use this data.
24116 +-----------------+----------+-------------+--------------+
24117 |server_scram_iter|Use: gsasl|Type: string*|Default: unset|
24118 +-----------------+----------+-------------+--------------+
24120 This option provides data for the SCRAM family of mechanisms. $auth1 is not
24121 available at evaluation time. (This may change, as we receive feedback on use)
24123 +-----------------+----------+-------------+--------------+
24124 |server_scram_salt|Use: gsasl|Type: string*|Default: unset|
24125 +-----------------+----------+-------------+--------------+
24127 This option provides data for the SCRAM family of mechanisms. $auth1 is not
24128 available at evaluation time. (This may change, as we receive feedback on use)
24130 +--------------+----------+------------+---------------+
24131 |server_service|Use: gsasl|Type: string|Default: "smtp"|
24132 +--------------+----------+------------+---------------+
24134 This is the SASL service that the server claims to implement. Some mechanisms
24135 will use this data.
24138 38.1 gsasl auth variables
24139 -------------------------
24141 These may be set when evaluating specific options, as detailed above. They will
24142 also be set when evaluating server_condition.
24144 Unless otherwise stated below, the gsasl integration will use the following
24145 meanings for these variables:
24147 * $auth1: the authentication id
24149 * $auth2: the authorization id
24151 * $auth3: the realm
24153 On a per-mechanism basis:
24155 * EXTERNAL: only $auth1 is set, to the possibly empty authorization id; the
24156 server_condition option must be present.
24158 * ANONYMOUS: only $auth1 is set, to the possibly empty anonymous token; the
24159 server_condition option must be present.
24161 * GSSAPI: $auth1 will be set to the GSSAPI Display Name; $auth2 will be set
24162 to the authorization id, the server_condition option must be present.
24164 An anonymous token is something passed along as an unauthenticated identifier;
24165 this is analogous to FTP anonymous authentication passing an email address, or
24166 software-identifier@, as the "password".
24168 An example showing the password having the realm specified in the callback and
24169 demonstrating a Cyrus SASL to GSASL migration approach is:
24171 gsasl_cyrusless_crammd5:
24173 public_name = CRAM-MD5
24174 server_realm = imap.example.org
24175 server_password = ${lookup{$auth1:$auth3:userPassword}\
24176 dbmjz{/etc/sasldb2}{$value}fail}
24177 server_set_id = ${quote:$auth1}
24178 server_condition = yes
24182 ===============================================================================
24183 39. THE HEIMDAL_GSSAPI AUTHENTICATOR
24185 The heimdal_gssapi authenticator provides server integration for the Heimdal
24186 GSSAPI/Kerberos library, permitting Exim to set a keytab pathname reliably.
24188 +---------------+-------------------+-------------+------------------+
24189 |server_hostname|Use: heimdal_gssapi|Type: string*|Default: see below|
24190 +---------------+-------------------+-------------+------------------+
24192 This option selects the hostname that is used, with server_service, for
24193 constructing the GSS server name, as a GSS_C_NT_HOSTBASED_SERVICE identifier.
24194 The default value is "$primary_hostname".
24196 +-------------+-------------------+-------------+--------------+
24197 |server_keytab|Use: heimdal_gssapi|Type: string*|Default: unset|
24198 +-------------+-------------------+-------------+--------------+
24200 If set, then Heimdal will not use the system default keytab (typically /etc/
24201 krb5.keytab) but instead the pathname given in this option. The value should be
24202 a pathname, with no "file:" prefix.
24204 +--------------+-------------------+-------------+-------------+
24205 |server_service|Use: heimdal_gssapi|Type: string*|Default: smtp|
24206 +--------------+-------------------+-------------+-------------+
24208 This option specifies the service identifier used, in conjunction with
24209 server_hostname, for building the identifer for finding credentials from the
24213 39.1 heimdal_gssapi auth variables
24214 ----------------------------------
24216 Beware that these variables will typically include a realm, thus will appear to
24217 be roughly like an email address already. The authzid in $auth2 is not
24218 verified, so a malicious client can set it to anything.
24220 The $auth1 field should be safely trustable as a value from the Key
24221 Distribution Center. Note that these are not quite email addresses. Each
24222 identifier is for a role, and so the left-hand-side may include a role suffix.
24223 For instance, "joe/admin@EXAMPLE.ORG".
24225 * $auth1: the authentication id, set to the GSS Display Name.
24227 * $auth2: the authorization id, sent within SASL encapsulation after
24228 authentication. If that was empty, this will also be set to the GSS Display
24233 ===============================================================================
24234 40. THE SPA AUTHENTICATOR
24236 The spa authenticator provides client support for Microsoft's Secure Password
24237 Authentication mechanism, which is also sometimes known as NTLM (NT LanMan).
24238 The code for client side of this authenticator was contributed by Marc
24239 Prud'hommeaux, and much of it is taken from the Samba project (http://
24240 www.samba.org). The code for the server side was subsequently contributed by
24241 Tom Kistner. The mechanism works as follows:
24243 * After the AUTH command has been accepted, the client sends an SPA
24244 authentication request based on the user name and optional domain.
24246 * The server sends back a challenge.
24248 * The client builds a challenge response which makes use of the user's
24249 password and sends it to the server, which then accepts or rejects it.
24251 Encryption is used to protect the password in transit.
24254 40.1 Using spa as a server
24255 --------------------------
24257 The spa authenticator has just one server option:
24259 +---------------+--------+-------------+--------------+
24260 |server_password|Use: spa|Type: string*|Default: unset|
24261 +---------------+--------+-------------+--------------+
24263 This option is expanded, and the result must be the cleartext password for the
24264 authenticating user, whose name is at this point in $auth1. For compatibility
24265 with previous releases of Exim, the user name is also placed in $1. However,
24266 the use of this variable for this purpose is now deprecated, as it can lead to
24267 confusion in string expansions that also use numeric variables for other
24268 things. For example:
24273 server_password = \
24274 ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail}
24276 If the expansion is forced to fail, authentication fails. Any other expansion
24277 failure causes a temporary error code to be returned.
24280 40.2 Using spa as a client
24281 --------------------------
24283 The spa authenticator has the following client options:
24285 +-------------+--------+-------------+--------------+
24286 |client_domain|Use: spa|Type: string*|Default: unset|
24287 +-------------+--------+-------------+--------------+
24289 This option specifies an optional domain for the authentication.
24291 +---------------+--------+-------------+--------------+
24292 |client_password|Use: spa|Type: string*|Default: unset|
24293 +---------------+--------+-------------+--------------+
24295 This option specifies the user's password, and must be set.
24297 +---------------+--------+-------------+--------------+
24298 |client_username|Use: spa|Type: string*|Default: unset|
24299 +---------------+--------+-------------+--------------+
24301 This option specifies the user name, and must be set. Here is an example of a
24302 configuration of this authenticator for use with the mail servers at msn.com:
24307 client_username = msn/msn_username
24308 client_password = msn_plaintext_password
24309 client_domain = DOMAIN_OR_UNSET
24313 ===============================================================================
24314 41. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL
24316 Support for TLS (Transport Layer Security), formerly known as SSL (Secure
24317 Sockets Layer), is implemented by making use of the OpenSSL library or the
24318 GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no
24319 cryptographic code in the Exim distribution itself for implementing TLS. In
24320 order to use this feature you must install OpenSSL or GnuTLS, and then build a
24321 version of Exim that includes TLS support (see section 4.7). You also need to
24322 understand the basic concepts of encryption at a managerial level, and in
24323 particular, the way that public keys, private keys, and certificates are used.
24325 RFC 3207 defines how SMTP connections can make use of encryption. Once a
24326 connection is established, the client issues a STARTTLS command. If the server
24327 accepts this, the client and the server negotiate an encryption mechanism. If
24328 the negotiation succeeds, the data that subsequently passes between them is
24331 Exim's ACLs can detect whether the current SMTP session is encrypted or not,
24332 and if so, what cipher suite is in use, whether the client supplied a
24333 certificate, and whether or not that certificate was verified. This makes it
24334 possible for an Exim server to deny or accept certain commands based on the
24337 Warning: Certain types of firewall and certain anti-virus products can disrupt
24338 TLS connections. You need to turn off SMTP scanning for these products in order
24339 to get TLS to work.
24342 41.1 Support for the legacy "ssmtp" (aka "smtps") protocol
24343 ----------------------------------------------------------
24345 Early implementations of encrypted SMTP used a different TCP port from normal
24346 SMTP, and expected an encryption negotiation to start immediately, instead of
24347 waiting for a STARTTLS command from the client using the standard SMTP port.
24348 The protocol was called "ssmtp" or "smtps", and port 465 was allocated for this
24351 This approach was abandoned when encrypted SMTP was standardized, but there are
24352 still some legacy clients that use it. Exim supports these clients by means of
24353 the tls_on_connect_ports global option. Its value must be a list of port
24354 numbers; the most common use is expected to be:
24356 tls_on_connect_ports = 465
24358 The port numbers specified by this option apply to all SMTP connections, both
24359 via the daemon and via inetd. You still need to specify all the ports that the
24360 daemon uses (by setting daemon_smtp_ports or local_interfaces or the -oX
24361 command line option) because tls_on_connect_ports does not add an extra port -
24362 rather, it specifies different behaviour on a port that is defined elsewhere.
24364 There is also a -tls-on-connect command line option. This overrides
24365 tls_on_connect_ports; it forces the legacy behaviour for all ports.
24368 41.2 OpenSSL vs GnuTLS
24369 ----------------------
24371 The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS
24372 followed later, when the first versions of GnuTLS were released. To build Exim
24373 to use GnuTLS, you need to set
24377 in Local/Makefile, in addition to
24381 You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the include
24382 files and libraries for GnuTLS can be found.
24384 There are some differences in usage when using GnuTLS instead of OpenSSL:
24386 * The tls_verify_certificates option must contain the name of a file, not the
24387 name of a directory (for OpenSSL it can be either).
24389 * The default value for tls_dhparam differs for historical reasons.
24391 * Distinguished Name (DN) strings reported by the OpenSSL library use a slash
24392 for separating fields; GnuTLS uses commas, in accordance with RFC 2253.
24393 This affects the value of the $tls_in_peerdn and $tls_out_peerdn variables.
24395 * OpenSSL identifies cipher suites using hyphens as separators, for example:
24396 DES-CBC3-SHA. GnuTLS historically used underscores, for example:
24397 RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present
24398 in a cipher list. To make life simpler, Exim changes underscores to hyphens
24399 for OpenSSL and passes the string unchanged to GnuTLS (expecting the
24400 library to handle its own older variants) when processing lists of cipher
24401 suites in the tls_require_ciphers options (the global option and the smtp
24404 * The tls_require_ciphers options operate differently, as described in the
24405 sections 41.4 and 41.5.
24407 * The tls_dh_min_bits SMTP transport option is only honoured by GnuTLS. When
24408 using OpenSSL, this option is ignored. (If an API is found to let OpenSSL
24409 be configured in this way, let the Exim Maintainers know and we'll likely
24412 * Some other recently added features may only be available in one or the
24413 other. This should be documented with the feature. If the documentation
24414 does not explicitly state that the feature is infeasible in the other TLS
24415 implementation, then patches are welcome.
24418 41.3 GnuTLS parameter computation
24419 ---------------------------------
24421 This section only applies if tls_dhparam is set to "historic" or to an explicit
24422 path; if the latter, then the text about generation still applies, but not the
24423 chosen filename. By default, as of Exim 4.80 a hard-coded D-H prime is used.
24424 See the documentation of tls_dhparam for more information.
24426 GnuTLS uses D-H parameters that may take a substantial amount of time to
24427 compute. It is unreasonable to re-compute them for every TLS session.
24428 Therefore, Exim keeps this data in a file in its spool directory, called
24429 gnutls-params-NNNN for some value of NNNN, corresponding to the number of bits
24430 requested. The file is owned by the Exim user and is readable only by its
24431 owner. Every Exim process that start up GnuTLS reads the D-H parameters from
24432 this file. If the file does not exist, the first Exim process that needs it
24433 computes the data and writes it to a temporary file which is renamed once it is
24434 complete. It does not matter if several Exim processes do this simultaneously
24435 (apart from wasting a few resources). Once a file is in place, new Exim
24436 processes immediately start using it.
24438 For maximum security, the parameters that are stored in this file should be
24439 recalculated periodically, the frequency depending on your paranoia level. If
24440 you are avoiding using the fixed D-H primes published in RFCs, then you are
24441 concerned about some advanced attacks and will wish to do this; if you do not
24442 regenerate then you might as well stick to the standard primes.
24444 Arranging this is easy in principle; just delete the file when you want new
24445 values to be computed. However, there may be a problem. The calculation of new
24446 parameters needs random numbers, and these are obtained from /dev/random. If
24447 the system is not very active, /dev/random may delay returning data until
24448 enough randomness (entropy) is available. This may cause Exim to hang for a
24449 substantial amount of time, causing timeouts on incoming connections.
24451 The solution is to generate the parameters externally to Exim. They are stored
24452 in gnutls-params-N in PEM format, which means that they can be generated
24453 externally using the certtool command that is part of GnuTLS.
24455 To replace the parameters with new ones, instead of deleting the file and
24456 letting Exim re-create it, you can generate new parameters using certtool and,
24457 when this has been done, replace Exim's cache file by renaming. The relevant
24458 commands are something like this:
24461 [ look for file; assume gnutls-params-2236 is the most recent ]
24464 # chown exim:exim new-params
24465 # chmod 0600 new-params
24466 # certtool --generate-dh-params --bits 2236 >>new-params
24467 # openssl dhparam -noout -text -in new-params | head
24468 [ check the first line, make sure it's not more than 2236;
24469 if it is, then go back to the start ("rm") and repeat
24470 until the size generated is at most the size requested ]
24471 # chmod 0400 new-params
24472 # mv new-params gnutls-params-2236
24474 If Exim never has to generate the parameters itself, the possibility of
24475 stalling is removed.
24477 The filename changed in Exim 4.80, to gain the -bits suffix. The value which
24478 Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS,
24479 the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is a
24480 way for Exim to ask for the "normal" number of bits for D-H public-key usage,
24481 and Exim does so. This attempt to remove Exim from TLS policy decisions failed,
24482 as GnuTLS 2.12 returns a value higher than the current hard-coded limit of the
24483 NSS library. Thus Exim gains the tls_dh_max_bits global option, which applies
24484 to all D-H usage, client or server. If the value returned by GnuTLS is greater
24485 than tls_dh_max_bits then the value will be clamped down to tls_dh_max_bits.
24486 The default value has been set at the current NSS limit, which is still much
24487 higher than Exim historically used.
24489 The filename and bits used will change as the GnuTLS maintainers change the
24490 value for their parameter "GNUTLS_SEC_PARAM_NORMAL", as clamped by
24491 tls_dh_max_bits. At the time of writing (mid 2012), GnuTLS 2.12 recommends 2432
24492 bits, while NSS is limited to 2236 bits.
24494 In fact, the requested value will be *lower* than tls_dh_max_bits, to increase
24495 the chance of the generated prime actually being within acceptable bounds, as
24496 GnuTLS has been observed to overshoot. Note the check step in the procedure
24497 above. There is no sane procedure available to Exim to double-check the size of
24498 the generated prime, so it might still be too large.
24501 41.4 Requiring specific ciphers in OpenSSL
24502 ------------------------------------------
24504 There is a function in the OpenSSL library that can be passed a list of cipher
24505 suites before the cipher negotiation takes place. This specifies which ciphers
24506 are acceptable. The list is colon separated and may contain names like
24507 DES-CBC3-SHA. Exim passes the expanded value of tls_require_ciphers directly to
24508 this function call. Many systems will install the OpenSSL manual-pages, so you
24509 may have ciphers(1) available to you. The following quotation from the OpenSSL
24510 documentation specifies what forms of item are allowed in the cipher string:
24512 * It can consist of a single cipher suite such as RC4-SHA.
24514 * It can represent a list of cipher suites containing a certain algorithm, or
24515 cipher suites of a certain type. For example SHA1 represents all ciphers
24516 suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3
24519 * Lists of cipher suites can be combined in a single cipher string using the
24520 + character. This is used as a logical and operation. For example SHA1+DES
24521 represents all cipher suites containing the SHA1 and the DES algorithms.
24523 Each cipher string can be optionally preceded by one of the characters "!", "-"
24526 * If "!" is used, the ciphers are permanently deleted from the list. The
24527 ciphers deleted can never reappear in the list even if they are explicitly
24530 * If "-" is used, the ciphers are deleted from the list, but some or all of
24531 the ciphers can be added again by later options.
24533 * If "+" is used, the ciphers are moved to the end of the list. This option
24534 does not add any new ciphers; it just moves matching existing ones.
24536 If none of these characters is present, the string is interpreted as a list of
24537 ciphers to be appended to the current preference list. If the list includes any
24538 ciphers already present they will be ignored: that is, they will not be moved
24539 to the end of the list.
24541 The OpenSSL ciphers(1) command may be used to test the results of a given
24544 # note single-quotes to get ! past any shell history expansion
24545 $ openssl ciphers 'HIGH:!MD5:!SHA1'
24547 This example will let the library defaults be permitted on the MX port, where
24548 there's probably no identity verification anyway, but ups the ante on the
24549 submission ports where the administrator might have some influence on the
24550 choice of clients used:
24552 # OpenSSL variant; see man ciphers(1)
24553 tls_require_ciphers = ${if =={$received_port}{25}\
24558 41.5 Requiring specific ciphers or other parameters in GnuTLS
24559 -------------------------------------------------------------
24561 The GnuTLS library allows the caller to provide a "priority string", documented
24562 as part of the gnutls_priority_init function. This is very similar to the
24563 ciphersuite specification in OpenSSL.
24565 The tls_require_ciphers option is treated as the GnuTLS priority string.
24567 The tls_require_ciphers option is available both as an global option,
24568 controlling how Exim behaves as a server, and also as an option of the smtp
24569 transport, controlling how Exim behaves as a client. In both cases the value is
24570 string expanded. The resulting string is not an Exim list and the string is
24571 given to the GnuTLS library, so that Exim does not need to be aware of future
24572 feature enhancements of GnuTLS.
24574 Documentation of the strings accepted may be found in the GnuTLS manual, under
24575 "Priority strings". This is online as http://www.gnutls.org/manual/html_node/
24576 Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be
24577 newer than the version installed on your system. If you are using GnuTLS 3,
24578 then the example code on that site can be used to test a given string.
24580 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
24581 additional options, "gnutls_require_kx", "gnutls_require_mac" and "
24582 gnutls_require_protocols". tls_require_ciphers was an Exim list.
24584 This example will let the library defaults be permitted on the MX port, where
24585 there's probably no identity verification anyway, and lowers security further
24586 by increasing compatibility; but this ups the ante on the submission ports
24587 where the administrator might have some influence on the choice of clients
24591 tls_require_ciphers = ${if =={$received_port}{25}\
24596 41.6 Configuring an Exim server to use TLS
24597 ------------------------------------------
24599 When Exim has been built with TLS support, it advertises the availability of
24600 the STARTTLS command to client hosts that match tls_advertise_hosts, but not to
24601 any others. The default value of this option is unset, which means that
24602 STARTTLS is not advertised at all. This default is chosen because you need to
24603 set some other options in order to make TLS available, and also it is sensible
24604 for systems that want to use TLS only as a client.
24606 If a client issues a STARTTLS command and there is some configuration problem
24607 in the server, the command is rejected with a 454 error. If the client persists
24608 in trying to issue SMTP commands, all except QUIT are rejected with the error
24610 554 Security failure
24612 If a STARTTLS command is issued within an existing TLS session, it is rejected
24613 with a 554 error code.
24615 To enable TLS operations on a server, you must set tls_advertise_hosts to match
24616 some hosts. You can, of course, set it to * to match all hosts. However, this
24617 is not all you need to do. TLS sessions to a server won't work without some
24618 further configuration at the server end.
24620 It is rumoured that all existing clients that support TLS/SSL use RSA
24621 encryption. To make this work you need to set, in the server,
24623 tls_certificate = /some/file/name
24624 tls_privatekey = /some/file/name
24626 These options are, in fact, expanded strings, so you can make them depend on
24627 the identity of the client that is connected if you wish. The first file
24628 contains the server's X509 certificate, and the second contains the private key
24629 that goes with it. These files need to be readable by the Exim user, and must
24630 always be given as full path names. They can be the same file if both the
24631 certificate and the key are contained within it. If tls_privatekey is not set,
24632 or if its expansion is forced to fail or results in an empty string, this is
24633 assumed to be the case. The certificate file may also contain intermediate
24634 certificates that need to be sent to the client to enable it to authenticate
24635 the server's certificate.
24637 If you do not understand about certificates and keys, please try to find a
24638 source of this background information, which is not Exim-specific. (There are a
24639 few comments below in section 41.12.)
24641 Note: These options do not apply when Exim is operating as a client - they
24642 apply only in the case of a server. If you need to use a certificate in an Exim
24643 client, you must set the options of the same names in an smtp transport.
24645 With just these options, an Exim server will be able to use TLS. It does not
24646 require the client to have a certificate (but see below for how to insist on
24647 this). There is one other option that may be needed in other situations. If
24649 tls_dhparam = /some/file/name
24651 is set, the SSL library is initialized for the use of Diffie-Hellman ciphers
24652 with the parameters contained in the file. Set this to "none" to disable use of
24653 DH entirely, by making no prime available:
24657 This may also be set to a string identifying a standard prime to be used for
24658 DH; if it is set to "default" or, for OpenSSL, is unset, then the prime used is
24659 "ike23". There are a few standard primes available, see the documentation for
24660 tls_dhparam for the complete list.
24666 for a way of generating file data.
24668 The strings supplied for these three options are expanded every time a client
24669 host connects. It is therefore possible to use different certificates and keys
24670 for different hosts, if you so wish, by making use of the client's IP address
24671 in $sender_host_address to control the expansion. If a string expansion is
24672 forced to fail, Exim behaves as if the option is not set.
24674 The variable $tls_in_cipher is set to the cipher suite that was negotiated for
24675 an incoming TLS connection. It is included in the Received: header of an
24676 incoming message (by default - you can, of course, change this), and it is also
24677 included in the log line that records a message's arrival, keyed by "X=",
24678 unless the tls_cipher log selector is turned off. The encrypted condition can
24679 be used to test for specific cipher suites in ACLs.
24681 Once TLS has been established, the ACLs that run for subsequent SMTP commands
24682 can check the name of the cipher suite and vary their actions accordingly. The
24683 cipher suite names vary, depending on which TLS library is being used. For
24684 example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other
24685 contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS
24686 documentation for more details.
24688 For outgoing SMTP deliveries, $tls_out_cipher is used and logged (again
24689 depending on the tls_cipher log selector).
24692 41.7 Requesting and verifying client certificates
24693 -------------------------------------------------
24695 If you want an Exim server to request a certificate when negotiating a TLS
24696 session with a client, you must set either tls_verify_hosts or
24697 tls_try_verify_hosts. You can, of course, set either of them to * to apply to
24698 all TLS connections. For any host that matches one of these options, Exim
24699 requests a certificate as part of the setup of the TLS session. The contents of
24700 the certificate are verified by comparing it with a list of expected
24701 certificates. These must be available in a file or, for OpenSSL only (not
24702 GnuTLS), a directory, identified by tls_verify_certificates.
24704 A file can contain multiple certificates, concatenated end to end. If a
24705 directory is used (OpenSSL only), each certificate must be in a separate file,
24706 with a name (or a symbolic link) of the form <hash>.0, where <hash> is a hash
24707 value constructed from the certificate. You can compute the relevant hash by
24708 running the command
24710 openssl x509 -hash -noout -in /cert/file
24712 where /cert/file contains a single certificate.
24714 The difference between tls_verify_hosts and tls_try_verify_hosts is what
24715 happens if the client does not supply a certificate, or if the certificate does
24716 not match any of the certificates in the collection named by
24717 tls_verify_certificates. If the client matches tls_verify_hosts, the attempt to
24718 set up a TLS session is aborted, and the incoming connection is dropped. If the
24719 client matches tls_try_verify_hosts, the (encrypted) SMTP session continues.
24720 ACLs that run for subsequent SMTP commands can detect the fact that no
24721 certificate was verified, and vary their actions accordingly. For example, you
24722 can insist on a certificate before accepting a message for relaying, but not
24723 when the message is destined for local delivery.
24725 When a client supplies a certificate (whether it verifies or not), the value of
24726 the Distinguished Name of the certificate is made available in the variable
24727 $tls_in_peerdn during subsequent processing of the message.
24729 Because it is often a long text string, it is not included in the log line or
24730 Received: header by default. You can arrange for it to be logged, keyed by "DN=
24731 ", by setting the tls_peerdn log selector, and you can use received_header_text
24732 to change the Received: header. When no certificate is supplied, $tls_in_peerdn
24736 41.8 Revoked certificates
24737 -------------------------
24739 Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
24740 certificates are revoked. If you have such a list, you can pass it to an Exim
24741 server using the global option called tls_crl and to an Exim client using an
24742 identically named option for the smtp transport. In each case, the value of the
24743 option is expanded and must then be the name of a file that contains a CRL in
24744 PEM format. The downside is that clients have to periodically re-download a
24745 potentially huge file from every certificate authority the know of.
24747 The way with most moving parts at query time is Online Certificate Status
24748 Protocol (OCSP), where the client verifies the certificate against an OCSP
24749 server run by the CA. This lets the CA track all usage of the certs. It
24750 requires running software with access to the private key of the CA, to sign the
24751 responses to the OCSP queries. OCSP is based on HTTP and can be proxied
24754 The only widespread OCSP server implementation (known to this writer) comes as
24755 part of OpenSSL and aborts on an invalid request, such as connecting to the
24756 port and then disconnecting. This requires re-entering the passphrase each time
24757 some random client does this.
24759 The third way is OCSP Stapling; in this, the server using a certificate issued
24760 by the CA periodically requests an OCSP proof of validity from the OCSP server,
24761 then serves it up inline as part of the TLS negotiation. This approach adds no
24762 extra round trips, does not let the CA track users, scales well with number of
24763 certs issued by the CA and is resilient to temporary OCSP server failures, as
24764 long as the server starts retrying to fetch an OCSP proof some time before its
24765 current proof expires. The downside is that it requires server support.
24767 Unless Exim is built with the support disabled, or with GnuTLS earlier than
24768 version 3.1.3, support for OCSP stapling is included.
24770 There is a global option called tls_ocsp_file. The file specified therein is
24771 expected to be in DER format, and contain an OCSP proof. Exim will serve it as
24772 part of the TLS handshake. This option will be re-expanded for SNI, if the
24773 tls_certificate option contains "tls_in_sni", as per other TLS options.
24775 Exim does not at this time implement any support for fetching a new OCSP proof.
24776 The burden is on the administrator to handle this, outside of Exim. The file
24777 specified should be replaced atomically, so that the contents are always valid.
24778 Exim will expand the tls_ocsp_file option on each connection, so a new file
24779 will be handled transparently on the next connection.
24781 When built with OpenSSL Exim will check for a valid next update timestamp in
24782 the OCSP proof; if not present, or if the proof has expired, it will be
24785 For the client to be able to verify the stapled OCSP the server must also
24786 supply, in its stapled information, any intermediate certificates for the chain
24787 leading to the OCSP proof from the signer of the server certificate. There may
24788 be zero or one such. These intermediate certificates should be added to the
24789 server OCSP stapling file named by tls_ocsp_file.
24791 Note that the proof only covers the terminal server certificate, not any of the
24792 chain from CA to it.
24794 There is no current way to staple a proof for a client certificate.
24796 A helper script "ocsp_fetch.pl" for fetching a proof from a CA
24797 OCSP server is supplied. The server URL may be included in the
24798 server certificate, if the CA is helpful.
24800 One failure mode seen was the OCSP Signer cert expiring before the end
24801 of validity of the OCSP proof. The checking done by Exim/OpenSSL
24802 noted this as invalid overall, but the re-fetch script did not.
24805 41.9 Configuring an Exim client to use TLS
24806 ------------------------------------------
24808 The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries
24809 as well as to incoming, the latter one causing logging of the server
24810 certificate's DN. The remaining client configuration for TLS is all within the
24813 It is not necessary to set any options to have TLS work in the smtp transport.
24814 If Exim is built with TLS support, and TLS is advertised by a server, the smtp
24815 transport always tries to start a TLS session. However, this can be prevented
24816 by setting hosts_avoid_tls (an option of the transport) to a list of server
24817 hosts for which TLS should not be used.
24819 If you do not want Exim to attempt to send messages unencrypted when an attempt
24820 to set up an encrypted connection fails in any way, you can set
24821 hosts_require_tls to a list of hosts for which encryption is mandatory. For
24822 those hosts, delivery is always deferred if an encrypted connection cannot be
24823 set up. If there are any other hosts for the address, they are tried in the
24826 When the server host is not in hosts_require_tls, Exim may try to deliver the
24827 message unencrypted. It always does this if the response to STARTTLS is a 5xx
24828 code. For a temporary error code, or for a failure to negotiate a TLS session
24829 after a success response code, what happens is controlled by the
24830 tls_tempfail_tryclear option of the smtp transport. If it is false, delivery to
24831 this host is deferred, and other hosts (if available) are tried. If it is true,
24832 Exim attempts to deliver unencrypted after a 4xx response to STARTTLS, and if
24833 STARTTLS is accepted, but the subsequent TLS negotiation fails, Exim closes the
24834 current connection (because it is in an unknown state), opens a new one to the
24835 same host, and then tries the delivery unencrypted.
24837 The tls_certificate and tls_privatekey options of the smtp transport provide
24838 the client with a certificate, which is passed to the server if it requests it.
24839 If the server is Exim, it will request a certificate only if tls_verify_hosts
24840 or tls_try_verify_hosts matches the client.
24842 If the tls_verify_certificates option is set on the smtp transport, it must
24843 name a file or, for OpenSSL only (not GnuTLS), a directory, that contains a
24844 collection of expected server certificates. The client verifies the server's
24845 certificate against this collection, taking into account any revoked
24846 certificates that are in the list defined by tls_crl. Failure to verify fails
24847 the TLS connection unless either of the tls_verify_hosts or
24848 tls_try_verify_hosts options are set.
24850 The tls_verify_hosts and tls_try_verify_hosts options restrict certificate
24851 verification to the listed servers. Verification either must or need not
24852 succeed respectively.
24854 The smtp transport has two OCSP-related options: hosts_require_ocsp; a
24855 host-list for which a Certificate Status is requested and required for the
24856 connection to proceed. The default value is empty. hosts_request_ocsp; a
24857 host-list for which (additionally) a Certificate Status is requested (but not
24858 necessarily verified). The default value is "*" meaning that requests are made
24859 unless configured otherwise.
24861 The host(s) should also be in hosts_require_tls, and tls_verify_certificates
24862 configured for the transport, for OCSP to be relevant.
24864 If tls_require_ciphers is set on the smtp transport, it must contain a list of
24865 permitted cipher suites. If either of these checks fails, delivery to the
24866 current host is abandoned, and the smtp transport tries to deliver to
24867 alternative hosts, if any.
24869 Note: These options must be set in the smtp transport for Exim to use TLS when
24870 it is operating as a client. Exim does not assume that a server certificate
24871 (set by the global options of the same name) should also be used when operating
24874 All the TLS options in the smtp transport are expanded before use, with $host
24875 and $host_address containing the name and address of the server to which the
24876 client is connected. Forced failure of an expansion causes Exim to behave as if
24877 the relevant option were unset.
24879 Before an SMTP connection is established, the $tls_out_bits, $tls_out_cipher,
24880 $tls_out_peerdn and $tls_out_sni variables are emptied. (Until the first
24881 connection, they contain the values that were set when the message was
24882 received.) If STARTTLS is subsequently successfully obeyed, these variables are
24883 set to the relevant values for the outgoing connection.
24886 41.10 Use of TLS Server Name Indication
24887 ---------------------------------------
24889 With TLS1.0 or above, there is an extension mechanism by which extra
24890 information can be included at various points in the protocol. One of these
24891 extensions, documented in RFC 6066 (and before that RFC 4366) is "Server Name
24892 Indication", commonly "SNI". This extension is sent by the client in the
24893 initial handshake, so that the server can examine the servername within and
24894 possibly choose to use different certificates and keys (and more) for this
24897 This is analagous to HTTP's "Host:" header, and is the main mechanism by which
24898 HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address.
24900 With SMTP to MX, there are the same problems here as in choosing the identity
24901 against which to validate a certificate: you can't rely on insecure DNS to
24902 provide the identity which you then cryptographically verify. So this will be
24903 of limited use in that environment.
24905 With SMTP to Submission, there is a well-defined hostname which clients are
24906 connecting to and can validate certificates against. Thus clients can choose to
24907 include this information in the TLS negotiation. If this becomes wide-spread,
24908 then hosters can choose to present different certificates to different clients.
24909 Or even negotiate different cipher suites.
24911 The tls_sni option on an SMTP transport is an expanded string; the result, if
24912 not empty, will be sent on a TLS session as part of the handshake. There's
24913 nothing more to it. Choosing a sensible value not derived insecurely is the
24914 only point of caution. The $tls_out_sni variable will be set to this string for
24915 the lifetime of the client connection (including during authentication).
24917 Except during SMTP client sessions, if $tls_in_sni is set then it is a string
24918 received from a client. It can be logged with the log_selector item "+tls_sni".
24920 If the string "tls_in_sni" appears in the main section's tls_certificate option
24921 (prior to expansion) then the following options will be re-expanded during TLS
24922 session handshake, to permit alternative values to be chosen:
24930 * tls_verify_certificates
24932 * tls_verify_certificates
24934 Great care should be taken to deal with matters of case, various injection
24935 attacks in the string ("../" or SQL), and ensuring that a valid filename can
24936 always be referenced; it is important to remember that $tls_sni is arbitrary
24937 unverified data provided prior to authentication.
24939 The Exim developers are proceeding cautiously and so far no other TLS options
24942 When Exim is built againt OpenSSL, OpenSSL must have been built with support
24943 for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with
24944 enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see
24945 "-servername" in the output, then OpenSSL has support.
24947 When Exim is built against GnuTLS, SNI support is available as of GnuTLS
24948 0.5.10. (Its presence predates the current API which Exim uses, so if Exim
24949 built, then you have SNI support).
24952 41.11 Multiple messages on the same encrypted TCP/IP connection
24953 ---------------------------------------------------------------
24955 Exim sends multiple messages down the same TCP/IP connection by starting up an
24956 entirely new delivery process for each message, passing the socket from one
24957 process to the next. This implementation does not fit well with the use of TLS,
24958 because there is quite a lot of state information associated with a TLS
24959 connection, not just a socket identification. Passing all the state information
24960 to a new process is not feasible. Consequently, Exim shuts down an existing TLS
24961 session before passing the socket to a new process. The new process may then
24962 try to start a new TLS session, and if successful, may try to re-authenticate
24963 if AUTH is in use, before sending the next message.
24965 The RFC is not clear as to whether or not an SMTP session continues in clear
24966 after TLS has been shut down, or whether TLS may be restarted again later, as
24967 just described. However, if the server is Exim, this shutdown and
24968 reinitialization works. It is not known which (if any) other servers operate
24969 successfully if the client closes a TLS session and continues with unencrypted
24970 SMTP, but there are certainly some that do not work. For such servers, Exim
24971 should not pass the socket to another process, because the failure of the
24972 subsequent attempt to use it would cause Exim to record a temporary host error,
24973 and delay other deliveries to that host.
24975 To test for this case, Exim sends an EHLO command to the server after closing
24976 down the TLS session. If this fails in any way, the connection is closed
24977 instead of being passed to a new delivery process, but no retry information is
24980 There is also a manual override; you can set hosts_nopass_tls on the smtp
24981 transport to match those hosts for which Exim should not pass connections to
24982 new processes if TLS has been used.
24985 41.12 Certificates and all that
24986 -------------------------------
24988 In order to understand fully how TLS works, you need to know about
24989 certificates, certificate signing, and certificate authorities. This is not the
24990 place to give a tutorial, especially as I do not know very much about it
24991 myself. Some helpful introduction can be found in the FAQ for the SSL addition
24992 to Apache, currently at
24994 http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24
24996 Other parts of the modssl documentation are also helpful, and have links to
24997 further files. Eric Rescorla's book, SSL and TLS, published by Addison-Wesley
24998 (ISBN 0-201-61598-3), contains both introductory and more in-depth
24999 descriptions. Some sample programs taken from the book are available from
25001 http://www.rtfm.com/openssl-examples/
25004 41.13 Certificate chains
25005 ------------------------
25007 The file named by tls_certificate may contain more than one certificate. This
25008 is useful in the case where the certificate that is being sent is validated by
25009 an intermediate certificate which the other end does not have. Multiple
25010 certificates must be in the correct order in the file. First the host's
25011 certificate itself, then the first intermediate certificate to validate the
25012 issuer of the host certificate, then the next intermediate certificate to
25013 validate the issuer of the first intermediate certificate, and so on, until
25014 finally (optionally) the root certificate. The root certificate must already be
25015 trusted by the recipient for validation to succeed, of course, but if it's not
25016 preinstalled, sending the root certificate along with the rest makes it
25017 available for the user to install if the receiving end is a client MUA that can
25018 interact with a user.
25020 Note that certificates using MD5 are unlikely to work on today's Internet; even
25021 if your libraries allow loading them for use in Exim when acting as a server,
25022 increasingly clients will not accept such certificates. The error diagnostics
25023 in such a case can be frustratingly vague.
25026 41.14 Self-signed certificates
25027 ------------------------------
25029 You can create a self-signed certificate using the req command provided with
25030 OpenSSL, like this:
25032 openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \
25035 file1 and file2 can be the same file; the key and the certificate are delimited
25036 and so can be identified independently. The -days option specifies a period for
25037 which the certificate is valid. The -nodes option is important: if you do not
25038 set it, the key is encrypted with a passphrase that you are prompted for, and
25039 any use that is made of the key causes more prompting for the passphrase. This
25040 is not helpful if you are going to use this certificate and key in an MTA,
25041 where prompting is not possible.
25043 NB: we are now past the point where 9999 days takes us past the 32-bit Unix
25044 epoch. If your system uses unsigned time_t (most do) and is 32-bit, then the
25045 above command might produce a date in the past. Think carefully about the
25046 lifetime of the systems you're deploying, and either reduce the duration of the
25047 certificate or reconsider your platform deployment. (At time of writing,
25048 reducing the duration is the most likely choice, but the inexorable progression
25049 of time takes us steadily towards an era where this will not be a sensible
25052 A self-signed certificate made in this way is sufficient for testing, and may
25053 be adequate for all your requirements if you are mainly interested in
25054 encrypting transfers, and not in secure identification.
25056 However, many clients require that the certificate presented by the server be a
25057 user (also called "leaf" or "site") certificate, and not a self-signed
25058 certificate. In this situation, the self-signed certificate described above
25059 must be installed on the client host as a trusted root certification authority
25060 (CA), and the certificate used by Exim must be a user certificate signed with
25061 that self-signed certificate.
25063 For information on creating self-signed CA certificates and using them to sign
25064 user certificates, see the General implementation overview chapter of the
25065 Open-source PKI book, available online at http://ospkibook.sourceforge.net/.
25069 ===============================================================================
25070 42. ACCESS CONTROL LISTS
25072 Access Control Lists (ACLs) are defined in a separate section of the run time
25073 configuration file, headed by "begin acl". Each ACL definition starts with a
25074 name, terminated by a colon. Here is a complete ACL section that contains just
25075 one very small ACL:
25079 accept hosts = one.host.only
25081 You can have as many lists as you like in the ACL section, and the order in
25082 which they appear does not matter. The lists are self-terminating.
25084 The majority of ACLs are used to control Exim's behaviour when it receives
25085 certain SMTP commands. This applies both to incoming TCP/IP connections, and
25086 when a local process submits a message using SMTP by specifying the -bs option.
25087 The most common use is for controlling which recipients are accepted in
25088 incoming messages. In addition, you can define an ACL that is used to check
25089 local non-SMTP messages. The default configuration file contains an example of
25090 a realistic ACL for checking RCPT commands. This is discussed in chapter 7.
25096 The -bh command line option provides a way of testing your ACL configuration
25097 locally by running a fake SMTP session with which you interact. The host
25098 relay-test.mail-abuse.org provides a service for checking your relaying
25099 configuration (see section 42.53 for more details).
25102 42.2 Specifying when ACLs are used
25103 ----------------------------------
25105 In order to cause an ACL to be used, you have to name it in one of the relevant
25106 options in the main part of the configuration. These options are:
25108 acl_not_smtp ACL for non-SMTP messages
25109 acl_not_smtp_mime ACL for non-SMTP MIME parts
25110 acl_not_smtp_start ACL at start of non-SMTP message
25111 acl_smtp_auth ACL for AUTH
25112 acl_smtp_connect ACL for start of SMTP connection
25113 acl_smtp_data ACL after DATA is complete
25114 acl_smtp_data_prdr ACL for each recipient, after DATA is complete
25115 acl_smtp_etrn ACL for ETRN
25116 acl_smtp_expn ACL for EXPN
25117 acl_smtp_helo ACL for HELO or EHLO
25118 acl_smtp_mail ACL for MAIL
25119 acl_smtp_mailauth ACL for the AUTH parameter of MAIL
25120 acl_smtp_mime ACL for content-scanning MIME parts
25121 acl_smtp_notquit ACL for non-QUIT terminations
25122 acl_smtp_predata ACL at start of DATA command
25123 acl_smtp_quit ACL for QUIT
25124 acl_smtp_rcpt ACL for RCPT
25125 acl_smtp_starttls ACL for STARTTLS
25126 acl_smtp_vrfy ACL for VRFY
25128 For example, if you set
25130 acl_smtp_rcpt = small_acl
25132 the little ACL defined above is used whenever Exim receives a RCPT command in
25133 an SMTP dialogue. The majority of policy tests on incoming messages can be done
25134 when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to
25135 give up on the recipient address contained in the RCPT command, whereas
25136 rejection at other times may cause the client MTA to keep on trying to deliver
25137 the message. It is therefore recommended that you do as much testing as
25138 possible at RCPT time.
25141 42.3 The non-SMTP ACLs
25142 ----------------------
25144 The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
25145 apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not
25146 really SMTP.) Many of the ACL conditions (for example, host tests, and tests on
25147 the state of the SMTP connection such as encryption and authentication) are not
25148 relevant and are forbidden in these ACLs. However, the sender and recipients
25149 are known, so the senders and sender_domains conditions and the $sender_address
25150 and $recipients variables can be used. Variables such as $authenticated_sender
25151 are also available. You can specify added header lines in any of these ACLs.
25153 The acl_not_smtp_start ACL is run right at the start of receiving a non-SMTP
25154 message, before any of the message has been read. (This is the analogue of the
25155 acl_smtp_predata ACL for SMTP input.) In the case of batched SMTP input, it
25156 runs after the DATA command has been reached. The result of this ACL is
25157 ignored; it cannot be used to reject a message. If you really need to, you
25158 could set a value in an ACL variable here and reject based on that in the
25159 acl_not_smtp ACL. However, this ACL can be used to set controls, and in
25160 particular, it can be used to set
25162 control = suppress_local_fixups
25164 This cannot be used in the other non-SMTP ACLs because by the time they are
25165 run, it is too late.
25167 The acl_not_smtp_mime ACL is available only when Exim is compiled with the
25168 content-scanning extension. For details, see chapter 43.
25170 The acl_not_smtp ACL is run just before the local_scan() function. Any kind of
25171 rejection is treated as permanent, because there is no way of sending a
25172 temporary error for these kinds of message.
25175 42.4 The SMTP connect ACL
25176 -------------------------
25178 The ACL test specified by acl_smtp_connect happens at the start of an SMTP
25179 session, after the test specified by host_reject_connection (which is now an
25180 anomaly) and any TCP Wrappers testing (if configured). If the connection is
25181 accepted by an accept verb that has a message modifier, the contents of the
25182 message override the banner message that is otherwise specified by the
25183 smtp_banner option.
25186 42.5 The EHLO/HELO ACL
25187 ----------------------
25189 The ACL test specified by acl_smtp_helo happens when the client issues an EHLO
25190 or HELO command, after the tests specified by helo_accept_junk_hosts,
25191 helo_allow_chars, helo_verify_hosts, and helo_try_verify_hosts. Note that a
25192 client may issue more than one EHLO or HELO command in an SMTP session, and
25193 indeed is required to issue a new EHLO or HELO after successfully setting up
25194 encryption following a STARTTLS command.
25196 If the command is accepted by an accept verb that has a message modifier, the
25197 message may not contain more than one line (it will be truncated at the first
25198 newline and a panic logged if it does). Such a message cannot affect the EHLO
25199 options that are listed on the second and subsequent lines of an EHLO response.
25205 Two ACLs are associated with the DATA command, because it is two-stage command,
25206 with two responses being sent to the client. When the DATA command is received,
25207 the ACL defined by acl_smtp_predata is obeyed. This gives you control after all
25208 the RCPT commands, but before the message itself is received. It offers the
25209 opportunity to give a negative response to the DATA command before the data is
25210 transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this
25211 time, but any that are defined here are visible when the acl_smtp_data ACL is
25214 You cannot test the contents of the message, for example, to verify addresses
25215 in the headers, at RCPT time or when the DATA command is received. Such tests
25216 have to appear in the ACL that is run after the message itself has been
25217 received, before the final response to the DATA command is sent. This is the
25218 ACL specified by acl_smtp_data, which is the second ACL that is associated with
25221 For both of these ACLs, it is not possible to reject individual recipients. An
25222 error response rejects the entire message. Unfortunately, it is known that some
25223 MTAs do not treat hard (5xx) responses to the DATA command (either before or
25224 after the data) correctly - they keep the message on their queues and try again
25225 later, but that is their problem, though it does waste some of your resources.
25227 The acl_smtp_data ACL is run after the acl_smtp_data_prdr, the acl_smtp_dkim
25228 and the acl_smtp_mime ACLs.
25231 42.7 The SMTP DKIM ACL
25232 ----------------------
25234 The acl_smtp_dkim ACL is available only when Exim is compiled with DKIM support
25235 enabled (which is the default).
25237 The ACL test specified by acl_smtp_dkim happens after a message has been
25238 received, and is executed for each DKIM signature found in a message. If not
25239 otherwise specified, the default action is to accept.
25241 This ACL is evaluated before acl_smtp_mime and acl_smtp_data.
25243 For details on the operation of DKIM, see chapter 56.
25246 42.8 The SMTP MIME ACL
25247 ----------------------
25249 The acl_smtp_mime option is available only when Exim is compiled with the
25250 content-scanning extension. For details, see chapter 43.
25252 This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data.
25255 42.9 The SMTP PRDR ACL
25256 ----------------------
25258 The acl_smtp_data_prdr ACL is available only when Exim is compiled with PRDR
25259 support enabled (which is the default). It becomes active only when the PRDR
25260 feature is negotiated between client and server for a message, and more than
25261 one recipient has been accepted.
25263 The ACL test specfied by acl_smtp_data_prdr happens after a message has been
25264 recieved, and is executed for each recipient of the message. The test may
25265 accept or deny for inividual recipients. The acl_smtp_data will still be called
25266 after this ACL and can reject the message overall, even if this ACL has
25267 accepted it for some or all recipients.
25269 PRDR may be used to support per-user content filtering. Without it one must
25270 defer any recipient after the first that has a different content-filter
25271 configuration. With PRDR, the RCPT-time check for this can be disabled when the
25272 MAIL-time $smtp_command included "PRDR". Any required difference in behaviour
25273 of the main DATA-time ACL should however depend on the PRDR-time ACL having
25274 run, as Exim will avoid doing so in some situations (eg. single-recipient
25277 See also the prdr_enable global option and the hosts_try_prdr smtp transport
25280 This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. If the ACL
25281 is not defined, processing completes as if the feature was not requested by the
25288 The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL
25289 does not affect the response code to QUIT, which is always 221. Thus, the ACL
25290 does not in fact control any access. For this reason, the only verbs that are
25291 permitted are accept and warn.
25293 This ACL can be used for tasks such as custom logging at the end of an SMTP
25294 session. For example, you can use ACL variables in other ACLs to count
25295 messages, recipients, etc., and log the totals at QUIT time using one or more
25296 logwrite modifiers on a warn verb.
25298 Warning: Only the $acl_cx variables can be used for this, because the $acl_mx
25299 variables are reset at the end of each incoming message.
25301 You do not need to have a final accept, but if you do, you can use a message
25302 modifier to specify custom text that is sent as part of the 221 response to
25305 This ACL is run only for a "normal" QUIT. For certain kinds of disastrous
25306 failure (for example, failure to open a log file, or when Exim is bombing out
25307 because it has detected an unrecoverable error), all SMTP commands from the
25308 client are given temporary error responses until QUIT is received or the
25309 connection is closed. In these special cases, the QUIT ACL does not run.
25312 42.11 The not-QUIT ACL
25313 ----------------------
25315 The not-QUIT ACL, specified by acl_smtp_notquit, is run in most cases when an
25316 SMTP session ends without sending QUIT. However, when Exim itself is in bad
25317 trouble, such as being unable to write to its log files, this ACL is not run,
25318 because it might try to do things (such as write to log files) that make the
25319 situation even worse.
25321 Like the QUIT ACL, this ACL is provided to make it possible to do customized
25322 logging or to gather statistics, and its outcome is ignored. The delay modifier
25323 is forbidden in this ACL, and the only permitted verbs are accept and warn.
25325 When the not-QUIT ACL is running, the variable $smtp_notquit_reason is set to a
25326 string that indicates the reason for the termination of the SMTP connection.
25327 The possible values are:
25329 "acl-drop" Another ACL issued a drop command
25330 "bad-commands" Too many unknown or non-mail commands
25331 "command-timeout" Timeout while reading SMTP commands
25332 "connection-lost" The SMTP connection has been lost
25333 "data-timeout" Timeout while reading message data
25334 "local-scan-error" The local_scan() function crashed
25335 "local-scan-timeout" The local_scan() function timed out
25336 "signal-exit" SIGTERM or SIGINT
25337 "synchronization-error" SMTP synchronization error
25338 "tls-failed" TLS failed to start
25340 In most cases when an SMTP connection is closed without having received QUIT,
25341 Exim sends an SMTP response message before actually closing the connection.
25342 With the exception of the "acl-drop" case, the default message can be
25343 overridden by the message modifier in the not-QUIT ACL. In the case of a drop
25344 verb in another ACL, it is the message from the other ACL that is used.
25347 42.12 Finding an ACL to use
25348 ---------------------------
25350 The value of an acl_smtp_xxx option is expanded before use, so you can use
25351 different ACLs in different circumstances. For example,
25353 acl_smtp_rcpt = ${if ={25}{$interface_port} \
25354 {acl_check_rcpt} {acl_check_rcpt_submit} }
25356 In the default configuration file there are some example settings for providing
25357 an RFC 4409 message submission service on port 587 and a non-standard "smtps"
25358 service on port 465. You can use a string expansion like this to choose an ACL
25359 for MUAs on these ports which is more appropriate for this purpose than the
25360 default ACL on port 25.
25362 The expanded string does not have to be the name of an ACL in the configuration
25363 file; there are other possibilities. Having expanded the string, Exim searches
25364 for an ACL as follows:
25366 * If the string begins with a slash, Exim uses it as a file name, and reads
25367 its contents as an ACL. The lines are processed in the same way as lines in
25368 the Exim configuration file. In particular, continuation lines are
25369 supported, blank lines are ignored, as are lines whose first non-whitespace
25370 character is "#". If the file does not exist or cannot be read, an error
25371 occurs (typically causing a temporary failure of whatever caused the ACL to
25372 be run). For example:
25374 acl_smtp_data = /etc/acls/\
25375 ${lookup{$sender_host_address}lsearch\
25376 {/etc/acllist}{$value}{default}}
25378 This looks up an ACL file to use on the basis of the host's IP address,
25379 falling back to a default if the lookup fails. If an ACL is successfully
25380 read from a file, it is retained in memory for the duration of the Exim
25381 process, so that it can be re-used without having to re-read the file.
25383 * If the string does not start with a slash, and does not contain any spaces,
25384 Exim searches the ACL section of the configuration for an ACL whose name
25385 matches the string.
25387 * If no named ACL is found, or if the string contains spaces, Exim parses the
25388 string as an inline ACL. This can save typing in cases where you just want
25389 to have something like
25391 acl_smtp_vrfy = accept
25393 in order to allow free use of the VRFY command. Such a string may contain
25394 newlines; it is processed in the same way as an ACL that is read from a
25398 42.13 ACL return codes
25399 ----------------------
25401 Except for the QUIT ACL, which does not affect the SMTP return code (see
25402 section 42.10 above), the result of running an ACL is either "accept" or
25403 "deny", or, if some test cannot be completed (for example, if a database is
25404 down), "defer". These results cause 2xx, 5xx, and 4xx return codes,
25405 respectively, to be used in the SMTP dialogue. A fourth return, "error", occurs
25406 when there is an error such as invalid syntax in the ACL. This also causes a 4
25409 For the non-SMTP ACL, "defer" and "error" are treated in the same way as
25410 "deny", because there is no mechanism for passing temporary errors to the
25411 submitters of non-SMTP messages.
25413 ACLs that are relevant to message reception may also return "discard". This has
25414 the effect of "accept", but causes either the entire message or an individual
25415 recipient address to be discarded. In other words, it is a blackholing
25416 facility. Use it with care.
25418 If the ACL for MAIL returns "discard", all recipients are discarded, and no ACL
25419 is run for subsequent RCPT commands. The effect of "discard" in a RCPT ACL is
25420 to discard just the one recipient address. If there are no recipients left when
25421 the message's data is received, the DATA ACL is not run. A "discard" return
25422 from the DATA or the non-SMTP ACL discards all the remaining recipients. The
25423 "discard" return is not permitted for the acl_smtp_predata ACL.
25425 The local_scan() function is always run, even if there are no remaining
25426 recipients; it may create new recipients.
25429 42.14 Unset ACL options
25430 -----------------------
25432 The default actions when any of the acl_xxx options are unset are not all the
25433 same. Note: These defaults apply only when the relevant ACL is not defined at
25434 all. For any defined ACL, the default action when control reaches the end of
25435 the ACL statements is "deny".
25437 For acl_smtp_quit and acl_not_smtp_start there is no default because these two
25438 are ACLs that are used only for their side effects. They cannot be used to
25439 accept or reject anything.
25441 For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo
25442 , acl_smtp_mail, acl_smtp_mailauth, acl_smtp_mime, acl_smtp_predata, and
25443 acl_smtp_starttls, the action when the ACL is not defined is "accept".
25445 For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy
25446 ), the action when the ACL is not defined is "deny". This means that
25447 acl_smtp_rcpt must be defined in order to receive any messages over an SMTP
25448 connection. For an example, see the ACL in the default configuration file.
25451 42.15 Data for message ACLs
25452 ---------------------------
25454 When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables
25455 that contain information about the host and the message's sender (for example,
25456 $sender_host_address and $sender_address) are set, and can be used in ACL
25457 statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part
25458 are set from the argument address. The entire SMTP command is available in
25461 When an ACL for the AUTH parameter of MAIL is running, the variables that
25462 contain information about the host are set, but $sender_address is not yet set.
25463 Section 33.2 contains a discussion of this parameter and how it is used.
25465 The $message_size variable is set to the value of the SIZE parameter on the
25466 MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not
25467 given. The value is updated to the true message size by the time the final DATA
25468 ACL is run (after the message data has been received).
25470 The $rcpt_count variable increases by one for each RCPT command received. The
25471 $recipients_count variable increases by one each time a RCPT command is
25472 accepted, so while an ACL for RCPT is being processed, it contains the number
25473 of previously accepted recipients. At DATA time (for both the DATA ACLs),
25474 $rcpt_count contains the total number of RCPT commands, and $recipients_count
25475 contains the total number of accepted recipients.
25478 42.16 Data for non-message ACLs
25479 -------------------------------
25481 When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY,
25482 the remainder of the SMTP command line is placed in $smtp_command_argument, and
25483 the entire SMTP command is available in $smtp_command. These variables can be
25484 tested using a condition condition. For example, here is an ACL for use with
25485 AUTH, which insists that either the session is encrypted, or the CRAM-MD5
25486 authentication method is used. In other words, it does not permit
25487 authentication methods that use cleartext passwords on unencrypted connections.
25490 accept encrypted = *
25491 accept condition = ${if eq{${uc:$smtp_command_argument}}\
25493 deny message = TLS encryption or CRAM-MD5 required
25495 (Another way of applying this restriction is to arrange for the authenticators
25496 that use cleartext passwords not to be advertised when the connection is not
25497 encrypted. You can use the generic server_advertise_condition authenticator
25498 option to do this.)
25501 42.17 Format of an ACL
25502 ----------------------
25504 An individual ACL consists of a number of statements. Each statement starts
25505 with a verb, optionally followed by a number of conditions and "modifiers".
25506 Modifiers can change the way the verb operates, define error and log messages,
25507 set variables, insert delays, and vary the processing of accepted messages.
25509 If all the conditions are met, the verb is obeyed. The same condition may be
25510 used (with different arguments) more than once in the same statement. This
25511 provides a means of specifying an "and" conjunction between conditions. For
25514 deny dnslists = list1.example
25515 dnslists = list2.example
25517 If there are no conditions, the verb is always obeyed. Exim stops evaluating
25518 the conditions and modifiers when it reaches a condition that fails. What
25519 happens then depends on the verb (and in one case, on a special modifier). Not
25520 all the conditions make sense at every testing point. For example, you cannot
25521 test a sender address in the ACL that is run for a VRFY command.
25527 The ACL verbs are as follows:
25529 * accept: If all the conditions are met, the ACL returns "accept". If any of
25530 the conditions are not met, what happens depends on whether endpass appears
25531 among the conditions (for syntax see below). If the failing condition is
25532 before endpass, control is passed to the next ACL statement; if it is after
25533 endpass, the ACL returns "deny". Consider this statement, used to check a
25536 accept domains = +local_domains
25540 If the recipient domain does not match the domains condition, control
25541 passes to the next statement. If it does match, the recipient is verified,
25542 and the command is accepted if verification succeeds. However, if
25543 verification fails, the ACL yields "deny", because the failing condition is
25546 The endpass feature has turned out to be confusing to many people, so its
25547 use is not recommended nowadays. It is always possible to rewrite an ACL so
25548 that endpass is not needed, and it is no longer used in the default
25551 If a message modifier appears on an accept statement, its action depends on
25552 whether or not endpass is present. In the absence of endpass (when an
25553 accept verb either accepts or passes control to the next statement),
25554 message can be used to vary the message that is sent when an SMTP command
25555 is accepted. For example, in a RCPT ACL you could have:
25557 accept <some conditions>
25558 message = OK, I will allow you through today
25560 You can specify an SMTP response code, optionally followed by an "extended
25561 response code" at the start of the message, but the first digit must be the
25562 same as would be sent by default, which is 2 for an accept verb.
25564 If endpass is present in an accept statement, message specifies an error
25565 message that is used when access is denied. This behaviour is retained for
25566 backward compatibility, but current "best practice" is to avoid the use of
25569 * defer: If all the conditions are true, the ACL returns "defer" which, in an
25570 SMTP session, causes a 4xx response to be given. For a non-SMTP ACL, defer
25571 is the same as deny, because there is no way of sending a temporary error.
25572 For a RCPT command, defer is much the same as using a redirect router and
25573 ":defer:" while verifying, but the defer verb can be used in any ACL, and
25574 even for a recipient it might be a simpler approach.
25576 * deny: If all the conditions are met, the ACL returns "deny". If any of the
25577 conditions are not met, control is passed to the next ACL statement. For
25580 deny dnslists = blackholes.mail-abuse.org
25582 rejects commands from hosts that are on a DNS black list.
25584 * discard: This verb behaves like accept, except that it returns "discard"
25585 from the ACL instead of "accept". It is permitted only on ACLs that are
25586 concerned with receiving messages. When all the conditions are true, the
25587 sending entity receives a "success" response. However, discard causes
25588 recipients to be discarded. If it is used in an ACL for RCPT, just the one
25589 recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all
25590 the message's recipients are discarded. Recipients that are discarded
25591 before DATA do not appear in the log line when the received_recipients log
25594 If the log_message modifier is set when discard operates, its contents are
25595 added to the line that is automatically written to the log. The message
25596 modifier operates exactly as it does for accept.
25598 * drop: This verb behaves like deny, except that an SMTP connection is
25599 forcibly closed after the 5xx error message has been sent. For example:
25601 drop message = I don't take more than 20 RCPTs
25602 condition = ${if > {$rcpt_count}{20}}
25604 There is no difference between deny and drop for the connect-time ACL. The
25605 connection is always dropped after sending a 550 response.
25607 * require: If all the conditions are met, control is passed to the next ACL
25608 statement. If any of the conditions are not met, the ACL returns "deny".
25609 For example, when checking a RCPT command,
25611 require message = Sender did not verify
25614 passes control to subsequent statements only if the message's sender can be
25615 verified. Otherwise, it rejects the command. Note the positioning of the
25616 message modifier, before the verify condition. The reason for this is
25617 discussed in section 42.20.
25619 * warn: If all the conditions are true, a line specified by the log_message
25620 modifier is written to Exim's main log. Control always passes to the next
25621 ACL statement. If any condition is false, the log line is not written. If
25622 an identical log line is requested several times in the same message, only
25623 one copy is actually written to the log. If you want to force duplicates to
25624 be written, use the logwrite modifier instead.
25626 If log_message is not present, a warn verb just checks its conditions and
25627 obeys any "immediate" modifiers (such as control, set, logwrite, add_header
25628 , and remove_header) that appear before the first failing condition. There
25629 is more about adding header lines in section 42.24.
25631 If any condition on a warn statement cannot be completed (that is, there is
25632 some sort of defer), the log line specified by log_message is not written.
25633 This does not include the case of a forced failure from a lookup, which is
25634 considered to be a successful completion. After a defer, no further
25635 conditions or modifiers in the warn statement are processed. The incident
25636 is logged, and the ACL continues to be processed, from the next statement
25639 When one of the warn conditions is an address verification that fails, the
25640 text of the verification failure message is in $acl_verify_message. If you
25641 want this logged, you must set it up explicitly. For example:
25643 warn !verify = sender
25644 log_message = sender verify failed: $acl_verify_message
25646 At the end of each ACL there is an implicit unconditional deny.
25648 As you can see from the examples above, the conditions and modifiers are
25649 written one to a line, with the first one on the same line as the verb, and
25650 subsequent ones on following lines. If you have a very long condition, you can
25651 continue it onto several physical lines by the usual backslash continuation
25652 mechanism. It is conventional to align the conditions vertically.
25655 42.19 ACL variables
25656 -------------------
25658 There are some special variables that can be set during ACL processing. They
25659 can be used to pass information between different ACLs, different invocations
25660 of the same ACL in the same SMTP connection, and between ACLs and the routers,
25661 transports, and filters that are used to deliver a message. The names of these
25662 variables must begin with $acl_c or $acl_m, followed either by a digit or an
25663 underscore, but the remainder of the name can be any sequence of alphanumeric
25664 characters and underscores that you choose. There is no limit on the number of
25665 ACL variables. The two sets act as follows:
25667 * The values of those variables whose names begin with $acl_c persist
25668 throughout an SMTP connection. They are never reset. Thus, a value that is
25669 set while receiving one message is still available when receiving the next
25670 message on the same SMTP connection.
25672 * The values of those variables whose names begin with $acl_m persist only
25673 while a message is being received. They are reset afterwards. They are also
25674 reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session.
25676 When a message is accepted, the current values of all the ACL variables are
25677 preserved with the message and are subsequently made available at delivery
25678 time. The ACL variables are set by a modifier called set. For example:
25680 accept hosts = whatever
25681 set acl_m4 = some value
25682 accept authenticated = *
25683 set acl_c_auth = yes
25685 Note: A leading dollar sign is not used when naming a variable that is to be
25686 set. If you want to set a variable without taking any action, you can use a
25687 warn verb without any other modifiers or conditions.
25689 What happens if a syntactically valid but undefined ACL variable is referenced
25690 depends on the setting of the strict_acl_vars option. If it is false (the
25691 default), an empty string is substituted; if it is true, an error is generated.
25693 Versions of Exim before 4.64 have a limited set of numbered variables, but
25694 their names are compatible, so there is no problem with upgrading.
25697 42.20 Condition and modifier processing
25698 ---------------------------------------
25700 An exclamation mark preceding a condition negates its result. For example:
25702 deny domains = *.dom.example
25703 !verify = recipient
25705 causes the ACL to return "deny" if the recipient domain ends in dom.example and
25706 the recipient address cannot be verified. Sometimes negation can be used on the
25707 right-hand side of a condition. For example, these two statements are
25710 deny hosts = !192.168.3.4
25711 deny !hosts = 192.168.3.4
25713 However, for many conditions (verify being a good example), only left-hand side
25714 negation of the whole condition is possible.
25716 The arguments of conditions and modifiers are expanded. A forced failure of an
25717 expansion causes a condition to be ignored, that is, it behaves as if the
25718 condition is true. Consider these two statements:
25720 accept senders = ${lookup{$host_name}lsearch\
25721 {/some/file}{$value}fail}
25722 accept senders = ${lookup{$host_name}lsearch\
25723 {/some/file}{$value}{}}
25725 Each attempts to look up a list of acceptable senders. If the lookup succeeds,
25726 the returned list is searched, but if the lookup fails the behaviour is
25727 different in the two cases. The fail in the first statement causes the
25728 condition to be ignored, leaving no further conditions. The accept verb
25729 therefore succeeds. The second statement, however, generates an empty list when
25730 the lookup fails. No sender can match an empty list, so the condition fails,
25731 and therefore the accept also fails.
25733 ACL modifiers appear mixed in with conditions in ACL statements. Some of them
25734 specify actions that are taken as the conditions for a statement are checked;
25735 others specify text for messages that are used when access is denied or a
25736 warning is generated. The control modifier affects the way an incoming message
25739 The positioning of the modifiers in an ACL statement is important, because the
25740 processing of a verb ceases as soon as its outcome is known. Only those
25741 modifiers that have already been encountered will take effect. For example,
25742 consider this use of the message modifier:
25744 require message = Can't verify sender
25746 message = Can't verify recipient
25748 message = This message cannot be used
25750 If sender verification fails, Exim knows that the result of the statement is
25751 "deny", so it goes no further. The first message modifier has been seen, so its
25752 text is used as the error message. If sender verification succeeds, but
25753 recipient verification fails, the second message is used. If recipient
25754 verification succeeds, the third message becomes "current", but is never used
25755 because there are no more conditions to cause failure.
25757 For the deny verb, on the other hand, it is always the last message modifier
25758 that is used, because all the conditions must be true for rejection to happen.
25759 Specifying more than one message modifier does not make sense, and the message
25760 can even be specified after all the conditions. For example:
25763 !senders = *@my.domain.example
25764 message = Invalid sender from client host
25766 The "deny" result does not happen until the end of the statement is reached, by
25767 which time Exim has set up the message.
25770 42.21 ACL modifiers
25771 -------------------
25773 The ACL modifiers are as follows:
25775 add_header = <text>
25777 This modifier specifies one or more header lines that are to be added to an
25778 incoming message, assuming, of course, that the message is ultimately
25779 accepted. For details, see section 42.24.
25783 This modifier does nothing of itself, and processing of the ACL always
25784 continues with the next condition or modifier. The value of continue is in
25785 the side effects of expanding its argument. Typically this could be used to
25786 update a database. It is really just a syntactic tidiness, to avoid having
25787 to write rather ugly lines like this:
25789 condition = ${if eq{0}{<some expansion>}{true}{true}}
25791 Instead, all you need is
25793 continue = <some expansion>
25797 This modifier affects the subsequent processing of the SMTP connection or
25798 of an incoming message that is accepted. The effect of the first type of
25799 control lasts for the duration of the connection, whereas the effect of the
25800 second type lasts only until the current message has been received. The
25801 message-specific controls always apply to the whole message, not to
25802 individual recipients, even if the control modifier appears in a RCPT ACL.
25804 As there are now quite a few controls that can be applied, they are
25805 described separately in section 42.22. The control modifier can be used in
25806 several different ways. For example:
25808 * It can be at the end of an accept statement:
25810 accept ...some conditions
25811 control = queue_only
25813 In this case, the control is applied when this statement yields
25814 "accept", in other words, when the conditions are all true.
25816 * It can be in the middle of an accept statement:
25818 accept ...some conditions...
25819 control = queue_only
25820 ...some more conditions...
25822 If the first set of conditions are true, the control is applied, even
25823 if the statement does not accept because one of the second set of
25824 conditions is false. In this case, some subsequent statement must yield
25825 "accept" for the control to be relevant.
25827 * It can be used with warn to apply the control, leaving the decision
25828 about accepting or denying to a subsequent verb. For example:
25830 warn ...some conditions...
25834 This example of warn does not contain message, log_message, or logwrite
25835 , so it does not add anything to the message and does not write a log
25838 * If you want to apply a control unconditionally, you can use it with a
25839 require verb. For example:
25841 require control = no_multiline_responses
25845 This modifier may appear in any ACL except notquit. It causes Exim to wait
25846 for the time interval before proceeding. However, when testing Exim using
25847 the -bh option, the delay is not actually imposed (an appropriate message
25848 is output instead). The time is given in the usual Exim notation, and the
25849 delay happens as soon as the modifier is processed. In an SMTP session,
25850 pending output is flushed before the delay is imposed.
25852 Like control, delay can be used with accept or deny, for example:
25854 deny ...some conditions...
25857 The delay happens if all the conditions are true, before the statement
25858 returns "deny". Compare this with:
25861 ...some conditions...
25863 which waits for 30s before processing the conditions. The delay modifier
25864 can also be used with warn and together with control:
25866 warn ...some conditions...
25871 If delay is encountered when the SMTP PIPELINING extension is in use,
25872 responses to several commands are no longer buffered and sent in one packet
25873 (as they would normally be) because all output is flushed before imposing
25874 the delay. This optimization is disabled so that a number of small delays
25875 do not appear to the client as one large aggregated delay that might
25876 provoke an unwanted timeout. You can, however, disable output flushing for
25877 delay by using a control modifier to set no_delay_flush.
25881 This modifier, which has no argument, is recognized only in accept and
25882 discard statements. It marks the boundary between the conditions whose
25883 failure causes control to pass to the next statement, and the conditions
25884 whose failure causes the ACL to return "deny". This concept has proved to
25885 be confusing to some people, so the use of endpass is no longer recommended
25886 as "best practice". See the description of accept above for more details.
25888 log_message = <text>
25890 This modifier sets up a message that is used as part of the log message if
25891 the ACL denies access or a warn statement's conditions are true. For
25894 require log_message = wrong cipher suite $tls_in_cipher
25895 encrypted = DES-CBC3-SHA
25897 log_message is also used when recipients are discarded by discard. For
25900 discard <some conditions>
25901 log_message = Discarded $local_part@$domain because...
25903 When access is denied, log_message adds to any underlying error message
25904 that may exist because of a condition failure. For example, while verifying
25905 a recipient address, a :fail: redirection might have already set up a
25908 The message may be defined before the conditions to which it applies,
25909 because the string expansion does not happen until Exim decides that access
25910 is to be denied. This means that any variables that are set by the
25911 condition are available for inclusion in the message. For example, the
25912 $dnslist_<xxx> variables are set after a DNS black list lookup succeeds. If
25913 the expansion of log_message fails, or if the result is an empty string,
25914 the modifier is ignored.
25916 If you want to use a warn statement to log the result of an address
25917 verification, you can use $acl_verify_message to include the verification
25920 If log_message is used with a warn statement, "Warning:" is added to the
25921 start of the logged message. If the same warning log message is requested
25922 more than once while receiving a single email message, only one copy is
25923 actually logged. If you want to log multiple copies, use logwrite instead
25924 of log_message. In the absence of log_message and logwrite, nothing is
25925 logged for a successful warn statement.
25927 If log_message is not present and there is no underlying error message (for
25928 example, from the failure of address verification), but message is present,
25929 the message text is used for logging rejections. However, if any text for
25930 logging contains newlines, only the first line is logged. In the absence of
25931 both log_message and message, a default built-in message is used for
25932 logging rejections.
25934 log_reject_target = <log name list>
25936 This modifier makes it possible to specify which logs are used for messages
25937 about ACL rejections. Its argument is a colon-separated list of words that
25938 can be "main", "reject", or "panic". The default is "main:reject". The list
25939 may be empty, in which case a rejection is not logged at all. For example,
25940 this ACL fragment writes no logging information when access is denied:
25942 deny <some conditions>
25943 log_reject_target =
25945 This modifier can be used in SMTP and non-SMTP ACLs. It applies to both
25946 permanent and temporary rejections. Its effect lasts for the rest of the
25951 This modifier writes a message to a log file as soon as it is encountered
25952 when processing an ACL. (Compare log_message, which, except in the case of
25953 warn and discard, is used only if the ACL statement denies access.) The
25954 logwrite modifier can be used to log special incidents in ACLs. For
25957 accept <some special conditions>
25959 logwrite = froze message because ...
25961 By default, the message is written to the main log. However, it may begin
25962 with a colon, followed by a comma-separated list of log names, and then
25963 another colon, to specify exactly which logs are to be written. For
25966 logwrite = :main,reject: text for main and reject logs
25967 logwrite = :panic: text for panic log only
25971 This modifier sets up a text string that is expanded and used as a response
25972 message when an ACL statement terminates the ACL with an "accept", "deny",
25973 or "defer" response. (In the case of the accept and discard verbs, there is
25974 some complication if endpass is involved; see the description of accept for
25977 The expansion of the message happens at the time Exim decides that the ACL
25978 is to end, not at the time it processes message. If the expansion fails, or
25979 generates an empty string, the modifier is ignored. Here is an example
25980 where message must be specified first, because the ACL ends with a
25981 rejection if the hosts condition fails:
25983 require message = Host not recognized
25986 (Once a condition has failed, no further conditions or modifiers are
25989 For ACLs that are triggered by SMTP commands, the message is returned as
25990 part of the SMTP response. The use of message with accept (or discard) is
25991 meaningful only for SMTP, as no message is returned when a non-SMTP message
25992 is accepted. In the case of the connect ACL, accepting with a message
25993 modifier overrides the value of smtp_banner. For the EHLO/HELO ACL, a
25994 customized accept message may not contain more than one line (otherwise it
25995 will be truncated at the first newline and a panic logged), and it cannot
25996 affect the EHLO options.
25998 When SMTP is involved, the message may begin with an overriding response
25999 code, consisting of three digits optionally followed by an "extended
26000 response code" of the form n.n.n, each code being followed by a space. For
26003 deny message = 599 1.2.3 Host not welcome
26004 hosts = 192.168.34.0/24
26006 The first digit of the supplied response code must be the same as would be
26007 sent by default. A panic occurs if it is not. Exim uses a 550 code when it
26008 denies access, but for the predata ACL, note that the default success code
26011 Notwithstanding the previous paragraph, for the QUIT ACL, unlike the
26012 others, the message modifier cannot override the 221 response code.
26014 The text in a message modifier is literal; any quotes are taken as
26015 literals, but because the string is expanded, backslash escapes are
26016 processed anyway. If the message contains newlines, this gives rise to a
26017 multi-line SMTP response.
26019 If message is used on a statement that verifies an address, the message
26020 specified overrides any message that is generated by the verification
26021 process. However, the original message is available in the variable
26022 $acl_verify_message, so you can incorporate it into your message if you
26023 wish. In particular, if you want the text from :fail: items in redirect
26024 routers to be passed back as part of the SMTP response, you should either
26025 not use a message modifier, or make use of $acl_verify_message.
26027 For compatibility with previous releases of Exim, a message modifier that
26028 is used with a warn verb behaves in a similar way to the add_header
26029 modifier, but this usage is now deprecated. However, message acts only when
26030 all the conditions are true, wherever it appears in an ACL command, whereas
26031 add_header acts as soon as it is encountered. If message is used with warn
26032 in an ACL that is not concerned with receiving a message, it has no effect.
26034 remove_header = <text>
26036 This modifier specifies one or more header names in a colon-separated list
26037 that are to be removed from an incoming message, assuming, of course, that
26038 the message is ultimately accepted. For details, see section 42.25.
26040 set <acl_name> = <value>
26042 This modifier puts a value into one of the ACL variables (see section 42.19
26045 udpsend = <parameters>
26047 This modifier sends a UDP packet, for purposes such as statistics
26048 collection or behaviour monitoring. The parameters are expanded, and the
26049 result of the expansion must be a colon-separated list consisting of a
26050 destination server, port number, and the packet contents. The server can be
26051 specified as a host name or IPv4 or IPv6 address. The separator can be
26052 changed with the usual angle bracket syntax. For example, you might want to
26053 collect information on which hosts connect when:
26055 udpsend = <; 2001:dB8::dead:beef ; 1234 ;\
26056 $tod_zulu $sender_host_address
26059 42.22 Use of the control modifier
26060 ---------------------------------
26062 The control modifier supports the following settings:
26064 control = allow_auth_unadvertised
26066 This modifier allows a client host to use the SMTP AUTH command even when
26067 it has not been advertised in response to EHLO. Furthermore, because there
26068 are apparently some really broken clients that do this, Exim will accept
26069 AUTH after HELO (rather than EHLO) when this control is set. It should be
26070 used only if you really need it, and you should limit its use to those
26071 broken clients that do not work without it. For example:
26073 warn hosts = 192.168.34.25
26074 control = allow_auth_unadvertised
26076 Normally, when an Exim server receives an AUTH command, it checks the name
26077 of the authentication mechanism that is given in the command to ensure that
26078 it matches an advertised mechanism. When this control is set, the check
26079 that a mechanism has been advertised is bypassed. Any configured mechanism
26080 can be used by the client. This control is permitted only in the connection
26083 control = caseful_local_part, control = caselower_local_part
26085 These two controls are permitted only in the ACL specified by acl_smtp_rcpt
26086 (that is, during RCPT processing). By default, the contents of $local_part
26087 are lower cased before ACL processing. If "caseful_local_part" is
26088 specified, any uppercase letters in the original local part are restored in
26089 $local_part for the rest of the ACL, or until a control that sets
26090 "caselower_local_part" is encountered.
26092 These controls affect only the current recipient. Moreover, they apply only
26093 to local part handling that takes place directly in the ACL (for example,
26094 as a key in lookups). If a test to verify the recipient is obeyed, the
26095 case-related handling of the local part during the verification is
26096 controlled by the router configuration (see the caseful_local_part generic
26099 This facility could be used, for example, to add a spam score to local
26100 parts containing upper case letters. For example, using $acl_m4 to
26101 accumulate the spam score:
26103 warn control = caseful_local_part
26104 set acl_m4 = ${eval:\
26106 ${if match{$local_part}{[A-Z]}{1}{0}}\
26108 control = caselower_local_part
26110 Notice that we put back the lower cased version afterwards, assuming that
26111 is what is wanted for subsequent tests.
26113 control = cutthrough_delivery
26115 This option requests delivery be attempted while the item is being
26116 received. It is usable in the RCPT ACL and valid only for single-recipient
26117 mails forwarded from one SMTP connection to another. If a recipient-verify
26118 callout connection is requested in the same ACL it is held open and used
26119 for the data, otherwise one is made after the ACL completes.
26121 Note that routers are used in verify mode, and cannot depend on content of
26122 received headers. Note also that headers cannot be modified by any of the
26123 post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers
26124 (subject to the above) and transports.
26126 Cutthrough delivery is not supported via transport-filters or when DKIM
26127 signing of outgoing messages is done, because it sends data to the ultimate
26128 destination before the entire message has been received from the source.
26130 Should the ultimate destination system positively accept or reject the
26131 mail, a corresponding indication is given to the source system and nothing
26132 is queued. If there is a temporary error the item is queued for later
26133 delivery in the usual fashion. If the item is successfully delivered in
26134 cutthrough mode the log line is tagged with ">>" rather than "=>" and
26135 appears before the acceptance "<=" line.
26137 Delivery in this mode avoids the generation of a bounce mail to a (possibly
26138 faked) sender when the destination system is doing content-scan based
26141 control = debug/<options>
26143 This control turns on debug logging, almost as though Exim had been invoked
26144 with "-d", with the output going to a new logfile, by default called
26145 debuglog. The filename can be adjusted with the tag option, which may
26146 access any variables already defined. The logging may be adjusted with the
26147 opts option, which takes the same values as the "-d" command-line option.
26148 Some examples (which depend on variables that don't exist in all contexts):
26151 control = debug/tag=.$sender_host_address
26152 control = debug/opts=+expand+acl
26153 control = debug/tag=.$message_exim_id/opts=+expand
26155 control = dkim_disable_verify
26157 This control turns off DKIM verification processing entirely. For details
26158 on the operation and configuration of DKIM, see chapter 56.
26160 control = dscp/<value>
26162 This option causes the DSCP value associated with the socket for the
26163 inbound connection to be adjusted to a given value, given as one of a
26164 number of fixed strings or to numeric value. The -bI:dscp option may be
26165 used to ask Exim which names it knows of. Common values include
26166 "throughput", "mincost", and on newer systems "ef", "af41", etc. Numeric
26167 values may be in the range 0 to 0x3F.
26169 The outbound packets from Exim will be marked with this value in the header
26170 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no
26171 guarantee that these values will have any effect, not be stripped by
26172 networking equipment, or do much of anything without cooperation with your
26173 Network Engineer and those of all network operators between the source and
26176 control = enforce_sync, control = no_enforce_sync
26178 These controls make it possible to be selective about when SMTP
26179 synchronization is enforced. The global option smtp_enforce_sync specifies
26180 the initial state of the switch (it is true by default). See the
26181 description of this option in chapter 14 for details of SMTP
26182 synchronization checking.
26184 The effect of these two controls lasts for the remainder of the SMTP
26185 connection. They can appear in any ACL except the one for the non-SMTP
26186 messages. The most straightforward place to put them is in the ACL defined
26187 by acl_smtp_connect, which is run at the start of an incoming SMTP
26188 connection, before the first synchronization check. The expected use is to
26189 turn off the synchronization checks for badly-behaved hosts that you
26190 nevertheless need to work with.
26192 control = fakedefer/<message>
26194 This control works in exactly the same way as fakereject (described below)
26195 except that it causes an SMTP 450 response after the message data instead
26196 of a 550 response. You must take care when using fakedefer because it
26197 causes the messages to be duplicated when the sender retries. Therefore,
26198 you should not use fakedefer if the message is to be delivered normally.
26200 control = fakereject/<message>
26202 This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
26203 words, only when an SMTP message is being received. If Exim accepts the
26204 message, instead the final 250 response, a 550 rejection message is sent.
26205 However, Exim proceeds to deliver the message as normal. The control
26206 applies only to the current message, not to any subsequent ones that may be
26207 received in the same SMTP connection.
26209 The text for the 550 response is taken from the control modifier. If no
26210 message is supplied, the following is used:
26212 550-Your message has been rejected but is being
26213 550-kept for evaluation.
26214 550-If it was a legitimate message, it may still be
26215 550 delivered to the target recipient(s).
26217 This facility should be used with extreme caution.
26221 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs,
26222 in other words, only when a message is being received. If the message is
26223 accepted, it is placed on Exim's queue and frozen. The control applies only
26224 to the current message, not to any subsequent ones that may be received in
26225 the same SMTP connection.
26227 This modifier can optionally be followed by "/no_tell". If the global
26228 option freeze_tell is set, it is ignored for the current message (that is,
26229 nobody is told about the freezing), provided all the control=freeze
26230 modifiers that are obeyed for the current message have the "/no_tell"
26233 control = no_delay_flush
26235 Exim normally flushes SMTP output before implementing a delay in an ACL, to
26236 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is
26237 in use. This control, as long as it is encountered before the delay
26238 modifier, disables such output flushing.
26240 control = no_callout_flush
26242 Exim normally flushes SMTP output before performing a callout in an ACL, to
26243 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is
26244 in use. This control, as long as it is encountered before the verify
26245 condition that causes the callout, disables such output flushing.
26247 control = no_mbox_unspool
26249 This control is available when Exim is compiled with the content scanning
26250 extension. Content scanning may require a copy of the current message, or
26251 parts of it, to be written in "mbox format" to a spool file, for passing to
26252 a virus or spam scanner. Normally, such copies are deleted when they are no
26253 longer needed. If this control is set, the copies are not deleted. The
26254 control applies only to the current message, not to any subsequent ones
26255 that may be received in the same SMTP connection. It is provided for
26256 debugging purposes and is unlikely to be useful in production.
26258 control = no_multiline_responses
26260 This control is permitted for any ACL except the one for non-SMTP messages.
26261 It seems that there are broken clients in use that cannot handle multiline
26262 SMTP responses, despite the fact that RFC 821 defined them over 20 years
26265 If this control is set, multiline SMTP responses from ACL rejections are
26266 suppressed. One way of doing this would have been to put out these
26267 responses as one long line. However, RFC 2821 specifies a maximum of 512
26268 bytes per response ("use multiline responses for more" it says - ha!), and
26269 some of the responses might get close to that. So this facility, which is
26270 after all only a sop to broken clients, is implemented by doing two very
26273 * Extra information that is normally output as part of a rejection caused
26274 by sender verification failure is omitted. Only the final line
26275 (typically "sender verification failed") is sent.
26277 * If a message modifier supplies a multiline response, only the first
26280 The setting of the switch can, of course, be made conditional on the
26281 calling host. Its effect lasts until the end of the SMTP connection.
26283 control = no_pipelining
26285 This control turns off the advertising of the PIPELINING extension to SMTP
26286 in the current session. To be useful, it must be obeyed before Exim sends
26287 its response to an EHLO command. Therefore, it should normally appear in an
26288 ACL controlled by acl_smtp_connect or acl_smtp_helo. See also
26289 pipelining_advertise_hosts.
26291 control = queue_only
26293 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs,
26294 in other words, only when a message is being received. If the message is
26295 accepted, it is placed on Exim's queue and left there for delivery by a
26296 subsequent queue runner. No immediate delivery process is started. In other
26297 words, it has the effect as the queue_only global option. However, the
26298 control applies only to the current message, not to any subsequent ones
26299 that may be received in the same SMTP connection.
26301 control = submission/<options>
26303 This control is permitted only for the MAIL, RCPT, and start of data ACLs
26304 (the latter is the one defined by acl_smtp_predata). Setting it tells Exim
26305 that the current message is a submission from a local MUA. In this case,
26306 Exim operates in "submission mode", and applies certain fixups to the
26307 message if necessary. For example, it adds a Date: header line if one is
26308 not present. This control is not permitted in the acl_smtp_data ACL,
26309 because that is too late (the message has already been created).
26311 Chapter 46 describes the processing that Exim applies to messages. Section
26312 46.1 covers the processing that happens in submission mode; the available
26313 options for this control are described there. The control applies only to
26314 the current message, not to any subsequent ones that may be received in the
26315 same SMTP connection.
26317 control = suppress_local_fixups
26319 This control applies to locally submitted (non TCP/IP) messages, and is the
26320 complement of "control = submission". It disables the fixups that are
26321 normally applied to locally-submitted messages. Specifically:
26323 * Any Sender: header line is left alone (in this respect, it is a dynamic
26324 version of local_sender_retain).
26326 * No Message-ID:, From:, or Date: header lines are added.
26328 * There is no check that From: corresponds to the actual sender.
26330 This control may be useful when a remotely-originated message is accepted,
26331 passed to some scanning program, and then re-submitted for delivery. It can
26332 be used only in the acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, and
26333 acl_not_smtp_start ACLs, because it has to be set before the message's data
26336 Note: This control applies only to the current message, not to any others
26337 that are being submitted at the same time using -bs or -bS.
26340 42.23 Summary of message fixup control
26341 --------------------------------------
26343 All four possibilities for message fixups can be specified:
26345 * Locally submitted, fixups applied: the default.
26347 * Locally submitted, no fixups applied: use "control =
26348 suppress_local_fixups".
26350 * Remotely submitted, no fixups applied: the default.
26352 * Remotely submitted, fixups applied: use "control = submission".
26355 42.24 Adding header lines in ACLs
26356 ---------------------------------
26358 The add_header modifier can be used to add one or more extra header lines to an
26359 incoming message, as in this example:
26361 warn dnslists = sbl.spamhaus.org : \
26362 dialup.mail-abuse.org
26363 add_header = X-blacklisted-at: $dnslist_domain
26365 The add_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME,
26366 DKIM, and non-SMTP ACLs (in other words, those that are concerned with
26367 receiving a message). The message must ultimately be accepted for add_header to
26368 have any significant effect. You can use add_header with any ACL verb,
26369 including deny (though this is potentially useful only in a RCPT ACL).
26371 Headers will not be added to the message if the modifier is used in DATA, MIME
26372 or DKIM ACLs for messages delivered by cutthrough routing.
26374 Leading and trailing newlines are removed from the data for the add_header
26375 modifier; if it then contains one or more newlines that are not followed by a
26376 space or a tab, it is assumed to contain multiple header lines. Each one is
26377 checked for valid syntax; "X-ACL-Warn:" is added to the front of any line that
26378 is not a valid header line.
26380 Added header lines are accumulated during the MAIL, RCPT, and predata ACLs.
26381 They are added to the message before processing the DATA and MIME ACLs.
26382 However, if an identical header line is requested more than once, only one copy
26383 is actually added to the message. Further header lines may be accumulated
26384 during the DATA and MIME ACLs, after which they are added to the message, again
26385 with duplicates suppressed. Thus, it is possible to add two identical header
26386 lines to an SMTP message, but only if one is added before DATA and one after.
26387 In the case of non-SMTP messages, new headers are accumulated during the
26388 non-SMTP ACLs, and are added to the message after all the ACLs have run. If a
26389 message is rejected after DATA or by the non-SMTP ACL, all added header lines
26390 are included in the entry that is written to the reject log.
26392 Header lines are not visible in string expansions of message headers until they
26393 are added to the message. It follows that header lines defined in the MAIL,
26394 RCPT, and predata ACLs are not visible until the DATA ACL and MIME ACLs are
26395 run. Similarly, header lines that are added by the DATA or MIME ACLs are not
26396 visible in those ACLs. Because of this restriction, you cannot use header lines
26397 as a way of passing data between (for example) the MAIL and RCPT ACLs. If you
26398 want to do this, you can use ACL variables, as described in section 42.19.
26400 The list of headers yet to be added is given by the $headers_added variable.
26402 The add_header modifier acts immediately as it is encountered during the
26403 processing of an ACL. Notice the difference between these two cases:
26405 accept add_header = ADDED: some text
26408 accept <some condition>
26409 add_header = ADDED: some text
26411 In the first case, the header line is always added, whether or not the
26412 condition is true. In the second case, the header line is added only if the
26413 condition is true. Multiple occurrences of add_header may occur in the same ACL
26414 statement. All those that are encountered before a condition fails are
26417 For compatibility with previous versions of Exim, a message modifier for a warn
26418 verb acts in the same way as add_header, except that it takes effect only if
26419 all the conditions are true, even if it appears before some of them.
26420 Furthermore, only the last occurrence of message is honoured. This usage of
26421 message is now deprecated. If both add_header and message are present on a warn
26422 verb, both are processed according to their specifications.
26424 By default, new header lines are added to a message at the end of the existing
26425 header lines. However, you can specify that any particular header line should
26426 be added right at the start (before all the Received: lines), immediately after
26427 the first block of Received: lines, or immediately before any line that is not
26428 a Received: or Resent-something: header.
26430 This is done by specifying ":at_start:", ":after_received:", or
26431 ":at_start_rfc:" (or, for completeness, ":at_end:") before the text of the
26432 header line, respectively. (Header text cannot start with a colon, as there has
26433 to be a header name first.) For example:
26435 warn add_header = \
26436 :after_received:X-My-Header: something or other...
26438 If more than one header line is supplied in a single add_header modifier, each
26439 one is treated independently and can therefore be placed differently. If you
26440 add more than one line at the start, or after the Received: block, they end up
26443 Warning: This facility currently applies only to header lines that are added in
26444 an ACL. It does NOT work for header lines that are added in a system filter or
26445 in a router or transport.
26448 42.25 Removing header lines in ACLs
26449 -----------------------------------
26451 The remove_header modifier can be used to remove one or more header lines from
26452 an incoming message, as in this example:
26454 warn message = Remove internal headers
26455 remove_header = x-route-mail1 : x-route-mail2
26457 The remove_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME,
26458 DKIM, and non-SMTP ACLs (in other words, those that are concerned with
26459 receiving a message). The message must ultimately be accepted for remove_header
26460 to have any significant effect. You can use remove_header with any ACL verb,
26461 including deny, though this is really not useful for any verb that doesn't
26462 result in a delivered message.
26464 Headers will not be removed to the message if the modifier is used in DATA,
26465 MIME or DKIM ACLs for messages delivered by cutthrough routing.
26467 More than one header can be removed at the same time by using a colon separated
26468 list of header names. The header matching is case insensitive. Wildcards are
26469 not permitted, nor is list expansion performed, so you cannot use hostlists to
26470 create a list of headers, however both connection and message variable
26471 expansion are performed ($acl_c_* and $acl_m_*), illustrated in this example:
26473 warn hosts = +internal_hosts
26474 set acl_c_ihdrs = x-route-mail1 : x-route-mail2
26475 warn message = Remove internal headers
26476 remove_header = $acl_c_ihdrs
26478 Removed header lines are accumulated during the MAIL, RCPT, and predata ACLs.
26479 They are removed from the message before processing the DATA and MIME ACLs.
26480 There is no harm in attempting to remove the same header twice nor is removing
26481 a non-existent header. Further header lines to be removed may be accumulated
26482 during the DATA and MIME ACLs, after which they are removed from the message,
26483 if present. In the case of non-SMTP messages, headers to be removed are
26484 accumulated during the non-SMTP ACLs, and are removed from the message after
26485 all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
26486 ACL, there really is no effect because there is no logging of what headers
26487 would have been removed.
26489 Header lines are not visible in string expansions until the DATA phase when it
26490 is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are
26491 not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are
26492 removed by the DATA or MIME ACLs are still visible in those ACLs. Because of
26493 this restriction, you cannot use header lines as a way of controlling data
26494 passed between (for example) the MAIL and RCPT ACLs. If you want to do this,
26495 you should instead use ACL variables, as described in section 42.19.
26497 The remove_header modifier acts immediately as it is encountered during the
26498 processing of an ACL. Notice the difference between these two cases:
26500 accept remove_header = X-Internal
26503 accept <some condition>
26504 remove_header = X-Internal
26506 In the first case, the header line is always removed, whether or not the
26507 condition is true. In the second case, the header line is removed only if the
26508 condition is true. Multiple occurrences of remove_header may occur in the same
26509 ACL statement. All those that are encountered before a condition fails are
26512 Warning: This facility currently applies only to header lines that are present
26513 during ACL processing. It does NOT remove header lines that are added in a
26514 system filter or in a router or transport.
26517 42.26 ACL conditions
26518 --------------------
26520 Some of the conditions listed in this section are available only when Exim is
26521 compiled with the content-scanning extension. They are included here briefly
26522 for completeness. More detailed descriptions can be found in the discussion on
26523 content scanning in chapter 43.
26525 Not all conditions are relevant in all circumstances. For example, testing
26526 senders and recipients does not make sense in an ACL that is being run as the
26527 result of the arrival of an ETRN command, and checks on message headers can be
26528 done only in the ACLs specified by acl_smtp_data and acl_not_smtp. You can use
26529 the same condition (with different parameters) more than once in the same ACL
26530 statement. This provides a way of specifying an "and" conjunction. The
26531 conditions are as follows:
26533 acl = <name of acl or ACL string or file name >
26535 The possible values of the argument are the same as for the acl_smtp_xxx
26536 options. The named or inline ACL is run. If it returns "accept" the
26537 condition is true; if it returns "deny" the condition is false. If it
26538 returns "defer", the current ACL returns "defer" unless the condition is on
26539 a warn verb. In that case, a "defer" return makes the condition false. This
26540 means that further processing of the warn verb ceases, but processing of
26543 If the argument is a named ACL, up to nine space-separated optional values
26544 can be appended; they appear within the called ACL in $acl_arg1 to
26545 $acl_arg9, and $acl_narg is set to the count of values. Previous values of
26546 these variables are restored after the call returns. The name and values
26547 are expanded separately.
26549 If the nested acl returns "drop" and the outer condition denies access, the
26550 connection is dropped. If it returns "discard", the verb must be accept or
26551 discard, and the action is taken immediately - no further conditions are
26554 ACLs may be nested up to 20 deep; the limit exists purely to catch runaway
26555 loops. This condition allows you to use different ACLs in different
26556 circumstances. For example, different ACLs can be used to handle RCPT
26557 commands for different local users or different local domains.
26559 authenticated = <string list>
26561 If the SMTP connection is not authenticated, the condition is false.
26562 Otherwise, the name of the authenticator is tested against the list. To
26563 test for authentication by any authenticator, you can set
26567 condition = <string>
26569 This feature allows you to make up custom conditions. If the result of
26570 expanding the string is an empty string, the number zero, or one of the
26571 strings "no" or "false", the condition is false. If the result is any
26572 non-zero number, or one of the strings "yes" or "true", the condition is
26573 true. For any other value, some error is assumed to have occurred, and the
26574 ACL returns "defer". However, if the expansion is forced to fail, the
26575 condition is ignored. The effect is to treat it as true, whether it is
26576 positive or negative.
26578 decode = <location>
26580 This condition is available only when Exim is compiled with the
26581 content-scanning extension, and it is allowed only in the ACL defined by
26582 acl_smtp_mime. It causes the current MIME part to be decoded into a file.
26583 If all goes well, the condition is true. It is false only if there are
26584 problems such as a syntax error or a memory shortage. For more details, see
26587 demime = <extension list>
26589 This condition is available only when Exim is compiled with the
26590 content-scanning extension. Its use is described in section 43.6.
26592 dnslists = <list of domain names and other data>
26594 This condition checks for entries in DNS black lists. These are also known
26595 as "RBL lists", after the original Realtime Blackhole List, but note that
26596 the use of the lists at mail-abuse.org now carries a charge. There are too
26597 many different variants of this condition to describe briefly here. See
26598 sections 42.27-42.37 for details.
26600 domains = <domain list>
26602 This condition is relevant only after a RCPT command. It checks that the
26603 domain of the recipient address is in the domain list. If percent-hack
26604 processing is enabled, it is done before this test is done. If the check
26605 succeeds with a lookup, the result of the lookup is placed in $domain_data
26606 until the next domains test.
26608 Note carefully (because many people seem to fall foul of this): you cannot
26609 use domains in a DATA ACL.
26611 encrypted = <string list>
26613 If the SMTP connection is not encrypted, the condition is false. Otherwise,
26614 the name of the cipher suite in use is tested against the list. To test for
26615 encryption without testing for any specific cipher suite(s), set
26619 hosts = <host list>
26621 This condition tests that the calling host matches the host list. If you
26622 have name lookups or wildcarded host names and IP addresses in the same
26623 host list, you should normally put the IP addresses first. For example, you
26626 accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
26628 The lookup in this example uses the host name for its key. This is implied
26629 by the lookup type "dbm". (For a host address lookup you would use
26630 "net-dbm" and it wouldn't matter which way round you had these two items.)
26632 The reason for the problem with host names lies in the left-to-right way
26633 that Exim processes lists. It can test IP addresses without doing any DNS
26634 lookups, but when it reaches an item that requires a host name, it fails if
26635 it cannot find a host name to compare with the pattern. If the above list
26636 is given in the opposite order, the accept statement fails for a host whose
26637 name cannot be found, even if its IP address is 10.9.8.7.
26639 If you really do want to do the name check first, and still recognize the
26640 IP address even if the name lookup fails, you can rewrite the ACL like
26643 accept hosts = dbm;/etc/friendly/hosts
26644 accept hosts = 10.9.8.7
26646 The default action on failing to find the host name is to assume that the
26647 host is not in the list, so the first accept statement fails. The second
26648 statement can then check the IP address.
26650 If a hosts condition is satisfied by means of a lookup, the result of the
26651 lookup is made available in the $host_data variable. This allows you, for
26652 example, to set up a statement like this:
26654 deny hosts = net-lsearch;/some/file
26655 message = $host_data
26657 which gives a custom error message for each denied host.
26659 local_parts = <local part list>
26661 This condition is relevant only after a RCPT command. It checks that the
26662 local part of the recipient address is in the list. If percent-hack
26663 processing is enabled, it is done before this test. If the check succeeds
26664 with a lookup, the result of the lookup is placed in $local_part_data,
26665 which remains set until the next local_parts test.
26669 This condition is available only when Exim is compiled with the
26670 content-scanning extension. It causes the incoming message to be scanned
26671 for viruses. For details, see chapter 43.
26673 mime_regex = <list of regular expressions>
26675 This condition is available only when Exim is compiled with the
26676 content-scanning extension, and it is allowed only in the ACL defined by
26677 acl_smtp_mime. It causes the current MIME part to be scanned for a match
26678 with any of the regular expressions. For details, see chapter 43.
26680 ratelimit = <parameters>
26682 This condition can be used to limit the rate at which a user or host
26683 submits messages. Details are given in section 42.38.
26685 recipients = <address list>
26687 This condition is relevant only after a RCPT command. It checks the entire
26688 recipient address against a list of recipients.
26690 regex = <list of regular expressions>
26692 This condition is available only when Exim is compiled with the
26693 content-scanning extension, and is available only in the DATA, MIME, and
26694 non-SMTP ACLs. It causes the incoming message to be scanned for a match
26695 with any of the regular expressions. For details, see chapter 43.
26697 sender_domains = <domain list>
26699 This condition tests the domain of the sender of the message against the
26700 given domain list. Note: The domain of the sender address is in
26701 $sender_address_domain. It is not put in $domain during the testing of this
26702 condition. This is an exception to the general rule for testing domain
26703 lists. It is done this way so that, if this condition is used in an ACL for
26704 a RCPT command, the recipient's domain (which is in $domain) can be used to
26705 influence the sender checking.
26707 Warning: It is a bad idea to use this condition on its own as a control on
26708 relaying, because sender addresses are easily, and commonly, forged.
26710 senders = <address list>
26712 This condition tests the sender of the message against the given list. To
26713 test for a bounce message, which has an empty sender, set
26717 Warning: It is a bad idea to use this condition on its own as a control on
26718 relaying, because sender addresses are easily, and commonly, forged.
26722 This condition is available only when Exim is compiled with the
26723 content-scanning extension. It causes the incoming message to be scanned by
26724 SpamAssassin. For details, see chapter 43.
26726 verify = certificate
26728 This condition is true in an SMTP session if the session is encrypted, and
26729 a certificate was received from the client, and the certificate was
26730 verified. The server requests a certificate only if the client matches
26731 tls_verify_hosts or tls_try_verify_hosts (see chapter 41).
26735 This condition checks whether the sending host (the client) is authorized
26736 to send email. Details of how this works are given in section 42.50.
26738 verify = header_names_ascii
26740 This condition is relevant only in an ACL that is run after a message has
26741 been received, that is, in an ACL specified by acl_smtp_data or
26742 acl_not_smtp. It checks all header names (not the content) to make sure
26743 there are no non-ASCII characters, also excluding control characters. The
26744 allowable characters are decimal ASCII values 33 through 126.
26746 Exim itself will handle headers with non-ASCII characters, but it can cause
26747 problems for downstream applications, so this option will allow their
26748 detection and rejection in the DATA ACL's.
26750 verify = header_sender/<options>
26752 This condition is relevant only in an ACL that is run after a message has
26753 been received, that is, in an ACL specified by acl_smtp_data or
26754 acl_not_smtp. It checks that there is a verifiable address in at least one
26755 of the Sender:, Reply-To:, or From: header lines. Such an address is
26756 loosely thought of as a "sender" address (hence the name of the test).
26757 However, an address that appears in one of these headers need not be an
26758 address that accepts bounce messages; only sender addresses in envelopes
26759 are required to accept bounces. Therefore, if you use the callout option on
26760 this check, you might want to arrange for a non-empty address in the MAIL
26763 Details of address verification and the options are given later, starting
26764 at section 42.44 (callouts are described in section 42.45). You can combine
26765 this condition with the senders condition to restrict it to bounce messages
26769 message = A valid sender header is required for bounces
26770 !verify = header_sender
26772 verify = header_syntax
26774 This condition is relevant only in an ACL that is run after a message has
26775 been received, that is, in an ACL specified by acl_smtp_data or
26776 acl_not_smtp. It checks the syntax of all header lines that can contain
26777 lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:).
26778 Unqualified addresses (local parts without domains) are permitted only in
26779 locally generated messages and from hosts that match
26780 sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.
26782 Note that this condition is a syntax check only. However, a common spamming
26783 ploy used to be to send syntactically invalid headers such as
26787 and this condition can be used to reject such messages, though they are not
26788 as common as they used to be.
26792 This condition is true if a HELO or EHLO command has been received from the
26793 client host, and its contents have been verified. If there has been no
26794 previous attempt to verify the HELO/EHLO contents, it is carried out when
26795 this condition is encountered. See the description of the helo_verify_hosts
26796 and helo_try_verify_hosts options for details of how to request
26797 verification independently of this condition.
26799 For SMTP input that does not come over TCP/IP (the -bs command line
26800 option), this condition is always true.
26804 This condition checks that there are no blind (bcc) recipients in the
26805 message. Every envelope recipient must appear either in a To: header line
26806 or in a Cc: header line for this condition to be true. Local parts are
26807 checked case-sensitively; domains are checked case-insensitively. If
26808 Resent-To: or Resent-Cc: header lines exist, they are also checked. This
26809 condition can be used only in a DATA or non-SMTP ACL.
26811 There are, of course, many legitimate messages that make use of blind (bcc)
26812 recipients. This check should not be used on its own for blocking messages.
26814 verify = recipient/<options>
26816 This condition is relevant only after a RCPT command. It verifies the
26817 current recipient. Details of address verification are given later,
26818 starting at section 42.44. After a recipient has been verified, the value
26819 of $address_data is the last value that was set while routing the address.
26820 This applies even if the verification fails. When an address that is being
26821 verified is redirected to a single address, verification continues with the
26822 new address, and in that case, the subsequent value of $address_data is the
26823 value for the child address.
26825 verify = reverse_host_lookup
26827 This condition ensures that a verified host name has been looked up from
26828 the IP address of the client host. (This may have happened already if the
26829 host name was needed for checking a host list, or if the host matched
26830 host_lookup.) Verification ensures that the host name obtained from a
26831 reverse DNS lookup, or one of its aliases, does, when it is itself looked
26832 up in the DNS, yield the original IP address.
26834 If this condition is used for a locally generated message (that is, when
26835 there is no client host involved), it always succeeds.
26837 verify = sender/<options>
26839 This condition is relevant only after a MAIL or RCPT command, or after a
26840 message has been received (the acl_smtp_data or acl_not_smtp ACLs). If the
26841 message's sender is empty (that is, this is a bounce message), the
26842 condition is true. Otherwise, the sender address is verified.
26844 If there is data in the $address_data variable at the end of routing, its
26845 value is placed in $sender_address_data at the end of verification. This
26846 value can be used in subsequent conditions and modifiers in the same ACL
26847 statement. It does not persist after the end of the current statement. If
26848 you want to preserve the value for longer, you can save it in an ACL
26851 Details of verification are given later, starting at section 42.44. Exim
26852 caches the result of sender verification, to avoid doing it more than once
26855 verify = sender=<address>/<options>
26857 This is a variation of the previous option, in which a modified address is
26858 verified as a sender.
26861 42.27 Using DNS lists
26862 ---------------------
26864 In its simplest form, the dnslists condition tests whether the calling host is
26865 on at least one of a number of DNS lists by looking up the inverted IP address
26866 in one or more DNS domains. (Note that DNS list domains are not mail domains,
26867 so the "+" syntax for named lists doesn't work - it is used for special options
26868 instead.) For example, if the calling host's IP address is 192.168.62.43, and
26869 the ACL statement is
26871 deny dnslists = blackholes.mail-abuse.org : \
26872 dialups.mail-abuse.org
26874 the following records are looked up:
26876 43.62.168.192.blackholes.mail-abuse.org
26877 43.62.168.192.dialups.mail-abuse.org
26879 As soon as Exim finds an existing DNS record, processing of the list stops.
26880 Thus, multiple entries on the list provide an "or" conjunction. If you want to
26881 test that a host is on more than one list (an "and" conjunction), you can use
26882 two separate conditions:
26884 deny dnslists = blackholes.mail-abuse.org
26885 dnslists = dialups.mail-abuse.org
26887 If a DNS lookup times out or otherwise fails to give a decisive answer, Exim
26888 behaves as if the host does not match the list item, that is, as if the DNS
26889 record does not exist. If there are further items in the DNS list, they are
26892 This is usually the required action when dnslists is used with deny (which is
26893 the most common usage), because it prevents a DNS failure from blocking mail.
26894 However, you can change this behaviour by putting one of the following special
26897 +include_unknown behave as if the item is on the list
26898 +exclude_unknown behave as if the item is not on the list (default)
26899 +defer_unknown give a temporary error
26901 Each of these applies to any subsequent items on the list. For example:
26903 deny dnslists = +defer_unknown : foo.bar.example
26905 Testing the list of domains stops as soon as a match is found. If you want to
26906 warn for one list and block for another, you can use two different statements:
26908 deny dnslists = blackholes.mail-abuse.org
26909 warn message = X-Warn: sending host is on dialups list
26910 dnslists = dialups.mail-abuse.org
26912 DNS list lookups are cached by Exim for the duration of the SMTP session, so a
26913 lookup based on the IP address is done at most once for any incoming
26914 connection. Exim does not share information between multiple incoming
26915 connections (but your local name server cache should be active).
26918 42.28 Specifying the IP address for a DNS list lookup
26919 -----------------------------------------------------
26921 By default, the IP address that is used in a DNS list lookup is the IP address
26922 of the calling host. However, you can specify another IP address by listing it
26923 after the domain name, introduced by a slash. For example:
26925 deny dnslists = black.list.tld/192.168.1.2
26927 This feature is not very helpful with explicit IP addresses; it is intended for
26928 use with IP addresses that are looked up, for example, the IP addresses of the
26929 MX hosts or nameservers of an email sender address. For an example, see section
26933 42.29 DNS lists keyed on domain names
26934 -------------------------------------
26936 There are some lists that are keyed on domain names rather than inverted IP
26937 addresses (see for example the domain based zones link at http://
26938 www.rfc-ignorant.org/). No reversing of components is used with these lists.
26939 You can change the name that is looked up in a DNS list by listing it after the
26940 domain name, introduced by a slash. For example,
26942 deny message = Sender's domain is listed at $dnslist_domain
26943 dnslists = dsn.rfc-ignorant.org/$sender_address_domain
26945 This particular example is useful only in ACLs that are obeyed after the RCPT
26946 or DATA commands, when a sender address is available. If (for example) the
26947 message's sender is user@tld.example the name that is looked up by this example
26950 tld.example.dsn.rfc-ignorant.org
26952 A single dnslists condition can contain entries for both names and IP
26953 addresses. For example:
26955 deny dnslists = sbl.spamhaus.org : \
26956 dsn.rfc-ignorant.org/$sender_address_domain
26958 The first item checks the sending host's IP address; the second checks a domain
26959 name. The whole condition is true if either of the DNS lookups succeeds.
26962 42.30 Multiple explicit keys for a DNS list
26963 -------------------------------------------
26965 The syntax described above for looking up explicitly-defined values (either
26966 names or IP addresses) in a DNS blacklist is a simplification. After the domain
26967 name for the DNS list, what follows the slash can in fact be a list of items.
26968 As with all lists in Exim, the default separator is a colon. However, because
26969 this is a sublist within the list of DNS blacklist domains, it is necessary
26970 either to double the separators like this:
26972 dnslists = black.list.tld/name.1::name.2
26974 or to change the separator character, like this:
26976 dnslists = black.list.tld/<;name.1;name.2
26978 If an item in the list is an IP address, it is inverted before the DNS
26979 blacklist domain is appended. If it is not an IP address, no inversion occurs.
26980 Consider this condition:
26982 dnslists = black.list.tld/<;192.168.1.2;a.domain
26984 The DNS lookups that occur are:
26986 2.1.168.192.black.list.tld
26987 a.domain.black.list.tld
26989 Once a DNS record has been found (that matches a specific IP return address, if
26990 specified - see section 42.33), no further lookups are done. If there is a
26991 temporary DNS error, the rest of the sublist of domains or IP addresses is
26992 tried. A temporary error for the whole dnslists item occurs only if no other
26993 DNS lookup in this sublist succeeds. In other words, a successful lookup for
26994 any of the items in the sublist overrides a temporary error for a previous
26997 The ability to supply a list of items after the slash is in some sense just a
26998 syntactic convenience. These two examples have the same effect:
27000 dnslists = black.list.tld/a.domain : black.list.tld/b.domain
27001 dnslists = black.list.tld/a.domain::b.domain
27003 However, when the data for the list is obtained from a lookup, the second form
27004 is usually much more convenient. Consider this example:
27006 deny message = The mail servers for the domain \
27007 $sender_address_domain \
27008 are listed at $dnslist_domain ($dnslist_value); \
27010 dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\
27011 ${lookup dnsdb {>|mxh=\
27012 $sender_address_domain} }} }
27014 Note the use of ">|" in the dnsdb lookup to specify the separator for multiple
27015 DNS records. The inner dnsdb lookup produces a list of MX hosts and the outer
27016 dnsdb lookup finds the IP addresses for these hosts. The result of expanding
27017 the condition might be something like this:
27019 dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|...
27021 Thus, this example checks whether or not the IP addresses of the sender
27022 domain's mail servers are on the Spamhaus black list.
27024 The key that was used for a successful DNS list lookup is put into the variable
27025 $dnslist_matched (see section 42.32).
27028 42.31 Data returned by DNS lists
27029 --------------------------------
27031 DNS lists are constructed using address records in the DNS. The original RBL
27032 just used the address 127.0.0.1 on the right hand side of each record, but the
27033 RBL+ list and some other lists use a number of values with different meanings.
27034 The values used on the RBL+ list are:
27038 127.1.0.3 DUL and RBL
27040 127.1.0.5 RSS and RBL
27041 127.1.0.6 RSS and DUL
27042 127.1.0.7 RSS and DUL and RBL
27044 Section 42.33 below describes how you can distinguish between different values.
27045 Some DNS lists may return more than one address record; see section 42.35 for
27046 details of how they are checked.
27049 42.32 Variables set from DNS lists
27050 ----------------------------------
27052 When an entry is found in a DNS list, the variable $dnslist_domain contains the
27053 name of the overall domain that matched (for example, "spamhaus.example"),
27054 $dnslist_matched contains the key within that domain (for example,
27055 "192.168.5.3"), and $dnslist_value contains the data from the DNS record. When
27056 the key is an IP address, it is not reversed in $dnslist_matched (though it is,
27057 of course, in the actual lookup). In simple cases, for example:
27059 deny dnslists = spamhaus.example
27061 the key is also available in another variable (in this case,
27062 $sender_host_address). In more complicated cases, however, this is not true.
27063 For example, using a data lookup (as described in section 42.30) might generate
27064 a dnslists lookup like this:
27066 deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
27068 If this condition succeeds, the value in $dnslist_matched might be
27069 "192.168.6.7" (for example).
27071 If more than one address record is returned by the DNS lookup, all the IP
27072 addresses are included in $dnslist_value, separated by commas and spaces. The
27073 variable $dnslist_text contains the contents of any associated TXT record. For
27074 lists such as RBL+ the TXT record for a merged entry is often not very
27075 meaningful. See section 42.36 for a way of obtaining more information.
27077 You can use the DNS list variables in message or log_message modifiers -
27078 although these appear before the condition in the ACL, they are not expanded
27079 until after it has failed. For example:
27081 deny hosts = !+local_networks
27082 message = $sender_host_address is listed \
27084 dnslists = rbl-plus.mail-abuse.example
27087 42.33 Additional matching conditions for DNS lists
27088 --------------------------------------------------
27090 You can add an equals sign and an IP address after a dnslists domain name in
27091 order to restrict its action to DNS records with a matching right hand side.
27094 deny dnslists = rblplus.mail-abuse.org=127.0.0.2
27096 rejects only those hosts that yield 127.0.0.2. Without this additional data,
27097 any address record is considered to be a match. For the moment, we assume that
27098 the DNS lookup returns just one record. Section 42.35 describes how multiple
27099 records are handled.
27101 More than one IP address may be given for checking, using a comma as a
27102 separator. These are alternatives - if any one of them matches, the dnslists
27103 condition is true. For example:
27105 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
27107 If you want to specify a constraining address list and also specify names or IP
27108 addresses to be looked up, the constraining address list must be specified
27109 first. For example:
27111 deny dnslists = dsn.rfc-ignorant.org\
27112 =127.0.0.2/$sender_address_domain
27114 If the character "&" is used instead of "=", the comparison for each listed IP
27115 address is done by a bitwise "and" instead of by an equality test. In other
27116 words, the listed addresses are used as bit masks. The comparison is true if
27117 all the bits in the mask are present in the address that is being tested. For
27120 dnslists = a.b.c&0.0.0.3
27122 matches if the address is x.x.x.3, x.x.x.7, x.x.x.11, etc. If you want to test
27123 whether one bit or another bit is present (as opposed to both being present),
27124 you must use multiple values. For example:
27126 dnslists = a.b.c&0.0.0.1,0.0.0.2
27128 matches if the final component of the address is an odd number or two times an
27132 42.34 Negated DNS matching conditions
27133 -------------------------------------
27135 You can supply a negative list of IP addresses as part of a dnslists condition.
27138 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
27140 means "deny if the host is in the black list at the domain a.b.c and the IP
27141 address yielded by the list is either 127.0.0.2 or 127.0.0.3",
27143 deny dnslists = a.b.c!=127.0.0.2,127.0.0.3
27145 means "deny if the host is in the black list at the domain a.b.c and the IP
27146 address yielded by the list is not 127.0.0.2 and not 127.0.0.3". In other
27147 words, the result of the test is inverted if an exclamation mark appears before
27148 the "=" (or the "&") sign.
27150 Note: This kind of negation is not the same as negation in a domain, host, or
27151 address list (which is why the syntax is different).
27153 If you are using just one list, the negation syntax does not gain you much. The
27154 previous example is precisely equivalent to
27156 deny dnslists = a.b.c
27157 !dnslists = a.b.c=127.0.0.2,127.0.0.3
27159 However, if you are using multiple lists, the negation syntax is clearer.
27160 Consider this example:
27162 deny dnslists = sbl.spamhaus.org : \
27164 dnsbl.njabl.org!=127.0.0.3 : \
27167 Using only positive lists, this would have to be:
27169 deny dnslists = sbl.spamhaus.org : \
27171 deny dnslists = dnsbl.njabl.org
27172 !dnslists = dnsbl.njabl.org=127.0.0.3
27173 deny dnslists = relays.ordb.org
27175 which is less clear, and harder to maintain.
27178 42.35 Handling multiple DNS records from a DNS list
27179 ---------------------------------------------------
27181 A DNS lookup for a dnslists condition may return more than one DNS record,
27182 thereby providing more than one IP address. When an item in a dnslists list is
27183 followed by "=" or "&" and a list of IP addresses, in order to restrict the
27184 match to specific results from the DNS lookup, there are two ways in which the
27185 checking can be handled. For example, consider the condition:
27187 dnslists = a.b.c=127.0.0.1
27189 What happens if the DNS lookup for the incoming IP address yields both
27190 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the condition
27191 true because at least one given value was found, or is it false because at
27192 least one of the found values was not listed? And how does this affect negated
27193 conditions? Both possibilities are provided for with the help of additional
27194 separators "==" and "=&".
27196 * If "=" or "&" is used, the condition is true if any one of the looked up IP
27197 addresses matches one of the listed addresses. For the example above, the
27198 condition is true because 127.0.0.1 matches.
27200 * If "==" or "=&" is used, the condition is true only if every one of the
27201 looked up IP addresses matches one of the listed addresses. If the
27202 condition is changed to:
27204 dnslists = a.b.c==127.0.0.1
27206 and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
27207 false because 127.0.0.2 is not listed. You would need to have:
27209 dnslists = a.b.c==127.0.0.1,127.0.0.2
27211 for the condition to be true.
27213 When "!" is used to negate IP address matching, it inverts the result, giving
27214 the precise opposite of the behaviour above. Thus:
27216 * If "!=" or "!&" is used, the condition is true if none of the looked up IP
27217 addresses matches one of the listed addresses. Consider:
27219 dnslists = a.b.c!&0.0.0.1
27221 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
27222 false because 127.0.0.1 matches.
27224 * If "!==" or "!=&" is used, the condition is true if there is at least one
27225 looked up IP address that does not match. Consider:
27227 dnslists = a.b.c!=&0.0.0.1
27229 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
27230 true, because 127.0.0.2 does not match. You would need to have:
27232 dnslists = a.b.c!=&0.0.0.1,0.0.0.2
27234 for the condition to be false.
27236 When the DNS lookup yields only a single IP address, there is no difference
27237 between "=" and "==" and between "&" and "=&".
27240 42.36 Detailed information from merged DNS lists
27241 ------------------------------------------------
27243 When the facility for restricting the matching IP values in a DNS list is used,
27244 the text from the TXT record that is set in $dnslist_text may not reflect the
27245 true reason for rejection. This happens when lists are merged and the IP
27246 address in the A record is used to distinguish them; unfortunately there is
27247 only one TXT record. One way round this is not to use merged lists, but that
27248 can be inefficient because it requires multiple DNS lookups where one would do
27249 in the vast majority of cases when the host of interest is not on any of the
27252 A less inefficient way of solving this problem is available. If two domain
27253 names, comma-separated, are given, the second is used first to do an initial
27254 check, making use of any IP value restrictions that are set. If there is a
27255 match, the first domain is used, without any IP value restrictions, to get the
27256 TXT record. As a byproduct of this, there is also a check that the IP being
27257 tested is indeed on the first list. The first domain is the one that is put in
27258 $dnslist_domain. For example:
27261 rejected because $sender_host_address is blacklisted \
27262 at $dnslist_domain\n$dnslist_text
27264 sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
27265 dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
27267 For the first blacklist item, this starts by doing a lookup in
27268 sbl-xbl.spamhaus.org and testing for a 127.0.0.2 return. If there is a match,
27269 it then looks in sbl.spamhaus.org, without checking the return value, and as
27270 long as something is found, it looks for the corresponding TXT record. If there
27271 is no match in sbl-xbl.spamhaus.org, nothing more is done. The second blacklist
27272 item is processed similarly.
27274 If you are interested in more than one merged list, the same list must be given
27275 several times, but because the results of the DNS lookups are cached, the DNS
27276 calls themselves are not repeated. For example:
27278 reject dnslists = \
27279 http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
27280 socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
27281 misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
27282 dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
27284 In this case there is one lookup in dnsbl.sorbs.net, and if none of the IP
27285 values matches (or if no record is found), this is the only lookup that is
27286 done. Only if there is a match is one of the more specific lists consulted.
27289 42.37 DNS lists and IPv6
27290 ------------------------
27292 If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
27293 nibble by nibble. For example, if the calling host's IP address is
27294 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up
27296 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8.
27297 f.f.f.f.e.f.f.3.blackholes.mail-abuse.org
27299 (split over two lines here to fit on the page). Unfortunately, some of the DNS
27300 lists contain wildcard records, intended for IPv4, that interact badly with
27301 IPv6. For example, the DNS entry
27303 *.3.some.list.example. A 127.0.0.1
27305 is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list.
27306 Unfortunately, it also matches the entire 3::/4 IPv6 network.
27308 You can exclude IPv6 addresses from DNS lookups by making use of a suitable
27309 condition condition, as in this example:
27311 deny condition = ${if isip4{$sender_host_address}}
27312 dnslists = some.list.example
27314 If an explicit key is being used for a DNS lookup and it may be an IPv6 address
27315 you should specify alternate list separators for both the outer (DNS list name)
27316 list and inner (lookup keys) list:
27318 dnslists = <; dnsbl.example.com/<|$acl_m_addrslist
27321 42.38 Rate limiting incoming messages
27322 -------------------------------------
27324 The ratelimit ACL condition can be used to measure and control the rate at
27325 which clients can send email. This is more powerful than the smtp_ratelimit_*
27326 options, because those options control the rate of commands in a single SMTP
27327 session only, whereas the ratelimit condition works across all connections
27328 (concurrent and sequential) from the same client host. The syntax of the
27329 ratelimit condition is:
27331 ratelimit = <m> / <p> / <options> / <key>
27333 If the average client sending rate is less than m messages per time period p
27334 then the condition is false; otherwise it is true.
27336 As a side-effect, the ratelimit condition sets the expansion variable
27337 $sender_rate to the client's computed rate, $sender_rate_limit to the
27338 configured value of m, and $sender_rate_period to the configured value of p.
27340 The parameter p is the smoothing time constant, in the form of an Exim time
27341 interval, for example, "8h" for eight hours. A larger time constant means that
27342 it takes Exim longer to forget a client's past behaviour. The parameter m is
27343 the maximum number of messages that a client is permitted to send in each time
27344 interval. It also specifies the number of messages permitted in a fast burst.
27345 By increasing both m and p but keeping m/p constant, you can allow a client to
27346 send more messages in a burst without changing its long-term sending rate
27347 limit. Conversely, if m and p are both small, messages must be sent at an even
27350 There is a script in util/ratelimit.pl which extracts sending rates from log
27351 files, to assist with choosing appropriate settings for m and p when deploying
27352 the ratelimit ACL condition. The script prints usage instructions when it is
27353 run with no arguments.
27355 The key is used to look up the data for calculating the client's average
27356 sending rate. This data is stored in Exim's spool directory, alongside the
27357 retry and other hints databases. The default key is $sender_host_address, which
27358 means Exim computes the sending rate of each client host IP address. By
27359 changing the key you can change how Exim identifies clients for the purpose of
27360 ratelimiting. For example, to limit the sending rate of each authenticated
27361 user, independent of the computer they are sending from, set the key to
27362 $authenticated_id. You must ensure that the lookup key is meaningful; for
27363 example, $authenticated_id is only meaningful if the client has authenticated
27364 (which you can check with the authenticated ACL condition).
27366 The lookup key does not have to identify clients: If you want to limit the rate
27367 at which a recipient receives messages, you can use the key
27368 "$local_part@$domain" with the per_rcpt option (see below) in a RCPT ACL.
27370 Each ratelimit condition can have up to four options. A per_* option specifies
27371 what Exim measures the rate of, for example messages or recipients or bytes.
27372 You can adjust the measurement using the unique= and/or count= options. You can
27373 also control when Exim updates the recorded rate using a strict, leaky, or
27374 readonly option. The options are separated by a slash, like the other
27375 parameters. They may appear in any order.
27377 Internally, Exim appends the smoothing constant p onto the lookup key with any
27378 options that alter the meaning of the stored data. The limit m is not stored,
27379 so you can alter the configured maximum rate and Exim will still remember
27380 clients' past behaviour. If you change the per_* mode or add or remove the
27381 unique= option, the lookup key changes so Exim will forget past behaviour. The
27382 lookup key is not affected by changes to the update mode and the count= option.
27385 42.39 Ratelimit options for what is being measured
27386 --------------------------------------------------
27388 The per_conn option limits the client's connection rate. It is not normally
27389 used in the acl_not_smtp, acl_not_smtp_mime, or acl_not_smtp_start ACLs.
27391 The per_mail option limits the client's rate of sending messages. This is the
27392 default if none of the per_* options is specified. It can be used in
27393 acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, acl_smtp_data,
27396 The per_byte option limits the sender's email bandwidth. It can be used in the
27397 same ACLs as the per_mail option, though it is best to use this option in the
27398 acl_smtp_mime, acl_smtp_data or acl_not_smtp ACLs; if it is used in an earlier
27399 ACL, Exim relies on the SIZE parameter given by the client in its MAIL command,
27400 which may be inaccurate or completely missing. You can follow the limit m in
27401 the configuration with K, M, or G to specify limits in kilobytes, megabytes, or
27402 gigabytes, respectively.
27404 The per_rcpt option causes Exim to limit the rate at which recipients are
27405 accepted. It can be used in the acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime,
27406 acl_smtp_data, or acl_smtp_rcpt ACLs. In acl_smtp_rcpt the rate is updated one
27407 recipient at a time; in the other ACLs the rate is updated with the total
27408 recipient count in one go. Note that in either case the rate limiting engine
27409 will see a message with many recipients as a large high-speed burst.
27411 The per_addr option is like the per_rcpt option, except it counts the number of
27412 different recipients that the client has sent messages to in the last time
27413 period. That is, if the client repeatedly sends messages to the same recipient,
27414 its measured rate is not increased. This option can only be used in
27417 The per_cmd option causes Exim to recompute the rate every time the condition
27418 is processed. This can be used to limit the rate of any SMTP command. If it is
27419 used in multiple ACLs it can limit the aggregate rate of multiple different
27422 The count= option can be used to alter how much Exim adds to the client's
27423 measured rate. For example, the per_byte option is equivalent to "per_mail/
27424 count=$message_size". If there is no count= option, Exim increases the measured
27425 rate by one (except for the per_rcpt option in ACLs other than acl_smtp_rcpt).
27426 The count does not have to be an integer.
27428 The unique= option is described in section 42.42 below.
27431 42.40 Ratelimit update modes
27432 ----------------------------
27434 You can specify one of three options with the ratelimit condition to control
27435 when its database is updated. This section describes the readonly mode, and the
27436 next section describes the strict and leaky modes.
27438 If the ratelimit condition is used in readonly mode, Exim looks up a
27439 previously-computed rate to check against the limit.
27441 For example, you can test the client's sending rate and deny it access (when it
27442 is too fast) in the connect ACL. If the client passes this check then it can go
27443 on to send a message, in which case its recorded rate will be updated in the
27444 MAIL ACL. Subsequent connections from the same client will check this new rate.
27447 deny ratelimit = 100 / 5m / readonly
27448 log_message = RATE CHECK: $sender_rate/$sender_rate_period \
27449 (max $sender_rate_limit)
27452 warn ratelimit = 100 / 5m / strict
27453 log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
27454 (max $sender_rate_limit)
27456 If Exim encounters multiple ratelimit conditions with the same key when
27457 processing a message then it may increase the client's measured rate more than
27458 it should. For example, this will happen if you check the per_rcpt option in
27459 both acl_smtp_rcpt and acl_smtp_data. However it's OK to check the same
27460 ratelimit condition multiple times in the same ACL. You can avoid any multiple
27461 update problems by using the readonly option on later ratelimit checks.
27463 The per_* options described above do not make sense in some ACLs. If you use a
27464 per_* option in an ACL where it is not normally permitted then the update mode
27465 defaults to readonly and you cannot specify the strict or leaky modes. In other
27466 ACLs the default update mode is leaky (see the next section) so you must
27467 specify the readonly option explicitly.
27470 42.41 Ratelimit options for handling fast clients
27471 -------------------------------------------------
27473 If a client's average rate is greater than the maximum, the rate limiting
27474 engine can react in two possible ways, depending on the presence of the strict
27475 or leaky update modes. This is independent of the other counter-measures (such
27476 as rejecting the message) that may be specified by the rest of the ACL.
27478 The leaky (default) option means that the client's recorded rate is not updated
27479 if it is above the limit. The effect of this is that Exim measures the client's
27480 average rate of successfully sent email, which cannot be greater than the
27481 maximum allowed. If the client is over the limit it may suffer some
27482 counter-measures (as specified in the ACL), but it will still be able to send
27483 email at the configured maximum rate, whatever the rate of its attempts. This
27484 is generally the better choice if you have clients that retry automatically.
27485 For example, it does not prevent a sender with an over-aggressive retry rate
27486 from getting any email through.
27488 The strict option means that the client's recorded rate is always updated. The
27489 effect of this is that Exim measures the client's average rate of attempts to
27490 send email, which can be much higher than the maximum it is actually allowed.
27491 If the client is over the limit it may be subjected to counter-measures by the
27492 ACL. It must slow down and allow sufficient time to pass that its computed rate
27493 falls below the maximum before it can send email again. The time (the number of
27494 smoothing periods) it must wait and not attempt to send mail can be calculated
27497 ln(peakrate/maxrate)
27500 42.42 Limiting the rate of different events
27501 -------------------------------------------
27503 The ratelimit unique= option controls a mechanism for counting the rate of
27504 different events. For example, the per_addr option uses this mechanism to count
27505 the number of different recipients that the client has sent messages to in the
27506 last time period; it is equivalent to "per_rcpt/unique=$local_part@$domain".
27507 You could use this feature to measure the rate that a client uses different
27508 sender addresses with the options "per_mail/unique=$sender_address".
27510 For each ratelimit key Exim stores the set of unique= values that it has seen
27511 for that key. The whole set is thrown away when it is older than the rate
27512 smoothing period p, so each different event is counted at most once per period.
27513 In the leaky update mode, an event that causes the client to go over the limit
27514 is not added to the set, in the same way that the client's recorded rate is not
27515 updated in the same situation.
27517 When you combine the unique= and readonly options, the specific unique= value
27518 is ignored, and Exim just retrieves the client's stored rate.
27520 The unique= mechanism needs more space in the ratelimit database than the other
27521 ratelimit options in order to store the event set. The number of unique values
27522 is potentially as large as the rate limit, so the extra space required
27523 increases with larger limits.
27525 The uniqueification is not perfect: there is a small probability that Exim will
27526 think a new event has happened before. If the sender's rate is less than the
27527 limit, Exim should be more than 99.9% correct. However in strict mode the
27528 measured rate can go above the limit, in which case Exim may under-count events
27529 by a significant margin. Fortunately, if the rate is high enough (2.7 times the
27530 limit) that the false positive rate goes above 9%, then Exim will throw away
27531 the over-full event set before the measured rate falls below the limit.
27532 Therefore the only harm should be that exceptionally high sending rates are
27533 logged incorrectly; any countermeasures you configure will be as effective as
27537 42.43 Using rate limiting
27538 -------------------------
27540 Exim's other ACL facilities are used to define what counter-measures are taken
27541 when the rate limit is exceeded. This might be anything from logging a warning
27542 (for example, while measuring existing sending rates in order to define
27543 policy), through time delays to slow down fast senders, up to rejecting the
27544 message. For example:
27546 # Log all senders' rates
27547 warn ratelimit = 0 / 1h / strict
27548 log_message = Sender rate $sender_rate / $sender_rate_period
27550 # Slow down fast senders; note the need to truncate $sender_rate
27551 # at the decimal point.
27552 warn ratelimit = 100 / 1h / per_rcpt / strict
27553 delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
27554 $sender_rate_limit }s
27556 # Keep authenticated users under control
27557 deny authenticated = *
27558 ratelimit = 100 / 1d / strict / $authenticated_id
27560 # System-wide rate limit
27561 defer message = Sorry, too busy. Try again later.
27562 ratelimit = 10 / 1s / $primary_hostname
27564 # Restrict incoming rate from each host, with a default
27565 # set using a macro and special cases looked up in a table.
27566 defer message = Sender rate exceeds $sender_rate_limit \
27567 messages per $sender_rate_period
27568 ratelimit = ${lookup {$sender_host_address} \
27569 cdb {DB/ratelimits.cdb} \
27570 {$value} {RATELIMIT} }
27572 Warning: If you have a busy server with a lot of ratelimit tests, especially
27573 with the per_rcpt option, you may suffer from a performance bottleneck caused
27574 by locking on the ratelimit hints database. Apart from making your ACLs less
27575 complicated, you can reduce the problem by using a RAM disk for Exim's hints
27576 directory (usually /var/spool/exim/db/). However this means that Exim will lose
27577 its hints data after a reboot (including retry hints, the callout cache, and
27581 42.44 Address verification
27582 --------------------------
27584 Several of the verify conditions described in section 42.26 cause addresses to
27585 be verified. Section 42.48 discusses the reporting of sender verification
27586 failures. The verification conditions can be followed by options that modify
27587 the verification process. The options are separated from the keyword and from
27588 each other by slashes, and some of them contain parameters. For example:
27590 verify = sender/callout
27591 verify = recipient/defer_ok/callout=10s,defer_ok
27593 The first stage of address verification, which always happens, is to run the
27594 address through the routers, in "verify mode". Routers can detect the
27595 difference between verification and routing for delivery, and their actions can
27596 be varied by a number of generic options such as verify and verify_only (see
27597 chapter 15). If routing fails, verification fails. The available options are as
27600 * If the callout option is specified, successful routing to one or more
27601 remote hosts is followed by a "callout" to those hosts as an additional
27602 check. Callouts and their sub-options are discussed in the next section.
27604 * If there is a defer error while doing verification routing, the ACL
27605 normally returns "defer". However, if you include defer_ok in the options,
27606 the condition is forced to be true instead. Note that this is a main
27607 verification option as well as a suboption for callouts.
27609 * The no_details option is covered in section 42.48, which discusses the
27610 reporting of sender address verification failures.
27612 * The success_on_redirect option causes verification always to succeed
27613 immediately after a successful redirection. By default, if a redirection
27614 generates just one address, that address is also verified. See further
27615 discussion in section 42.49.
27617 After an address verification failure, $acl_verify_message contains the error
27618 message that is associated with the failure. It can be preserved by coding like
27621 warn !verify = sender
27622 set acl_m0 = $acl_verify_message
27624 If you are writing your own custom rejection message or log message when
27625 denying access, you can use this variable to include information about the
27626 verification failure.
27628 In addition, $sender_verify_failure or $recipient_verify_failure (as
27629 appropriate) contains one of the following words:
27631 * qualify: The address was unqualified (no domain), and the message was
27632 neither local nor came from an exempted host.
27634 * route: Routing failed.
27636 * mail: Routing succeeded, and a callout was attempted; rejection occurred at
27637 or before the MAIL command (that is, on initial connection, HELO, or MAIL).
27639 * recipient: The RCPT command in a callout was rejected.
27641 * postmaster: The postmaster check in a callout was rejected.
27643 The main use of these variables is expected to be to distinguish between
27644 rejections of MAIL and rejections of RCPT in callouts.
27647 42.45 Callout verification
27648 --------------------------
27650 For non-local addresses, routing verifies the domain, but is unable to do any
27651 checking of the local part. There are situations where some means of verifying
27652 the local part is desirable. One way this can be done is to make an SMTP
27653 callback to a delivery host for the sender address or a callforward to a
27654 subsequent host for a recipient address, to see if the host accepts the
27655 address. We use the term callout to cover both cases. Note that for a sender
27656 address, the callback is not to the client host that is trying to deliver the
27657 message, but to one of the hosts that accepts incoming mail for the sender's
27660 Exim does not do callouts by default. If you want them to happen, you must
27661 request them by setting appropriate options on the verify condition, as
27662 described below. This facility should be used with care, because it can add a
27663 lot of resource usage to the cost of verifying an address. However, Exim does
27664 cache the results of callouts, which helps to reduce the cost. Details of
27665 caching are in section 42.47.
27667 Recipient callouts are usually used only between hosts that are controlled by
27668 the same administration. For example, a corporate gateway host could use
27669 callouts to check for valid recipients on an internal mailserver. A successful
27670 callout does not guarantee that a real delivery to the address would succeed;
27671 on the other hand, a failing callout does guarantee that a delivery would fail.
27673 If the callout option is present on a condition that verifies an address, a
27674 second stage of verification occurs if the address is successfully routed to
27675 one or more remote hosts. The usual case is routing by a dnslookup or a
27676 manualroute router, where the router specifies the hosts. However, if a router
27677 that does not set up hosts routes to an smtp transport with a hosts setting,
27678 the transport's hosts are used. If an smtp transport has hosts_override set,
27679 its hosts are always used, whether or not the router supplies a host list.
27680 Callouts are only supported on smtp transports.
27682 The port that is used is taken from the transport, if it is specified and is a
27683 remote transport. (For routers that do verification only, no transport need be
27684 specified.) Otherwise, the default SMTP port is used. If a remote transport
27685 specifies an outgoing interface, this is used; otherwise the interface is not
27686 specified. Likewise, the text that is used for the HELO command is taken from
27687 the transport's helo_data option; if there is no transport, the value of
27688 $smtp_active_hostname is used.
27690 For a sender callout check, Exim makes SMTP connections to the remote hosts, to
27691 test whether a bounce message could be delivered to the sender address. The
27692 following SMTP commands are sent:
27694 HELO <local host name>
27696 RCPT TO:<the address to be tested>
27699 LHLO is used instead of HELO if the transport's protocol option is set to
27702 The callout may use EHLO, AUTH and/or STARTTLS given appropriate option
27705 A recipient callout check is similar. By default, it also uses an empty address
27706 for the sender. This default is chosen because most hosts do not make use of
27707 the sender address when verifying a recipient. Using the same address means
27708 that a single cache entry can be used for each recipient. Some sites, however,
27709 do make use of the sender address when verifying. These are catered for by the
27710 use_sender and use_postmaster options, described in the next section.
27712 If the response to the RCPT command is a 2xx code, the verification succeeds.
27713 If it is 5xx, the verification fails. For any other condition, Exim tries the
27714 next host, if any. If there is a problem with all the remote hosts, the ACL
27715 yields "defer", unless the defer_ok parameter of the callout option is given,
27716 in which case the condition is forced to succeed.
27718 A callout may take a little time. For this reason, Exim normally flushes SMTP
27719 output before performing a callout in an ACL, to avoid unexpected timeouts in
27720 clients when the SMTP PIPELINING extension is in use. The flushing can be
27721 disabled by using a control modifier to set no_callout_flush.
27724 42.46 Additional parameters for callouts
27725 ----------------------------------------
27727 The callout option can be followed by an equals sign and a number of optional
27728 parameters, separated by commas. For example:
27730 verify = recipient/callout=10s,defer_ok
27732 The old syntax, which had callout_defer_ok and check_postmaster as separate
27733 verify options, is retained for backwards compatibility, but is now deprecated.
27734 The additional parameters for callout are as follows:
27738 This specifies the timeout that applies for the callout attempt to each
27741 verify = sender/callout=5s
27743 The default is 30 seconds. The timeout is used for each response from the
27744 remote host. It is also used for the initial connection, unless overridden
27745 by the connect parameter.
27747 connect = <time interval>
27749 This parameter makes it possible to set a different (usually smaller)
27750 timeout for making the SMTP connection. For example:
27752 verify = sender/callout=5s,connect=1s
27754 If not specified, this timeout defaults to the general timeout value.
27758 When this parameter is present, failure to contact any host, or any other
27759 kind of temporary error, is treated as success by the ACL. However, the
27760 cache is not updated in this circumstance.
27764 This operates like the postmaster option (see below), but if the check for
27765 postmaster@domain fails, it tries just postmaster, without a domain, in
27766 accordance with the specification in RFC 2821. The RFC states that the
27767 unqualified address postmaster should be accepted.
27769 mailfrom = <email address>
27771 When verifying addresses in header lines using the header_sender
27772 verification option, Exim behaves by default as if the addresses are
27773 envelope sender addresses from a message. Callout verification therefore
27774 tests to see whether a bounce message could be delivered, by using an empty
27775 address in the MAIL command. However, it is arguable that these addresses
27776 might never be used as envelope senders, and could therefore justifiably
27777 reject bounce messages (empty senders). The mailfrom callout parameter
27778 allows you to specify what address to use in the MAIL command. For example:
27780 require verify = header_sender/callout=mailfrom=abcd@x.y.z
27782 This parameter is available only for the header_sender verification option.
27784 maxwait = <time interval>
27786 This parameter sets an overall timeout for performing a callout
27787 verification. For example:
27789 verify = sender/callout=5s,maxwait=30s
27791 This timeout defaults to four times the callout timeout for individual SMTP
27792 commands. The overall timeout applies when there is more than one host that
27793 can be tried. The timeout is checked before trying the next host. This
27794 prevents very long delays if there are a large number of hosts and all are
27795 timing out (for example, when network connections are timing out).
27799 When this parameter is given, the callout cache is neither read nor
27804 When this parameter is set, a successful callout check is followed by a
27805 similar check for the local part postmaster at the same domain. If this
27806 address is rejected, the callout fails (but see fullpostmaster above). The
27807 result of the postmaster check is recorded in a cache record; if it is a
27808 failure, this is used to fail subsequent callouts for the domain without a
27809 connection being made, until the cache record expires.
27811 postmaster_mailfrom = <email address>
27813 The postmaster check uses an empty sender in the MAIL command by default.
27814 You can use this parameter to do a postmaster check using a different
27815 address. For example:
27817 require verify = sender/callout=postmaster_mailfrom=abc@x.y.z
27819 If both postmaster and postmaster_mailfrom are present, the rightmost one
27820 overrides. The postmaster parameter is equivalent to this example:
27822 require verify = sender/callout=postmaster_mailfrom=
27824 Warning: The caching arrangements for postmaster checking do not take
27825 account of the sender address. It is assumed that either the empty address
27826 or a fixed non-empty address will be used. All that Exim remembers is that
27827 the postmaster check for the domain succeeded or failed.
27831 When this parameter is set, before doing the normal callout check, Exim
27832 does a check for a "random" local part at the same domain. The local part
27833 is not really random - it is defined by the expansion of the option
27834 callout_random_local_part, which defaults to
27836 $primary_hostname-$tod_epoch-testing
27838 The idea here is to try to determine whether the remote host accepts all
27839 local parts without checking. If it does, there is no point in doing
27840 callouts for specific local parts. If the "random" check succeeds, the
27841 result is saved in a cache record, and used to force the current and
27842 subsequent callout checks to succeed without a connection being made, until
27843 the cache record expires.
27847 This parameter applies to recipient callouts only. For example:
27849 deny !verify = recipient/callout=use_postmaster
27851 It causes a non-empty postmaster address to be used in the MAIL command
27852 when performing the callout for the recipient, and also for a "random"
27853 check if that is configured. The local part of the address is "postmaster"
27854 and the domain is the contents of $qualify_domain.
27858 This option applies to recipient callouts only. For example:
27860 require verify = recipient/callout=use_sender
27862 It causes the message's actual sender address to be used in the MAIL
27863 command when performing the callout, instead of an empty address. There is
27864 no need to use this option unless you know that the called hosts make use
27865 of the sender when checking recipients. If used indiscriminately, it
27866 reduces the usefulness of callout caching.
27868 If you use any of the parameters that set a non-empty sender for the MAIL
27869 command (mailfrom, postmaster_mailfrom, use_postmaster, or use_sender), you
27870 should think about possible loops. Recipient checking is usually done between
27871 two hosts that are under the same management, and the host that receives the
27872 callouts is not normally configured to do callouts itself. Therefore, it is
27873 normally safe to use use_postmaster or use_sender in these circumstances.
27875 However, if you use a non-empty sender address for a callout to an arbitrary
27876 host, there is the likelihood that the remote host will itself initiate a
27877 callout check back to your host. As it is checking what appears to be a message
27878 sender, it is likely to use an empty address in MAIL, thus avoiding a callout
27879 loop. However, to be on the safe side it would be best to set up your own ACLs
27880 so that they do not do sender verification checks when the recipient is the
27881 address you use for header sender or postmaster callout checking.
27883 Another issue to think about when using non-empty senders for callouts is
27884 caching. When you set mailfrom or use_sender, the cache record is keyed by the
27885 sender/recipient combination; thus, for any given recipient, many more actual
27886 callouts are performed than when an empty sender or postmaster is used.
27889 42.47 Callout caching
27890 ---------------------
27892 Exim caches the results of callouts in order to reduce the amount of resources
27893 used, unless you specify the no_cache parameter with the callout option. A
27894 hints database called "callout" is used for the cache. Two different record
27895 types are used: one records the result of a callout check for a specific
27896 address, and the other records information that applies to the entire domain
27897 (for example, that it accepts the local part postmaster).
27899 When an original callout fails, a detailed SMTP error message is given about
27900 the failure. However, for subsequent failures use the cache data, this message
27903 The expiry times for negative and positive address cache records are
27904 independent, and can be set by the global options callout_negative_expire
27905 (default 2h) and callout_positive_expire (default 24h), respectively.
27907 If a host gives a negative response to an SMTP connection, or rejects any
27908 commands up to and including
27912 (but not including the MAIL command with a non-empty address), any callout
27913 attempt is bound to fail. Exim remembers such failures in a domain cache
27914 record, which it uses to fail callouts for the domain without making new
27915 connections, until the domain record times out. There are two separate expiry
27916 times for domain cache records: callout_domain_negative_expire (default 3h) and
27917 callout_domain_positive_expire (default 7d).
27919 Domain records expire when the negative expiry time is reached if callouts
27920 cannot be made for the domain, or if the postmaster check failed. Otherwise,
27921 they expire when the positive expiry time is reached. This ensures that, for
27922 example, a host that stops accepting "random" local parts will eventually be
27925 The callout caching mechanism is based on the domain of the address that is
27926 being tested. If the domain routes to several hosts, it is assumed that their
27927 behaviour will be the same.
27930 42.48 Sender address verification reporting
27931 -------------------------------------------
27933 See section 42.44 for a general discussion of verification. When sender
27934 verification fails in an ACL, the details of the failure are given as
27935 additional output lines before the 550 response to the relevant SMTP command
27936 (RCPT or DATA). For example, if sender callout is in use, you might see:
27938 MAIL FROM:<xyz@abc.example>
27940 RCPT TO:<pqr@def.example>
27941 550-Verification failed for <xyz@abc.example>
27942 550-Called: 192.168.34.43
27943 550-Sent: RCPT TO:<xyz@abc.example>
27944 550-Response: 550 Unknown local part xyz in <xyz@abc.example>
27945 550 Sender verification failed
27947 If more than one RCPT command fails in the same way, the details are given only
27948 for the first of them. However, some administrators do not want to send out
27949 this much information. You can suppress the details by adding "/no_details" to
27950 the ACL statement that requests sender verification. For example:
27952 verify = sender/no_details
27955 42.49 Redirection while verifying
27956 ---------------------------------
27958 A dilemma arises when a local address is redirected by aliasing or forwarding
27959 during verification: should the generated addresses themselves be verified, or
27960 should the successful expansion of the original address be enough to verify it?
27961 By default, Exim takes the following pragmatic approach:
27963 * When an incoming address is redirected to just one child address,
27964 verification continues with the child address, and if that fails to verify,
27965 the original verification also fails.
27967 * When an incoming address is redirected to more than one child address,
27968 verification does not continue. A success result is returned.
27970 This seems the most reasonable behaviour for the common use of aliasing as a
27971 way of redirecting different local parts to the same mailbox. It means, for
27972 example, that a pair of alias entries of the form
27975 aw123: :fail: Gone away, no forwarding address
27977 work as expected, with both local parts causing verification failure. When a
27978 redirection generates more than one address, the behaviour is more like a
27979 mailing list, where the existence of the alias itself is sufficient for
27980 verification to succeed.
27982 It is possible, however, to change the default behaviour so that all successful
27983 redirections count as successful verifications, however many new addresses are
27984 generated. This is specified by the success_on_redirect verification option.
27987 require verify = recipient/success_on_redirect/callout=10s
27989 In this example, verification succeeds if a router generates a new address, and
27990 the callout does not occur, because no address was routed to a remote host.
27992 When verification is being tested via the -bv option, the treatment of
27993 redirections is as just described, unless the -v or any debugging option is
27994 also specified. In that case, full verification is done for every generated
27995 address and a report is output for each of them.
27998 42.50 Client SMTP authorization (CSA)
27999 -------------------------------------
28001 Client SMTP Authorization is a system that allows a site to advertise which
28002 machines are and are not permitted to send email. This is done by placing
28003 special SRV records in the DNS; these are looked up using the client's HELO
28004 domain. At the time of writing, CSA is still an Internet Draft. Client SMTP
28005 Authorization checks in Exim are performed by the ACL condition:
28009 This fails if the client is not authorized. If there is a DNS problem, or if no
28010 valid CSA SRV record is found, or if the client is authorized, the condition
28011 succeeds. These three cases can be distinguished using the expansion variable
28012 $csa_status, which can take one of the values "fail", "defer", "unknown", or
28013 "ok". The condition does not itself defer because that would be likely to cause
28014 problems for legitimate email.
28016 The error messages produced by the CSA code include slightly more detail. If
28017 $csa_status is "defer", this may be because of problems looking up the CSA SRV
28018 record, or problems looking up the CSA target address record. There are four
28019 reasons for $csa_status being "fail":
28021 * The client's host name is explicitly not authorized.
28023 * The client's IP address does not match any of the CSA target IP addresses.
28025 * The client's host name is authorized but it has no valid target IP
28026 addresses (for example, the target's addresses are IPv6 and the client is
28029 * The client's host name has no CSA SRV record but a parent domain has
28030 asserted that all subdomains must be explicitly authorized.
28032 The csa verification condition can take an argument which is the domain to use
28033 for the DNS query. The default is:
28035 verify = csa/$sender_helo_name
28037 This implementation includes an extension to CSA. If the query domain is an
28038 address literal such as [192.0.2.95], or if it is a bare IP address, Exim
28039 searches for CSA SRV records in the reverse DNS as if the HELO domain was (for
28040 example) 95.2.0.192.in-addr.arpa. Therefore it is meaningful to say:
28042 verify = csa/$sender_host_address
28044 In fact, this is the check that Exim performs if the client does not say HELO.
28045 This extension can be turned off by setting the main configuration option
28046 dns_csa_use_reverse to be false.
28048 If a CSA SRV record is not found for the domain itself, a search is performed
28049 through its parent domains for a record which might be making assertions about
28050 subdomains. The maximum depth of this search is limited using the main
28051 configuration option dns_csa_search_limit, which is 5 by default. Exim does not
28052 look for CSA SRV records in a top level domain, so the default settings handle
28053 HELO domains as long as seven (hostname.five.four.three.two.one.com). This
28054 encompasses the vast majority of legitimate HELO domains.
28056 The dnsdb lookup also has support for CSA. Although dnsdb also supports direct
28057 SRV lookups, this is not sufficient because of the extra parent domain search
28058 behaviour of CSA, and (as with PTR lookups) dnsdb also turns IP addresses into
28059 lookups in the reverse DNS space. The result of a successful lookup such as:
28061 ${lookup dnsdb {csa=$sender_helo_name}}
28063 has two space-separated fields: an authorization code and a target host name.
28064 The authorization code can be "Y" for yes, "N" for no, "X" for explicit
28065 authorization required but absent, or "?" for unknown.
28068 42.51 Bounce address tag validation
28069 -----------------------------------
28071 Bounce address tag validation (BATV) is a scheme whereby the envelope senders
28072 of outgoing messages have a cryptographic, timestamped "tag" added to them.
28073 Genuine incoming bounce messages should therefore always be addressed to
28074 recipients that have a valid tag. This scheme is a way of detecting unwanted
28075 bounce messages caused by sender address forgeries (often called "collateral
28076 spam"), because the recipients of such messages do not include valid tags.
28078 There are two expansion items to help with the implementation of the BATV
28079 "prvs" (private signature) scheme in an Exim configuration. This scheme signs
28080 the original envelope sender address by using a simple key to add a hash of the
28081 address and some time-based randomizing information. The prvs expansion item
28082 creates a signed address, and the prvscheck expansion item checks one. The
28083 syntax of these expansion items is described in section 11.5.
28085 As an example, suppose the secret per-address keys are stored in an MySQL
28086 database. A query to look up the key for an address could be defined as a macro
28089 PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \
28090 WHERE sender='${quote_mysql:$prvscheck_address}'\
28093 Suppose also that the senders who make use of BATV are defined by an address
28094 list called batv_senders. Then, in the ACL for RCPT commands, you could use
28097 # Bounces: drop unsigned addresses for BATV senders
28098 deny message = This address does not send an unsigned reverse path
28100 recipients = +batv_senders
28102 # Bounces: In case of prvs-signed address, check signature.
28103 deny message = Invalid reverse path signature.
28105 condition = ${prvscheck {$local_part@$domain}\
28106 {PRVSCHECK_SQL}{1}}
28107 !condition = $prvscheck_result
28109 The first statement rejects recipients for bounce messages that are addressed
28110 to plain BATV sender addresses, because it is known that BATV senders do not
28111 send out messages with plain sender addresses. The second statement rejects
28112 recipients that are prvs-signed, but with invalid signatures (either because
28113 the key is wrong, or the signature has timed out).
28115 A non-prvs-signed address is not rejected by the second statement, because the
28116 prvscheck expansion yields an empty string if its first argument is not a
28117 prvs-signed address, thus causing the condition condition to be false. If the
28118 first argument is a syntactically valid prvs-signed address, the yield is the
28119 third string (in this case "1"), whether or not the cryptographic and timeout
28120 checks succeed. The $prvscheck_result variable contains the result of the
28121 checks (empty for failure, "1" for success).
28123 There is one more issue you must consider when implementing prvs-signing: you
28124 have to ensure that the routers accept prvs-signed addresses and deliver them
28125 correctly. The easiest way to handle this is to use a redirect router to remove
28126 the signature with a configuration along these lines:
28130 data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}}
28132 This works because, if the third argument of prvscheck is empty, the result of
28133 the expansion of a prvs-signed address is the decoded value of the original
28134 address. This router should probably be the first of your routers that handles
28137 To create BATV-signed addresses in the first place, a transport of this form
28140 external_smtp_batv:
28142 return_path = ${prvs {$return_path} \
28143 {${lookup mysql{SELECT \
28144 secret FROM batv_prvs WHERE \
28145 sender='${quote_mysql:$sender_address}'} \
28148 If no key can be found for the existing return path, no signing takes place.
28151 42.52 Using an ACL to control relaying
28152 --------------------------------------
28154 An MTA is said to relay a message if it receives it from some host and delivers
28155 it directly to another host as a result of a remote address contained within
28156 it. Redirecting a local address via an alias or forward file and then passing
28157 the message on to another host is not relaying, but a redirection as a result
28158 of the "percent hack" is.
28160 Two kinds of relaying exist, which are termed "incoming" and "outgoing". A host
28161 which is acting as a gateway or an MX backup is concerned with incoming
28162 relaying from arbitrary hosts to a specific set of domains. On the other hand,
28163 a host which is acting as a smart host for a number of clients is concerned
28164 with outgoing relaying from those clients to the Internet at large. Often the
28165 same host is fulfilling both functions, but in principle these two kinds of
28166 relaying are entirely independent. What is not wanted is the transmission of
28167 mail from arbitrary remote hosts through your system to arbitrary domains.
28169 You can implement relay control by means of suitable statements in the ACL that
28170 runs for each RCPT command. For convenience, it is often easiest to use Exim's
28171 named list facility to define the domains and hosts involved. For example,
28172 suppose you want to do the following:
28174 * Deliver a number of domains to mailboxes on the local host (or process them
28175 locally in some other way). Let's say these are my.dom1.example and
28178 * Relay mail for a number of other domains for which you are the secondary
28179 MX. These might be friend1.example and friend2.example.
28181 * Relay mail from the hosts on your local LAN, to whatever domains are
28182 involved. Suppose your LAN is 192.168.45.0/24.
28184 In the main part of the configuration, you put the following definitions:
28186 domainlist local_domains = my.dom1.example : my.dom2.example
28187 domainlist relay_to_domains = friend1.example : friend2.example
28188 hostlist relay_from_hosts = 192.168.45.0/24
28190 Now you can use these definitions in the ACL that is run for every RCPT
28194 accept domains = +local_domains : +relay_to_domains
28195 accept hosts = +relay_from_hosts
28197 The first statement accepts any RCPT command that contains an address in the
28198 local or relay domains. For any other domain, control passes to the second
28199 statement, which accepts the command only if it comes from one of the relay
28200 hosts. In practice, you will probably want to make your ACL more sophisticated
28201 than this, for example, by including sender and recipient verification. The
28202 default configuration includes a more comprehensive example, which is described
28206 42.53 Checking a relay configuration
28207 ------------------------------------
28209 You can check the relay characteristics of your configuration in the same way
28210 that you can test any ACL behaviour for an incoming SMTP connection, by using
28211 the -bh option to run a fake SMTP session with which you interact.
28213 For specifically testing for unwanted relaying, the host
28214 relay-test.mail-abuse.org provides a useful service. If you telnet to this host
28215 from the host on which Exim is running, using the normal telnet port, you will
28216 see a normal telnet connection message and then quite a long delay. Be patient.
28217 The remote host is making an SMTP connection back to your host, and trying a
28218 number of common probes to test for open relay vulnerability. The results of
28219 the tests will eventually appear on your terminal.
28223 ===============================================================================
28224 43. CONTENT SCANNING AT ACL TIME
28226 The extension of Exim to include content scanning at ACL time, formerly known
28227 as "exiscan", was originally implemented as a patch by Tom Kistner. The code
28228 was integrated into the main source for Exim release 4.50, and Tom continues to
28229 maintain it. Most of the wording of this chapter is taken from Tom's
28232 It is also possible to scan the content of messages at other times. The
28233 local_scan() function (see chapter 44) allows for content scanning after all
28234 the ACLs have run. A transport filter can be used to scan messages at delivery
28235 time (see the transport_filter option, described in chapter 24).
28237 If you want to include the ACL-time content-scanning features when you compile
28238 Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your Local/
28239 Makefile. When you do that, the Exim binary is built with:
28241 * Two additional ACLs (acl_smtp_mime and acl_not_smtp_mime) that are run for
28242 all MIME parts for SMTP and non-SMTP messages, respectively.
28244 * Additional ACL conditions and modifiers: decode, malware, mime_regex, regex
28245 , and spam. These can be used in the ACL that is run at the end of message
28246 reception (the acl_smtp_data ACL).
28248 * An additional control feature ("no_mbox_unspool") that saves spooled copies
28249 of messages, or parts of messages, for debugging purposes.
28251 * Additional expansion variables that are set in the new ACL and by the new
28254 * Two new main configuration options: av_scanner and spamd_address.
28256 There is another content-scanning configuration option for Local/Makefile,
28257 called WITH_OLD_DEMIME. If this is set, the old, deprecated demime ACL
28258 condition is compiled, in addition to all the other content-scanning features.
28260 Content-scanning is continually evolving, and new features are still being
28261 added. While such features are still unstable and liable to incompatible
28262 changes, they are made available in Exim by setting options whose names begin
28263 EXPERIMENTAL_ in Local/Makefile. Such features are not documented in this
28264 manual. You can find out about them by reading the file called doc/
28267 All the content-scanning facilities work on a MBOX copy of the message that is
28268 temporarily created in a file called:
28270 <spool_directory>/scan/<message_id>/<message_id>.eml
28272 The .eml extension is a friendly hint to virus scanners that they can expect an
28273 MBOX-like structure inside that file. The file is created when the first
28274 content scanning facility is called. Subsequent calls to content scanning
28275 conditions open the same file again. The directory is recursively removed when
28276 the acl_smtp_data ACL has finished running, unless
28278 control = no_mbox_unspool
28280 has been encountered. When the MIME ACL decodes files, they are put into the
28281 same directory by default.
28284 43.1 Scanning for viruses
28285 -------------------------
28287 The malware ACL condition lets you connect virus scanner software to Exim. It
28288 supports a "generic" interface to scanners called via the shell, and
28289 specialized interfaces for "daemon" type virus scanners, which are resident in
28290 memory and thus are much faster.
28292 You can set the av_scanner option in first part of the Exim configuration file
28293 to specify which scanner to use, together with any additional options that are
28294 needed. The basic syntax is as follows:
28296 av_scanner = <scanner-type>:<option1>:<option2>:[...]
28298 If you do not set av_scanner, it defaults to
28300 av_scanner = sophie:/var/run/sophie
28302 If the value of av_scanner starts with a dollar character, it is expanded
28303 before use. The usual list-parsing of the content (see 6.19) applies. The
28304 following scanner types are supported in this release:
28308 This is the scanner daemon of Kaspersky Version 5. You can get a trial
28309 version at http://www.kaspersky.com. This scanner type takes one option,
28310 which is the path to the daemon's UNIX socket. The default is shown in this
28313 av_scanner = aveserver:/var/run/aveserver
28317 This daemon-type scanner is GPL and free. You can get it at http://
28318 www.clamav.net/. Some older versions of clamd do not seem to unpack MIME
28319 containers, so it used to be recommended to unpack MIME attachments in the
28320 MIME ACL. This no longer believed to be necessary. One option is required:
28321 either the path and name of a UNIX socket file, or a hostname or IP number,
28322 and a port, separated by space, as in the second of these examples:
28324 av_scanner = clamd:/opt/clamd/socket
28325 av_scanner = clamd:192.0.2.3 1234
28326 av_scanner = clamd:192.0.2.3 1234:local
28327 av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234
28329 If the value of av_scanner points to a UNIX socket file or contains the
28330 local keyword, then the ClamAV interface will pass a filename containing
28331 the data to be scanned, which will should normally result in less I/O
28332 happening and be more efficient. Normally in the TCP case, the data is
28333 streamed to ClamAV as Exim does not assume that there is a common
28334 filesystem with the remote host. There is an option WITH_OLD_CLAMAV_STREAM
28335 in src/EDITME available, should you be running a version of ClamAV prior to
28338 The final example shows that multiple TCP targets can be specified. Exim
28339 will randomly use one for each incoming email (i.e. it load balances them).
28340 Note that only TCP targets may be used if specifying a list of scanners; a
28341 UNIX socket cannot be mixed in with TCP targets. If one of the servers
28342 becomes unavailable, Exim will try the remaining one(s) until it finds one
28343 that works. When a clamd server becomes unreachable, Exim will log a
28344 message. Exim does not keep track of scanner state between multiple
28345 messages, and the scanner selection is random, so the message will get
28346 logged in the mainlog for each email that the down scanner gets chosen
28347 first (message wrapped to be readable):
28349 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition:
28350 clamd: connection to localhost, port 3310 failed
28351 (Connection refused)
28353 If the option is unset, the default is /tmp/clamd. Thanks to David Saez for
28354 contributing the code for this scanner.
28358 This is the keyword for the generic command line scanner interface. It can
28359 be used to attach virus scanners that are invoked from the shell. This
28360 scanner type takes 3 mandatory options:
28362 1. The full path and name of the scanner binary, with all command line
28363 options, and a placeholder ("%s") for the directory to scan.
28365 2. A regular expression to match against the STDOUT and STDERR output of
28366 the virus scanner. If the expression matches, a virus was found. You
28367 must make absolutely sure that this expression matches on "virus
28368 found". This is called the "trigger" expression.
28370 3. Another regular expression, containing exactly one pair of parentheses,
28371 to match the name of the virus found in the scanners output. This is
28372 called the "name" expression.
28374 For example, Sophos Sweep reports a virus on a line like this:
28376 Virus 'W32/Magistr-B' found in file ./those.bat
28378 For the trigger expression, we can match the phrase "found in file". For
28379 the name expression, we want to extract the W32/Magistr-B string, so we can
28380 match for the single quotes left and right of it. Altogether, this makes
28381 the configuration setting:
28383 av_scanner = cmdline:\
28384 /path/to/sweep -ss -all -rec -archive %s:\
28385 found in file:'(.+)'
28389 The DrWeb daemon scanner (http://www.sald.com/) interface takes one
28390 argument, either a full path to a UNIX socket, or an IP address and port
28391 separated by white space, as in these examples:
28393 av_scanner = drweb:/var/run/drwebd.sock
28394 av_scanner = drweb:192.168.2.20 31337
28396 If you omit the argument, the default path /usr/local/drweb/run/drwebd.sock
28397 is used. Thanks to Alex Miller for contributing the code for this scanner.
28401 The F-Secure daemon scanner (http://www.f-secure.com) takes one argument
28402 which is the path to a UNIX socket. For example:
28404 av_scanner = fsecure:/path/to/.fsav
28406 If no argument is given, the default is /var/run/.fsav. Thanks to Johan
28407 Thelmen for contributing the code for this scanner.
28411 This is the scanner daemon of Kaspersky Version 4. This version of the
28412 Kaspersky scanner is outdated. Please upgrade (see aveserver above). This
28413 scanner type takes one option, which is the path to the daemon's UNIX
28414 socket. For example:
28416 av_scanner = kavdaemon:/opt/AVP/AvpCtl
28418 The default path is /var/run/AvpCtl.
28422 This is a daemon type scanner that is aimed mainly at Polish users, though
28423 some parts of documentation are now available in English. You can get it at
28424 http://linux.mks.com.pl/. The only option for this scanner type is the
28425 maximum number of processes used simultaneously to scan the attachments,
28426 provided that the demime facility is employed and also provided that mksd
28427 has been run with at least the same number of child processes. For example:
28429 av_scanner = mksd:2
28431 You can safely omit this option (the default value is 1).
28435 This is a general-purpose way of talking to simple scanner daemons running
28436 on the local machine. There are four options: an address (which may be an
28437 IP addres and port, or the path of a Unix socket), a commandline to send
28438 (may include a single %s which will be replaced with the path to the mail
28439 file to be scanned), an RE to trigger on from the returned data, an RE to
28440 extract malware_name from the returned data. For example:
28442 av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$
28444 Default for the socket specifier is /tmp/malware.sock. Default for the
28445 commandline is %s\n. Both regular-expressions are required.
28449 Sophie is a daemon that uses Sophos' libsavi library to scan for viruses.
28450 You can get Sophie at http://www.clanfield.info/sophie/. The only option
28451 for this scanner type is the path to the UNIX socket that Sophie uses for
28452 client communication. For example:
28454 av_scanner = sophie:/tmp/sophie
28456 The default path is /var/run/sophie, so if you are using this, you can omit
28459 When av_scanner is correctly set, you can use the malware condition in the DATA
28460 ACL. Note: You cannot use the malware condition in the MIME ACL.
28462 The av_scanner option is expanded each time malware is called. This makes it
28463 possible to use different scanners. See further below for an example. The
28464 malware condition caches its results, so when you use it multiple times for the
28465 same message, the actual scanning process is only carried out once. However,
28466 using expandable items in av_scanner disables this caching, in which case each
28467 use of the malware condition causes a new scan of the message.
28469 The malware condition takes a right-hand argument that is expanded before use.
28470 It can then be one of
28472 * "true", "*", or "1", in which case the message is scanned for viruses. The
28473 condition succeeds if a virus was found, and fail otherwise. This is the
28476 * "false" or "0" or an empty string, in which case no scanning is done and
28477 the condition fails immediately.
28479 * A regular expression, in which case the message is scanned for viruses. The
28480 condition succeeds if a virus is found and its name matches the regular
28481 expression. This allows you to take special actions on certain types of
28484 You can append "/defer_ok" to the malware condition to accept messages even if
28485 there is a problem with the virus scanner. Otherwise, such a problem causes the
28488 When a virus is found, the condition sets up an expansion variable called
28489 $malware_name that contains the name of the virus. You can use it in a message
28490 modifier that specifies the error returned to the sender, and/or in logging
28493 If your virus scanner cannot unpack MIME and TNEF containers itself, you should
28494 use the demime condition (see section 43.6) before the malware condition.
28496 Beware the interaction of Exim's message_size_limit with any size limits
28497 imposed by your anti-virus scanner.
28499 Here is a very simple scanning example:
28501 deny message = This message contains malware ($malware_name)
28505 The next example accepts messages when there is a problem with the scanner:
28507 deny message = This message contains malware ($malware_name)
28509 malware = */defer_ok
28511 The next example shows how to use an ACL variable to scan with both sophie and
28512 aveserver. It assumes you have set:
28514 av_scanner = $acl_m0
28516 in the main Exim configuration.
28518 deny message = This message contains malware ($malware_name)
28519 set acl_m0 = sophie
28522 deny message = This message contains malware ($malware_name)
28523 set acl_m0 = aveserver
28527 43.2 Scanning with SpamAssassin
28528 -------------------------------
28530 The spam ACL condition calls SpamAssassin's spamd daemon to get a spam score
28531 and a report for the message. You can get SpamAssassin at http://
28532 www.spamassassin.org, or, if you have a working Perl installation, you can use
28535 perl -MCPAN -e 'install Mail::SpamAssassin'
28537 SpamAssassin has its own set of configuration files. Please review its
28538 documentation to see how you can tweak it. The default installation should work
28541 After having installed and configured SpamAssassin, start the spamd daemon. By
28542 default, it listens on 127.0.0.1, TCP port 783. If you use another host or port
28543 for spamd, you must set the spamd_address option in the global part of the Exim
28544 configuration as follows (example):
28546 spamd_address = 192.168.99.45 387
28548 You do not need to set this option if you use the default. As of version 2.60,
28549 spamd also supports communication over UNIX sockets. If you want to use these,
28550 supply spamd_address with an absolute file name instead of a address/port pair:
28552 spamd_address = /var/run/spamd_socket
28554 You can have multiple spamd servers to improve scalability. These can reside on
28555 other hardware reachable over the network. To specify multiple spamd servers,
28556 put multiple address/port pairs in the spamd_address option, separated with
28559 spamd_address = 192.168.2.10 783 : \
28560 192.168.2.11 783 : \
28563 Up to 32 spamd servers are supported. The servers are queried in a random
28564 fashion. When a server fails to respond to the connection attempt, all other
28565 servers are tried until one succeeds. If no server responds, the spam condition
28568 Warning: It is not possible to use the UNIX socket connection method with
28569 multiple spamd servers.
28571 The spamd_address variable is expanded before use if it starts with a dollar
28572 sign. In this case, the expansion may return a string that is used as the list
28573 so that multiple spamd servers can be the result of an expansion.
28576 43.3 Calling SpamAssassin from an Exim ACL
28577 ------------------------------------------
28579 Here is a simple example of the use of the spam condition in a DATA ACL:
28581 deny message = This message was classified as SPAM
28584 The right-hand side of the spam condition specifies a name. This is relevant if
28585 you have set up multiple SpamAssassin profiles. If you do not want to scan
28586 using a specific profile, but rather use the SpamAssassin system-wide default
28587 profile, you can scan for an unknown name, or simply use "nobody". However, you
28588 must put something on the right-hand side.
28590 The name allows you to use per-domain or per-user antispam profiles in
28591 principle, but this is not straightforward in practice, because a message may
28592 have multiple recipients, not necessarily all in the same domain. Because the
28593 spam condition has to be called from a DATA ACL in order to be able to read the
28594 contents of the message, the variables $local_part and $domain are not set.
28596 The right-hand side of the spam condition is expanded before being used, so you
28597 can put lookups or conditions there. When the right-hand side evaluates to "0"
28598 or "false", no scanning is done and the condition fails immediately.
28600 Scanning with SpamAssassin uses a lot of resources. If you scan every message,
28601 large ones may cause significant performance degradation. As most spam messages
28602 are quite small, it is recommended that you do not scan the big ones. For
28605 deny message = This message was classified as SPAM
28606 condition = ${if < {$message_size}{10K}}
28609 The spam condition returns true if the threshold specified in the user's
28610 SpamAssassin profile has been matched or exceeded. If you want to use the spam
28611 condition for its side effects (see the variables below), you can make it
28612 always return "true" by appending ":true" to the username.
28614 When the spam condition is run, it sets up a number of expansion variables.
28615 These variables are saved with the received message, thus they are available
28616 for use at delivery time.
28620 The spam score of the message, for example "3.4" or "30.5". This is useful
28621 for inclusion in log or reject messages.
28625 The spam score of the message, multiplied by ten, as an integer value. For
28626 example "34" or "305". It may appear to disagree with $spam_score because
28627 $spam_score is rounded and $spam_score_int is truncated. The integer value
28628 is useful for numeric comparisons in conditions.
28632 A string consisting of a number of "+" or "-" characters, representing the
28633 integer part of the spam score value. A spam score of 4.4 would have a
28634 $spam_bar value of "++++". This is useful for inclusion in warning headers,
28635 since MUAs can match on such strings.
28639 A multiline text table, containing the full SpamAssassin report for the
28640 message. Useful for inclusion in headers or reject messages.
28642 The spam condition caches its results unless expansion in spamd_address was
28643 used. If you call it again with the same user name, it does not scan again, but
28644 rather returns the same values as before.
28646 The spam condition returns DEFER if there is any error while running the
28647 message through SpamAssassin or if the expansion of spamd_address failed. If
28648 you want to treat DEFER as FAIL (to pass on to the next ACL statement block),
28649 append "/defer_ok" to the right-hand side of the spam condition, like this:
28651 deny message = This message was classified as SPAM
28652 spam = joe/defer_ok
28654 This causes messages to be accepted even if there is a problem with spamd.
28656 Here is a longer, commented example of the use of the spam condition:
28658 # put headers in all messages (no matter if spam or not)
28659 warn spam = nobody:true
28660 add_header = X-Spam-Score: $spam_score ($spam_bar)
28661 add_header = X-Spam-Report: $spam_report
28663 # add second subject line with *SPAM* marker when message
28664 # is over threshold
28666 add_header = Subject: *SPAM* $h_Subject:
28668 # reject spam at high scores (> 12)
28669 deny message = This message scored $spam_score spam points.
28671 condition = ${if >{$spam_score_int}{120}{1}{0}}
28674 43.4 Scanning MIME parts
28675 ------------------------
28677 The acl_smtp_mime global option specifies an ACL that is called once for each
28678 MIME part of an SMTP message, including multipart types, in the sequence of
28679 their position in the message. Similarly, the acl_not_smtp_mime option
28680 specifies an ACL that is used for the MIME parts of non-SMTP messages. These
28681 options may both refer to the same ACL if you want the same processing in both
28684 These ACLs are called (possibly many times) just before the acl_smtp_data ACL
28685 in the case of an SMTP message, or just before the acl_not_smtp ACL in the case
28686 of a non-SMTP message. However, a MIME ACL is called only if the message
28687 contains a Content-Type: header line. When a call to a MIME ACL does not yield
28688 "accept", ACL processing is aborted and the appropriate result code is sent to
28689 the client. In the case of an SMTP message, the acl_smtp_data ACL is not called
28692 You cannot use the malware or spam conditions in a MIME ACL; these can only be
28693 used in the DATA or non-SMTP ACLs. However, you can use the regex condition to
28694 match against the raw MIME part. You can also use the mime_regex condition to
28695 match against the decoded MIME part (see section 43.5).
28697 At the start of a MIME ACL, a number of variables are set from the header
28698 information for the relevant MIME part. These are described below. The contents
28699 of the MIME part are not by default decoded into a disk file except for MIME
28700 parts whose content-type is "message/rfc822". If you want to decode a MIME part
28701 into a disk file, you can use the decode condition. The general syntax is:
28703 decode = [/<path>/]<filename>
28705 The right hand side is expanded before use. After expansion, the value can be:
28707 1. "0" or "false", in which case no decoding is done.
28709 2. The string "default". In that case, the file is put in the temporary
28710 "default" directory <spool_directory>/scan/<message_id>/ with a sequential
28711 file name consisting of the message id and a sequence number. The full path
28712 and name is available in $mime_decoded_filename after decoding.
28714 3. A full path name starting with a slash. If the full name is an existing
28715 directory, it is used as a replacement for the default directory. The
28716 filename is then sequentially assigned. If the path does not exist, it is
28717 used as the full path and file name.
28719 4. If the string does not start with a slash, it is used as the filename, and
28720 the default path is then used.
28722 The decode condition normally succeeds. It is only false for syntax errors or
28723 unusual circumstances such as memory shortages. You can easily decode a file
28724 with its original, proposed filename using
28726 decode = $mime_filename
28728 However, you should keep in mind that $mime_filename might contain anything. If
28729 you place files outside of the default path, they are not automatically
28732 For RFC822 attachments (these are messages attached to messages, with a
28733 content-type of "message/rfc822"), the ACL is called again in the same manner
28734 as for the primary message, only that the $mime_is_rfc822 expansion variable is
28735 set (see below). Attached messages are always decoded to disk before being
28736 checked, and the files are unlinked once the check is done.
28738 The MIME ACL supports the regex and mime_regex conditions. These can be used to
28739 match regular expressions against raw and decoded MIME parts, respectively.
28740 They are described in section 43.5.
28742 The following list describes all expansion variables that are available in the
28747 If the current part is a multipart (see $mime_is_multipart) below, it
28748 should have a boundary string, which is stored in this variable. If the
28749 current part has no boundary parameter in the Content-Type: header, this
28750 variable contains the empty string.
28754 This variable contains the character set identifier, if one was found in
28755 the Content-Type: header. Examples for charset identifiers are:
28761 Please note that this value is not normalized, so you should do matches
28762 case-insensitively.
28764 $mime_content_description
28766 This variable contains the normalized content of the Content-Description:
28767 header. It can contain a human-readable description of the parts content.
28768 Some implementations repeat the filename for attachments here, but they are
28769 usually only used for display purposes.
28771 $mime_content_disposition
28773 This variable contains the normalized content of the Content-Disposition:
28774 header. You can expect strings like "attachment" or "inline" here.
28778 This variable contains the normalized content of the Content-ID: header.
28779 This is a unique ID that can be used to reference a part from another part.
28783 This variable is set only after the decode modifier (see above) has been
28784 successfully run. It contains the size of the decoded part in kilobytes.
28785 The size is always rounded up to full kilobytes, so only a completely empty
28786 part has a $mime_content_size of zero.
28788 $mime_content_transfer_encoding
28790 This variable contains the normalized content of the
28791 Content-transfer-encoding: header. This is a symbolic name for an encoding
28792 type. Typical values are "base64" and "quoted-printable".
28796 If the MIME part has a Content-Type: header, this variable contains its
28797 value, lowercased, and without any options (like "name" or "charset"). Here
28798 are some examples of popular MIME types, as they may appear in this
28803 application/octet-stream
28807 If the MIME part has no Content-Type: header, this variable contains the
28810 $mime_decoded_filename
28812 This variable is set only after the decode modifier (see above) has been
28813 successfully run. It contains the full path and file name of the file
28814 containing the decoded data.
28818 This is perhaps the most important of the MIME variables. It contains a
28819 proposed filename for an attachment, if one was found in either the
28820 Content-Type: or Content-Disposition: headers. The filename will be RFC2047
28821 decoded, but no additional sanity checks are done. If no filename was
28822 found, this variable contains the empty string.
28824 $mime_is_coverletter
28826 This variable attempts to differentiate the "cover letter" of an e-mail
28827 from attached data. It can be used to clamp down on flashy or unnecessarily
28828 encoded content in the cover letter, while not restricting attachments at
28831 The variable contains 1 (true) for a MIME part believed to be part of the
28832 cover letter, and 0 (false) for an attachment. At present, the algorithm is
28835 1. The outermost MIME part of a message is always a cover letter.
28837 2. If a multipart/alternative or multipart/related MIME part is a cover
28838 letter, so are all MIME subparts within that multipart.
28840 3. If any other multipart is a cover letter, the first subpart is a cover
28841 letter, and the rest are attachments.
28843 4. All parts contained within an attachment multipart are attachments.
28845 As an example, the following will ban "HTML mail" (including that sent with
28846 alternative plain text), while allowing HTML files to be attached. HTML
28847 coverletter mail attached to non-HMTL coverletter mail will also be
28850 deny message = HTML mail is not accepted here
28851 !condition = $mime_is_rfc822
28852 condition = $mime_is_coverletter
28853 condition = ${if eq{$mime_content_type}{text/html}{1}{0}}
28857 This variable has the value 1 (true) when the current part has the main
28858 type "multipart", for example "multipart/alternative" or "multipart/mixed".
28859 Since multipart entities only serve as containers for other parts, you may
28860 not want to carry out specific actions on them.
28864 This variable has the value 1 (true) if the current part is not a part of
28865 the checked message itself, but part of an attached message. Attached
28866 message decoding is fully recursive.
28870 This variable is a counter that is raised for each processed MIME part. It
28871 starts at zero for the very first part (which is usually a multipart). The
28872 counter is per-message, so it is reset when processing RFC822 attachments
28873 (see $mime_is_rfc822). The counter stays set after acl_smtp_mime is
28874 complete, so you can use it in the DATA ACL to determine the number of MIME
28875 parts of a message. For non-MIME messages, this variable contains the value
28879 43.5 Scanning with regular expressions
28880 --------------------------------------
28882 You can specify your own custom regular expression matches on the full body of
28883 the message, or on individual MIME parts.
28885 The regex condition takes one or more regular expressions as arguments and
28886 matches them against the full message (when called in the DATA ACL) or a raw
28887 MIME part (when called in the MIME ACL). The regex condition matches linewise,
28888 with a maximum line length of 32K characters. That means you cannot have
28889 multiline matches with the regex condition.
28891 The mime_regex condition can be called only in the MIME ACL. It matches up to
28892 32K of decoded content (the whole content at once, not linewise). If the part
28893 has not been decoded with the decode modifier earlier in the ACL, it is decoded
28894 automatically when mime_regex is executed (using default path and filename
28895 values). If the decoded data is larger than 32K, only the first 32K characters
28898 The regular expressions are passed as a colon-separated list. To include a
28899 literal colon, you must double it. Since the whole right-hand side string is
28900 expanded before being used, you must also escape dollar signs and backslashes
28901 with more backslashes, or use the "\N" facility to disable expansion. Here is a
28902 simple example that contains two regular expressions:
28904 deny message = contains blacklisted regex ($regex_match_string)
28905 regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL
28907 The conditions returns true if any one of the regular expressions matches. The
28908 $regex_match_string expansion variable is then set up and contains the matching
28909 regular expression.
28911 Warning: With large messages, these conditions can be fairly CPU-intensive.
28914 43.6 The demime condition
28915 -------------------------
28917 The demime ACL condition provides MIME unpacking, sanity checking and file
28918 extension blocking. It is usable only in the DATA and non-SMTP ACLs. The demime
28919 condition uses a simpler interface to MIME decoding than the MIME ACL
28920 functionality, but provides no additional facilities. Please note that this
28921 condition is deprecated and kept only for backward compatibility. You must set
28922 the WITH_OLD_DEMIME option in Local/Makefile at build time to be able to use
28923 the demime condition.
28925 The demime condition unpacks MIME containers in the message. It detects errors
28926 in MIME containers and can match file extensions found in the message against a
28927 list. Using this facility produces files containing the unpacked MIME parts of
28928 the message in the temporary scan directory. If you do antivirus scanning, it
28929 is recommended that you use the demime condition before the antivirus (malware)
28932 On the right-hand side of the demime condition you can pass a colon-separated
28933 list of file extensions that it should match against. For example:
28935 deny message = Found blacklisted file attachment
28936 demime = vbs:com:bat:pif:prf:lnk
28938 If one of the file extensions is found, the condition is true, otherwise it is
28939 false. If there is a temporary error while demimeing (for example, "disk
28940 full"), the condition defers, and the message is temporarily rejected (unless
28941 the condition is on a warn verb).
28943 The right-hand side is expanded before being treated as a list, so you can have
28944 conditions and lookups there. If it expands to an empty string, "false", or
28945 zero ("0"), no demimeing is done and the condition is false.
28947 The demime condition set the following variables:
28951 When an error is detected in a MIME container, this variable contains the
28952 severity of the error, as an integer number. The higher the value, the more
28953 severe the error (the current maximum value is 3). If this variable is
28954 unset or zero, no error occurred.
28958 When $demime_errorlevel is greater than zero, this variable contains a
28959 human-readable text string describing the MIME error that occurred.
28963 When the demime condition is true, this variable contains the file
28964 extension it found.
28966 Both $demime_errorlevel and $demime_reason are set by the first call of the
28967 demime condition, and are not changed on subsequent calls.
28969 If you do not want to check for file extensions, but rather use the demime
28970 condition for unpacking or error checking purposes, pass "*" as the right-hand
28971 side value. Here is a more elaborate example of how to use this facility:
28973 # Reject messages with serious MIME container errors
28974 deny message = Found MIME error ($demime_reason).
28976 condition = ${if >{$demime_errorlevel}{2}{1}{0}}
28978 # Reject known virus spreading file extensions.
28979 # Accepting these is pretty much braindead.
28980 deny message = contains $found_extension file (blacklisted).
28981 demime = com:vbs:bat:pif:scr
28983 # Freeze .exe and .doc files. Postmaster can
28984 # examine them and eventually thaw them.
28985 deny log_message = Another $found_extension file.
28991 ===============================================================================
28992 44. ADDING A LOCAL SCAN FUNCTION TO EXIM
28994 In these days of email worms, viruses, and ever-increasing spam, some sites
28995 want to apply a lot of checking to messages before accepting them.
28997 The content scanning extension (chapter 43) has facilities for passing messages
28998 to external virus and spam scanning software. You can also do a certain amount
28999 in Exim itself through string expansions and the condition condition in the ACL
29000 that runs after the SMTP DATA command or the ACL for non-SMTP messages (see
29001 chapter 42), but this has its limitations.
29003 To allow for further customization to a site's own requirements, there is the
29004 possibility of linking Exim with a private message scanning function, written
29005 in C. If you want to run code that is written in something other than C, you
29006 can of course use a little C stub to call it.
29008 The local scan function is run once for every incoming message, at the point
29009 when Exim is just about to accept the message. It can therefore be used to
29010 control non-SMTP messages from local processes as well as messages arriving via
29013 Exim applies a timeout to calls of the local scan function, and there is an
29014 option called local_scan_timeout for setting it. The default is 5 minutes. Zero
29015 means "no timeout". Exim also sets up signal handlers for SIGSEGV, SIGILL,
29016 SIGFPE, and SIGBUS before calling the local scan function, so that the most
29017 common types of crash are caught. If the timeout is exceeded or one of those
29018 signals is caught, the incoming message is rejected with a temporary error if
29019 it is an SMTP message. For a non-SMTP message, the message is dropped and Exim
29020 ends with a non-zero code. The incident is logged on the main and reject logs.
29023 44.1 Building Exim to use a local scan function
29024 -----------------------------------------------
29026 To make use of the local scan function feature, you must tell Exim where your
29027 function is before building Exim, by setting LOCAL_SCAN_SOURCE in your Local/
29028 Makefile. A recommended place to put it is in the Local directory, so you might
29031 LOCAL_SCAN_SOURCE=Local/local_scan.c
29033 for example. The function must be called local_scan(). It is called by Exim
29034 after it has received a message, when the success return code is about to be
29035 sent. This is after all the ACLs have been run. The return code from your
29036 function controls whether the message is actually accepted or not. There is a
29037 commented template function (that just accepts the message) in the file _src/
29040 If you want to make use of Exim's run time configuration file to set options
29041 for your local_scan() function, you must also set
29043 LOCAL_SCAN_HAS_OPTIONS=yes
29045 in Local/Makefile (see section 44.3 below).
29048 44.2 API for local_scan()
29049 -------------------------
29051 You must include this line near the start of your code:
29053 #include "local_scan.h"
29055 This header file defines a number of variables and other values, and the
29056 prototype for the function itself. Exim is coded to use unsigned char values
29057 almost exclusively, and one of the things this header defines is a shorthand
29058 for "unsigned char" called "uschar". It also contains the following macro
29059 definitions, to simplify casting character strings and pointers to character
29062 #define CS (char *)
29063 #define CCS (const char *)
29064 #define CSS (char **)
29065 #define US (unsigned char *)
29066 #define CUS (const unsigned char *)
29067 #define USS (unsigned char **)
29069 The function prototype for local_scan() is:
29071 extern int local_scan(int fd, uschar **return_text);
29073 The arguments are as follows:
29075 * fd is a file descriptor for the file that contains the body of the message
29076 (the -D file). The file is open for reading and writing, but updating it is
29077 not recommended. Warning: You must not close this file descriptor.
29079 The descriptor is positioned at character 19 of the file, which is the
29080 first character of the body itself, because the first 19 characters are the
29081 message id followed by "-D" and a newline. If you rewind the file, you
29082 should use the macro SPOOL_DATA_START_OFFSET to reset to the start of the
29083 data, just in case this changes in some future version.
29085 * return_text is an address which you can use to return a pointer to a text
29086 string at the end of the function. The value it points to on entry is NULL.
29088 The function must return an int value which is one of the following macros:
29090 "LOCAL_SCAN_ACCEPT"
29092 The message is accepted. If you pass back a string of text, it is saved
29093 with the message, and made available in the variable $local_scan_data. No
29094 newlines are permitted (if there are any, they are turned into spaces) and
29095 the maximum length of text is 1000 characters.
29097 "LOCAL_SCAN_ACCEPT_FREEZE"
29099 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
29100 queued without immediate delivery, and is frozen.
29102 "LOCAL_SCAN_ACCEPT_QUEUE"
29104 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
29105 queued without immediate delivery.
29107 "LOCAL_SCAN_REJECT"
29109 The message is rejected; the returned text is used as an error message
29110 which is passed back to the sender and which is also logged. Newlines are
29111 permitted - they cause a multiline response for SMTP rejections, but are
29112 converted to "\n" in log lines. If no message is given, "Administrative
29113 prohibition" is used.
29115 "LOCAL_SCAN_TEMPREJECT"
29117 The message is temporarily rejected; the returned text is used as an error
29118 message as for LOCAL_SCAN_REJECT. If no message is given, "Temporary local
29121 "LOCAL_SCAN_REJECT_NOLOGHDR"
29123 This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected
29124 message is not written to the reject log. It has the effect of unsetting
29125 the rejected_header log selector for just this rejection. If
29126 rejected_header is already unset (see the discussion of the log_selection
29127 option in section 51.15), this code is the same as LOCAL_SCAN_REJECT.
29129 "LOCAL_SCAN_TEMPREJECT_NOLOGHDR"
29131 This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that
29132 LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT.
29134 If the message is not being received by interactive SMTP, rejections are
29135 reported by writing to stderr or by sending an email, as configured by the -oe
29136 command line options.
29139 44.3 Configuration options for local_scan()
29140 -------------------------------------------
29142 It is possible to have option settings in the main configuration file that set
29143 values in static variables in the local_scan() module. If you want to do this,
29144 you must have the line
29146 LOCAL_SCAN_HAS_OPTIONS=yes
29148 in your Local/Makefile when you build Exim. (This line is in OS/
29149 Makefile-Default, commented out). Then, in the local_scan() source file, you
29150 must define static variables to hold the option values, and a table to define
29153 The table must be a vector called local_scan_options, of type "optionlist".
29154 Each entry is a triplet, consisting of a name, an option type, and a pointer to
29155 the variable that holds the value. The entries must appear in alphabetical
29156 order. Following local_scan_options you must also define a variable called
29157 local_scan_options_count that contains the number of entries in the table. Here
29158 is a short example, showing two kinds of option:
29160 static int my_integer_option = 42;
29161 static uschar *my_string_option = US"a default string";
29163 optionlist local_scan_options[] = {
29164 { "my_integer", opt_int, &my_integer_option },
29165 { "my_string", opt_stringptr, &my_string_option }
29168 int local_scan_options_count =
29169 sizeof(local_scan_options)/sizeof(optionlist);
29171 The values of the variables can now be changed from Exim's runtime
29172 configuration file by including a local scan section as in this example:
29176 my_string = some string of text...
29178 The available types of option data are as follows:
29182 This specifies a boolean (true/false) option. The address should point to a
29183 variable of type "BOOL", which will be set to TRUE or FALSE, which are
29184 macros that are defined as "1" and "0", respectively. If you want to detect
29185 whether such a variable has been set at all, you can initialize it to
29186 TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than
29191 This specifies a fixed point number, such as is used for load averages. The
29192 address should point to a variable of type "int". The value is stored
29193 multiplied by 1000, so, for example, 1.4142 is truncated and stored as
29198 This specifies an integer; the address should point to a variable of type
29199 "int". The value may be specified in any of the integer formats accepted by
29204 This is the same as opt_int, except that when such a value is output in a
29205 -bP listing, if it is an exact number of kilobytes or megabytes, it is
29206 printed with the suffix K or M.
29210 This also specifies an integer, but the value is always interpreted as an
29211 octal integer, whether or not it starts with the digit zero, and it is
29212 always output in octal.
29216 This specifies a string value; the address must be a pointer to a variable
29217 that points to a string (for example, of type "uschar *").
29221 This specifies a time interval value. The address must point to a variable
29222 of type "int". The value that is placed there is a number of seconds.
29224 If the -bP command line option is followed by "local_scan", Exim prints out the
29225 values of all the local_scan() options.
29228 44.4 Available Exim variables
29229 -----------------------------
29231 The header local_scan.h gives you access to a number of C variables. These are
29232 the only ones that are guaranteed to be maintained from release to release.
29233 Note, however, that you can obtain the value of any Exim expansion variable,
29234 including $recipients, by calling expand_string(). The exported C variables are
29239 This variable contains the number of lines in the message's body.
29243 This variable contains the number of binary zero bytes in the message's
29246 unsigned int debug_selector
29248 This variable is set to zero when no debugging is taking place. Otherwise,
29249 it is a bitmap of debugging selectors. Two bits are identified for use in
29250 local_scan(); they are defined as macros:
29252 * The "D_v" bit is set when -v was present on the command line. This is a
29253 testing option that is not privileged - any caller may set it. All the
29254 other selector bits can be set only by admin users.
29256 * The "D_local_scan" bit is provided for use by local_scan(); it is set
29257 by the "+local_scan" debug selector. It is not included in the default
29258 set of debugging bits.
29260 Thus, to write to the debugging output only when "+local_scan" has been
29261 selected, you should use code like this:
29263 if ((debug_selector & D_local_scan) != 0)
29264 debug_printf("xxx", ...);
29266 uschar *expand_string_message
29268 After a failing call to expand_string() (returned value NULL), the variable
29269 expand_string_message contains the error message, zero-terminated.
29271 header_line *header_list
29273 A pointer to a chain of header lines. The header_line structure is
29276 header_line *header_last
29278 A pointer to the last of the header lines.
29280 uschar *headers_charset
29282 The value of the headers_charset configuration option.
29286 This variable is TRUE during a host checking session that is initiated by
29287 the -bh command line option.
29289 uschar *interface_address
29291 The IP address of the interface that received the message, as a string.
29292 This is NULL for locally submitted messages.
29296 The port on which this message was received. When testing with the -bh
29297 command line option, the value of this variable is -1 unless a port has
29298 been specified via the -oMi option.
29302 This variable contains Exim's message id for the incoming message (the
29303 value of $message_exim_id) as a zero-terminated string.
29305 uschar *received_protocol
29307 The name of the protocol by which the message was received.
29309 int recipients_count
29311 The number of accepted recipients.
29313 recipient_item *recipients_list
29315 The list of accepted recipients, held in a vector of length
29316 recipients_count. The recipient_item structure is discussed below. You can
29317 add additional recipients by calling receive_add_recipient() (see below).
29318 You can delete recipients by removing them from the vector and adjusting
29319 the value in recipients_count. In particular, by setting recipients_count
29320 to zero you remove all recipients. If you then return the value
29321 "LOCAL_SCAN_ACCEPT", the message is accepted, but immediately blackholed.
29322 To replace the recipients, you can set recipients_count to zero and then
29323 call receive_add_recipient() as often as needed.
29325 uschar *sender_address
29327 The envelope sender address. For bounce messages this is the empty string.
29329 uschar *sender_host_address
29331 The IP address of the sending host, as a string. This is NULL for
29332 locally-submitted messages.
29334 uschar *sender_host_authenticated
29336 The name of the authentication mechanism that was used, or NULL if the
29337 message was not received over an authenticated SMTP connection.
29339 uschar *sender_host_name
29341 The name of the sending host, if known.
29343 int sender_host_port
29345 The port on the sending host.
29349 This variable is TRUE for all SMTP input, including BSMTP.
29351 BOOL smtp_batched_input
29353 This variable is TRUE for BSMTP input.
29357 The contents of this variable control which pool of memory is used for new
29358 requests. See section 44.8 for details.
29361 44.5 Structure of header lines
29362 ------------------------------
29364 The header_line structure contains the members listed below. You can add
29365 additional header lines by calling the header_add() function (see below). You
29366 can cause header lines to be ignored (deleted) by setting their type to *.
29368 struct header_line *next
29370 A pointer to the next header line, or NULL for the last line.
29374 A code identifying certain headers that Exim recognizes. The codes are
29375 printing characters, and are documented in chapter 55 of this manual.
29376 Notice in particular that any header line whose type is * is not
29377 transmitted with the message. This flagging is used for header lines that
29378 have been rewritten, or are to be removed (for example, Envelope-sender:
29379 header lines.) Effectively, * means "deleted".
29383 The number of characters in the header line, including the terminating and
29384 any internal newlines.
29388 A pointer to the text of the header. It always ends with a newline,
29389 followed by a zero byte. Internal newlines are preserved.
29392 44.6 Structure of recipient items
29393 ---------------------------------
29395 The recipient_item structure contains these members:
29399 This is a pointer to the recipient address as it was received.
29403 This is used in later Exim processing when top level addresses are created
29404 by the one_time option. It is not relevant at the time local_scan() is run
29405 and must always contain -1 at this stage.
29409 If this value is not NULL, bounce messages caused by failing to deliver to
29410 the recipient are sent to the address it contains. In other words, it
29411 overrides the envelope sender for this one recipient. (Compare the
29412 errors_to generic router option.) If a local_scan() function sets an
29413 errors_to field to an unqualified address, Exim qualifies it using the
29414 domain from qualify_recipient. When local_scan() is called, the errors_to
29415 field is NULL for all recipients.
29418 44.7 Available Exim functions
29419 -----------------------------
29421 The header local_scan.h gives you access to a number of Exim functions. These
29422 are the only ones that are guaranteed to be maintained from release to release:
29425 (uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr,
29428 This function creates a child process that runs the command specified by
29429 argv. The environment for the process is specified by envp, which can be
29430 NULL if no environment variables are to be passed. A new umask is supplied
29431 for the process in newumask.
29433 Pipes to the standard input and output of the new process are set up and
29434 returned to the caller via the infdptr and outfdptr arguments. The standard
29435 error is cloned to the standard output. If there are any file descriptors
29436 "in the way" in the new process, they are closed. If the final argument is
29437 TRUE, the new process is made into a process group leader.
29439 The function returns the pid of the new process, or -1 if things go wrong.
29441 int child_close(pid_t pid, int timeout)
29443 This function waits for a child process to terminate, or for a timeout (in
29444 seconds) to expire. A timeout value of zero means wait as long as it takes.
29445 The return value is as follows:
29449 The process terminated by a normal exit and the value is the process
29454 The process was terminated by a signal and the value is the negation of
29459 The process timed out.
29463 The was some other error in wait(); errno is still set.
29465 pid_t child_open_exim(int *fd)
29467 This function provide you with a means of submitting a new message to Exim.
29468 (Of course, you can also call /usr/sbin/sendmail yourself if you want, but
29469 this packages it all up for you.) The function creates a pipe, forks a
29470 subprocess that is running
29472 exim -t -oem -oi -f <>
29474 and returns to you (via the "int *" argument) a file descriptor for the
29475 pipe that is connected to the standard input. The yield of the function is
29476 the PID of the subprocess. You can then write a message to the file
29477 descriptor, with recipients in To:, Cc:, and/or Bcc: header lines.
29479 When you have finished, call child_close() to wait for the process to
29480 finish and to collect its ending status. A timeout value of zero is usually
29481 fine in this circumstance. Unless you have made a mistake with the
29482 recipient addresses, you should get a return code of zero.
29484 pid_t child_open_exim2(int *fd, uschar *sender, uschar *sender_authentication)
29486 This function is a more sophisticated version of child_open(). The command
29489 exim -t -oem -oi -f sender -oMas sender_authentication
29491 The third argument may be NULL, in which case the -oMas option is omitted.
29493 void debug_printf(char *, ...)
29495 This is Exim's debugging function, with arguments as for (printf(). The
29496 output is written to the standard error stream. If no debugging is
29497 selected, calls to debug_printf() have no effect. Normally, you should make
29498 calls conditional on the "local_scan" debug selector by coding like this:
29500 if ((debug_selector & D_local_scan) != 0)
29501 debug_printf("xxx", ...);
29503 uschar *expand_string(uschar *string)
29505 This is an interface to Exim's string expansion code. The return value is
29506 the expanded string, or NULL if there was an expansion failure. The C
29507 variable expand_string_message contains an error message after an expansion
29508 failure. If expansion does not change the string, the return value is the
29509 pointer to the input string. Otherwise, the return value points to a new
29510 block of memory that was obtained by a call to store_get(). See section
29511 44.8 below for a discussion of memory handling.
29513 void header_add(int type, char *format, ...)
29515 This function allows you to an add additional header line at the end of the
29516 existing ones. The first argument is the type, and should normally be a
29517 space character. The second argument is a format string and any number of
29518 substitution arguments as for sprintf(). You may include internal newlines
29519 if you want, and you must ensure that the string ends with a newline.
29521 void header_add_at_position
29522 (BOOL after, uschar *name, BOOL topnot, int type, char *format, ...)
29524 This function adds a new header line at a specified point in the header
29525 chain. The header itself is specified as for header_add().
29527 If name is NULL, the new header is added at the end of the chain if after
29528 is true, or at the start if after is false. If name is not NULL, the header
29529 lines are searched for the first non-deleted header that matches the name.
29530 If one is found, the new header is added before it if after is false. If
29531 after is true, the new header is added after the found header and any
29532 adjacent subsequent ones with the same name (even if marked "deleted"). If
29533 no matching non-deleted header is found, the topnot option controls where
29534 the header is added. If it is true, addition is at the top; otherwise at
29535 the bottom. Thus, to add a header after all the Received: headers, or at
29536 the top if there are no Received: headers, you could use
29538 header_add_at_position(TRUE, US"Received", TRUE,
29539 ' ', "X-xxx: ...");
29541 Normally, there is always at least one non-deleted Received: header, but
29542 there may not be if received_header_text expands to an empty string.
29544 void header_remove(int occurrence, uschar *name)
29546 This function removes header lines. If occurrence is zero or negative, all
29547 occurrences of the header are removed. If occurrence is greater than zero,
29548 that particular instance of the header is removed. If no header(s) can be
29549 found that match the specification, the function does nothing.
29551 BOOL header_testname(header_line *hdr, uschar *name, int length, BOOL notdel)
29553 This function tests whether the given header has the given name. It is not
29554 just a string comparison, because white space is permitted between the name
29555 and the colon. If the notdel argument is true, a false return is forced for
29556 all "deleted" headers; otherwise they are not treated specially. For
29559 if (header_testname(h, US"X-Spam", 6, TRUE)) ...
29561 uschar *lss_b64encode(uschar *cleartext, int length)
29563 This function base64-encodes a string, which is passed by address and
29564 length. The text may contain bytes of any value, including zero. The result
29565 is passed back in dynamic memory that is obtained by calling store_get().
29566 It is zero-terminated.
29568 int lss_b64decode(uschar *codetext, uschar **cleartext)
29570 This function decodes a base64-encoded string. Its arguments are a
29571 zero-terminated base64-encoded string and the address of a variable that is
29572 set to point to the result, which is in dynamic memory. The length of the
29573 decoded string is the yield of the function. If the input is invalid base64
29574 data, the yield is -1. A zero byte is added to the end of the output string
29575 to make it easy to interpret as a C string (assuming it contains no zeros
29576 of its own). The added zero byte is not included in the returned count.
29578 int lss_match_domain(uschar *domain, uschar *list)
29580 This function checks for a match in a domain list. Domains are always
29581 matched caselessly. The return value is one of the following:
29585 DEFER match deferred
29587 DEFER is usually caused by some kind of lookup defer, such as the inability
29588 to contact a database.
29590 int lss_match_local_part(uschar *localpart, uschar *list, BOOL caseless)
29592 This function checks for a match in a local part list. The third argument
29593 controls case-sensitivity. The return values are as for lss_match_domain().
29595 int lss_match_address(uschar *address, uschar *list, BOOL caseless)
29597 This function checks for a match in an address list. The third argument
29598 controls the case-sensitivity of the local part match. The domain is always
29599 matched caselessly. The return values are as for lss_match_domain().
29601 int lss_match_host(uschar *host_name, uschar *host_address, uschar *list)
29603 This function checks for a match in a host list. The most common usage is
29606 lss_match_host(sender_host_name, sender_host_address, ...)
29608 An empty address field matches an empty item in the host list. If the host
29609 name is NULL, the name corresponding to $sender_host_address is
29610 automatically looked up if a host name is required to match an item in the
29611 list. The return values are as for lss_match_domain(), but in addition,
29612 lss_match_host() returns ERROR in the case when it had to look up a host
29613 name, but the lookup failed.
29615 void log_write(unsigned int selector, int which, char *format, ...)
29617 This function writes to Exim's log files. The first argument should be zero
29618 (it is concerned with log_selector). The second argument can be "LOG_MAIN"
29619 or "LOG_REJECT" or "LOG_PANIC" or the inclusive "or" of any combination of
29620 them. It specifies to which log or logs the message is written. The
29621 remaining arguments are a format and relevant insertion arguments. The
29622 string should not contain any newlines, not even at the end.
29624 void receive_add_recipient(uschar *address, int pno)
29626 This function adds an additional recipient to the message. The first
29627 argument is the recipient address. If it is unqualified (has no domain), it
29628 is qualified with the qualify_recipient domain. The second argument must
29631 This function does not allow you to specify a private errors_to address (as
29632 described with the structure of recipient_item above), because it pre-dates
29633 the addition of that field to the structure. However, it is easy to add
29634 such a value afterwards. For example:
29636 receive_add_recipient(US"monitor@mydom.example", -1);
29637 recipients_list[recipients_count-1].errors_to =
29638 US"postmaster@mydom.example";
29640 BOOL receive_remove_recipient(uschar *recipient)
29642 This is a convenience function to remove a named recipient from the list of
29643 recipients. It returns true if a recipient was removed, and false if no
29644 matching recipient could be found. The argument must be a complete email
29647 uschar rfc2047_decode
29648 (uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr,
29651 This function decodes strings that are encoded according to RFC 2047.
29652 Typically these are the contents of header lines. First, each "encoded
29653 word" is decoded from the Q or B encoding into a byte-string. Then, if
29654 provided with the name of a charset encoding, and if the iconv() function
29655 is available, an attempt is made to translate the result to the named
29656 character set. If this fails, the binary string is returned with an error
29659 The first argument is the string to be decoded. If lencheck is TRUE, the
29660 maximum MIME word length is enforced. The third argument is the target
29661 encoding, or NULL if no translation is wanted.
29663 If a binary zero is encountered in the decoded string, it is replaced by
29664 the contents of the zeroval argument. For use with Exim headers, the value
29665 must not be 0 because header lines are handled as zero-terminated strings.
29667 The function returns the result of processing the string, zero-terminated;
29668 if lenptr is not NULL, the length of the result is set in the variable to
29669 which it points. When zeroval is 0, lenptr should not be NULL.
29671 If an error is encountered, the function returns NULL and uses the error
29672 argument to return an error message. The variable pointed to by error is
29673 set to NULL if there is no error; it may be set non-NULL even when the
29674 function returns a non-NULL value if decoding was successful, but there was
29675 a problem with translation.
29677 int smtp_fflush(void)
29679 This function is used in conjunction with smtp_printf(), as described
29682 void smtp_printf(char *, ...)
29684 The arguments of this function are like printf(); it writes to the SMTP
29685 output stream. You should use this function only when there is an SMTP
29686 output stream, that is, when the incoming message is being received via
29687 interactive SMTP. This is the case when smtp_input is TRUE and
29688 smtp_batched_input is FALSE. If you want to test for an incoming message
29689 from another host (as opposed to a local process that used the -bs command
29690 line option), you can test the value of sender_host_address, which is
29691 non-NULL when a remote host is involved.
29693 If an SMTP TLS connection is established, smtp_printf() uses the TLS output
29694 function, so it can be used for all forms of SMTP connection.
29696 Strings that are written by smtp_printf() from within local_scan() must
29697 start with an appropriate response code: 550 if you are going to return
29698 LOCAL_SCAN_REJECT, 451 if you are going to return LOCAL_SCAN_TEMPREJECT,
29699 and 250 otherwise. Because you are writing the initial lines of a
29700 multi-line response, the code must be followed by a hyphen to indicate that
29701 the line is not the final response line. You must also ensure that the
29702 lines you write terminate with CRLF. For example:
29704 smtp_printf("550-this is some extra info\r\n");
29705 return LOCAL_SCAN_REJECT;
29707 Note that you can also create multi-line responses by including newlines in
29708 the data returned via the return_text argument. The added value of using
29709 smtp_printf() is that, for instance, you could introduce delays between
29710 multiple output lines.
29712 The smtp_printf() function does not return any error indication, because it
29713 does not automatically flush pending output, and therefore does not test
29714 the state of the stream. (In the main code of Exim, flushing and error
29715 detection is done when Exim is ready for the next SMTP input command.) If
29716 you want to flush the output and check for an error (for example, the
29717 dropping of a TCP/IP connection), you can call smtp_fflush(), which has no
29718 arguments. It flushes the output stream, and returns a non-zero value if
29721 void *store_get(int)
29723 This function accesses Exim's internal store (memory) manager. It gets a
29724 new chunk of memory whose size is given by the argument. Exim bombs out if
29725 it ever runs out of memory. See the next section for a discussion of memory
29728 void *store_get_perm(int)
29730 This function is like store_get(), but it always gets memory from the
29731 permanent pool. See the next section for a discussion of memory handling.
29733 uschar *string_copy(uschar *string)
29737 uschar *string_copyn(uschar *string, int length)
29741 uschar *string_sprintf(char *format, ...)
29743 These three functions create strings using Exim's dynamic memory
29744 facilities. The first makes a copy of an entire string. The second copies
29745 up to a maximum number of characters, indicated by the second argument. The
29746 third uses a format and insertion arguments to create a new string. In each
29747 case, the result is a pointer to a new string in the current memory pool.
29748 See the next section for more discussion.
29751 44.8 More about Exim's memory handling
29752 --------------------------------------
29754 No function is provided for freeing memory, because that is never needed. The
29755 dynamic memory that Exim uses when receiving a message is automatically
29756 recycled if another message is received by the same process (this applies only
29757 to incoming SMTP connections - other input methods can supply only one message
29758 at a time). After receiving the last message, a reception process terminates.
29760 Because it is recycled, the normal dynamic memory cannot be used for holding
29761 data that must be preserved over a number of incoming messages on the same SMTP
29762 connection. However, Exim in fact uses two pools of dynamic memory; the second
29763 one is not recycled, and can be used for this purpose.
29765 If you want to allocate memory that remains available for subsequent messages
29766 in the same SMTP connection, you should set
29768 store_pool = POOL_PERM
29770 before calling the function that does the allocation. There is no need to
29771 restore the value if you do not need to; however, if you do want to revert to
29772 the normal pool, you can either restore the previous value of store_pool or set
29773 it explicitly to POOL_MAIN.
29775 The pool setting applies to all functions that get dynamic memory, including
29776 expand_string(), store_get(), and the string_xxx() functions. There is also a
29777 convenience function called store_get_perm() that gets a block of memory from
29778 the permanent pool while preserving the value of store_pool.
29782 ===============================================================================
29783 45. SYSTEM-WIDE MESSAGE FILTERING
29785 The previous chapters (on ACLs and the local scan function) describe checks
29786 that can be applied to messages before they are accepted by a host. There is
29787 also a mechanism for checking messages once they have been received, but before
29788 they are delivered. This is called the system filter.
29790 The system filter operates in a similar manner to users' filter files, but it
29791 is run just once per message (however many recipients the message has). It
29792 should not normally be used as a substitute for routing, because deliver
29793 commands in a system router provide new envelope recipient addresses. The
29794 system filter must be an Exim filter. It cannot be a Sieve filter.
29796 The system filter is run at the start of a delivery attempt, before any routing
29797 is done. If a message fails to be completely delivered at the first attempt,
29798 the system filter is run again at the start of every retry. If you want your
29799 filter to do something only once per message, you can make use of the
29800 first_delivery condition in an if command in the filter to prevent it happening
29803 Warning: Because the system filter runs just once, variables that are specific
29804 to individual recipient addresses, such as $local_part and $domain, are not
29805 set, and the "personal" condition is not meaningful. If you want to run a
29806 centrally-specified filter for each recipient address independently, you can do
29807 so by setting up a suitable redirect router, as described in section 45.8
29811 45.1 Specifying a system filter
29812 -------------------------------
29814 The name of the file that contains the system filter must be specified by
29815 setting system_filter. If you want the filter to run under a uid and gid other
29816 than root, you must also set system_filter_user and system_filter_group as
29817 appropriate. For example:
29819 system_filter = /etc/mail/exim.filter
29820 system_filter_user = exim
29822 If a system filter generates any deliveries directly to files or pipes (via the
29823 save or pipe commands), transports to handle these deliveries must be specified
29824 by setting system_filter_file_transport and system_filter_pipe_transport,
29825 respectively. Similarly, system_filter_reply_transport must be set to handle
29826 any messages generated by the reply command.
29829 45.2 Testing a system filter
29830 ----------------------------
29832 You can run simple tests of a system filter in the same way as for a user
29833 filter, but you should use -bF rather than -bf, so that features that are
29834 permitted only in system filters are recognized.
29836 If you want to test the combined effect of a system filter and a user filter,
29837 you can use both -bF and -bf on the same command line.
29840 45.3 Contents of a system filter
29841 --------------------------------
29843 The language used to specify system filters is the same as for users' filter
29844 files. It is described in the separate end-user document Exim's interface to
29845 mail filtering. However, there are some additional features that are available
29846 only in system filters; these are described in subsequent sections. If they are
29847 encountered in a user's filter file or when testing with -bf, they cause
29850 There are two special conditions which, though available in users' filter
29851 files, are designed for use in system filters. The condition first_delivery is
29852 true only for the first attempt at delivering a message, and manually_thawed is
29853 true only if the message has been frozen, and subsequently thawed by an admin
29854 user. An explicit forced delivery counts as a manual thaw, but thawing as a
29855 result of the auto_thaw setting does not.
29857 Warning: If a system filter uses the first_delivery condition to specify an
29858 "unseen" (non-significant) delivery, and that delivery does not succeed, it
29859 will not be tried again. If you want Exim to retry an unseen delivery until it
29860 succeeds, you should arrange to set it up every time the filter runs.
29862 When a system filter finishes running, the values of the variables $n0 - $n9
29863 are copied into $sn0 - $sn9 and are thereby made available to users' filter
29864 files. Thus a system filter can, for example, set up "scores" to which users'
29865 filter files can refer.
29868 45.4 Additional variable for system filters
29869 -------------------------------------------
29871 The expansion variable $recipients, containing a list of all the recipients of
29872 the message (separated by commas and white space), is available in system
29873 filters. It is not available in users' filters for privacy reasons.
29876 45.5 Defer, freeze, and fail commands for system filters
29877 --------------------------------------------------------
29879 There are three extra commands (defer, freeze and fail) which are always
29880 available in system filters, but are not normally enabled in users' filters.
29881 (See the allow_defer, allow_freeze and allow_fail options for the redirect
29882 router.) These commands can optionally be followed by the word text and a
29883 string containing an error message, for example:
29885 fail text "this message looks like spam to me"
29887 The keyword text is optional if the next character is a double quote.
29889 The defer command defers delivery of the original recipients of the message.
29890 The fail command causes all the original recipients to be failed, and a bounce
29891 message to be created. The freeze command suspends all delivery attempts for
29892 the original recipients. In all cases, any new deliveries that are specified by
29893 the filter are attempted as normal after the filter has run.
29895 The freeze command is ignored if the message has been manually unfrozen and not
29896 manually frozen since. This means that automatic freezing by a system filter
29897 can be used as a way of checking out suspicious messages. If a message is found
29898 to be all right, manually unfreezing it allows it to be delivered.
29900 The text given with a fail command is used as part of the bounce message as
29901 well as being written to the log. If the message is quite long, this can fill
29902 up a lot of log space when such failures are common. To reduce the size of the
29903 log message, Exim interprets the text in a special way if it starts with the
29904 two characters "<<" and contains ">>" later. The text between these two strings
29905 is written to the log, and the rest of the text is used in the bounce message.
29908 fail "<<filter test 1>>Your message is rejected \
29909 because it contains attachments that we are \
29910 not prepared to receive."
29912 Take great care with the fail command when basing the decision to fail on the
29913 contents of the message, because the bounce message will of course include the
29914 contents of the original message and will therefore trigger the fail command
29915 again (causing a mail loop) unless steps are taken to prevent this. Testing the
29916 error_message condition is one way to prevent this. You could use, for example
29918 if $message_body contains "this is spam" and not error_message
29919 then fail text "spam is not wanted here" endif
29921 though of course that might let through unwanted bounce messages. The
29922 alternative is clever checking of the body and/or headers to detect bounces
29923 generated by the filter.
29925 The interpretation of a system filter file ceases after a defer, freeze, or
29926 fail command is obeyed. However, any deliveries that were set up earlier in the
29927 filter file are honoured, so you can use a sequence such as
29932 to send a specified message when the system filter is freezing (or deferring or
29933 failing) a message. The normal deliveries for the message do not, of course,
29937 45.6 Adding and removing headers in a system filter
29938 ---------------------------------------------------
29940 Two filter commands that are available only in system filters are:
29942 headers add <string>
29943 headers remove <string>
29945 The argument for the headers add is a string that is expanded and then added to
29946 the end of the message's headers. It is the responsibility of the filter
29947 maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is
29948 ignored, and if the string is otherwise empty, or if the expansion is forced to
29949 fail, the command has no effect.
29951 You can use "\n" within the string, followed by white space, to specify
29952 continued header lines. More than one header may be added in one command by
29953 including "\n" within the string without any following white space. For
29956 headers add "X-header-1: ....\n \
29957 continuation of X-header-1 ...\n\
29960 Note that the header line continuation white space after the first newline must
29961 be placed before the backslash that continues the input string, because white
29962 space after input continuations is ignored.
29964 The argument for headers remove is a colon-separated list of header names. This
29965 command applies only to those headers that are stored with the message; those
29966 that are added at delivery time (such as Envelope-To: and Return-Path:) cannot
29967 be removed by this means. If there is more than one header with the same name,
29968 they are all removed.
29970 The headers command in a system filter makes an immediate change to the set of
29971 header lines that was received with the message (with possible additions from
29972 ACL processing). Subsequent commands in the system filter operate on the
29973 modified set, which also forms the basis for subsequent message delivery.
29974 Unless further modified during routing or transporting, this set of headers is
29975 used for all recipients of the message.
29977 During routing and transporting, the variables that refer to the contents of
29978 header lines refer only to those lines that are in this set. Thus, header lines
29979 that are added by a system filter are visible to users' filter files and to all
29980 routers and transports. This contrasts with the manipulation of header lines by
29981 routers and transports, which is not immediate, but which instead is saved up
29982 until the message is actually being written (see section 46.17).
29984 If the message is not delivered at the first attempt, header lines that were
29985 added by the system filter are stored with the message, and so are still
29986 present at the next delivery attempt. Header lines that were removed are still
29987 present, but marked "deleted" so that they are not transported with the
29988 message. For this reason, it is usual to make the headers command conditional
29989 on first_delivery so that the set of header lines is not modified more than
29992 Because header modification in a system filter acts immediately, you have to
29993 use an indirect approach if you want to modify the contents of a header line.
29996 headers add "Old-Subject: $h_subject:"
29997 headers remove "Subject"
29998 headers add "Subject: new subject (was: $h_old-subject:)"
29999 headers remove "Old-Subject"
30002 45.7 Setting an errors address in a system filter
30003 -------------------------------------------------
30005 In a system filter, if a deliver command is followed by
30007 errors_to <some address>
30009 in order to change the envelope sender (and hence the error reporting) for that
30010 delivery, any address may be specified. (In a user filter, only the current
30011 user's address can be set.) For example, if some mail is being monitored, you
30014 unseen deliver monitor@spying.example errors_to root@local.example
30016 to take a copy which would not be sent back to the normal error reporting
30017 address if its delivery failed.
30020 45.8 Per-address filtering
30021 --------------------------
30023 In contrast to the system filter, which is run just once per message for each
30024 delivery attempt, it is also possible to set up a system-wide filtering
30025 operation that runs once for each recipient address. In this case, variables
30026 such as $local_part and $domain can be used, and indeed, the choice of filter
30027 file could be made dependent on them. This is an example of a router which
30028 implements such a filter:
30033 domains = +local_domains
30034 file = /central/filters/$local_part
30039 The filter is run in a separate process under its own uid. Therefore, either
30040 check_local_user must be set (as above), in which case the filter is run as the
30041 local user, or the user option must be used to specify which user to use. If
30042 both are set, user overrides.
30044 Care should be taken to ensure that none of the commands in the filter file
30045 specify a significant delivery if the message is to go on to be delivered to
30046 its intended recipient. The router will not then claim to have dealt with the
30047 address, so it will be passed on to subsequent routers to be delivered in the
30052 ===============================================================================
30053 46. MESSAGE PROCESSING
30055 Exim performs various transformations on the sender and recipient addresses of
30056 all messages that it handles, and also on the messages' header lines. Some of
30057 these are optional and configurable, while others always take place. All of
30058 this processing, except rewriting as a result of routing, and the addition or
30059 removal of header lines while delivering, happens when a message is received,
30060 before it is placed on Exim's queue.
30062 Some of the automatic processing takes place by default only for
30063 "locally-originated" messages. This adjective is used to describe messages that
30064 are not received over TCP/IP, but instead are passed to an Exim process on its
30065 standard input. This includes the interactive "local SMTP" case that is set up
30066 by the -bs command line option.
30068 Note: Messages received over TCP/IP on the loopback interface (127.0.0.1 or
30069 ::1) are not considered to be locally-originated. Exim does not treat the
30070 loopback interface specially in any way.
30072 If you want the loopback interface to be treated specially, you must ensure
30073 that there are appropriate entries in your ACLs.
30076 46.1 Submission mode for non-local messages
30077 -------------------------------------------
30079 Processing that happens automatically for locally-originated messages (unless
30080 suppress_local_fixups is set) can also be requested for messages that are
30081 received over TCP/IP. The term "submission mode" is used to describe this
30082 state. Submission mode is set by the modifier
30084 control = submission
30086 in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 42.21
30087 and 42.22). This makes Exim treat the message as a local submission, and is
30088 normally used when the source of the message is known to be an MUA running on a
30089 client host (as opposed to an MTA). For example, to set submission mode for
30090 messages originating on the IPv4 loopback interface, you could include the
30091 following in the MAIL ACL:
30093 warn hosts = 127.0.0.1
30094 control = submission
30096 There are some options that can be used when setting submission mode. A slash
30097 is used to separate options. For example:
30099 control = submission/sender_retain
30101 Specifying sender_retain has the effect of setting local_sender_retain true and
30102 local_from_check false for the current incoming message. The first of these
30103 allows an existing Sender: header in the message to remain, and the second
30104 suppresses the check to ensure that From: matches the authenticated sender.
30105 With this setting, Exim still fixes up messages by adding Date: and Message-ID:
30106 header lines if they are missing, but makes no attempt to check sender
30107 authenticity in header lines.
30109 When sender_retain is not set, a submission mode setting may specify a domain
30110 to be used when generating a From: or Sender: header line. For example:
30112 control = submission/domain=some.domain
30114 The domain may be empty. How this value is used is described in sections 46.11
30115 and 46.16. There is also a name option that allows you to specify the user's
30116 full name for inclusion in a created Sender: or From: header line. For example:
30118 accept authenticated = *
30119 control = submission/domain=wonderland.example/\
30120 name=${lookup {$authenticated_id} \
30121 lsearch {/etc/exim/namelist}}
30123 Because the name may contain any characters, including slashes, the name option
30124 must be given last. The remainder of the string is used as the name. For the
30125 example above, if /etc/exim/namelist contains:
30127 bigegg: Humpty Dumpty
30129 then when the sender has authenticated as bigegg, the generated Sender: line
30132 Sender: Humpty Dumpty <bigegg@wonderland.example>
30134 By default, submission mode forces the return path to the same address as is
30135 used to create the Sender: header. However, if sender_retain is specified, the
30136 return path is also left unchanged.
30138 Note: The changes caused by submission mode take effect after the predata ACL.
30139 This means that any sender checks performed before the fix-ups use the
30140 untrusted sender address specified by the user, not the trusted sender address
30141 specified by submission mode. Although this might be slightly unexpected, it
30142 does mean that you can configure ACL checks to spot that a user is trying to
30143 spoof another's address.
30149 RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
30150 linefeed) is the line ending for messages transmitted over the Internet using
30151 SMTP over TCP/IP. However, within individual operating systems, different
30152 conventions are used. For example, Unix-like systems use just LF, but others
30153 use CRLF or just CR.
30155 Exim was designed for Unix-like systems, and internally, it stores messages
30156 using the system's convention of a single LF as a line terminator. When
30157 receiving a message, all line endings are translated to this standard format.
30158 Originally, it was thought that programs that passed messages directly to an
30159 MTA within an operating system would use that system's convention. Experience
30160 has shown that this is not the case; for example, there are Unix applications
30161 that use CRLF in this circumstance. For this reason, and for compatibility with
30162 other MTAs, the way Exim handles line endings for all messages is now as
30165 * LF not preceded by CR is treated as a line ending.
30167 * CR is treated as a line ending; if it is immediately followed by LF, the LF
30170 * The sequence "CR, dot, CR" does not terminate an incoming SMTP message, nor
30171 a local message in the state where a line containing only a dot is a
30174 * If a bare CR is encountered within a header line, an extra space is added
30175 after the line terminator so as not to end the header line. The reasoning
30176 behind this is that bare CRs in header lines are most likely either to be
30177 mistakes, or people trying to play silly games.
30179 * If the first header line received in a message ends with CRLF, a subsequent
30180 bare LF in a header line is treated in the same way as a bare CR in a
30184 46.3 Unqualified addresses
30185 --------------------------
30187 By default, Exim expects every envelope address it receives from an external
30188 host to be fully qualified. Unqualified addresses cause negative responses to
30189 SMTP commands. However, because SMTP is used as a means of transporting
30190 messages from MUAs running on personal workstations, there is sometimes a
30191 requirement to accept unqualified addresses from specific hosts or IP networks.
30193 Exim has two options that separately control which hosts may send unqualified
30194 sender or recipient addresses in SMTP commands, namely sender_unqualified_hosts
30195 and recipient_unqualified_hosts. In both cases, if an unqualified address is
30196 accepted, it is qualified by adding the value of qualify_domain or
30197 qualify_recipient, as appropriate.
30199 Unqualified addresses in header lines are automatically qualified for messages
30200 that are locally originated, unless the -bnq option is given on the command
30201 line. For messages received over SMTP, unqualified addresses in header lines
30202 are qualified only if unqualified addresses are permitted in SMTP commands. In
30203 other words, such qualification is also controlled by sender_unqualified_hosts
30204 and recipient_unqualified_hosts,
30207 46.4 The UUCP From line
30208 -----------------------
30210 Messages that have come from UUCP (and some other applications) often begin
30211 with a line containing the envelope sender and a timestamp, following the word
30212 "From". Examples of two common formats are:
30214 From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996
30215 From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT
30217 This line precedes the RFC 2822 header lines. For compatibility with Sendmail,
30218 Exim recognizes such lines at the start of messages that are submitted to it
30219 via the command line (that is, on the standard input). It does not recognize
30220 such lines in incoming SMTP messages, unless the sending host matches
30221 ignore_fromline_hosts or the -bs option was used for a local message and
30222 ignore_fromline_local is set. The recognition is controlled by a regular
30223 expression that is defined by the uucp_from_pattern option, whose default value
30224 matches the two common cases shown above and puts the address that follows
30227 When the caller of Exim for a non-SMTP message that contains a "From" line is a
30228 trusted user, the message's sender address is constructed by expanding the
30229 contents of uucp_sender_address, whose default value is "$1". This is then
30230 parsed as an RFC 2822 address. If there is no domain, the local part is
30231 qualified with qualify_domain unless it is the empty string. However, if the
30232 command line -f option is used, it overrides the "From" line.
30234 If the caller of Exim is not trusted, the "From" line is recognized, but the
30235 sender address is not changed. This is also the case for incoming SMTP messages
30236 that are permitted to contain "From" lines.
30238 Only one "From" line is recognized. If there is more than one, the second is
30239 treated as a data line that starts the body of the message, as it is not valid
30240 as a header line. This also happens if a "From" line is present in an incoming
30241 SMTP message from a source that is not permitted to send them.
30244 46.5 Resent- header lines
30245 -------------------------
30247 RFC 2822 makes provision for sets of header lines starting with the string
30248 "Resent-" to be added to a message when it is resent by the original recipient
30249 to somebody else. These headers are Resent-Date:, Resent-From:, Resent-Sender:,
30250 Resent-To:, Resent-Cc:, Resent-Bcc: and Resent-Message-ID:. The RFC says:
30252 Resent fields are strictly informational. They MUST NOT be used in the
30253 normal processing of replies or other such automatic actions on messages.
30255 This leaves things a bit vague as far as other processing actions such as
30256 address rewriting are concerned. Exim treats Resent- header lines as follows:
30258 * A Resent-From: line that just contains the login id of the submitting user
30259 is automatically rewritten in the same way as From: (see below).
30261 * If there's a rewriting rule for a particular header line, it is also
30262 applied to Resent- header lines of the same type. For example, a rule that
30263 rewrites From: also rewrites Resent-From:.
30265 * For local messages, if Sender: is removed on input, Resent-Sender: is also
30268 * For a locally-submitted message, if there are any Resent- header lines but
30269 no Resent-Date:, Resent-From:, or Resent-Message-Id:, they are added as
30270 necessary. It is the contents of Resent-Message-Id: (rather than
30271 Message-Id:) which are included in log lines in this case.
30273 * The logic for adding Sender: is duplicated for Resent-Sender: when any
30274 Resent- header lines are present.
30277 46.6 The Auto-Submitted: header line
30278 ------------------------------------
30280 Whenever Exim generates an autoreply, a bounce, or a delay warning message, it
30281 includes the header line:
30283 Auto-Submitted: auto-replied
30286 46.7 The Bcc: header line
30287 -------------------------
30289 If Exim is called with the -t option, to take recipient addresses from a
30290 message's header, it removes any Bcc: header line that may exist (after
30291 extracting its addresses). If -t is not present on the command line, any
30292 existing Bcc: is not removed.
30295 46.8 The Date: header line
30296 --------------------------
30298 If a locally-generated or submission-mode message has no Date: header line,
30299 Exim adds one, using the current date and time, unless the
30300 suppress_local_fixups control has been specified.
30303 46.9 The Delivery-date: header line
30304 -----------------------------------
30306 Delivery-date: header lines are not part of the standard RFC 2822 header set.
30307 Exim can be configured to add them to the final delivery of messages. (See the
30308 generic delivery_date_add transport option.) They should not be present in
30309 messages in transit. If the delivery_date_remove configuration option is set
30310 (the default), Exim removes Delivery-date: header lines from incoming messages.
30313 46.10 The Envelope-to: header line
30314 ----------------------------------
30316 Envelope-to: header lines are not part of the standard RFC 2822 header set.
30317 Exim can be configured to add them to the final delivery of messages. (See the
30318 generic envelope_to_add transport option.) They should not be present in
30319 messages in transit. If the envelope_to_remove configuration option is set (the
30320 default), Exim removes Envelope-to: header lines from incoming messages.
30323 46.11 The From: header line
30324 ---------------------------
30326 If a submission-mode message does not contain a From: header line, Exim adds
30327 one if either of the following conditions is true:
30329 * The envelope sender address is not empty (that is, this is not a bounce
30330 message). The added header line copies the envelope sender address.
30332 * The SMTP session is authenticated and $authenticated_id is not empty.
30334 1. If no domain is specified by the submission control, the local part is
30335 $authenticated_id and the domain is $qualify_domain.
30337 2. If a non-empty domain is specified by the submission control, the local
30338 part is $authenticated_id, and the domain is the specified domain.
30340 3. If an empty domain is specified by the submission control,
30341 $authenticated_id is assumed to be the complete address.
30343 A non-empty envelope sender takes precedence.
30345 If a locally-generated incoming message does not contain a From: header line,
30346 and the suppress_local_fixups control is not set, Exim adds one containing the
30347 sender's address. The calling user's login name and full name are used to
30348 construct the address, as described in section 46.18. They are obtained from
30349 the password data by calling getpwuid() (but see the unknown_login
30350 configuration option). The address is qualified with qualify_domain.
30352 For compatibility with Sendmail, if an incoming, non-SMTP message has a From:
30353 header line containing just the unqualified login name of the calling user,
30354 this is replaced by an address containing the user's login name and full name
30355 as described in section 46.18.
30358 46.12 The Message-ID: header line
30359 ---------------------------------
30361 If a locally-generated or submission-mode incoming message does not contain a
30362 Message-ID: or Resent-Message-ID: header line, and the suppress_local_fixups
30363 control is not set, Exim adds a suitable header line to the message. If there
30364 are any Resent-: headers in the message, it creates Resent-Message-ID:. The id
30365 is constructed from Exim's internal message id, preceded by the letter E to
30366 ensure it starts with a letter, and followed by @ and the primary host name.
30367 Additional information can be included in this header line by setting the
30368 message_id_header_text and/or message_id_header_domain options.
30371 46.13 The Received: header line
30372 -------------------------------
30374 A Received: header line is added at the start of every message. The contents
30375 are defined by the received_header_text configuration option, and Exim
30376 automatically adds a semicolon and a timestamp to the configured string.
30378 The Received: header is generated as soon as the message's header lines have
30379 been received. At this stage, the timestamp in the Received: header line is the
30380 time that the message started to be received. This is the value that is seen by
30381 the DATA ACL and by the local_scan() function.
30383 Once a message is accepted, the timestamp in the Received: header line is
30384 changed to the time of acceptance, which is (apart from a small delay while the
30385 -H spool file is written) the earliest time at which delivery could start.
30388 46.14 The References: header line
30389 ---------------------------------
30391 Messages created by the autoreply transport include a References: header line.
30392 This is constructed according to the rules that are described in section 3.64
30393 of RFC 2822 (which states that replies should contain such a header line), and
30394 section 3.14 of RFC 3834 (which states that automatic responses are not
30395 different in this respect). However, because some mail processing software does
30396 not cope well with very long header lines, no more than 12 message IDs are
30397 copied from the References: header line in the incoming message. If there are
30398 more than 12, the first one and then the final 11 are copied, before adding the
30399 message ID of the incoming message.
30402 46.15 The Return-path: header line
30403 ----------------------------------
30405 Return-path: header lines are defined as something an MTA may insert when it
30406 does the final delivery of messages. (See the generic return_path_add transport
30407 option.) Therefore, they should not be present in messages in transit. If the
30408 return_path_remove configuration option is set (the default), Exim removes
30409 Return-path: header lines from incoming messages.
30412 46.16 The Sender: header line
30413 -----------------------------
30415 For a locally-originated message from an untrusted user, Exim may remove an
30416 existing Sender: header line, and it may add a new one. You can modify these
30417 actions by setting the local_sender_retain option true, the local_from_check
30418 option false, or by using the suppress_local_fixups control setting.
30420 When a local message is received from an untrusted user and local_from_check is
30421 true (the default), and the suppress_local_fixups control has not been set, a
30422 check is made to see if the address given in the From: header line is the
30423 correct (local) sender of the message. The address that is expected has the
30424 login name as the local part and the value of qualify_domain as the domain.
30425 Prefixes and suffixes for the local part can be permitted by setting
30426 local_from_prefix and local_from_suffix appropriately. If From: does not
30427 contain the correct sender, a Sender: line is added to the message.
30429 If you set local_from_check false, this checking does not occur. However, the
30430 removal of an existing Sender: line still happens, unless you also set
30431 local_sender_retain to be true. It is not possible to set both of these options
30432 true at the same time.
30434 By default, no processing of Sender: header lines is done for messages received
30435 over TCP/IP or for messages submitted by trusted users. However, when a message
30436 is received over TCP/IP in submission mode, and sender_retain is not specified
30437 on the submission control, the following processing takes place:
30439 First, any existing Sender: lines are removed. Then, if the SMTP session is
30440 authenticated, and $authenticated_id is not empty, a sender address is created
30443 * If no domain is specified by the submission control, the local part is
30444 $authenticated_id and the domain is $qualify_domain.
30446 * If a non-empty domain is specified by the submission control, the local
30447 part is $authenticated_id, and the domain is the specified domain.
30449 * If an empty domain is specified by the submission control,
30450 $authenticated_id is assumed to be the complete address.
30452 This address is compared with the address in the From: header line. If they are
30453 different, a Sender: header line containing the created address is added.
30454 Prefixes and suffixes for the local part in From: can be permitted by setting
30455 local_from_prefix and local_from_suffix appropriately.
30457 Note: Whenever a Sender: header line is created, the return path for the
30458 message (the envelope sender address) is changed to be the same address, except
30459 in the case of submission mode when sender_retain is specified.
30462 46.17 Adding and removing header lines in routers and transports
30463 ----------------------------------------------------------------
30465 When a message is delivered, the addition and removal of header lines can be
30466 specified in a system filter, or on any of the routers and transports that
30467 process the message. Section 45.6 contains details about modifying headers in a
30468 system filter. Header lines can also be added in an ACL as a message is
30469 received (see section 42.24).
30471 In contrast to what happens in a system filter, header modifications that are
30472 specified on routers and transports apply only to the particular recipient
30473 addresses that are being processed by those routers and transports. These
30474 changes do not actually take place until a copy of the message is being
30475 transported. Therefore, they do not affect the basic set of header lines, and
30476 they do not affect the values of the variables that refer to header lines.
30478 Note: In particular, this means that any expansions in the configuration of the
30479 transport cannot refer to the modified header lines, because such expansions
30480 all occur before the message is actually transported.
30482 For both routers and transports, the argument of a headers_add option must be
30483 in the form of one or more RFC 2822 header lines, separated by newlines (coded
30484 as "\n"). For example:
30486 headers_add = X-added-header: added by $primary_hostname\n\
30487 X-added-second: another added header line
30489 Exim does not check the syntax of these added header lines.
30491 Multiple headers_add options for a single router or transport can be specified;
30492 the values will append to a single list of header lines. Each header-line is
30493 separately expanded.
30495 The argument of a headers_remove option must consist of a colon-separated list
30496 of header names. This is confusing, because header names themselves are often
30497 terminated by colons. In this case, the colons are the list separators, not
30498 part of the names. For example:
30500 headers_remove = return-receipt-to:acknowledge-to
30502 Multiple headers_remove options for a single router or transport can be
30503 specified; the arguments will append to a single header-names list. Each item
30504 is separately expanded.
30506 When headers_add or headers_remove is specified on a router, items are expanded
30507 at routing time, and then associated with all addresses that are accepted by
30508 that router, and also with any new addresses that it generates. If an address
30509 passes through several routers as a result of aliasing or forwarding, the
30510 changes are cumulative.
30512 However, this does not apply to multiple routers that result from the use of
30513 the unseen option. Any header modifications that were specified by the "unseen"
30514 router or its predecessors apply only to the "unseen" delivery.
30516 Addresses that end up with different headers_add or headers_remove settings
30517 cannot be delivered together in a batch, so a transport is always dealing with
30518 a set of addresses that have the same header-processing requirements.
30520 The transport starts by writing the original set of header lines that arrived
30521 with the message, possibly modified by the system filter. As it writes out
30522 these lines, it consults the list of header names that were attached to the
30523 recipient address(es) by headers_remove options in routers, and it also
30524 consults the transport's own headers_remove option. Header lines whose names
30525 are on either of these lists are not written out. If there are multiple
30526 instances of any listed header, they are all skipped.
30528 After the remaining original header lines have been written, new header lines
30529 that were specified by routers' headers_add options are written, in the order
30530 in which they were attached to the address. These are followed by any header
30531 lines specified by the transport's headers_add option.
30533 This way of handling header line modifications in routers and transports has
30534 the following consequences:
30536 * The original set of header lines, possibly modified by the system filter,
30537 remains "visible", in the sense that the $header_xxx variables refer to it,
30540 * Header lines that are added by a router's headers_add option are not
30541 accessible by means of the $header_xxx expansion syntax in subsequent
30542 routers or the transport.
30544 * Conversely, header lines that are specified for removal by headers_remove
30545 in a router remain visible to subsequent routers and the transport.
30547 * Headers added to an address by headers_add in a router cannot be removed by
30548 a later router or by a transport.
30550 * An added header can refer to the contents of an original header that is to
30551 be removed, even it has the same name as the added header. For example:
30553 headers_remove = subject
30554 headers_add = Subject: new subject (was: $h_subject:)
30556 Warning: The headers_add and headers_remove options cannot be used for a
30557 redirect router that has the one_time option set.
30560 46.18 Constructed addresses
30561 ---------------------------
30563 When Exim constructs a sender address for a locally-generated message, it uses
30566 <user name> <login@qualify_domain>
30570 Zaphod Beeblebrox <zaphod@end.univ.example>
30572 The user name is obtained from the -F command line option if set, or otherwise
30573 by looking up the calling user by getpwuid() and extracting the "gecos" field
30574 from the password entry. If the "gecos" field contains an ampersand character,
30575 this is replaced by the login name with the first letter upper cased, as is
30576 conventional in a number of operating systems. See the gecos_name option for a
30577 way to tailor the handling of the "gecos" field. The unknown_username option
30578 can be used to specify user names in cases when there is no password file
30581 In all cases, the user name is made to conform to RFC 2822 by quoting all or
30582 parts of it if necessary. In addition, if it contains any non-printing
30583 characters, it is encoded as described in RFC 2047, which defines a way of
30584 including non-ASCII characters in header lines. The value of the
30585 headers_charset option specifies the name of the encoding that is used (the
30586 characters are assumed to be in this encoding). The setting of
30587 print_topbitchars controls whether characters with the top bit set (that is,
30588 with codes greater than 127) count as printing characters or not.
30591 46.19 Case of local parts
30592 -------------------------
30594 RFC 2822 states that the case of letters in the local parts of addresses cannot
30595 be assumed to be non-significant. Exim preserves the case of local parts of
30596 addresses, but by default it uses a lower-cased form when it is routing,
30597 because on most Unix systems, usernames are in lower case and case-insensitive
30598 routing is required. However, any particular router can be made to use the
30599 original case for local parts by setting the caseful_local_part generic router
30602 If you must have mixed-case user names on your system, the best way to proceed,
30603 assuming you want case-independent handling of incoming email, is to set up
30604 your first router to convert incoming local parts in your domains to the
30605 correct case by means of a file lookup. For example:
30609 domains = +local_domains
30610 data = ${lookup{$local_part}cdb\
30611 {/etc/usercased.cdb}{$value}fail}\
30614 For this router, the local part is forced to lower case by the default action (
30615 caseful_local_part is not set). The lower-cased local part is used to look up a
30616 new local part in the correct case. If you then set caseful_local_part on any
30617 subsequent routers which process your domains, they will operate on local parts
30618 with the correct case in a case-sensitive manner.
30621 46.20 Dots in local parts
30622 -------------------------
30624 RFC 2822 forbids empty components in local parts. That is, an unquoted local
30625 part may not begin or end with a dot, nor have two consecutive dots in the
30626 middle. However, it seems that many MTAs do not enforce this, so Exim permits
30627 empty components for compatibility.
30630 46.21 Rewriting addresses
30631 -------------------------
30633 Rewriting of sender and recipient addresses, and addresses in headers, can
30634 happen automatically, or as the result of configuration options, as described
30635 in chapter 31. The headers that may be affected by this are Bcc:, Cc:, From:,
30636 Reply-To:, Sender:, and To:.
30638 Automatic rewriting includes qualification, as mentioned above. The other case
30639 in which it can happen is when an incomplete non-local domain is given. The
30640 routing process may cause this to be expanded into the full domain name. For
30641 example, a header such as
30645 might get rewritten as
30647 To: hare@teaparty.wonderland.fict.example
30649 Rewriting as a result of routing is the one kind of message processing that
30650 does not happen at input time, as it cannot be done until the address has been
30653 Strictly, one should not do any deliveries of a message until all its addresses
30654 have been routed, in case any of the headers get changed as a result of
30655 routing. However, doing this in practice would hold up many deliveries for
30656 unreasonable amounts of time, just because one address could not immediately be
30657 routed. Exim therefore does not delay other deliveries when routing of one or
30658 more addresses is deferred.
30662 ===============================================================================
30663 47. SMTP PROCESSING
30665 Exim supports a number of different ways of using the SMTP protocol, and its
30666 LMTP variant, which is an interactive protocol for transferring messages into a
30667 closed mail store application. This chapter contains details of how SMTP is
30668 processed. For incoming mail, the following are available:
30670 * SMTP over TCP/IP (Exim daemon or inetd);
30672 * SMTP over the standard input and output (the -bs option);
30674 * Batched SMTP on the standard input (the -bS option).
30676 For mail delivery, the following are available:
30678 * SMTP over TCP/IP (the smtp transport);
30680 * LMTP over TCP/IP (the smtp transport with the protocol option set to
30683 * LMTP over a pipe to a process running in the local host (the lmtp
30686 * Batched SMTP to a file or pipe (the appendfile and pipe transports with the
30687 use_bsmtp option set).
30689 Batched SMTP is the name for a process in which batches of messages are stored
30690 in or read from files (or pipes), in a format in which SMTP commands are used
30691 to contain the envelope information.
30694 47.1 Outgoing SMTP and LMTP over TCP/IP
30695 ---------------------------------------
30697 Outgoing SMTP and LMTP over TCP/IP is implemented by the smtp transport. The
30698 protocol option selects which protocol is to be used, but the actual processing
30699 is the same in both cases.
30701 If, in response to its EHLO command, Exim is told that the SIZE parameter is
30702 supported, it adds SIZE=<n> to each subsequent MAIL command. The value of <n>
30703 is the message size plus the value of the size_addition option (default 1024)
30704 to allow for additions to the message such as per-transport header lines, or
30705 changes made in a transport filter. If size_addition is set negative, the use
30706 of SIZE is suppressed.
30708 If the remote server advertises support for PIPELINING, Exim uses the
30709 pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets
30710 required for the transaction.
30712 If the remote server advertises support for the STARTTLS command, and Exim was
30713 built to support TLS encryption, it tries to start a TLS session unless the
30714 server matches hosts_avoid_tls. See chapter 41 for more details. Either a match
30715 in that or hosts_verify_avoid_tls apply when the transport is called for
30718 If the remote server advertises support for the AUTH command, Exim scans the
30719 authenticators configuration for any suitable client settings, as described in
30722 Responses from the remote host are supposed to be terminated by CR followed by
30723 LF. However, there are known to be hosts that do not send CR characters, so in
30724 order to be able to interwork with such hosts, Exim treats LF on its own as a
30727 If a message contains a number of different addresses, all those with the same
30728 characteristics (for example, the same envelope sender) that resolve to the
30729 same set of hosts, in the same order, are sent in a single SMTP transaction,
30730 even if they are for different domains, unless there are more than the setting
30731 of the max_rcpts option in the smtp transport allows, in which case they are
30732 split into groups containing no more than max_rcpts addresses each. If
30733 remote_max_parallel is greater than one, such groups may be sent in parallel
30734 sessions. The order of hosts with identical MX values is not significant when
30735 checking whether addresses can be batched in this way.
30737 When the smtp transport suffers a temporary failure that is not
30738 message-related, Exim updates its transport-specific database, which contains
30739 records indexed by host name that remember which messages are waiting for each
30740 particular host. It also updates the retry database with new retry times.
30742 Exim's retry hints are based on host name plus IP address, so if one address of
30743 a multi-homed host is broken, it will soon be skipped most of the time. See the
30744 next section for more detail about error handling.
30746 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
30747 looks in the hints database for the transport to see if there are any queued
30748 messages waiting for the host to which it is connected. If it finds one, it
30749 creates a new Exim process using the -MC option (which can only be used by a
30750 process running as root or the Exim user) and passes the TCP/IP socket to it so
30751 that it can deliver another message using the same socket. The new process does
30752 only those deliveries that are routed to the connected host, and may in turn
30753 pass the socket on to a third process, and so on.
30755 The connection_max_messages option of the smtp transport can be used to limit
30756 the number of messages sent down a single TCP/IP connection.
30758 The second and subsequent messages delivered down an existing connection are
30759 identified in the main log by the addition of an asterisk after the closing
30760 square bracket of the IP address.
30763 47.2 Errors in outgoing SMTP
30764 ----------------------------
30766 Three different kinds of error are recognized for outgoing SMTP: host errors,
30767 message errors, and recipient errors.
30771 A host error is not associated with a particular message or with a
30772 particular recipient of a message. The host errors are:
30774 * Connection refused or timed out,
30776 * Any error response code on connection,
30778 * Any error response code to EHLO or HELO,
30780 * Loss of connection at any time, except after ".",
30782 * I/O errors at any time,
30784 * Timeouts during the session, other than in response to MAIL, RCPT or
30785 the "." at the end of the data.
30787 For a host error, a permanent error response on connection, or in response
30788 to EHLO, causes all addresses routed to the host to be failed. Any other
30789 host error causes all addresses to be deferred, and retry data to be
30790 created for the host. It is not tried again, for any message, until its
30791 retry time arrives. If the current set of addresses are not all delivered
30792 in this run (to some alternative host), the message is added to the list of
30793 those waiting for this host, so if it is still undelivered when a
30794 subsequent successful delivery is made to the host, it will be sent down
30795 the same SMTP connection.
30799 A message error is associated with a particular message when sent to a
30800 particular host, but not with a particular recipient of the message. The
30801 message errors are:
30803 * Any error response code to MAIL, DATA, or the "." that terminates the
30806 * Timeout after MAIL,
30808 * Timeout or loss of connection after the "." that terminates the data. A
30809 timeout after the DATA command itself is treated as a host error, as is
30810 loss of connection at any other time.
30812 For a message error, a permanent error response (5xx) causes all addresses
30813 to be failed, and a delivery error report to be returned to the sender. A
30814 temporary error response (4xx), or one of the timeouts, causes all
30815 addresses to be deferred. Retry data is not created for the host, but
30816 instead, a retry record for the combination of host plus message id is
30817 created. The message is not added to the list of those waiting for this
30818 host. This ensures that the failing message will not be sent to this host
30819 again until the retry time arrives. However, other messages that are routed
30820 to the host are not affected, so if it is some property of the message that
30821 is causing the error, it will not stop the delivery of other mail.
30823 If the remote host specified support for the SIZE parameter in its response
30824 to EHLO, Exim adds SIZE=nnn to the MAIL command, so an over-large message
30825 will cause a message error because the error arrives as a response to MAIL.
30829 A recipient error is associated with a particular recipient of a message.
30830 The recipient errors are:
30832 * Any error response to RCPT,
30834 * Timeout after RCPT.
30836 For a recipient error, a permanent error response (5xx) causes the
30837 recipient address to be failed, and a bounce message to be returned to the
30838 sender. A temporary error response (4xx) or a timeout causes the failing
30839 address to be deferred, and routing retry data to be created for it. This
30840 is used to delay processing of the address in subsequent queue runs, until
30841 its routing retry time arrives. This applies to all messages, but because
30842 it operates only in queue runs, one attempt will be made to deliver a new
30843 message to the failing address before the delay starts to operate. This
30844 ensures that, if the failure is really related to the message rather than
30845 the recipient ("message too big for this recipient" is a possible example),
30846 other messages have a chance of getting delivered. If a delivery to the
30847 address does succeed, the retry information gets cleared, so all stuck
30848 messages get tried again, and the retry clock is reset.
30850 The message is not added to the list of those waiting for this host. Use of
30851 the host for other messages is unaffected, and except in the case of a
30852 timeout, other recipients are processed independently, and may be
30853 successfully delivered in the current SMTP session. After a timeout it is
30854 of course impossible to proceed with the session, so all addresses get
30855 deferred. However, those other than the one that failed do not suffer any
30856 subsequent retry delays. Therefore, if one recipient is causing trouble,
30857 the others have a chance of getting through when a subsequent delivery
30858 attempt occurs before the failing recipient's retry time.
30860 In all cases, if there are other hosts (or IP addresses) available for the
30861 current set of addresses (for example, from multiple MX records), they are
30862 tried in this run for any undelivered addresses, subject of course to their own
30863 retry data. In other words, recipient error retry data does not take effect
30864 until the next delivery attempt.
30866 Some hosts have been observed to give temporary error responses to every MAIL
30867 command at certain times ("insufficient space" has been seen). It would be nice
30868 if such circumstances could be recognized, and defer data for the host itself
30869 created, but this is not possible within the current Exim design. What actually
30870 happens is that retry data for every (host, message) combination is created.
30872 The reason that timeouts after MAIL and RCPT are treated specially is that
30873 these can sometimes arise as a result of the remote host's verification
30874 procedures. Exim makes this assumption, and treats them as if a temporary error
30875 response had been received. A timeout after "." is treated specially because it
30876 is known that some broken implementations fail to recognize the end of the
30877 message if the last character of the last line is a binary zero. Thus, it is
30878 helpful to treat this case as a message error.
30880 Timeouts at other times are treated as host errors, assuming a problem with the
30881 host, or the connection to it. If a timeout after MAIL, RCPT, or "." is really
30882 a connection problem, the assumption is that at the next try the timeout is
30883 likely to occur at some other point in the dialogue, causing it then to be
30884 treated as a host error.
30886 There is experimental evidence that some MTAs drop the connection after the
30887 terminating "." if they do not like the contents of the message for some
30888 reason, in contravention of the RFC, which indicates that a 5xx response should
30889 be given. That is why Exim treats this case as a message rather than a host
30890 error, in order not to delay other messages to the same host.
30893 47.3 Incoming SMTP messages over TCP/IP
30894 ---------------------------------------
30896 Incoming SMTP messages can be accepted in one of two ways: by running a
30897 listening daemon, or by using inetd. In the latter case, the entry in /etc/
30898 inetd.conf should be like this:
30900 smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs
30902 Exim distinguishes between this case and the case of a locally running user
30903 agent using the -bs option by checking whether or not the standard input is a
30904 socket. When it is, either the port must be privileged (less than 1024), or the
30905 caller must be root or the Exim user. If any other user passes a socket with an
30906 unprivileged port number, Exim prints a message on the standard error stream
30907 and exits with an error code.
30909 By default, Exim does not make a log entry when a remote host connects or
30910 disconnects (either via the daemon or inetd), unless the disconnection is
30911 unexpected. It can be made to write such log entries by setting the
30912 smtp_connection log selector.
30914 Commands from the remote host are supposed to be terminated by CR followed by
30915 LF. However, there are known to be hosts that do not send CR characters. In
30916 order to be able to interwork with such hosts, Exim treats LF on its own as a
30917 line terminator. Furthermore, because common code is used for receiving
30918 messages from all sources, a CR on its own is also interpreted as a line
30919 terminator. However, the sequence "CR, dot, CR" does not terminate incoming
30922 One area that sometimes gives rise to problems concerns the EHLO or HELO
30923 commands. Some clients send syntactically invalid versions of these commands,
30924 which Exim rejects by default. (This is nothing to do with verifying the data
30925 that is sent, so helo_verify_hosts is not relevant.) You can tell Exim not to
30926 apply a syntax check by setting helo_accept_junk_hosts to match the broken
30927 hosts that send invalid commands.
30929 The amount of disk space available is checked whenever SIZE is received on a
30930 MAIL command, independently of whether message_size_limit or check_spool_space
30931 is configured, unless smtp_check_spool_space is set false. A temporary error is
30932 given if there is not enough space. If check_spool_space is set, the check is
30933 for that amount of space plus the value given with SIZE, that is, it checks
30934 that the addition of the incoming message will not reduce the space below the
30937 When a message is successfully received, Exim includes the local message id in
30938 its response to the final "." that terminates the data. If the remote host logs
30939 this text it can help with tracing what has happened to a message.
30941 The Exim daemon can limit the number of simultaneous incoming connections it is
30942 prepared to handle (see the smtp_accept_max option). It can also limit the
30943 number of simultaneous incoming connections from a single remote host (see the
30944 smtp_accept_max_per_host option). Additional connection attempts are rejected
30945 using the SMTP temporary error code 421.
30947 The Exim daemon does not rely on the SIGCHLD signal to detect when a subprocess
30948 has finished, as this can get lost at busy times. Instead, it looks for
30949 completed subprocesses every time it wakes up. Provided there are other things
30950 happening (new incoming calls, starts of queue runs), completed processes will
30951 be noticed and tidied away. On very quiet systems you may sometimes see a
30952 "defunct" Exim process hanging about. This is not a problem; it will be noticed
30953 when the daemon next wakes up.
30955 When running as a daemon, Exim can reserve some SMTP slots for specific hosts,
30956 and can also be set up to reject SMTP calls from non-reserved hosts at times of
30957 high system load - for details see the smtp_accept_reserve, smtp_load_reserve,
30958 and smtp_reserve_hosts options. The load check applies in both the daemon and
30961 Exim normally starts a delivery process for each message received, though this
30962 can be varied by means of the -odq command line option and the queue_only,
30963 queue_only_file, and queue_only_load options. The number of simultaneously
30964 running delivery processes started in this way from SMTP input can be limited
30965 by the smtp_accept_queue and smtp_accept_queue_per_connection options. When
30966 either limit is reached, subsequently received messages are just put on the
30967 input queue without starting a delivery process.
30969 The controls that involve counts of incoming SMTP calls (smtp_accept_max,
30970 smtp_accept_queue, smtp_accept_reserve) are not available when Exim is started
30971 up from the inetd daemon, because in that case each connection is handled by an
30972 entirely independent Exim process. Control by load average is, however,
30973 available with inetd.
30975 Exim can be configured to verify addresses in incoming SMTP commands as they
30976 are received. See chapter 42 for details. It can also be configured to rewrite
30977 addresses at this time - before any syntax checking is done. See section 31.9.
30979 Exim can also be configured to limit the rate at which a client host submits
30980 MAIL and RCPT commands in a single SMTP session. See the smtp_ratelimit_hosts
30984 47.4 Unrecognized SMTP commands
30985 -------------------------------
30987 If Exim receives more than smtp_max_unknown_commands unrecognized SMTP commands
30988 during a single SMTP connection, it drops the connection after sending the
30989 error response to the last command. The default value for
30990 smtp_max_unknown_commands is 3. This is a defence against some kinds of abuse
30991 that subvert web servers into making connections to SMTP ports; in these
30992 circumstances, a number of non-SMTP lines are sent first.
30995 47.5 Syntax and protocol errors in SMTP commands
30996 ------------------------------------------------
30998 A syntax error is detected if an SMTP command is recognized, but there is
30999 something syntactically wrong with its data, for example, a malformed email
31000 address in a RCPT command. Protocol errors include invalid command sequencing
31001 such as RCPT before MAIL. If Exim receives more than smtp_max_synprot_errors
31002 such commands during a single SMTP connection, it drops the connection after
31003 sending the error response to the last command. The default value for
31004 smtp_max_synprot_errors is 3. This is a defence against broken clients that
31005 loop sending bad commands (yes, it has been seen).
31008 47.6 Use of non-mail SMTP commands
31009 ----------------------------------
31011 The "non-mail" SMTP commands are those other than MAIL, RCPT, and DATA. Exim
31012 counts such commands, and drops the connection if there are too many of them in
31013 a single SMTP session. This action catches some denial-of-service attempts and
31014 things like repeated failing AUTHs, or a mad client looping sending EHLO. The
31015 global option smtp_accept_max_nonmail defines what "too many" means. Its
31016 default value is 10.
31018 When a new message is expected, one occurrence of RSET is not counted. This
31019 allows a client to send one RSET between messages (this is not necessary, but
31020 some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO,
31021 and one occurrence of STARTTLS between messages. After starting up a TLS
31022 session, another EHLO is expected, and so it too is not counted.
31024 The first occurrence of AUTH in a connection, or immediately following STARTTLS
31025 is also not counted. Otherwise, all commands other than MAIL, RCPT, DATA, and
31028 You can control which hosts are subject to the limit set by
31029 smtp_accept_max_nonmail by setting smtp_accept_max_nonmail_hosts. The default
31030 value is "*", which makes the limit apply to all hosts. This option means that
31031 you can exclude any specific badly-behaved hosts that you have to live with.
31034 47.7 The VRFY and EXPN commands
31035 -------------------------------
31037 When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the
31038 ACL specified by acl_smtp_vrfy or acl_smtp_expn (as appropriate) in order to
31039 decide whether the command should be accepted or not. If no ACL is defined, the
31040 command is rejected.
31042 When VRFY is accepted, it runs exactly the same code as when Exim is called
31043 with the -bv option.
31045 When EXPN is accepted, a single-level expansion of the address is done. EXPN is
31046 treated as an "address test" (similar to the -bt option) rather than a
31047 verification (the -bv option). If an unqualified local part is given as the
31048 argument to EXPN, it is qualified with qualify_domain. Rejections of VRFY and
31049 EXPN commands are logged on the main and reject logs, and VRFY verification
31050 failures are logged on the main log for consistency with RCPT failures.
31053 47.8 The ETRN command
31054 ---------------------
31056 RFC 1985 describes an SMTP command called ETRN that is designed to overcome the
31057 security problems of the TURN command (which has fallen into disuse). When Exim
31058 receives an ETRN command on a TCP/IP connection, it runs the ACL specified by
31059 acl_smtp_etrn in order to decide whether the command should be accepted or not.
31060 If no ACL is defined, the command is rejected.
31062 The ETRN command is concerned with "releasing" messages that are awaiting
31063 delivery to certain hosts. As Exim does not organize its message queue by host,
31064 the only form of ETRN that is supported by default is the one where the text
31065 starts with the "#" prefix, in which case the remainder of the text is specific
31066 to the SMTP server. A valid ETRN command causes a run of Exim with the -R
31067 option to happen, with the remainder of the ETRN text as its argument. For
31076 which causes a delivery attempt on all messages with undelivered addresses
31077 containing the text "brigadoon". When smtp_etrn_serialize is set (the default),
31078 Exim prevents the simultaneous execution of more than one queue run for the
31079 same argument string as a result of an ETRN command. This stops a misbehaving
31080 client from starting more than one queue runner at once.
31082 Exim implements the serialization by means of a hints database in which a
31083 record is written whenever a process is started by ETRN, and deleted when the
31084 process completes. However, Exim does not keep the SMTP session waiting for the
31085 ETRN process to complete. Once ETRN is accepted, the client is sent a "success"
31086 return code. Obviously there is scope for hints records to get left lying
31087 around if there is a system or program crash. To guard against this, Exim
31088 ignores any records that are more than six hours old.
31090 For more control over what ETRN does, the smtp_etrn_command option can used.
31091 This specifies a command that is run whenever ETRN is received, whatever the
31092 form of its argument. For example:
31094 smtp_etrn_command = /etc/etrn_command $domain \
31095 $sender_host_address
31097 The string is split up into arguments which are independently expanded. The
31098 expansion variable $domain is set to the argument of the ETRN command, and no
31099 syntax checking is done on the contents of this argument. Exim does not wait
31100 for the command to complete, so its status code is not checked. Exim runs under
31101 its own uid and gid when receiving incoming SMTP, so it is not possible for it
31102 to change them before running the command.
31105 47.9 Incoming local SMTP
31106 ------------------------
31108 Some user agents use SMTP to pass messages to their local MTA using the
31109 standard input and output, as opposed to passing the envelope on the command
31110 line and writing the message to the standard input. This is supported by the
31111 -bs option. This form of SMTP is handled in the same way as incoming messages
31112 over TCP/IP (including the use of ACLs), except that the envelope sender given
31113 in a MAIL command is ignored unless the caller is trusted. In an ACL you can
31114 detect this form of SMTP input by testing for an empty host identification. It
31115 is common to have this as the first line in the ACL that runs for RCPT
31120 This accepts SMTP messages from local processes without doing any other tests.
31123 47.10 Outgoing batched SMTP
31124 ---------------------------
31126 Both the appendfile and pipe transports can be used for handling batched SMTP.
31127 Each has an option called use_bsmtp which causes messages to be output in BSMTP
31128 format. No SMTP responses are possible for this form of delivery. All it is
31129 doing is using SMTP commands as a way of transmitting the envelope along with
31132 The message is written to the file or pipe preceded by the SMTP commands MAIL
31133 and RCPT, and followed by a line containing a single dot. Lines in the message
31134 that start with a dot have an extra dot added. The SMTP command HELO is not
31135 normally used. If it is required, the message_prefix option can be used to
31138 Because appendfile and pipe are both local transports, they accept only one
31139 recipient address at a time by default. However, you can arrange for them to
31140 handle several addresses at once by setting the batch_max option. When this is
31141 done for BSMTP, messages may contain multiple RCPT commands. See chapter 25 for
31144 When one or more addresses are routed to a BSMTP transport by a router that
31145 sets up a host list, the name of the first host on the list is available to the
31146 transport in the variable $host. Here is an example of such a transport and
31151 driver = manualroute
31152 transport = smtp_appendfile
31153 route_list = domain.example batch.host.example
31157 driver = appendfile
31158 directory = /var/bsmtp/$host
31163 This causes messages addressed to domain.example to be written in BSMTP format
31164 to /var/bsmtp/batch.host.example, with only a single copy of each message
31165 (unless there are more than 1000 recipients).
31168 47.11 Incoming batched SMTP
31169 ---------------------------
31171 The -bS command line option causes Exim to accept one or more messages by
31172 reading SMTP on the standard input, but to generate no responses. If the caller
31173 is trusted, the senders in the MAIL commands are believed; otherwise the sender
31174 is always the caller of Exim. Unqualified senders and receivers are not
31175 rejected (there seems little point) but instead just get qualified. HELO and
31176 EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act as NOOP; QUIT quits.
31178 Minimal policy checking is done for BSMTP input. Only the non-SMTP ACL is run
31179 in the same way as for non-SMTP local input.
31181 If an error is detected while reading a message, including a missing "." at the
31182 end, Exim gives up immediately. It writes details of the error to the standard
31183 output in a stylized way that the calling program should be able to make some
31184 use of automatically, for example:
31186 554 Unexpected end of file
31187 Transaction started in line 10
31188 Error detected in line 14
31190 It writes a more verbose version, for human consumption, to the standard error
31193 An error was detected while processing a file of BSMTP input.
31194 The error message was:
31196 501 '>' missing at end of address
31198 The SMTP transaction started in line 10.
31199 The error was detected in line 12.
31200 The SMTP command at fault was:
31202 rcpt to:<malformed@in.com.plete
31204 1 previous message was successfully processed.
31205 The rest of the batch was abandoned.
31207 The return code from Exim is zero only if there were no errors. It is 1 if some
31208 messages were accepted before an error was detected, and 2 if no messages were
31213 ===============================================================================
31214 48. CUSTOMIZING BOUNCE AND WARNING MESSAGES
31216 When a message fails to be delivered, or remains on the queue for more than a
31217 configured amount of time, Exim sends a message to the original sender, or to
31218 an alternative configured address. The text of these messages is built into the
31219 code of Exim, but it is possible to change it, either by adding a single
31220 string, or by replacing each of the paragraphs by text supplied in a file.
31222 The From: and To: header lines are automatically generated; you can cause a
31223 Reply-To: line to be added by setting the errors_reply_to option. Exim also
31226 Auto-Submitted: auto-generated
31228 to all warning and bounce messages,
31231 48.1 Customizing bounce messages
31232 --------------------------------
31234 If bounce_message_text is set, its contents are included in the default message
31235 immediately after "This message was created automatically by mail delivery
31236 software." The string is not expanded. It is not used if bounce_message_file is
31239 When bounce_message_file is set, it must point to a template file for
31240 constructing error messages. The file consists of a series of text items,
31241 separated by lines consisting of exactly four asterisks. If the file cannot be
31242 opened, default text is used and a message is written to the main and panic
31243 logs. If any text item in the file is empty, default text is used for that
31246 Each item of text that is read from the file is expanded, and there are two
31247 expansion variables which can be of use here: $bounce_recipient is set to the
31248 recipient of an error message while it is being created, and
31249 $bounce_return_size_limit contains the value of the return_size_limit option,
31250 rounded to a whole number.
31252 The items must appear in the file in the following order:
31254 * The first item is included in the headers, and should include at least a
31255 Subject: header. Exim does not check the syntax of these headers.
31257 * The second item forms the start of the error message. After it, Exim lists
31258 the failing addresses with their error messages.
31260 * The third item is used to introduce any text from pipe transports that is
31261 to be returned to the sender. It is omitted if there is no such text.
31263 * The fourth item is used to introduce the copy of the message that is
31264 returned as part of the error report.
31266 * The fifth item is added after the fourth one if the returned message is
31267 truncated because it is bigger than return_size_limit.
31269 * The sixth item is added after the copy of the original message.
31271 The default state (bounce_message_file unset) is equivalent to the following
31272 file, in which the sixth item is empty. The Subject: and some other lines have
31273 been split in order to fit them on the page:
31275 Subject: Mail delivery failed
31276 ${if eq{$sender_address}{$bounce_recipient}
31277 {: returning message to sender}}
31279 This message was created automatically by mail delivery software.
31281 A message ${if eq{$sender_address}{$bounce_recipient}
31282 {that you sent }{sent by
31286 }}could not be delivered to all of its recipients.
31287 This is a permanent error. The following address(es) failed:
31289 The following text was generated during the delivery attempt(s):
31291 ------ This is a copy of the message, including all the headers.
31294 ------ The body of the message is $message_size characters long;
31296 ------ $bounce_return_size_limit or so are included here.
31300 48.2 Customizing warning messages
31301 ---------------------------------
31303 The option warn_message_file can be pointed at a template file for use when
31304 warnings about message delays are created. In this case there are only three
31307 * The first item is included in the headers, and should include at least a
31308 Subject: header. Exim does not check the syntax of these headers.
31310 * The second item forms the start of the warning message. After it, Exim
31311 lists the delayed addresses.
31313 * The third item then ends the message.
31315 The default state is equivalent to the following file, except that some lines
31316 have been split here, in order to fit them on the page:
31318 Subject: Warning: message $message_exim_id delayed
31319 $warn_message_delay
31321 This message was created automatically by mail delivery software.
31323 A message ${if eq{$sender_address}{$warn_message_recipients}
31324 {that you sent }{sent by
31328 }}has not been delivered to all of its recipients after
31329 more than $warn_message_delay on the queue on $primary_hostname.
31331 The message identifier is: $message_exim_id
31332 The subject of the message is: $h_subject
31333 The date of the message is: $h_date
31335 The following address(es) have not yet been delivered:
31337 No action is required on your part. Delivery attempts will
31338 continue for some time, and this warning may be repeated at
31339 intervals if the message remains undelivered. Eventually the
31340 mail delivery software will give up, and when that happens,
31341 the message will be returned to you.
31343 However, in the default state the subject and date lines are omitted if no
31344 appropriate headers exist. During the expansion of this file,
31345 $warn_message_delay is set to the delay time in one of the forms "<n> minutes"
31346 or "<n> hours", and $warn_message_recipients contains a list of recipients for
31347 the warning message. There may be more than one if there are multiple addresses
31348 with different errors_to settings on the routers that handled them.
31352 ===============================================================================
31353 49. SOME COMMON CONFIGURATION SETTINGS
31355 This chapter discusses some configuration settings that seem to be fairly
31356 common. More examples and discussion can be found in the Exim book.
31359 49.1 Sending mail to a smart host
31360 ---------------------------------
31362 If you want to send all mail for non-local domains to a "smart host", you
31363 should replace the default dnslookup router with a router which does the
31364 routing explicitly:
31366 send_to_smart_host:
31367 driver = manualroute
31368 route_list = !+local_domains smart.host.name
31369 transport = remote_smtp
31371 You can use the smart host's IP address instead of the name if you wish. If you
31372 are using Exim only to submit messages to a smart host, and not for receiving
31373 incoming messages, you can arrange for it to do the submission synchronously by
31374 setting the mua_wrapper option (see chapter 50).
31377 49.2 Using Exim to handle mailing lists
31378 ---------------------------------------
31380 Exim can be used to run simple mailing lists, but for large and/or complicated
31381 requirements, the use of additional specialized mailing list software such as
31382 Majordomo or Mailman is recommended.
31384 The redirect router can be used to handle mailing lists where each list is
31385 maintained in a separate file, which can therefore be managed by an independent
31386 manager. The domains router option can be used to run these lists in a separate
31387 domain from normal mail. For example:
31391 domains = lists.example
31392 file = /usr/lists/$local_part
31395 errors_to = $local_part-request@lists.example
31398 This router is skipped for domains other than lists.example. For addresses in
31399 that domain, it looks for a file that matches the local part. If there is no
31400 such file, the router declines, but because no_more is set, no subsequent
31401 routers are tried, and so the whole delivery fails.
31403 The forbid_pipe and forbid_file options prevent a local part from being
31404 expanded into a file name or a pipe delivery, which is usually inappropriate in
31407 The errors_to option specifies that any delivery errors caused by addresses
31408 taken from a mailing list are to be sent to the given address rather than the
31409 original sender of the message. However, before acting on this, Exim verifies
31410 the error address, and ignores it if verification fails.
31412 For example, using the configuration above, mail sent to dicts@lists.example is
31413 passed on to those addresses contained in /usr/lists/dicts, with error reports
31414 directed to dicts-request@lists.example, provided that this address can be
31415 verified. There could be a file called /usr/lists/dicts-request containing the
31416 address(es) of this particular list's manager(s), but other approaches, such as
31417 setting up an earlier router (possibly using the local_part_prefix or
31418 local_part_suffix options) to handle addresses of the form owner-xxx or xxx-
31419 request, are also possible.
31422 49.3 Syntax errors in mailing lists
31423 -----------------------------------
31425 If an entry in redirection data contains a syntax error, Exim normally defers
31426 delivery of the original address. That means that a syntax error in a mailing
31427 list holds up all deliveries to the list. This may not be appropriate when a
31428 list is being maintained automatically from data supplied by users, and the
31429 addresses are not rigorously checked.
31431 If the skip_syntax_errors option is set, the redirect router just skips entries
31432 that fail to parse, noting the incident in the log. If in addition
31433 syntax_errors_to is set to a verifiable address, a message is sent to it
31434 whenever a broken address is skipped. It is usually appropriate to set
31435 syntax_errors_to to the same address as errors_to.
31438 49.4 Re-expansion of mailing lists
31439 ----------------------------------
31441 Exim remembers every individual address to which a message has been delivered,
31442 in order to avoid duplication, but it normally stores only the original
31443 recipient addresses with a message. If all the deliveries to a mailing list
31444 cannot be done at the first attempt, the mailing list is re-expanded when the
31445 delivery is next tried. This means that alterations to the list are taken into
31446 account at each delivery attempt, so addresses that have been added to the list
31447 since the message arrived will therefore receive a copy of the message, even
31448 though it pre-dates their subscription.
31450 If this behaviour is felt to be undesirable, the one_time option can be set on
31451 the redirect router. If this is done, any addresses generated by the router
31452 that fail to deliver at the first attempt are added to the message as "top
31453 level" addresses, and the parent address that generated them is marked
31454 "delivered". Thus, expansion of the mailing list does not happen again at the
31455 subsequent delivery attempts. The disadvantage of this is that if any of the
31456 failing addresses are incorrect, correcting them in the file has no effect on
31457 pre-existing messages.
31459 The original top-level address is remembered with each of the generated
31460 addresses, and is output in any log messages. However, any intermediate parent
31461 addresses are not recorded. This makes a difference to the log only if the
31462 all_parents selector is set, but for mailing lists there is normally only one
31463 level of expansion anyway.
31466 49.5 Closed mailing lists
31467 -------------------------
31469 The examples so far have assumed open mailing lists, to which anybody may send
31470 mail. It is also possible to set up closed lists, where mail is accepted from
31471 specified senders only. This is done by making use of the generic senders
31472 option to restrict the router that handles the list.
31474 The following example uses the same file as a list of recipients and as a list
31475 of permitted senders. It requires three routers:
31479 domains = lists.example
31480 local_part_suffix = -request
31481 file = /usr/lists/$local_part$local_part_suffix
31486 domains = lists.example
31487 senders = ${if exists {/usr/lists/$local_part}\
31488 {lsearch;/usr/lists/$local_part}{*}}
31489 file = /usr/lists/$local_part
31492 errors_to = $local_part-request@lists.example
31497 domains = lists.example
31499 data = :fail: $local_part@lists.example is a closed mailing list
31501 All three routers have the same domains setting, so for any other domains, they
31502 are all skipped. The first router runs only if the local part ends in -request.
31503 It handles messages to the list manager(s) by means of an open mailing list.
31505 The second router runs only if the senders precondition is satisfied. It checks
31506 for the existence of a list that corresponds to the local part, and then checks
31507 that the sender is on the list by means of a linear search. It is necessary to
31508 check for the existence of the file before trying to search it, because
31509 otherwise Exim thinks there is a configuration error. If the file does not
31510 exist, the expansion of senders is *, which matches all senders. This means
31511 that the router runs, but because there is no list, declines, and no_more
31512 ensures that no further routers are run. The address fails with an "unrouteable
31515 The third router runs only if the second router is skipped, which happens when
31516 a mailing list exists, but the sender is not on it. This router forcibly fails
31517 the address, giving a suitable error message.
31520 49.6 Variable Envelope Return Paths (VERP)
31521 ------------------------------------------
31523 Variable Envelope Return Paths - see http://cr.yp.to/proto/verp.txt - are a way
31524 of helping mailing list administrators discover which subscription address is
31525 the cause of a particular delivery failure. The idea is to encode the original
31526 recipient address in the outgoing envelope sender address, so that if the
31527 message is forwarded by another host and then subsequently bounces, the
31528 original recipient can be extracted from the recipient address of the bounce.
31530 Envelope sender addresses can be modified by Exim using two different
31531 facilities: the errors_to option on a router (as shown in previous mailing list
31532 examples), or the return_path option on a transport. The second of these is
31533 effective only if the message is successfully delivered to another host; it is
31534 not used for errors detected on the local host (see the description of
31535 return_path in chapter 24). Here is an example of the use of return_path to
31536 implement VERP on an smtp transport:
31542 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
31543 {$1-request+$local_part=$domain@your.dom.example}fail}
31545 This has the effect of rewriting the return path (envelope sender) on outgoing
31546 SMTP messages, if the local part of the original return path ends in
31547 "-request", and the domain is your.dom.example. The rewriting inserts the local
31548 part and domain of the recipient into the return path. Suppose, for example,
31549 that a message whose return path has been set to
31550 somelist-request@your.dom.example is sent to subscriber@other.dom.example. In
31551 the transport, the return path is rewritten as
31553 somelist-request+subscriber=other.dom.example@your.dom.example
31555 For this to work, you must tell Exim to send multiple copies of messages that
31556 have more than one recipient, so that each copy has just one recipient. This is
31557 achieved by setting max_rcpt to 1. Without this, a single copy of a message
31558 might be sent to several different recipients in the same domain, in which case
31559 $local_part is not available in the transport, because it is not unique.
31561 Unless your host is doing nothing but mailing list deliveries, you should
31562 probably use a separate transport for the VERP deliveries, so as not to use
31563 extra resources in making one-per-recipient copies for other deliveries. This
31564 can easily be done by expanding the transport option in the router:
31568 domains = ! +local_domains
31570 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
31571 {verp_smtp}{remote_smtp}}
31574 If you want to change the return path using errors_to in a router instead of
31575 using return_path in the transport, you need to set errors_to on all routers
31576 that handle mailing list addresses. This will ensure that all delivery errors,
31577 including those detected on the local host, are sent to the VERP address.
31579 On a host that does no local deliveries and has no manual routing, only the
31580 dnslookup router needs to be changed. A special transport is not needed for
31581 SMTP deliveries. Every mailing list recipient has its own return path value,
31582 and so Exim must hand them to the transport one at a time. Here is an example
31583 of a dnslookup router that implements VERP:
31587 domains = ! +local_domains
31588 transport = remote_smtp
31590 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
31591 {$1-request+$local_part=$domain@your.dom.example}fail}
31594 Before you start sending out messages with VERPed return paths, you must also
31595 configure Exim to accept the bounce messages that come back to those paths.
31596 Typically this is done by setting a local_part_suffix option for a router, and
31597 using this to route the messages to wherever you want to handle them.
31599 The overhead incurred in using VERP depends very much on the size of the
31600 message, the number of recipient addresses that resolve to the same remote
31601 host, and the speed of the connection over which the message is being sent. If
31602 a lot of addresses resolve to the same host and the connection is slow, sending
31603 a separate copy of the message for each address may take substantially longer
31604 than sending a single copy with many recipients (for which VERP cannot be
31608 49.7 Virtual domains
31609 --------------------
31611 The phrase virtual domain is unfortunately used with two rather different
31614 * A domain for which there are no real mailboxes; all valid local parts are
31615 aliases for other email addresses. Common examples are organizational
31616 top-level domains and "vanity" domains.
31618 * One of a number of independent domains that are all handled by the same
31619 host, with mailboxes on that host, but where the mailbox owners do not
31620 necessarily have login accounts on that host.
31622 The first usage is probably more common, and does seem more "virtual" than the
31623 second. This kind of domain can be handled in Exim with a straightforward
31624 aliasing router. One approach is to create a separate alias file for each
31625 virtual domain. Exim can test for the existence of the alias file to determine
31626 whether the domain exists. The dsearch lookup type is useful here, leading to a
31627 router of this form:
31631 domains = dsearch;/etc/mail/virtual
31632 data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}}
31635 The domains option specifies that the router is to be skipped, unless there is
31636 a file in the /etc/mail/virtual directory whose name is the same as the domain
31637 that is being processed. When the router runs, it looks up the local part in
31638 the file to find a new address (or list of addresses). The no_more setting
31639 ensures that if the lookup fails (leading to data being an empty string), Exim
31640 gives up on the address without trying any subsequent routers.
31642 This one router can handle all the virtual domains because the alias file names
31643 follow a fixed pattern. Permissions can be arranged so that appropriate people
31644 can edit the different alias files. A successful aliasing operation results in
31645 a new envelope recipient address, which is then routed from scratch.
31647 The other kind of "virtual" domain can also be handled in a straightforward
31648 way. One approach is to create a file for each domain containing a list of
31649 valid local parts, and use it in a router like this:
31653 domains = dsearch;/etc/mail/domains
31654 local_parts = lsearch;/etc/mail/domains/$domain
31655 transport = my_mailboxes
31657 The address is accepted if there is a file for the domain, and the local part
31658 can be found in the file. The domains option is used to check for the file's
31659 existence because domains is tested before the local_parts option (see section
31660 3.12). You cannot use require_files, because that option is tested after
31661 local_parts. The transport is as follows:
31664 driver = appendfile
31665 file = /var/mail/$domain/$local_part
31668 This uses a directory of mailboxes for each domain. The user setting is
31669 required, to specify which uid is to be used for writing to the mailboxes.
31671 The configuration shown here is just one example of how you might support this
31672 requirement. There are many other ways this kind of configuration can be set
31673 up, for example, by using a database instead of separate files to hold all the
31674 information about the domains.
31677 49.8 Multiple user mailboxes
31678 ----------------------------
31680 Heavy email users often want to operate with multiple mailboxes, into which
31681 incoming mail is automatically sorted. A popular way of handling this is to
31682 allow users to use multiple sender addresses, so that replies can easily be
31683 identified. Users are permitted to add prefixes or suffixes to their local
31684 parts for this purpose. The wildcard facility of the generic router options
31685 local_part_prefix and local_part_suffix can be used for this. For example,
31686 consider this router:
31691 file = $home/.forward
31692 local_part_suffix = -*
31693 local_part_suffix_optional
31696 It runs a user's .forward file for all local parts of the form username-*.
31697 Within the filter file the user can distinguish different cases by testing the
31698 variable $local_part_suffix. For example:
31700 if $local_part_suffix contains -special then
31701 save /home/$local_part/Mail/special
31704 If the filter file does not exist, or does not deal with such addresses, they
31705 fall through to subsequent routers, and, assuming no subsequent use of the
31706 local_part_suffix option is made, they presumably fail. Thus, users have
31707 control over which suffixes are valid.
31709 Alternatively, a suffix can be used to trigger the use of a different .forward
31710 file - which is the way a similar facility is implemented in another MTA:
31715 file = $home/.forward$local_part_suffix
31716 local_part_suffix = -*
31717 local_part_suffix_optional
31720 If there is no suffix, .forward is used; if the suffix is -special, for
31721 example, .forward-special is used. Once again, if the appropriate file does not
31722 exist, or does not deal with the address, it is passed on to subsequent
31723 routers, which could, if required, look for an unqualified .forward file to use
31727 49.9 Simplified vacation processing
31728 -----------------------------------
31730 The traditional way of running the vacation program is for a user to set up a
31731 pipe command in a .forward file (see section 22.6 for syntax details). This is
31732 prone to error by inexperienced users. There are two features of Exim that can
31733 be used to make this process simpler for users:
31735 * A local part prefix such as "vacation-" can be specified on a router which
31736 can cause the message to be delivered directly to the vacation program, or
31737 alternatively can use Exim's autoreply transport. The contents of a user's
31738 .forward file are then much simpler. For example:
31740 spqr, vacation-spqr
31742 * The require_files generic router option can be used to trigger a vacation
31743 delivery by checking for the existence of a certain file in the user's home
31744 directory. The unseen generic option should also be used, to ensure that
31745 the original delivery also proceeds. In this case, all the user has to do
31746 is to create a file called, say, .vacation, containing a vacation message.
31748 Another advantage of both these methods is that they both work even when the
31749 use of arbitrary pipes by users is locked out.
31752 49.10 Taking copies of mail
31753 ---------------------------
31755 Some installations have policies that require archive copies of all messages to
31756 be made. A single copy of each message can easily be taken by an appropriate
31757 command in a system filter, which could, for example, use a different file for
31758 each day's messages.
31760 There is also a shadow transport mechanism that can be used to take copies of
31761 messages that are successfully delivered by local transports, one copy per
31762 delivery. This could be used, inter alia, to implement automatic notification
31763 of delivery by sites that insist on doing such things.
31766 49.11 Intermittently connected hosts
31767 ------------------------------------
31769 It has become quite common (because it is cheaper) for hosts to connect to the
31770 Internet periodically rather than remain connected all the time. The normal
31771 arrangement is that mail for such hosts accumulates on a system that is
31772 permanently connected.
31774 Exim was designed for use on permanently connected hosts, and so it is not
31775 particularly well-suited to use in an intermittently connected environment.
31776 Nevertheless there are some features that can be used.
31779 49.12 Exim on the upstream server host
31780 --------------------------------------
31782 It is tempting to arrange for incoming mail for the intermittently connected
31783 host to remain on Exim's queue until the client connects. However, this
31784 approach does not scale very well. Two different kinds of waiting message are
31785 being mixed up in the same queue - those that cannot be delivered because of
31786 some temporary problem, and those that are waiting for their destination host
31787 to connect. This makes it hard to manage the queue, as well as wasting
31788 resources, because each queue runner scans the entire queue.
31790 A better approach is to separate off those messages that are waiting for an
31791 intermittently connected host. This can be done by delivering these messages
31792 into local files in batch SMTP, "mailstore", or other envelope-preserving
31793 format, from where they are transmitted by other software when their
31794 destination connects. This makes it easy to collect all the mail for one host
31795 in a single directory, and to apply local timeout rules on a per-message basis
31798 On a very small scale, leaving the mail on Exim's queue can be made to work. If
31799 you are doing this, you should configure Exim with a long retry period for the
31800 intermittent host. For example:
31802 cheshire.wonderland.fict.example * F,5d,24h
31804 This stops a lot of failed delivery attempts from occurring, but Exim remembers
31805 which messages it has queued up for that host. Once the intermittent host comes
31806 online, forcing delivery of one message (either by using the -M or -R options,
31807 or by using the ETRN SMTP command (see section 47.8) causes all the queued up
31808 messages to be delivered, often down a single SMTP connection. While the host
31809 remains connected, any new messages get delivered immediately.
31811 If the connecting hosts do not have fixed IP addresses, that is, if a host is
31812 issued with a different IP address each time it connects, Exim's retry
31813 mechanisms on the holding host get confused, because the IP address is normally
31814 used as part of the key string for holding retry information. This can be
31815 avoided by unsetting retry_include_ip_address on the smtp transport. Since this
31816 has disadvantages for permanently connected hosts, it is best to arrange a
31817 separate transport for the intermittently connected ones.
31820 49.13 Exim on the intermittently connected client host
31821 ------------------------------------------------------
31823 The value of smtp_accept_queue_per_connection should probably be increased, or
31824 even set to zero (that is, disabled) on the intermittently connected host, so
31825 that all incoming messages down a single connection get delivered immediately.
31827 Mail waiting to be sent from an intermittently connected host will probably not
31828 have been routed, because without a connection DNS lookups are not possible.
31829 This means that if a normal queue run is done at connection time, each message
31830 is likely to be sent in a separate SMTP session. This can be avoided by
31831 starting the queue run with a command line option beginning with -qq instead of
31832 -q. In this case, the queue is scanned twice. In the first pass, routing is
31833 done but no deliveries take place. The second pass is a normal queue run; since
31834 all the messages have been previously routed, those destined for the same host
31835 are likely to get sent as multiple deliveries in a single SMTP connection.
31839 ===============================================================================
31840 50. USING EXIM AS A NON-QUEUEING CLIENT
31842 On a personal computer, it is a common requirement for all email to be sent to
31843 a "smart host". There are plenty of MUAs that can be configured to operate that
31844 way, for all the popular operating systems. However, there are some MUAs for
31845 Unix-like systems that cannot be so configured: they submit messages using the
31846 command line interface of /usr/sbin/sendmail. Furthermore, utility programs
31847 such as cron submit messages this way.
31849 If the personal computer runs continuously, there is no problem, because it can
31850 run a conventional MTA that handles delivery to the smart host, and deal with
31851 any delays via its queueing mechanism. However, if the computer does not run
31852 continuously or runs different operating systems at different times, queueing
31853 email is not desirable.
31855 There is therefore a requirement for something that can provide the /usr/sbin/
31856 sendmail interface but deliver messages to a smart host without any queueing or
31857 retrying facilities. Furthermore, the delivery to the smart host should be
31858 synchronous, so that if it fails, the sending MUA is immediately informed. In
31859 other words, we want something that extends an MUA that submits to a local MTA
31860 via the command line so that it behaves like one that submits to a remote smart
31861 host using TCP/SMTP.
31863 There are a number of applications (for example, there is one called ssmtp)
31864 that do this job. However, people have found them to be lacking in various
31865 ways. For instance, you might want to allow aliasing and forwarding to be done
31866 before sending a message to the smart host.
31868 Exim already had the necessary infrastructure for doing this job. Just a few
31869 tweaks were needed to make it behave as required, though it is somewhat of an
31870 overkill to use a fully-featured MTA for this purpose.
31872 There is a Boolean global option called mua_wrapper, defaulting false. Setting
31873 mua_wrapper true causes Exim to run in a special mode where it assumes that it
31874 is being used to "wrap" a command-line MUA in the manner just described. As
31875 well as setting mua_wrapper, you also need to provide a compatible router and
31876 transport configuration. Typically there will be just one router and one
31877 transport, sending everything to a smart host.
31879 When run in MUA wrapping mode, the behaviour of Exim changes in the following
31882 * A daemon cannot be run, nor will Exim accept incoming messages from inetd.
31883 In other words, the only way to submit messages is via the command line.
31885 * Each message is synchronously delivered as soon as it is received (-odi is
31886 assumed). All queueing options (queue_only, queue_smtp_domains, control in
31887 an ACL, etc.) are quietly ignored. The Exim reception process does not
31888 finish until the delivery attempt is complete. If the delivery is
31889 successful, a zero return code is given.
31891 * Address redirection is permitted, but the final routing for all addresses
31892 must be to the same remote transport, and to the same list of hosts.
31893 Furthermore, the return address (envelope sender) must be the same for all
31894 recipients, as must any added or deleted header lines. In other words, it
31895 must be possible to deliver the message in a single SMTP transaction,
31896 however many recipients there are.
31898 * If these conditions are not met, or if routing any address results in a
31899 failure or defer status, or if Exim is unable to deliver all the recipients
31900 successfully to one of the smart hosts, delivery of the entire message
31903 * Because no queueing is allowed, all failures are treated as permanent;
31904 there is no distinction between 4xx and 5xx SMTP response codes from the
31905 smart host. Furthermore, because only a single yes/no response can be given
31906 to the caller, it is not possible to deliver to some recipients and not
31907 others. If there is an error (temporary or permanent) for any recipient,
31910 * If more than one smart host is listed, Exim will try another host after a
31911 connection failure or a timeout, in the normal way. However, if this kind
31912 of failure happens for all the hosts, the delivery fails.
31914 * When delivery fails, an error message is written to the standard error
31915 stream (as well as to Exim's log), and Exim exits to the caller with a
31916 return code value 1. The message is expunged from Exim's spool files. No
31917 bounce messages are ever generated.
31919 * No retry data is maintained, and any retry rules are ignored.
31921 * A number of Exim options are overridden: deliver_drop_privilege is forced
31922 true, max_rcpt in the smtp transport is forced to "unlimited",
31923 remote_max_parallel is forced to one, and fallback hosts are ignored.
31925 The overall effect is that Exim makes a single synchronous attempt to deliver
31926 the message, failing if there is any kind of problem. Because no local
31927 deliveries are done and no daemon can be run, Exim does not need root
31928 privilege. It should be possible to run it setuid to exim instead of setuid to
31929 root. See section 54.3 for a general discussion about the advantages and
31930 disadvantages of running without root privilege.
31934 ===============================================================================
31937 Exim writes three different logs, referred to as the main log, the reject log,
31940 * The main log records the arrival of each message and each delivery in a
31941 single line in each case. The format is as compact as possible, in an
31942 attempt to keep down the size of log files. Two-character flag sequences
31943 make it easy to pick out these lines. A number of other events are recorded
31944 in the main log. Some of them are optional, in which case the log_selector
31945 option controls whether they are included or not. A Perl script called
31946 eximstats, which does simple analysis of main log files, is provided in the
31947 Exim distribution (see section 52.7).
31949 * The reject log records information from messages that are rejected as a
31950 result of a configuration option (that is, for policy reasons). The first
31951 line of each rejection is a copy of the line that is also written to the
31952 main log. Then, if the message's header has been read at the time the log
31953 is written, its contents are written to this log. Only the original header
31954 lines are available; header lines added by ACLs are not logged. You can use
31955 the reject log to check that your policy controls are working correctly; on
31956 a busy host this may be easier than scanning the main log for rejection
31957 messages. You can suppress the writing of the reject log by setting
31958 write_rejectlog false.
31960 * When certain serious errors occur, Exim writes entries to its panic log. If
31961 the error is sufficiently disastrous, Exim bombs out afterwards. Panic log
31962 entries are usually written to the main log as well, but can get lost amid
31963 the mass of other entries. The panic log should be empty under normal
31964 circumstances. It is therefore a good idea to check it (or to have a cron
31965 script check it) regularly, in order to become aware of any problems. When
31966 Exim cannot open its panic log, it tries as a last resort to write to the
31967 system log (syslog). This is opened with LOG_PID+LOG_CONS and the facility
31968 code of LOG_MAIL. The message itself is written at priority LOG_CRIT.
31970 Every log line starts with a timestamp, in the format shown in the following
31971 example. Note that many of the examples shown in this chapter are line-wrapped.
31972 In the log file, this would be all on one line:
31974 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed
31977 By default, the timestamps are in the local timezone. There are two ways of
31980 * You can set the timezone option to a different time zone; in particular, if
31985 the timestamps will be in UTC (aka GMT).
31987 * If you set log_timezone true, the time zone is added to the timestamp, for
31990 2003-04-25 11:17:07 +0100 Start queue run: pid=12762
31992 Exim does not include its process id in log lines by default, but you can
31993 request that it does so by specifying the "pid" log selector (see section 51.15
31994 ). When this is set, the process id is output, in square brackets, immediately
31995 after the time and date.
31998 51.1 Where the logs are written
31999 -------------------------------
32001 The logs may be written to local files, or to syslog, or both. However, it
32002 should be noted that many syslog implementations use UDP as a transport, and
32003 are therefore unreliable in the sense that messages are not guaranteed to
32004 arrive at the loghost, nor is the ordering of messages necessarily maintained.
32005 It has also been reported that on large log files (tens of megabytes) you may
32006 need to tweak syslog to prevent it syncing the file with each write - on Linux
32007 this has been seen to make syslog take 90% plus of CPU time.
32009 The destination for Exim's logs is configured by setting LOG_FILE_PATH in Local
32010 /Makefile or by setting log_file_path in the run time configuration. This
32011 latter string is expanded, so it can contain, for example, references to the
32014 log_file_path = /var/log/$primary_hostname/exim_%slog
32016 It is generally advisable, however, to set the string in Local/Makefile rather
32017 than at run time, because then the setting is available right from the start of
32018 Exim's execution. Otherwise, if there's something it wants to log before it has
32019 read the configuration file (for example, an error in the configuration file)
32020 it will not use the path you want, and may not be able to log at all.
32022 The value of LOG_FILE_PATH or log_file_path is a colon-separated list,
32023 currently limited to at most two items. This is one option where the facility
32024 for changing a list separator may not be used. The list must always be
32025 colon-separated. If an item in the list is "syslog" then syslog is used;
32026 otherwise the item must either be an absolute path, containing "%s" at the
32027 point where "main", "reject", or "panic" is to be inserted, or be empty,
32028 implying the use of a default path.
32030 When Exim encounters an empty item in the list, it searches the list defined by
32031 LOG_FILE_PATH, and uses the first item it finds that is neither empty nor
32032 "syslog". This means that an empty item in log_file_path can be used to mean
32033 "use the path specified at build time". It no such item exists, log files are
32034 written in the log subdirectory of the spool directory. This is equivalent to
32037 log_file_path = $spool_directory/log/%slog
32039 If you do not specify anything at build time or run time, that is where the
32042 A log file path may also contain "%D" or "%M" if datestamped log file names are
32043 in use - see section 51.3 below.
32045 Here are some examples of possible settings:
32047 LOG_FILE_PATH=syslog syslog only
32048 LOG_FILE_PATH=:syslog syslog and default path
32049 LOG_FILE_PATH=syslog : /usr/log/exim_%s syslog and specified path
32050 LOG_FILE_PATH=/usr/log/exim_%s specified path only
32052 If there are more than two paths in the list, the first is used and a panic
32056 51.2 Logging to local files that are periodically "cycled"
32057 ----------------------------------------------------------
32059 Some operating systems provide centralized and standardized methods for cycling
32060 log files. For those that do not, a utility script called exicyclog is provided
32061 (see section 52.6). This renames and compresses the main and reject logs each
32062 time it is called. The maximum number of old logs to keep can be set. It is
32063 suggested this script is run as a daily cron job.
32065 An Exim delivery process opens the main log when it first needs to write to it,
32066 and it keeps the file open in case subsequent entries are required - for
32067 example, if a number of different deliveries are being done for the same
32068 message. However, remote SMTP deliveries can take a long time, and this means
32069 that the file may be kept open long after it is renamed if exicyclog or
32070 something similar is being used to rename log files on a regular basis. To
32071 ensure that a switch of log files is noticed as soon as possible, Exim calls
32072 stat() on the main log's name before reusing an open file, and if the file does
32073 not exist, or its inode has changed, the old file is closed and Exim tries to
32074 open the main log from scratch. Thus, an old log file may remain open for quite
32075 some time, but no Exim processes should write to it once it has been renamed.
32078 51.3 Datestamped log files
32079 --------------------------
32081 Instead of cycling the main and reject log files by renaming them periodically,
32082 some sites like to use files whose names contain a datestamp, for example,
32083 mainlog-20031225. The datestamp is in the form yyyymmdd or yyyymm. Exim has
32084 support for this way of working. It is enabled by setting the log_file_path
32085 option to a path that includes "%D" or "%M" at the point where the datestamp is
32086 required. For example:
32088 log_file_path = /var/spool/exim/log/%slog-%D
32089 log_file_path = /var/log/exim-%s-%D.log
32090 log_file_path = /var/spool/exim/log/%D-%slog
32091 log_file_path = /var/log/exim/%s.%M
32093 As before, "%s" is replaced by "main" or "reject"; the following are examples
32094 of names generated by the above examples:
32096 /var/spool/exim/log/mainlog-20021225
32097 /var/log/exim-reject-20021225.log
32098 /var/spool/exim/log/20021225-mainlog
32099 /var/log/exim/main.200212
32101 When this form of log file is specified, Exim automatically switches to new
32102 files at midnight. It does not make any attempt to compress old logs; you will
32103 need to write your own script if you require this. You should not run exicyclog
32104 with this form of logging.
32106 The location of the panic log is also determined by log_file_path, but it is
32107 not datestamped, because rotation of the panic log does not make sense. When
32108 generating the name of the panic log, "%D" or "%M" are removed from the string.
32109 In addition, if it immediately follows a slash, a following non-alphanumeric
32110 character is removed; otherwise a preceding non-alphanumeric character is
32111 removed. Thus, the four examples above would give these panic log names:
32113 /var/spool/exim/log/paniclog
32114 /var/log/exim-panic.log
32115 /var/spool/exim/log/paniclog
32116 /var/log/exim/panic
32119 51.4 Logging to syslog
32120 ----------------------
32122 The use of syslog does not change what Exim logs or the format of its messages,
32123 except in one respect. If syslog_timestamp is set false, the timestamps on
32124 Exim's log lines are omitted when these lines are sent to syslog. Apart from
32125 that, the same strings are written to syslog as to log files. The syslog
32126 "facility" is set to LOG_MAIL, and the program name to "exim" by default, but
32127 you can change these by setting the syslog_facility and syslog_processname
32128 options, respectively. If Exim was compiled with SYSLOG_LOG_PID set in Local/
32129 Makefile (this is the default in src/EDITME), then, on systems that permit it
32130 (all except ULTRIX), the LOG_PID flag is set so that the syslog() call adds the
32131 pid as well as the time and host name to each line. The three log streams are
32132 mapped onto syslog priorities as follows:
32134 * mainlog is mapped to LOG_INFO
32136 * rejectlog is mapped to LOG_NOTICE
32138 * paniclog is mapped to LOG_ALERT
32140 Many log lines are written to both mainlog and rejectlog, and some are written
32141 to both mainlog and paniclog, so there will be duplicates if these are routed
32142 by syslog to the same place. You can suppress this duplication by setting
32143 syslog_duplication false.
32145 Exim's log lines can sometimes be very long, and some of its rejectlog entries
32146 contain multiple lines when headers are included. To cope with both these
32147 cases, entries written to syslog are split into separate syslog() calls at each
32148 internal newline, and also after a maximum of 870 data characters. (This allows
32149 for a total syslog line length of 1024, when additions such as timestamps are
32150 added.) If you are running a syslog replacement that can handle lines longer
32151 than the 1024 characters allowed by RFC 3164, you should set
32153 SYSLOG_LONG_LINES=yes
32155 in Local/Makefile before building Exim. That stops Exim from splitting long
32156 lines, but it still splits at internal newlines in reject log entries.
32158 To make it easy to re-assemble split lines later, each component of a split
32159 entry starts with a string of the form [<n>/<m>] or [<n>\<m>] where <n> is the
32160 component number and <m> is the total number of components in the entry. The /
32161 delimiter is used when the line was split because it was too long; if it was
32162 split because of an internal newline, the \ delimiter is used. For example,
32163 supposing the length limit to be 50 instead of 870, the following would be the
32164 result of a typical rejection message to mainlog (LOG_INFO), each line in
32165 addition being preceded by the time, host name, and pid as added by syslog:
32167 [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from
32168 [2/5] [127.0.0.1] (ph10): syntax error in 'From' header
32169 [3/5] when scanning for sender: missing or malformed lo
32170 [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa
32173 The same error might cause the following lines to be written to "rejectlog"
32176 [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro
32177 [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head
32178 [3/18] er when scanning for sender: missing or malformed
32179 [4/18] local part in "<>" (envelope sender is <ph10@cam
32181 [6\18] Recipients: ph10@some.domain.cam.example
32182 [7\18] P Received: from [127.0.0.1] (ident=ph10)
32183 [8\18] by xxxxx.cam.example with smtp (Exim 4.00)
32184 [9\18] id 16RdAL-0006pc-00
32185 [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16:
32186 [11\18] 09:43 +0100
32188 [13\18] Subject: this is a test header
32189 [18\18] X-something: this is another header
32190 [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp
32193 [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100
32195 Log lines that are neither too long nor contain newlines are written to syslog
32196 without modification.
32198 If only syslog is being used, the Exim monitor is unable to provide a log tail
32199 display, unless syslog is routing mainlog to a file on the local host and the
32200 environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor where it
32204 51.5 Log line flags
32205 -------------------
32207 One line is written to the main log for each message received, and for each
32208 successful, unsuccessful, and delayed delivery. These lines can readily be
32209 picked out by the distinctive two-character flags that immediately follow the
32210 timestamp. The flags are:
32213 => normal message delivery
32214 -> additional address in same delivery
32215 >> cutthrough message delivery
32216 *> delivery suppressed by -N
32217 ** delivery failed; address bounced
32218 == delivery deferred; temporary problem
32221 51.6 Logging message reception
32222 ------------------------------
32224 The format of the single-line entry in the main log that is written for every
32225 message received is shown in the basic example below, which is split over
32226 several lines in order to fit it on the page:
32228 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example
32229 H=mailer.fict.example [192.168.123.123] U=exim
32230 P=smtp S=5678 id=<incoming message id>
32232 The address immediately following "<=" is the envelope sender address. A bounce
32233 message is shown with the sender address "<>", and if it is locally generated,
32234 this is followed by an item of the form
32238 which is a reference to the message that caused the bounce to be sent.
32240 For messages from other hosts, the H and U fields identify the remote host and
32241 record the RFC 1413 identity of the user that sent the message, if one was
32242 received. The number given in square brackets is the IP address of the sending
32243 host. If there is a single, unparenthesized host name in the H field, as above,
32244 it has been verified to correspond to the IP address (see the host_lookup
32245 option). If the name is in parentheses, it was the name quoted by the remote
32246 host in the SMTP HELO or EHLO command, and has not been verified. If
32247 verification yields a different name to that given for HELO or EHLO, the
32248 verified name appears first, followed by the HELO or EHLO name in parentheses.
32250 Misconfigured hosts (and mail forgers) sometimes put an IP address, with or
32251 without brackets, in the HELO or EHLO command, leading to entries in the log
32252 containing text like these examples:
32254 H=(10.21.32.43) [192.168.8.34]
32255 H=([10.21.32.43]) [192.168.8.34]
32257 This can be confusing. Only the final address in square brackets can be relied
32260 For locally generated messages (that is, messages not received over TCP/IP),
32261 the H field is omitted, and the U field contains the login name of the caller
32264 For all messages, the P field specifies the protocol used to receive the
32265 message. This is the value that is stored in $received_protocol. In the case of
32266 incoming SMTP messages, the value indicates whether or not any SMTP extensions
32267 (ESMTP), encryption, or authentication were used. If the SMTP session was
32268 encrypted, there is an additional X field that records the cipher suite that
32271 The protocol is set to "esmtpsa" or "esmtpa" for messages received from hosts
32272 that have authenticated themselves using the SMTP AUTH command. The first value
32273 is used when the SMTP connection was encrypted ("secure"). In this case there
32274 is an additional item A= followed by the name of the authenticator that was
32275 used. If an authenticated identification was set up by the authenticator's
32276 server_set_id option, this is logged too, separated by a colon from the
32277 authenticator name.
32279 The id field records the existing message id, if present. The size of the
32280 received message is given by the S field. When the message is delivered,
32281 headers may be removed or added, so that the size of delivered copies of the
32282 message may not correspond with this value (and indeed may be different to each
32285 The log_selector option can be used to request the logging of additional data
32286 when a message is received. See section 51.15 below.
32289 51.7 Logging deliveries
32290 -----------------------
32292 The format of the single-line entry in the main log that is written for every
32293 delivery is shown in one of the examples below, for local and remote
32294 deliveries, respectively. Each example has been split into two lines in order
32295 to fit it on the page:
32297 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv
32298 <marv@hitch.fict.example> R=localuser T=local_delivery
32299 2002-10-31 09:00:10 16ZCW1-0005MB-00 =>
32300 monk@holistic.fict.example R=dnslookup T=remote_smtp
32301 H=holistic.fict.example [192.168.234.234]
32303 For ordinary local deliveries, the original address is given in angle brackets
32304 after the final delivery address, which might be a pipe or a file. If
32305 intermediate address(es) exist between the original and the final address, the
32306 last of these is given in parentheses after the final address. The R and T
32307 fields record the router and transport that were used to process the address.
32309 If SMTP AUTH was used for the delivery there is an additional item A= followed
32310 by the name of the authenticator that was used. If an authenticated
32311 identification was set up by the authenticator's client_set_id option, this is
32312 logged too, separated by a colon from the authenticator name.
32314 If a shadow transport was run after a successful local delivery, the log line
32315 for the successful delivery has an item added on the end, of the form
32317 ST=<shadow transport name>
32319 If the shadow transport did not succeed, the error message is put in
32320 parentheses afterwards.
32322 When more than one address is included in a single delivery (for example, two
32323 SMTP RCPT commands in one transaction) the second and subsequent addresses are
32324 flagged with "->" instead of "=>". When two or more messages are delivered down
32325 a single SMTP connection, an asterisk follows the IP address in the log lines
32326 for the second and subsequent messages.
32328 When delivery is done in cutthrough mode it is flagged with ">>" and the log
32329 line precedes the reception line, since cutthrough waits for a possible
32330 rejection from the destination in case it can reject the sourced item.
32332 The generation of a reply message by a filter file gets logged as a "delivery"
32333 to the addressee, preceded by ">".
32335 The log_selector option can be used to request the logging of additional data
32336 when a message is delivered. See section 51.15 below.
32339 51.8 Discarded deliveries
32340 -------------------------
32342 When a message is discarded as a result of the command "seen finish" being
32343 obeyed in a filter file which generates no deliveries, a log entry of the form
32345 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded
32346 <low.club@bridge.example> R=userforward
32348 is written, to record why no deliveries are logged. When a message is discarded
32349 because it is aliased to ":blackhole:" the log line is like this:
32351 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole:
32352 <hole@nowhere.example> R=blackhole_router
32355 51.9 Deferred deliveries
32356 ------------------------
32358 When a delivery is deferred, a line of the following form is logged:
32360 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example
32361 R=dnslookup T=smtp defer (146): Connection refused
32363 In the case of remote deliveries, the error is the one that was given for the
32364 last IP address that was tried. Details of individual SMTP failures are also
32365 written to the log, so the above line would be preceded by something like
32367 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to
32368 mail1.endrest.example [192.168.239.239]: Connection refused
32370 When a deferred address is skipped because its retry time has not been reached,
32371 a message is written to the log, but this can be suppressed by setting an
32372 appropriate value in log_selector.
32375 51.10 Delivery failures
32376 -----------------------
32378 If a delivery fails because an address cannot be routed, a line of the
32379 following form is logged:
32381 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example
32382 <jim@trek99.example>: unknown mail domain
32384 If a delivery fails at transport time, the router and transport are shown, and
32385 the response from the remote host is included, as in this example:
32387 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example
32388 R=dnslookup T=remote_smtp: SMTP error from remote mailer
32389 after pipelined RCPT TO:<ace400@pb.example>: host
32390 pbmail3.py.example [192.168.63.111]: 553 5.3.0
32391 <ace400@pb.example>...Addressee unknown
32393 The word "pipelined" indicates that the SMTP PIPELINING extension was being
32394 used. See hosts_avoid_esmtp in the smtp transport for a way of disabling
32395 PIPELINING. The log lines for all forms of delivery failure are flagged with
32399 51.11 Fake deliveries
32400 ---------------------
32402 If a delivery does not actually take place because the -N option has been used
32403 to suppress it, a normal delivery line is written to the log, except that "=>"
32404 is replaced by "*>".
32412 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed
32414 is written to the main log when a message is about to be removed from the spool
32415 at the end of its processing.
32418 51.13 Summary of Fields in Log Lines
32419 ------------------------------------
32421 A summary of the field identifiers that are used in log lines is shown in the
32424 A authenticator name (and optional id and sender)
32425 C SMTP confirmation on delivery
32426 command list for "no mail in SMTP session"
32427 CV certificate verification status
32428 D duration of "no mail in SMTP session"
32429 DN distinguished name from peer certificate
32430 DT on => lines: time taken for a delivery
32431 F sender address (on delivery lines)
32432 H host name and IP address
32433 I local interface used
32434 id message id for incoming message
32435 P on <= lines: protocol used
32436 on => and ** lines: return path
32437 QT on => lines: time spent on queue so far
32438 on "Completed" lines: time spent on queue
32439 R on <= lines: reference for local bounce
32440 on => ** and == lines: router name
32442 SNI server name indication from TLS client hello
32443 ST shadow transport name
32444 T on <= lines: message subject (topic)
32445 on => ** and == lines: transport name
32446 U local user or RFC 1413 identity
32450 51.14 Other log entries
32451 -----------------------
32453 Various other types of log entry are written from time to time. Most should be
32454 self-explanatory. Among the more common are:
32456 * retry time not reached An address previously suffered a temporary error
32457 during routing or local delivery, and the time to retry has not yet
32458 arrived. This message is not written to an individual message log file
32459 unless it happens during the first delivery attempt.
32461 * retry time not reached for any host An address previously suffered
32462 temporary errors during remote delivery, and the retry time has not yet
32463 arrived for any of the hosts to which it is routed.
32465 * spool file locked An attempt to deliver a message cannot proceed because
32466 some other Exim process is already working on the message. This can be
32467 quite common if queue running processes are started at frequent intervals.
32468 The exiwhat utility script can be used to find out what Exim processes are
32471 * error ignored There are several circumstances that give rise to this
32474 1. Exim failed to deliver a bounce message whose age was greater than
32475 ignore_bounce_errors_after. The bounce was discarded.
32477 2. A filter file set up a delivery using the "noerror" option, and the
32478 delivery failed. The delivery was discarded.
32480 3. A delivery set up by a router configured with
32484 failed. The delivery was discarded.
32487 51.15 Reducing or increasing what is logged
32488 -------------------------------------------
32490 By setting the log_selector global option, you can disable some of Exim's
32491 default logging, or you can request additional logging. The value of
32492 log_selector is made up of names preceded by plus or minus characters. For
32495 log_selector = +arguments -retry_defer
32497 The list of optional log items is in the following table, with the default
32498 selection marked by asterisks:
32500 8bitmime received 8BITMIME status
32501 *acl_warn_skipped skipped warn statement in ACL
32502 address_rewrite address rewriting
32503 all_parents all parents in => lines
32504 arguments command line arguments
32505 *connection_reject connection rejections
32506 *delay_delivery immediate delivery delayed
32507 deliver_time time taken to perform delivery
32508 delivery_size add S=nnn to => lines
32509 *dnslist_defer defers of DNS list (aka RBL) lookups
32510 *etrn ETRN commands
32511 *host_lookup_failed as it says
32512 ident_timeout timeout for ident connection
32513 incoming_interface incoming interface on <= lines
32514 incoming_port incoming port on <= lines
32515 *lost_incoming_connection as it says (includes timeouts)
32516 outgoing_port add remote port to => lines
32517 *queue_run start and end queue runs
32518 queue_time time on queue for one recipient
32519 queue_time_overall time on queue for whole message
32520 pid Exim process id
32521 received_recipients recipients on <= lines
32522 received_sender sender on <= lines
32523 *rejected_header header contents on reject log
32524 *retry_defer "retry time not reached"
32525 return_path_on_delivery put return path on => and ** lines
32526 sender_on_delivery add sender to => lines
32527 *sender_verify_fail sender verification failures
32528 *size_reject rejection because too big
32529 *skip_delivery delivery skipped in a queue run
32530 *smtp_confirmation SMTP confirmation on => lines
32531 smtp_connection SMTP connections
32532 smtp_incomplete_transaction incomplete SMTP transactions
32533 smtp_mailauth AUTH argument to MAIL commands
32534 smtp_no_mail session with no MAIL commands
32535 smtp_protocol_error SMTP protocol errors
32536 smtp_syntax_error SMTP syntax errors
32537 subject contents of Subject: on <= lines
32538 tls_certificate_verified certificate verification status
32539 *tls_cipher TLS cipher suite on <= and => lines
32540 tls_peerdn TLS peer DN on <= and => lines
32541 tls_sni TLS SNI on <= lines
32542 unknown_in_list DNS lookup failed in list match
32544 all all of the above
32546 More details on each of these items follows:
32548 * 8bitmime: This causes Exim to log any 8BITMIME status of received messages,
32549 which may help in tracking down interoperability issues with ancient MTAs
32550 that are not 8bit clean. This is added to the "<=" line, tagged with "M8S="
32551 and a value of "0", "7" or "8", corresponding to "not given", "7BIT" and
32552 "8BITMIME" respectively.
32554 * acl_warn_skipped: When an ACL warn statement is skipped because one of its
32555 conditions cannot be evaluated, a log line to this effect is written if
32556 this log selector is set.
32558 * address_rewrite: This applies both to global rewrites and per-transport
32559 rewrites, but not to rewrites in filters run as an unprivileged user
32560 (because such users cannot access the log).
32562 * all_parents: Normally only the original and final addresses are logged on
32563 delivery lines; with this selector, intermediate parents are given in
32564 parentheses between them.
32566 * arguments: This causes Exim to write the arguments with which it was called
32567 to the main log, preceded by the current working directory. This is a
32568 debugging feature, added to make it easier to find out how certain MUAs
32569 call /usr/sbin/sendmail. The logging does not happen if Exim has given up
32570 root privilege because it was called with the -C or -D options. Arguments
32571 that are empty or that contain white space are quoted. Non-printing
32572 characters are shown as escape sequences. This facility cannot log
32573 unrecognized arguments, because the arguments are checked before the
32574 configuration file is read. The only way to log such cases is to interpose
32575 a script such as util/logargs.sh between the caller and Exim.
32577 * connection_reject: A log entry is written whenever an incoming SMTP
32578 connection is rejected, for whatever reason.
32580 * delay_delivery: A log entry is written whenever a delivery process is not
32581 started for an incoming message because the load is too high or too many
32582 messages were received on one connection. Logging does not occur if no
32583 delivery process is started because queue_only is set or -odq was used.
32585 * deliver_time: For each delivery, the amount of real time it has taken to
32586 perform the actual delivery is logged as DT=<time>, for example, "DT=1s".
32588 * delivery_size: For each delivery, the size of message delivered is added to
32589 the "=>" line, tagged with S=.
32591 * dnslist_defer: A log entry is written if an attempt to look up a host in a
32592 DNS black list suffers a temporary error.
32594 * etrn: Every valid ETRN command that is received is logged, before the ACL
32595 is run to determine whether or not it is actually accepted. An invalid ETRN
32596 command, or one received within a message transaction is not logged by this
32597 selector (see smtp_syntax_error and smtp_protocol_error).
32599 * host_lookup_failed: When a lookup of a host's IP addresses fails to find
32600 any addresses, or when a lookup of an IP address fails to find a host name,
32601 a log line is written. This logging does not apply to direct DNS lookups
32602 when routing email addresses, but it does apply to "byname" lookups.
32604 * ident_timeout: A log line is written whenever an attempt to connect to a
32605 client's ident port times out.
32607 * incoming_interface: The interface on which a message was received is added
32608 to the "<=" line as an IP address in square brackets, tagged by I= and
32609 followed by a colon and the port number. The local interface and port are
32610 also added to other SMTP log lines, for example "SMTP connection from", and
32611 to rejection lines.
32613 * incoming_port: The remote port number from which a message was received is
32614 added to log entries and Received: header lines, following the IP address
32615 in square brackets, and separated from it by a colon. This is implemented
32616 by changing the value that is put in the $sender_fullhost and
32617 $sender_rcvhost variables. Recording the remote port number has become more
32618 important with the widening use of NAT (see RFC 2505).
32620 * lost_incoming_connection: A log line is written when an incoming SMTP
32621 connection is unexpectedly dropped.
32623 * outgoing_port: The remote port number is added to delivery log lines (those
32624 containing => tags) following the IP address. This option is not included
32625 in the default setting, because for most ordinary configurations, the
32626 remote port number is always 25 (the SMTP port).
32628 * pid: The current process id is added to every log line, in square brackets,
32629 immediately after the time and date.
32631 * queue_run: The start and end of every queue run are logged.
32633 * queue_time: The amount of time the message has been in the queue on the
32634 local host is logged as QT=<time> on delivery ("=>") lines, for example,
32635 "QT=3m45s". The clock starts when Exim starts to receive the message, so it
32636 includes reception time as well as the delivery time for the current
32637 address. This means that it may be longer than the difference between the
32638 arrival and delivery log line times, because the arrival log line is not
32639 written until the message has been successfully received.
32641 * queue_time_overall: The amount of time the message has been in the queue on
32642 the local host is logged as QT=<time> on "Completed" lines, for example,
32643 "QT=3m45s". The clock starts when Exim starts to receive the message, so it
32644 includes reception time as well as the total delivery time.
32646 * received_recipients: The recipients of a message are listed in the main log
32647 as soon as the message is received. The list appears at the end of the log
32648 line that is written when a message is received, preceded by the word
32649 "for". The addresses are listed after they have been qualified, but before
32650 any rewriting has taken place. Recipients that were discarded by an ACL for
32651 MAIL or RCPT do not appear in the list.
32653 * received_sender: The unrewritten original sender of a message is added to
32654 the end of the log line that records the message's arrival, after the word
32655 "from" (before the recipients if received_recipients is also set).
32657 * rejected_header: If a message's header has been received at the time a
32658 rejection is written to the reject log, the complete header is added to the
32659 log. Header logging can be turned off individually for messages that are
32660 rejected by the local_scan() function (see section 44.2).
32662 * retry_defer: A log line is written if a delivery is deferred because a
32663 retry time has not yet been reached. However, this "retry time not reached"
32664 message is always omitted from individual message logs after the first
32667 * return_path_on_delivery: The return path that is being transmitted with the
32668 message is included in delivery and bounce lines, using the tag P=. This is
32669 omitted if no delivery actually happens, for example, if routing fails, or
32670 if delivery is to /dev/null or to ":blackhole:".
32672 * sender_on_delivery: The message's sender address is added to every delivery
32673 and bounce line, tagged by F= (for "from"). This is the original sender
32674 that was received with the message; it is not necessarily the same as the
32675 outgoing return path.
32677 * sender_verify_fail: If this selector is unset, the separate log line that
32678 gives details of a sender verification failure is not written. Log lines
32679 for the rejection of SMTP commands contain just "sender verify failed", so
32680 some detail is lost.
32682 * size_reject: A log line is written whenever a message is rejected because
32685 * skip_delivery: A log line is written whenever a message is skipped during a
32686 queue run because it is frozen or because another process is already
32687 delivering it. The message that is written is "spool file is locked".
32689 * smtp_confirmation: The response to the final "." in the SMTP or LMTP
32690 dialogue for outgoing messages is added to delivery log lines in the form
32691 "C="<text>. A number of MTAs (including Exim) return an identifying string
32694 * smtp_connection: A log line is written whenever an SMTP connection is
32695 established or closed, unless the connection is from a host that matches
32696 hosts_connection_nolog. (In contrast, lost_incoming_connection applies only
32697 when the closure is unexpected.) This applies to connections from local
32698 processes that use -bs as well as to TCP/IP connections. If a connection is
32699 dropped in the middle of a message, a log line is always written, whether
32700 or not this selector is set, but otherwise nothing is written at the start
32701 and end of connections unless this selector is enabled.
32703 For TCP/IP connections to an Exim daemon, the current number of connections
32704 is included in the log message for each new connection, but note that the
32705 count is reset if the daemon is restarted. Also, because connections are
32706 closed (and the closure is logged) in subprocesses, the count may not
32707 include connections that have been closed but whose termination the daemon
32708 has not yet noticed. Thus, while it is possible to match up the opening and
32709 closing of connections in the log, the value of the logged counts may not
32710 be entirely accurate.
32712 * smtp_incomplete_transaction: When a mail transaction is aborted by RSET,
32713 QUIT, loss of connection, or otherwise, the incident is logged, and the
32714 message sender plus any accepted recipients are included in the log line.
32715 This can provide evidence of dictionary attacks.
32717 * smtp_no_mail: A line is written to the main log whenever an accepted SMTP
32718 connection terminates without having issued a MAIL command. This includes
32719 both the case when the connection is dropped, and the case when QUIT is
32720 used. It does not include cases where the connection is rejected right at
32721 the start (by an ACL, or because there are too many connections, or
32722 whatever). These cases already have their own log lines.
32724 The log line that is written contains the identity of the client in the
32725 usual way, followed by D= and a time, which records the duration of the
32726 connection. If the connection was authenticated, this fact is logged
32727 exactly as it is for an incoming message, with an A= item. If the
32728 connection was encrypted, CV=, DN=, and X= items may appear as they do for
32729 an incoming message, controlled by the same logging options.
32731 Finally, if any SMTP commands were issued during the connection, a C= item
32732 is added to the line, listing the commands that were used. For example,
32736 shows that the client issued QUIT straight after EHLO. If there were fewer
32737 than 20 commands, they are all listed. If there were more than 20 commands,
32738 the last 20 are listed, preceded by "...". However, with the default
32739 setting of 10 for smtp_accep_max_nonmail, the connection will in any case
32740 have been aborted before 20 non-mail commands are processed.
32742 * smtp_mailauth: A third subfield with the authenticated sender,
32743 colon-separated, is appended to the A= item for a message arrival or
32744 delivery log line, if an AUTH argument to the SMTP MAIL command (see 33.2)
32745 was accepted or used.
32747 * smtp_protocol_error: A log line is written for every SMTP protocol error
32748 encountered. Exim does not have perfect detection of all protocol errors
32749 because of transmission delays and the use of pipelining. If PIPELINING has
32750 been advertised to a client, an Exim server assumes that the client will
32751 use it, and therefore it does not count "expected" errors (for example,
32752 RCPT received after rejecting MAIL) as protocol errors.
32754 * smtp_syntax_error: A log line is written for every SMTP syntax error
32755 encountered. An unrecognized command is treated as a syntax error. For an
32756 external connection, the host identity is given; for an internal connection
32757 using -bs the sender identification (normally the calling user) is given.
32759 * subject: The subject of the message is added to the arrival log line,
32760 preceded by "T=" (T for "topic", since S is already used for "size"). Any
32761 MIME "words" in the subject are decoded. The print_topbitchars option
32762 specifies whether characters with values greater than 127 should be logged
32763 unchanged, or whether they should be rendered as escape sequences.
32765 * tls_certificate_verified: An extra item is added to <= and => log lines
32766 when TLS is in use. The item is "CV=yes" if the peer's certificate was
32767 verified, and "CV=no" if not.
32769 * tls_cipher: When a message is sent or received over an encrypted
32770 connection, the cipher suite used is added to the log line, preceded by X=.
32772 * tls_peerdn: When a message is sent or received over an encrypted
32773 connection, and a certificate is supplied by the remote host, the peer DN
32774 is added to the log line, preceded by DN=.
32776 * tls_sni: When a message is received over an encrypted connection, and the
32777 remote host provided the Server Name Indication extension, the SNI is added
32778 to the log line, preceded by SNI=.
32780 * unknown_in_list: This setting causes a log entry to be written when the
32781 result of a list match is failure because a DNS lookup failed.
32787 In addition to the general log files, Exim writes a log file for each message
32788 that it handles. The names of these per-message logs are the message ids, and
32789 they are kept in the msglog sub-directory of the spool directory. Each message
32790 log contains copies of the log lines that apply to the message. This makes it
32791 easier to inspect the status of an individual message without having to search
32792 the main log. A message log is deleted when processing of the message is
32793 complete, unless preserve_message_logs is set, but this should be used only
32794 with great care because they can fill up your disk very quickly.
32796 On a heavily loaded system, it may be desirable to disable the use of
32797 per-message logs, in order to reduce disk I/O. This can be done by setting the
32798 message_logs option false.
32802 ===============================================================================
32805 A number of utility scripts and programs are supplied with Exim and are
32806 described in this chapter. There is also the Exim Monitor, which is covered in
32807 the next chapter. The utilities described here are:
32809 52.1 exiwhat list what Exim processes are doing
32810 52.2 exiqgrep grep the queue
32811 52.3 exiqsumm summarize the queue
32812 52.4 exigrep search the main log
32813 52.5 exipick select messages on various criteria
32814 52.6 exicyclog cycle (rotate) log files
32815 52.7 eximstats extract statistics from the log
32816 52.8 exim_checkaccess check address acceptance from given IP
32817 52.9 exim_dbmbuild build a DBM file
32818 52.10 exinext extract retry information
32819 52.11 exim_dumpdb dump a hints database
32820 52.11 exim_tidydb clean up a hints database
32821 52.11 exim_fixdb patch a hints database
32822 52.15 exim_lock lock a mailbox file
32824 Another utility that might be of use to sites with many MTAs is Tom Kistner's
32825 exilog. It provides log visualizations across multiple Exim servers. See http:/
32826 /duncanthrax.net/exilog/ for details.
32829 52.1 Finding out what Exim processes are doing (exiwhat)
32830 --------------------------------------------------------
32832 On operating systems that can restart a system call after receiving a signal
32833 (most modern OS), an Exim process responds to the SIGUSR1 signal by writing a
32834 line describing what it is doing to the file exim-process.info in the Exim
32835 spool directory. The exiwhat script sends the signal to all Exim processes it
32836 can find, having first emptied the file. It then waits for one second to allow
32837 the Exim processes to react before displaying the results. In order to run
32838 exiwhat successfully you have to have sufficient privilege to send the signal
32839 to the Exim processes, so it is normally run as root.
32841 Warning: This is not an efficient process. It is intended for occasional use by
32842 system administrators. It is not sensible, for example, to set up a script that
32843 sends SIGUSR1 signals to Exim processes at short intervals.
32845 Unfortunately, the ps command that exiwhat uses to find Exim processes varies
32846 in different operating systems. Not only are different options used, but the
32847 format of the output is different. For this reason, there are some system
32848 configuration options that configure exactly how exiwhat works. If it doesn't
32849 seem to be working for you, check the following compile-time options:
32851 EXIWHAT_PS_CMD the command for running ps
32852 EXIWHAT_PS_ARG the argument for ps
32853 EXIWHAT_EGREP_ARG the argument for egrep to select from ps output
32854 EXIWHAT_KILL_ARG the argument for the kill command
32856 An example of typical output from exiwhat is
32858 164 daemon: -q1h, listening on port 25
32859 10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
32860 10492 delivering 0tAycK-0002ij-00 to mail.ref.example
32861 [10.19.42.42] (editor@ref.example)
32862 10592 handling incoming call from [192.168.243.242]
32863 10628 accepting a local non-SMTP message
32865 The first number in the output line is the process number. The third line has
32866 been split here, in order to fit it on the page.
32869 52.2 Selective queue listing (exiqgrep)
32870 ---------------------------------------
32872 This utility is a Perl script contributed by Matt Hubbard. It runs
32876 or (in case -a switch is specified)
32880 The -C option is used to specify an alternate exim.conf which might contain
32881 alternate exim configuration the queue management might be using.
32883 to obtain a queue listing, and then greps the output to select messages that
32884 match given criteria. The following selection options are available:
32888 Match the sender address using a case-insensitive search. The field that is
32889 tested is enclosed in angle brackets, so you can test for bounce messages
32896 Match a recipient address using a case-insensitve search. The field that is
32897 tested is not enclosed in angle brackets.
32901 Match against the size field.
32905 Match messages that are younger than the given time.
32909 Match messages that are older than the given time.
32913 Match only frozen messages.
32917 Match only non-frozen messages.
32919 The following options control the format of the output:
32923 Display only the count of matching messages.
32927 Long format - display the full message information as output by Exim. This
32932 Display message ids only.
32936 Brief format - one line per message.
32940 Display messages in reverse order.
32944 Include delivered recipients in queue listing.
32946 There is one more option, -h, which outputs a list of options.
32949 52.3 Summarizing the queue (exiqsumm)
32950 -------------------------------------
32952 The exiqsumm utility is a Perl script which reads the output of "exim -bp" and
32953 produces a summary of the messages on the queue. Thus, you use it by running a
32956 exim -bp | exiqsumm
32958 The output consists of one line for each domain that has messages waiting for
32959 it, as in the following example:
32961 3 2322 74m 66m msn.com.example
32963 Each line lists the number of pending deliveries for a domain, their total
32964 volume, and the length of time that the oldest and the newest messages have
32965 been waiting. Note that the number of pending deliveries is greater than the
32966 number of messages when messages have more than one recipient.
32968 A summary line is output at the end. By default the output is sorted on the
32969 domain name, but exiqsumm has the options -a and -c, which cause the output to
32970 be sorted by oldest message and by count of messages, respectively. There are
32971 also three options that split the messages for each domain into two or more
32972 subcounts: -b separates bounce messages, -f separates frozen messages, and -s
32973 separates messages according to their sender.
32975 The output of exim -bp contains the original addresses in the message, so this
32976 also applies to the output from exiqsumm. No domains from addresses generated
32977 by aliasing or forwarding are included (unless the one_time option of the
32978 redirect router has been used to convert them into "top level" addresses).
32981 52.4 Extracting specific information from the log (exigrep)
32982 -----------------------------------------------------------
32984 The exigrep utility is a Perl script that searches one or more main log files
32985 for entries that match a given pattern. When it finds a match, it extracts all
32986 the log entries for the relevant message, not just those that match the
32987 pattern. Thus, exigrep can extract complete log entries for a given message, or
32988 all mail for a given user, or for a given host, for example. The input files
32989 can be in Exim log format or syslog format. If a matching log line is not
32990 associated with a specific message, it is included in exigrep's output without
32991 any additional lines. The usage is:
32993 exigrep [-t<n>] [-I] [-l] [-v] <pattern> [<log file>] ...
32995 If no log file names are given on the command line, the standard input is read.
32997 The -t argument specifies a number of seconds. It adds an additional condition
32998 for message selection. Messages that are complete are shown only if they spent
32999 more than <n> seconds on the queue.
33001 By default, exigrep does case-insensitive matching. The -I option makes it
33002 case-sensitive. This may give a performance improvement when searching large
33003 log files. Without -I, the Perl pattern matches use Perl's "/i" option; with -I
33004 they do not. In both cases it is possible to change the case sensitivity within
33005 the pattern by using "(?i)" or "(?-i)".
33007 The -l option means "literal", that is, treat all characters in the pattern as
33008 standing for themselves. Otherwise the pattern must be a Perl regular
33011 The -v option inverts the matching condition. That is, a line is selected if it
33012 does not match the pattern.
33014 If the location of a zcat command is known from the definition of ZCAT_COMMAND
33015 in Local/Makefile, exigrep automatically passes any file whose name ends in
33016 COMPRESS_SUFFIX through zcat as it searches it.
33019 52.5 Selecting messages by various criteria (exipick)
33020 -----------------------------------------------------
33022 John Jetmore's exipick utility is included in the Exim distribution. It lists
33023 messages from the queue according to a variety of criteria. For details of
33024 exipick's facilities, visit the web page at http://www.exim.org/eximwiki/
33025 ToolExipickManPage or run exipick with the --help option.
33028 52.6 Cycling log files (exicyclog)
33029 ----------------------------------
33031 The exicyclog script can be used to cycle (rotate) mainlog and rejectlog files.
33032 This is not necessary if only syslog is being used, or if you are using log
33033 files with datestamps in their names (see section 51.3). Some operating systems
33034 have their own standard mechanisms for log cycling, and these can be used
33035 instead of exicyclog if preferred. There are two command line options for
33038 * -k <count> specifies the number of log files to keep, overriding the
33039 default that is set when Exim is built. The default default is 10.
33041 * -l <path> specifies the log file path, in the same format as Exim's
33042 log_file_path option (for example, "/var/log/exim_%slog"), again overriding
33043 the script's default, which is to find the setting from Exim's
33046 Each time exicyclog is run the file names get "shuffled down" by one. If the
33047 main log file name is mainlog (the default) then when exicyclog is run mainlog
33048 becomes mainlog.01, the previous mainlog.01 becomes mainlog.02 and so on, up to
33049 the limit that is set in the script or by the -k option. Log files whose
33050 numbers exceed the limit are discarded. Reject logs are handled similarly.
33052 If the limit is greater than 99, the script uses 3-digit numbers such as
33053 mainlog.001, mainlog.002, etc. If you change from a number less than 99 to one
33054 that is greater, or vice versa, you will have to fix the names of any existing
33057 If no mainlog file exists, the script does nothing. Files that "drop off" the
33058 end are deleted. All files with numbers greater than 01 are compressed, using a
33059 compression command which is configured by the COMPRESS_COMMAND setting in
33060 Local/Makefile. It is usual to run exicyclog daily from a root crontab entry of
33063 1 0 * * * su exim -c /usr/exim/bin/exicyclog
33065 assuming you have used the name "exim" for the Exim user. You can run exicyclog
33066 as root if you wish, but there is no need.
33069 52.7 Mail statistics (eximstats)
33070 --------------------------------
33072 A Perl script called eximstats is provided for extracting statistical
33073 information from log files. The output is either plain text, or HTML. Exim log
33074 files are also supported by the Lire system produced by the LogReport
33075 Foundation http://www.logreport.org.
33077 The eximstats script has been hacked about quite a bit over time. The latest
33078 version is the result of some extensive revision by Steve Campbell. A lot of
33079 information is given by default, but there are options for suppressing various
33080 parts of it. Following any options, the arguments to the script are a list of
33081 files, which should be main log files. For example:
33083 eximstats -nr /var/spool/exim/log/mainlog.01
33085 By default, eximstats extracts information about the number and volume of
33086 messages received from or delivered to various hosts. The information is sorted
33087 both by message count and by volume, and the top fifty hosts in each category
33088 are listed on the standard output. Similar information, based on email
33089 addresses or domains instead of hosts can be requested by means of various
33090 options. For messages delivered and received locally, similar statistics are
33091 also produced per user.
33093 The output also includes total counts and statistics about delivery errors, and
33094 histograms showing the number of messages received and deliveries made in each
33095 hour of the day. A delivery with more than one address in its envelope (for
33096 example, an SMTP transaction with more than one RCPT command) is counted as a
33097 single delivery by eximstats.
33099 Though normally more deliveries than receipts are reported (as messages may
33100 have multiple recipients), it is possible for eximstats to report more messages
33101 received than delivered, even though the queue is empty at the start and end of
33102 the period in question. If an incoming message contains no valid recipients, no
33103 deliveries are recorded for it. A bounce message is handled as an entirely
33106 eximstats always outputs a grand total summary giving the volume and number of
33107 messages received and deliveries made, and the number of hosts involved in each
33108 case. It also outputs the number of messages that were delayed (that is, not
33109 completely delivered at the first attempt), and the number that had at least
33110 one address that failed.
33112 The remainder of the output is in sections that can be independently disabled
33113 or modified by various options. It consists of a summary of deliveries by
33114 transport, histograms of messages received and delivered per time interval
33115 (default per hour), information about the time messages spent on the queue, a
33116 list of relayed messages, lists of the top fifty sending hosts, local senders,
33117 destination hosts, and destination local users by count and by volume, and a
33118 list of delivery errors that occurred.
33120 The relay information lists messages that were actually relayed, that is, they
33121 came from a remote host and were directly delivered to some other remote host,
33122 without being processed (for example, for aliasing or forwarding) locally.
33124 There are quite a few options for eximstats to control exactly what it outputs.
33125 These are documented in the Perl script itself, and can be extracted by running
33126 the command perldoc on the script. For example:
33128 perldoc /usr/exim/bin/eximstats
33131 52.8 Checking access policy (exim_checkaccess)
33132 ----------------------------------------------
33134 The -bh command line argument allows you to run a fake SMTP session with
33135 debugging output, in order to check what Exim is doing when it is applying
33136 policy controls to incoming SMTP mail. However, not everybody is sufficiently
33137 familiar with the SMTP protocol to be able to make full use of -bh, and
33138 sometimes you just want to answer the question "Does this address have access?"
33139 without bothering with any further details.
33141 The exim_checkaccess utility is a "packaged" version of -bh. It takes two
33142 arguments, an IP address and an email address:
33144 exim_checkaccess 10.9.8.7 A.User@a.domain.example
33146 The utility runs a call to Exim with the -bh option, to test whether the given
33147 email address would be accepted in a RCPT command in a TCP/IP connection from
33148 the host with the given IP address. The output of the utility is either the
33149 word "accepted", or the SMTP error response, for example:
33152 550 Relay not permitted
33154 When running this test, the utility uses "<>" as the envelope sender address
33155 for the MAIL command, but you can change this by providing additional options.
33156 These are passed directly to the Exim command. For example, to specify that the
33157 test is to be run with the sender address himself@there.example you can use:
33159 exim_checkaccess 10.9.8.7 A.User@a.domain.example \
33160 -f himself@there.example
33162 Note that these additional Exim command line items must be given after the two
33163 mandatory arguments.
33165 Because the exim_checkaccess uses -bh, it does not perform callouts while
33166 running its checks. You can run checks that include callouts by using -bhc, but
33167 this is not yet available in a "packaged" form.
33170 52.9 Making DBM files (exim_dbmbuild)
33171 -------------------------------------
33173 The exim_dbmbuild program reads an input file containing keys and data in the
33174 format used by the lsearch lookup (see section 9.3). It writes a DBM file using
33175 the lower-cased alias names as keys and the remainder of the information as
33176 data. The lower-casing can be prevented by calling the program with the -nolc
33179 A terminating zero is included as part of the key string. This is expected by
33180 the dbm lookup type. However, if the option -nozero is given, exim_dbmbuild
33181 creates files without terminating zeroes in either the key strings or the data
33182 strings. The dbmnz lookup type can be used with such files.
33184 The program requires two arguments: the name of the input file (which can be a
33185 single hyphen to indicate the standard input), and the name of the output file.
33186 It creates the output under a temporary name, and then renames it if all went
33189 If the native DB interface is in use (USE_DB is set in a compile-time
33190 configuration file - this is common in free versions of Unix) the two file
33191 names must be different, because in this mode the Berkeley DB functions create
33192 a single output file using exactly the name given. For example,
33194 exim_dbmbuild /etc/aliases /etc/aliases.db
33196 reads the system alias file and creates a DBM version of it in /etc/aliases.db.
33198 In systems that use the ndbm routines (mostly proprietary versions of Unix),
33199 two files are used, with the suffixes .dir and .pag. In this environment, the
33200 suffixes are added to the second argument of exim_dbmbuild, so it can be the
33201 same as the first. This is also the case when the Berkeley functions are used
33202 in compatibility mode (though this is not recommended), because in that case it
33203 adds a .db suffix to the file name.
33205 If a duplicate key is encountered, the program outputs a warning, and when it
33206 finishes, its return code is 1 rather than zero, unless the -noduperr option is
33207 used. By default, only the first of a set of duplicates is used - this makes it
33208 compatible with lsearch lookups. There is an option -lastdup which causes it to
33209 use the data for the last duplicate instead. There is also an option -nowarn,
33210 which stops it listing duplicate keys to stderr. For other errors, where it
33211 doesn't actually make a new file, the return code is 2.
33214 52.10 Finding individual retry times (exinext)
33215 ----------------------------------------------
33217 A utility called exinext (mostly a Perl script) provides the ability to fish
33218 specific information out of the retry database. Given a mail domain (or a
33219 complete address), it looks up the hosts for that domain, and outputs any retry
33220 information for the hosts or for the domain. At present, the retry information
33221 is obtained by running exim_dumpdb (see below) and post-processing the output.
33224 $ exinext piglet@milne.fict.example
33225 kanga.milne.example:192.168.8.1 error 146: Connection refused
33226 first failed: 21-Feb-1996 14:57:34
33227 last tried: 21-Feb-1996 14:57:34
33228 next try at: 21-Feb-1996 15:02:34
33229 roo.milne.example:192.168.8.3 error 146: Connection refused
33230 first failed: 20-Jan-1996 13:12:08
33231 last tried: 21-Feb-1996 11:42:03
33232 next try at: 21-Feb-1996 19:42:03
33233 past final cutoff time
33235 You can also give exinext a local part, without a domain, and it will give any
33236 retry information for that local part in your default domain. A message id can
33237 be used to obtain retry information pertaining to a specific message. This
33238 exists only when an attempt to deliver a message to a remote host suffers a
33239 message-specific error (see section 47.2). exinext is not particularly
33240 efficient, but then it is not expected to be run very often.
33242 The exinext utility calls Exim to find out information such as the location of
33243 the spool directory. The utility has -C and -D options, which are passed on to
33244 the exim commands. The first specifies an alternate Exim configuration file,
33245 and the second sets macros for use within the configuration file. These
33246 features are mainly to help in testing, but might also be useful in
33247 environments where more than one configuration file is in use.
33250 52.11 Hints database maintenance
33251 --------------------------------
33253 Three utility programs are provided for maintaining the DBM files that Exim
33254 uses to contain its delivery hint information. Each program requires two
33255 arguments. The first specifies the name of Exim's spool directory, and the
33256 second is the name of the database it is to operate on. These are as follows:
33258 * retry: the database of retry information
33260 * wait-<transport name>: databases of information about messages waiting for
33263 * callout: the callout cache
33265 * ratelimit: the data for implementing the ratelimit ACL condition
33267 * misc: other hints data
33269 The misc database is used for
33271 * Serializing ETRN runs (when smtp_etrn_serialize is set)
33273 * Serializing delivery to a specific host (when serialize_hosts is set in an
33280 The entire contents of a database are written to the standard output by the
33281 exim_dumpdb program, which has no options or arguments other than the spool and
33282 database names. For example, to dump the retry database:
33284 exim_dumpdb /var/spool/exim retry
33286 Two lines of output are produced for each entry:
33288 T:mail.ref.example:192.168.242.242 146 77 Connection refused
33289 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 *
33291 The first item on the first line is the key of the record. It starts with one
33292 of the letters R, or T, depending on whether it refers to a routing or
33293 transport retry. For a local delivery, the next part is the local address; for
33294 a remote delivery it is the name of the remote host, followed by its failing IP
33295 address (unless retry_include_ip_address is set false on the smtp transport).
33296 If the remote port is not the standard one (port 25), it is added to the IP
33297 address. Then there follows an error code, an additional error code, and a
33298 textual description of the error.
33300 The three times on the second line are the time of first failure, the time of
33301 the last delivery attempt, and the computed time for the next attempt. The line
33302 ends with an asterisk if the cutoff time for the last retry rule has been
33305 Each output line from exim_dumpdb for the wait-xxx databases consists of a host
33306 name followed by a list of ids for messages that are or were waiting to be
33307 delivered to that host. If there are a very large number for any one host,
33308 continuation records, with a sequence number added to the host name, may be
33309 seen. The data in these records is often out of date, because a message may be
33310 routed to several alternative hosts, and Exim makes no effort to keep
33317 The exim_tidydb utility program is used to tidy up the contents of a hints
33318 database. If run with no options, it removes all records that are more than 30
33319 days old. The age is calculated from the date and time that the record was last
33320 updated. Note that, in the case of the retry database, it is not the time since
33321 the first delivery failure. Information about a host that has been down for
33322 more than 30 days will remain in the database, provided that the record is
33323 updated sufficiently often.
33325 The cutoff date can be altered by means of the -t option, which must be
33326 followed by a time. For example, to remove all records older than a week from
33327 the retry database:
33329 exim_tidydb -t 7d /var/spool/exim retry
33331 Both the wait-xxx and retry databases contain items that involve message ids.
33332 In the former these appear as data in records keyed by host - they were
33333 messages that were waiting for that host - and in the latter they are the keys
33334 for retry information for messages that have suffered certain types of error.
33335 When exim_tidydb is run, a check is made to ensure that message ids in database
33336 records are those of messages that are still on the queue. Message ids for
33337 messages that no longer exist are removed from wait-xxx records, and if this
33338 leaves any records empty, they are deleted. For the retry database, records
33339 whose keys are non-existent message ids are removed. The exim_tidydb utility
33340 outputs comments on the standard output whenever it removes information from
33343 Certain records are automatically removed by Exim when they are no longer
33344 needed, but others are not. For example, if all the MX hosts for a domain are
33345 down, a retry record is created for each one. If the primary MX host comes back
33346 first, its record is removed when Exim successfully delivers to it, but the
33347 records for the others remain because Exim has not tried to use those hosts.
33349 It is important, therefore, to run exim_tidydb periodically on all the hints
33350 databases. You should do this at a quiet time of day, because it requires a
33351 database to be locked (and therefore inaccessible to Exim) while it does its
33352 work. Removing records from a DBM file does not normally make the file smaller,
33353 but all the common DBM libraries are able to re-use the space that is released.
33354 After an initial phase of increasing in size, the databases normally reach a
33355 point at which they no longer get any bigger, as long as they are regularly
33358 Warning: If you never run exim_tidydb, the space used by the hints databases is
33359 likely to keep on increasing.
33365 The exim_fixdb program is a utility for interactively modifying databases. Its
33366 main use is for testing Exim, but it might also be occasionally useful for
33367 getting round problems in a live system. It has no options, and its interface
33368 is somewhat crude. On entry, it prompts for input with a right angle-bracket. A
33369 key of a database record can then be entered, and the data for that record is
33372 If "d" is typed at the next prompt, the entire record is deleted. For all
33373 except the retry database, that is the only operation that can be carried out.
33374 For the retry database, each field is output preceded by a number, and data for
33375 individual fields can be changed by typing the field number followed by new
33380 resets the time of the next delivery attempt. Time values are given as a
33381 sequence of digit pairs for year, month, day, hour, and minute. Colons can be
33382 used as optional separators.
33385 52.15 Mailbox maintenance (exim_lock)
33386 -------------------------------------
33388 The exim_lock utility locks a mailbox file using the same algorithm as Exim.
33389 For a discussion of locking issues, see section 26.3. Exim_lock can be used to
33390 prevent any modification of a mailbox by Exim or a user agent while
33391 investigating a problem. The utility requires the name of the file as its first
33392 argument. If the locking is successful, the second argument is run as a command
33393 (using C's system() function); if there is no second argument, the value of the
33394 SHELL environment variable is used; if this is unset or empty, /bin/sh is run.
33395 When the command finishes, the mailbox is unlocked and the utility ends. The
33396 following options are available:
33400 Use fcntl() locking on the open mailbox.
33404 Use flock() locking on the open mailbox, provided the operating system
33409 This must be followed by a number, which is a number of seconds; it sets
33410 the interval to sleep between retries (default 3).
33414 Create a lock file before opening the mailbox.
33418 Lock the mailbox using MBX rules.
33422 Suppress verification output.
33426 This must be followed by a number; it sets the number of times to try to
33427 get the lock (default 10).
33431 This option causes exim_lock to restore the modified and read times to the
33432 locked file before exiting. This allows you to access a locked mailbox (for
33433 example, to take a backup copy) without disturbing the times that the user
33438 This must be followed by a number, which is a number of seconds; it sets a
33439 timeout to be used with a blocking fcntl() lock. If it is not set (the
33440 default), a non-blocking call is used.
33444 Generate verbose output.
33446 If none of -fcntl, -flock, -lockfile or -mbx are given, the default is to
33447 create a lock file and also to use fcntl() locking on the mailbox, which is the
33448 same as Exim's default. The use of -flock or -fcntl requires that the file be
33449 writeable; the use of -lockfile requires that the directory containing the file
33450 be writeable. Locking by lock file does not last for ever; Exim assumes that a
33451 lock file is expired if it is more than 30 minutes old.
33453 The -mbx option can be used with either or both of -fcntl or -flock. It assumes
33454 -fcntl by default. MBX locking causes a shared lock to be taken out on the open
33455 mailbox, and an exclusive lock on the file /tmp/.n.m where n and m are the
33456 device number and inode number of the mailbox file. When the locking is
33457 released, if an exclusive lock can be obtained for the mailbox, the file in /
33460 The default output contains verification of the locking that takes place. The
33461 -v option causes some additional information to be given. The -q option
33462 suppresses all output except error messages.
33466 exim_lock /var/spool/mail/spqr
33468 runs an interactive shell while the file is locked, whereas
33470 exim_lock -q /var/spool/mail/spqr <<End
33474 runs a specific non-interactive sequence of commands while the file is locked,
33475 suppressing all verification output. A single command can be run by a command
33478 exim_lock -q /var/spool/mail/spqr \
33479 "cp /var/spool/mail/spqr /some/where"
33481 Note that if a command is supplied, it must be entirely contained within the
33482 second argument - hence the quotes.
33486 ===============================================================================
33487 53. THE EXIM MONITOR
33489 The Exim monitor is an application which displays in an X window information
33490 about the state of Exim's queue and what Exim is doing. An admin user can
33491 perform certain operations on messages from this GUI interface; however all
33492 such facilities are also available from the command line, and indeed, the
33493 monitor itself makes use of the command line to perform any actions requested.
33496 53.1 Running the monitor
33497 ------------------------
33499 The monitor is started by running the script called eximon. This is a shell
33500 script that sets up a number of environment variables, and then runs the binary
33501 called eximon.bin. The default appearance of the monitor window can be changed
33502 by editing the Local/eximon.conf file created by editing exim_monitor/EDITME.
33503 Comments in that file describe what the various parameters are for.
33505 The parameters that get built into the eximon script can be overridden for a
33506 particular invocation by setting up environment variables of the same names,
33507 preceded by "EXIMON_". For example, a shell command such as
33509 EXIMON_LOG_DEPTH=400 eximon
33511 (in a Bourne-compatible shell) runs eximon with an overriding setting of the
33512 LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it
33513 overrides the Exim log file configuration. This makes it possible to have
33514 eximon tailing log data that is written to syslog, provided that MAIL.INFO
33515 syslog messages are routed to a file on the local host.
33517 X resources can be used to change the appearance of the window in the normal
33518 way. For example, a resource setting of the form
33520 Eximon*background: gray94
33522 changes the colour of the background to light grey rather than white. The
33523 stripcharts are drawn with both the data lines and the reference lines in
33524 black. This means that the reference lines are not visible when on top of the
33525 data. However, their colour can be changed by setting a resource called
33526 "highlight" (an odd name, but that's what the Athena stripchart widget uses).
33527 For example, if your X server is running Unix, you could set up lighter
33528 reference lines in the stripcharts by obeying
33531 Eximon*highlight: gray
33534 In order to see the contents of messages on the queue, and to operate on them,
33535 eximon must either be run as root or by an admin user.
33537 The command-line parameters of eximon are passed to eximon.bin and may contain
33538 X11 resource parameters interpreted by the X11 library. In addition, if the
33539 first parameter starts with the string "gdb" then it is removed and the binary
33540 is invoked under gdb (the parameter is used as the gdb command-name, so
33541 versioned variants of gdb can be invoked).
33543 The monitor's window is divided into three parts. The first contains one or
33544 more stripcharts and two action buttons, the second contains a "tail" of the
33545 main log file, and the third is a display of the queue of messages awaiting
33546 delivery, with two more action buttons. The following sections describe these
33547 different parts of the display.
33550 53.2 The stripcharts
33551 --------------------
33553 The first stripchart is always a count of messages on the queue. Its name can
33554 be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file.
33555 The remaining stripcharts are defined in the configuration script by regular
33556 expression matches on log file entries, making it possible to display, for
33557 example, counts of messages delivered to certain hosts or using certain
33558 transports. The supplied defaults display counts of received and delivered
33559 messages, and of local and SMTP deliveries. The default period between
33560 stripchart updates is one minute; this can be adjusted by a parameter in the
33561 Local/eximon.conf file.
33563 The stripchart displays rescale themselves automatically as the value they are
33564 displaying changes. There are always 10 horizontal lines in each chart; the
33565 title string indicates the value of each division when it is greater than one.
33566 For example, "x2" means that each division represents a value of 2.
33568 It is also possible to have a stripchart which shows the percentage fullness of
33569 a particular disk partition, which is useful when local deliveries are confined
33570 to a single partition.
33572 This relies on the availability of the statvfs() function or equivalent in the
33573 operating system. Most, but not all versions of Unix that support Exim have
33574 this. For this particular stripchart, the top of the chart always represents
33575 100%, and the scale is given as "x10%". This chart is configured by setting
33576 SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the Local/eximon.conf
33580 53.3 Main action buttons
33581 ------------------------
33583 Below the stripcharts there is an action button for quitting the monitor. Next
33584 to this is another button marked "Size". They are placed here so that shrinking
33585 the window to its default minimum size leaves just the queue count stripchart
33586 and these two buttons visible. Pressing the "Size" button causes the window to
33587 expand to its maximum size, unless it is already at the maximum, in which case
33588 it is reduced to its minimum.
33590 When expanding to the maximum, if the window cannot be fully seen where it
33591 currently is, it is moved back to where it was the last time it was at full
33592 size. When it is expanding from its minimum size, the old position is
33593 remembered, and next time it is reduced to the minimum it is moved back there.
33595 The idea is that you can keep a reduced window just showing one or two
33596 stripcharts at a convenient place on your screen, easily expand it to show the
33597 full window when required, and just as easily put it back to what it was. The
33598 idea is copied from what the twm window manager does for its f.fullzoom action.
33599 The minimum size of the window can be changed by setting the MIN_HEIGHT and
33600 MIN_WIDTH values in Local/eximon.conf.
33602 Normally, the monitor starts up with the window at its full size, but it can be
33603 built so that it starts up with the window at its smallest size, by setting
33604 START_SMALL=yes in Local/eximon.conf.
33607 53.4 The log display
33608 --------------------
33610 The second section of the window is an area in which a display of the tail of
33611 the main log is maintained. To save space on the screen, the timestamp on each
33612 log line is shortened by removing the date and, if log_timezone is set, the
33613 timezone. The log tail is not available when the only destination for logging
33614 data is syslog, unless the syslog lines are routed to a local file whose name
33615 is passed to eximon via the EXIMON_LOG_FILE_PATH environment variable.
33617 The log sub-window has a scroll bar at its lefthand side which can be used to
33618 move back to look at earlier text, and the up and down arrow keys also have a
33619 scrolling effect. The amount of log that is kept depends on the setting of
33620 LOG_BUFFER in Local/eximon.conf, which specifies the amount of memory to use.
33621 When this is full, the earlier 50% of data is discarded - this is much more
33622 efficient than throwing it away line by line. The sub-window also has a
33623 horizontal scroll bar for accessing the ends of long log lines. This is the
33624 only means of horizontal scrolling; the right and left arrow keys are not
33625 available. Text can be cut from this part of the window using the mouse in the
33626 normal way. The size of this subwindow is controlled by parameters in the
33627 configuration file Local/eximon.conf.
33629 Searches of the text in the log window can be carried out by means of the ^R
33630 and ^S keystrokes, which default to a reverse and a forward search,
33631 respectively. The search covers only the text that is displayed in the window.
33632 It cannot go further back up the log.
33634 The point from which the search starts is indicated by a caret marker. This is
33635 normally at the end of the text in the window, but can be positioned explicitly
33636 by pointing and clicking with the left mouse button, and is moved automatically
33637 by a successful search. If new text arrives in the window when it is scrolled
33638 back, the caret remains where it is, but if the window is not scrolled back,
33639 the caret is moved to the end of the new text.
33641 Pressing ^R or ^S pops up a window into which the search text can be typed.
33642 There are buttons for selecting forward or reverse searching, for carrying out
33643 the search, and for cancelling. If the "Search" button is pressed, the search
33644 happens and the window remains so that further searches can be done. If the
33645 "Return" key is pressed, a single search is done and the window is closed. If ^
33646 C is typed the search is cancelled.
33648 The searching facility is implemented using the facilities of the Athena text
33649 widget. By default this pops up a window containing both "search" and "replace"
33650 options. In order to suppress the unwanted "replace" portion for eximon, a
33651 modified version of the TextPop widget is distributed with Exim. However, the
33652 linkers in BSDI and HP-UX seem unable to handle an externally provided version
33653 of TextPop when the remaining parts of the text widget come from the standard
33654 libraries. The compile-time option EXIMON_TEXTPOP can be unset to cut out the
33655 modified TextPop, making it possible to build Eximon on these systems, at the
33656 expense of having unwanted items in the search popup window.
33659 53.5 The queue display
33660 ----------------------
33662 The bottom section of the monitor window contains a list of all messages that
33663 are on the queue, which includes those currently being received or delivered,
33664 as well as those awaiting delivery. The size of this subwindow is controlled by
33665 parameters in the configuration file Local/eximon.conf, and the frequency at
33666 which it is updated is controlled by another parameter in the same file - the
33667 default is 5 minutes, since queue scans can be quite expensive. However, there
33668 is an "Update" action button just above the display which can be used to force
33669 an update of the queue display at any time.
33671 When a host is down for some time, a lot of pending mail can build up for it,
33672 and this can make it hard to deal with other messages on the queue. To help
33673 with this situation there is a button next to "Update" called "Hide". If
33674 pressed, a dialogue box called "Hide addresses ending with" is put up. If you
33675 type anything in here and press "Return", the text is added to a chain of such
33676 texts, and if every undelivered address in a message matches at least one of
33677 the texts, the message is not displayed.
33679 If there is an address that does not match any of the texts, all the addresses
33680 are displayed as normal. The matching happens on the ends of addresses so, for
33681 example, cam.ac.uk specifies all addresses in Cambridge, while
33682 xxx@foo.com.example specifies just one specific address. When any hiding has
33683 been set up, a button called "Unhide" is displayed. If pressed, it cancels all
33684 hiding. Also, to ensure that hidden messages do not get forgotten, a hide
33685 request is automatically cancelled after one hour.
33687 While the dialogue box is displayed, you can't press any buttons or do anything
33688 else to the monitor window. For this reason, if you want to cut text from the
33689 queue display to use in the dialogue box, you have to do the cutting before
33690 pressing the "Hide" button.
33692 The queue display contains, for each unhidden queued message, the length of
33693 time it has been on the queue, the size of the message, the message id, the
33694 message sender, and the first undelivered recipient, all on one line. If it is
33695 a bounce message, the sender is shown as "<>". If there is more than one
33696 recipient to which the message has not yet been delivered, subsequent ones are
33697 listed on additional lines, up to a maximum configured number, following which
33698 an ellipsis is displayed. Recipients that have already received the message are
33701 If a message is frozen, an asterisk is displayed at the left-hand side.
33703 The queue display has a vertical scroll bar, and can also be scrolled by means
33704 of the arrow keys. Text can be cut from it using the mouse in the normal way.
33705 The text searching facilities, as described above for the log window, are also
33706 available, but the caret is always moved to the end of the text when the queue
33707 display is updated.
33710 53.6 The queue menu
33711 -------------------
33713 If the shift key is held down and the left button is clicked when the mouse
33714 pointer is over the text for any message, an action menu pops up, and the first
33715 line of the queue display for the message is highlighted. This does not affect
33718 If you want to use some other event for popping up the menu, you can set the
33719 MENU_EVENT parameter in Local/eximon.conf to change the default, or set
33720 EXIMON_MENU_EVENT in the environment before starting the monitor. The value set
33721 in this parameter is a standard X event description. For example, to run eximon
33722 using ctrl rather than shift you could use
33724 EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
33726 The title of the menu is the message id, and it contains entries which act as
33729 * message log: The contents of the message log for the message are displayed
33730 in a new text window.
33732 * headers: Information from the spool file that contains the envelope
33733 information and headers is displayed in a new text window. See chapter 55
33734 for a description of the format of spool files.
33736 * body: The contents of the spool file containing the body of the message are
33737 displayed in a new text window. There is a default limit of 20,000 bytes to
33738 the amount of data displayed. This can be changed by setting the BODY_MAX
33739 option at compile time, or the EXIMON_BODY_MAX option at run time.
33741 * deliver message: A call to Exim is made using the -M option to request
33742 delivery of the message. This causes an automatic thaw if the message is
33743 frozen. The -v option is also set, and the output from Exim is displayed in
33744 a new text window. The delivery is run in a separate process, to avoid
33745 holding up the monitor while the delivery proceeds.
33747 * freeze message: A call to Exim is made using the -Mf option to request that
33748 the message be frozen.
33750 * thaw message: A call to Exim is made using the -Mt option to request that
33751 the message be thawed.
33753 * give up on msg: A call to Exim is made using the -Mg option to request that
33754 Exim gives up trying to deliver the message. A bounce message is generated
33755 for any remaining undelivered addresses.
33757 * remove message: A call to Exim is made using the -Mrm option to request
33758 that the message be deleted from the system without generating a bounce
33761 * add recipient: A dialog box is displayed into which a recipient address can
33762 be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
33763 is set in Local/eximon.conf, the address is qualified with that domain.
33764 Otherwise it must be entered as a fully qualified address. Pressing RETURN
33765 causes a call to Exim to be made using the -Mar option to request that an
33766 additional recipient be added to the message, unless the entry box is
33767 empty, in which case no action is taken.
33769 * mark delivered: A dialog box is displayed into which a recipient address
33770 can be typed. If the address is not qualified and the QUALIFY_DOMAIN
33771 parameter is set in Local/eximon.conf, the address is qualified with that
33772 domain. Otherwise it must be entered as a fully qualified address. Pressing
33773 RETURN causes a call to Exim to be made using the -Mmd option to mark the
33774 given recipient address as already delivered, unless the entry box is
33775 empty, in which case no action is taken.
33777 * mark all delivered: A call to Exim is made using the -Mmad option to mark
33778 all recipient addresses as already delivered.
33780 * edit sender: A dialog box is displayed initialized with the current
33781 sender's address. Pressing RETURN causes a call to Exim to be made using
33782 the -Mes option to replace the sender address, unless the entry box is
33783 empty, in which case no action is taken. If you want to set an empty sender
33784 (as in bounce messages), you must specify it as "<>". Otherwise, if the
33785 address is not qualified and the QUALIFY_DOMAIN parameter is set in Local/
33786 eximon.conf, the address is qualified with that domain.
33788 When a delivery is forced, a window showing the -v output is displayed. In
33789 other cases when a call to Exim is made, if there is any output from Exim (in
33790 particular, if the command fails) a window containing the command and the
33791 output is displayed. Otherwise, the results of the action are normally apparent
33792 from the log and queue displays. However, if you set ACTION_OUTPUT=yes in Local
33793 /eximon.conf, a window showing the Exim command is always opened, even if no
33794 output is generated.
33796 The queue display is automatically updated for actions such as freezing and
33797 thawing, unless ACTION_QUEUE_UPDATE=no has been set in Local/eximon.conf. In
33798 this case the "Update" button has to be used to force an update of the display
33799 after one of these actions.
33801 In any text window that is displayed as result of a menu action, the normal
33802 cut-and-paste facility is available, and searching can be carried out using ^R
33803 and ^S, as described above for the log tail window.
33807 ===============================================================================
33808 54. SECURITY CONSIDERATIONS
33810 This chapter discusses a number of issues concerned with security, some of
33811 which are also covered in other parts of this manual.
33813 For reasons that this author does not understand, some people have promoted
33814 Exim as a "particularly secure" mailer. Perhaps it is because of the existence
33815 of this chapter in the documentation. However, the intent of the chapter is
33816 simply to describe the way Exim works in relation to certain security concerns,
33817 not to make any specific claims about the effectiveness of its security as
33818 compared with other MTAs.
33820 What follows is a description of the way Exim is supposed to be. Best efforts
33821 have been made to try to ensure that the code agrees with the theory, but an
33822 absence of bugs can never be guaranteed. Any that are reported will get fixed
33823 as soon as possible.
33826 54.1 Building a more "hardened" Exim
33827 ------------------------------------
33829 There are a number of build-time options that can be set in Local/Makefile to
33830 create Exim binaries that are "harder" to attack, in particular by a rogue Exim
33831 administrator who does not have the root password, or by someone who has
33832 penetrated the Exim (but not the root) account. These options are as follows:
33834 * ALT_CONFIG_PREFIX can be set to a string that is required to match the
33835 start of any file names used with the -C option. When it is set, these file
33836 names are also not allowed to contain the sequence "/../". (However, if the
33837 value of the -C option is identical to the value of CONFIGURE_FILE in Local
33838 /Makefile, Exim ignores -C and proceeds as usual.) There is no default
33839 setting for ALT_CONFIG_PREFIX.
33841 If the permitted configuration files are confined to a directory to which
33842 only root has access, this guards against someone who has broken into the
33843 Exim account from running a privileged Exim with an arbitrary configuration
33844 file, and using it to break into other accounts.
33846 * If a non-trusted configuration file (i.e. not the default configuration
33847 file or one which is trusted by virtue of being listed in the
33848 TRUSTED_CONFIG_LIST file) is specified with -C, or if macros are given with
33849 -D (but see the next item), then root privilege is retained only if the
33850 caller of Exim is root. This locks out the possibility of testing a
33851 configuration using -C right through message reception and delivery, even
33852 if the caller is root. The reception works, but by that time, Exim is
33853 running as the Exim user, so when it re-execs to regain privilege for the
33854 delivery, the use of -C causes privilege to be lost. However, root can test
33855 reception and delivery using two separate commands.
33857 * The WHITELIST_D_MACROS build option declares some macros to be safe to
33858 override with -D if the real uid is one of root, the Exim run-time user or
33859 the CONFIGURE_OWNER, if defined. The potential impact of this option is
33860 limited by requiring the run-time value supplied to -D to match a regex
33861 that errs on the restrictive side. Requiring build-time selection of safe
33862 macros is onerous but this option is intended solely as a transition
33863 mechanism to permit previously-working configurations to continue to work
33864 after release 4.73.
33866 * If DISABLE_D_OPTION is defined, the use of the -D command line option is
33869 * FIXED_NEVER_USERS can be set to a colon-separated list of users that are
33870 never to be used for any deliveries. This is like the never_users runtime
33871 option, but it cannot be overridden; the runtime option adds additional
33872 users to the list. The default setting is "root"; this prevents a non-root
33873 user who is permitted to modify the runtime file from using Exim as a way
33877 54.2 Root privilege
33878 -------------------
33880 The Exim binary is normally setuid to root, which means that it gains root
33881 privilege (runs as root) when it starts execution. In some special cases (for
33882 example, when the daemon is not in use and there are no local deliveries), it
33883 may be possible to run Exim setuid to some user other than root. This is
33884 discussed in the next section. However, in most installations, root privilege
33885 is required for two things:
33887 * To set up a socket connected to the standard SMTP port (25) when
33888 initialising the listening daemon. If Exim is run from inetd, this
33889 privileged action is not required.
33891 * To be able to change uid and gid in order to read users' .forward files and
33892 perform local deliveries as the receiving user or as specified in the
33895 It is not necessary to be root to do any of the other things Exim does, such as
33896 receiving messages and delivering them externally over SMTP, and it is
33897 obviously more secure if Exim does not run as root except when necessary. For
33898 this reason, a user and group for Exim to use must be defined in Local/Makefile
33899 . These are known as "the Exim user" and "the Exim group". Their values can be
33900 changed by the run time configuration, though this is not recommended. Often a
33901 user called exim is used, but some sites use mail or another user name
33904 Exim uses setuid() whenever it gives up root privilege. This is a permanent
33905 abdication; the process cannot regain root afterwards. Prior to release 4.00,
33906 seteuid() was used in some circumstances, but this is no longer the case.
33908 After a new Exim process has interpreted its command line options, it changes
33909 uid and gid in the following cases:
33911 * If the -C option is used to specify an alternate configuration file, or if
33912 the -D option is used to define macro values for the configuration, and the
33913 calling process is not running as root, the uid and gid are changed to
33914 those of the calling process. However, if DISABLE_D_OPTION is defined in
33915 Local/Makefile, the -D option may not be used at all. If WHITELIST_D_MACROS
33916 is defined in Local/Makefile, then some macro values can be supplied if the
33917 calling process is running as root, the Exim run-time user or
33918 CONFIGURE_OWNER, if defined.
33920 * If the expansion test option (-be) or one of the filter testing options (
33921 -bf or -bF) are used, the uid and gid are changed to those of the calling
33924 * If the process is not a daemon process or a queue runner process or a
33925 delivery process or a process for testing address routing (started with -bt
33926 ), the uid and gid are changed to the Exim user and group. This means that
33927 Exim always runs under its own uid and gid when receiving messages. This
33928 also applies when testing address verification (the -bv option) and testing
33929 incoming message policy controls (the -bh option).
33931 * For a daemon, queue runner, delivery, or address testing process, the uid
33932 remains as root at this stage, but the gid is changed to the Exim group.
33934 The processes that initially retain root privilege behave as follows:
33936 * A daemon process changes the gid to the Exim group and the uid to the Exim
33937 user after setting up one or more listening sockets. The initgroups()
33938 function is called, so that if the Exim user is in any additional groups,
33939 they will be used during message reception.
33941 * A queue runner process retains root privilege throughout its execution. Its
33942 job is to fork a controlled sequence of delivery processes.
33944 * A delivery process retains root privilege throughout most of its execution,
33945 but any actual deliveries (that is, the transports themselves) are run in
33946 subprocesses which always change to a non-root uid and gid. For local
33947 deliveries this is typically the uid and gid of the owner of the mailbox;
33948 for remote deliveries, the Exim uid and gid are used. Once all the delivery
33949 subprocesses have been run, a delivery process changes to the Exim uid and
33950 gid while doing post-delivery tidying up such as updating the retry
33951 database and generating bounce and warning messages.
33953 While the recipient addresses in a message are being routed, the delivery
33954 process runs as root. However, if a user's filter file has to be processed,
33955 this is done in a subprocess that runs under the individual user's uid and
33956 gid. A system filter is run as root unless system_filter_user is set.
33958 * A process that is testing addresses (the -bt option) runs as root so that
33959 the routing is done in the same environment as a message delivery.
33962 54.3 Running Exim without privilege
33963 -----------------------------------
33965 Some installations like to run Exim in an unprivileged state for more of its
33966 operation, for added security. Support for this mode of operation is provided
33967 by the global option deliver_drop_privilege. When this is set, the uid and gid
33968 are changed to the Exim user and group at the start of a delivery process (and
33969 also queue runner and address testing processes). This means that address
33970 routing is no longer run as root, and the deliveries themselves cannot change
33973 Leaving the binary setuid to root, but setting deliver_drop_privilege means
33974 that the daemon can still be started in the usual way, and it can respond
33975 correctly to SIGHUP because the re-invocation regains root privilege.
33977 An alternative approach is to make Exim setuid to the Exim user and also setgid
33978 to the Exim group. If you do this, the daemon must be started from a root
33979 process. (Calling Exim from a root process makes it behave in the way it does
33980 when it is setuid root.) However, the daemon cannot restart itself after a
33981 SIGHUP signal because it cannot regain privilege.
33983 It is still useful to set deliver_drop_privilege in this case, because it stops
33984 Exim from trying to re-invoke itself to do a delivery after a message has been
33985 received. Such a re-invocation is a waste of resources because it has no
33988 If restarting the daemon is not an issue (for example, if mua_wrapper is set,
33989 or inetd is being used instead of a daemon), having the binary setuid to the
33990 Exim user seems a clean approach, but there is one complication:
33992 In this style of operation, Exim is running with the real uid and gid set to
33993 those of the calling process, and the effective uid/gid set to Exim's values.
33994 Ideally, any association with the calling process' uid/gid should be dropped,
33995 that is, the real uid/gid should be reset to the effective values so as to
33996 discard any privileges that the caller may have. While some operating systems
33997 have a function that permits this action for a non-root effective uid, quite a
33998 number of them do not. Because of this lack of standardization, Exim does not
33999 address this problem at this time.
34001 For this reason, the recommended approach for "mostly unprivileged" running is
34002 to keep the Exim binary setuid to root, and to set deliver_drop_privilege. This
34003 also has the advantage of allowing a daemon to be used in the most
34004 straightforward way.
34006 If you configure Exim not to run delivery processes as root, there are a number
34007 of restrictions on what you can do:
34009 * You can deliver only as the Exim user/group. You should explicitly use the
34010 user and group options to override routers or local transports that
34011 normally deliver as the recipient. This makes sure that configurations that
34012 work in this mode function the same way in normal mode. Any implicit or
34013 explicit specification of another user causes an error.
34015 * Use of .forward files is severely restricted, such that it is usually not
34016 worthwhile to include them in the configuration.
34018 * Users who wish to use .forward would have to make their home directory and
34019 the file itself accessible to the Exim user. Pipe and append-to-file
34020 entries, and their equivalents in Exim filters, cannot be used. While they
34021 could be enabled in the Exim user's name, that would be insecure and not
34024 * Unless the local user mailboxes are all owned by the Exim user (possible in
34025 some POP3 or IMAP-only environments):
34027 1. They must be owned by the Exim group and be writeable by that group.
34028 This implies you must set mode in the appendfile configuration, as well
34029 as the mode of the mailbox files themselves.
34031 2. You must set no_check_owner, since most or all of the files will not be
34032 owned by the Exim user.
34034 3. You must set file_must_exist, because Exim cannot set the owner
34035 correctly on a newly created mailbox when unprivileged. This also
34036 implies that new mailboxes need to be created manually.
34038 These restrictions severely restrict what can be done in local deliveries.
34039 However, there are no restrictions on remote deliveries. If you are running a
34040 gateway host that does no local deliveries, setting deliver_drop_privilege
34041 gives more security at essentially no cost.
34043 If you are using the mua_wrapper facility (see chapter 50),
34044 deliver_drop_privilege is forced to be true.
34047 54.4 Delivering to local files
34048 ------------------------------
34050 Full details of the checks applied by appendfile before it writes to a file are
34051 given in chapter 26.
34054 54.5 Running local commands
34055 ---------------------------
34057 There are a number of ways in which an administrator can configure Exim to run
34058 commands based upon received, untrustworthy, data. Further, in some
34059 configurations a user who can control a .forward file can also arrange to run
34060 commands. Configuration to check includes, but is not limited to:
34062 * Use of use_shell in the pipe transport: various forms of shell command
34063 injection may be possible with this option present. It is dangerous and
34064 should be used only with considerable caution. Consider constraints which
34065 whitelist allowed characters in a variable which is to be used in a pipe
34066 transport that has use_shell enabled.
34068 * A number of options such as forbid_filter_run, forbid_filter_perl,
34069 forbid_filter_dlfunc and so forth which restrict facilities available to
34070 .forward files in a redirect router. If Exim is running on a central mail
34071 hub to which ordinary users do not have shell access, but home directories
34072 are NFS mounted (for instance) then administrators should review the list
34073 of these forbid options available, and should bear in mind that the options
34074 that may need forbidding can change as new features are added between
34077 * The ${run...} expansion item does not use a shell by default, but
34078 administrators can configure use of /bin/sh as part of the command. Such
34079 invocations should be viewed with prejudicial suspicion.
34081 * Administrators who use embedded Perl are advised to explore how Perl's
34082 taint checking might apply to their usage.
34084 * Use of ${expand...} is somewhat analagous to shell's eval builtin and
34085 administrators are well advised to view its use with suspicion, in case
34086 (for instance) it allows a local-part to contain embedded Exim directives.
34088 * Use of ${match_local_part...} and friends becomes more dangerous if Exim
34089 was built with EXPAND_LISTMATCH_RHS defined: the second string in each can
34090 reference arbitrary lists and files, rather than just being a list of
34091 opaque strings. The EXPAND_LISTMATCH_RHS option was added and set false by
34092 default because of real-world security vulnerabilities caused by its use
34093 with untrustworthy data injected in, for SQL injection attacks. Consider
34094 the use of the inlisti expansion condition instead.
34097 54.6 Trust in configuration data
34098 --------------------------------
34100 If configuration data for Exim can come from untrustworthy sources, there are
34101 some issues to be aware of:
34103 * Use of ${expand...} may provide a path for shell injection attacks.
34105 * Letting untrusted data provide a regular expression is unwise.
34107 * Using ${match...} to apply a fixed regular expression against untrusted
34108 data may result in pathological behaviour within PCRE. Be aware of what
34109 "backtracking" means and consider options for being more strict with a
34110 regular expression. Avenues to explore include limiting what can match
34111 (avoiding "." when "[a-z0-9]" or other character class will do), use of
34112 atomic grouping and possessive quantifiers or just not using regular
34113 expressions against untrusted data.
34115 * It can be important to correctly use ${quote:...}, ${quote_local_part:...}
34116 and ${quote_<lookup-type>:...} expansion items to ensure that data is
34117 correctly constructed.
34119 * Some lookups might return multiple results, even though normal usage is
34120 only expected to yield one result.
34123 54.7 IPv4 source routing
34124 ------------------------
34126 Many operating systems suppress IP source-routed packets in the kernel, but
34127 some cannot be made to do this, so Exim does its own check. It logs incoming
34128 IPv4 source-routed TCP calls, and then drops them. Things are all different in
34129 IPv6. No special checking is currently done.
34132 54.8 The VRFY, EXPN, and ETRN commands in SMTP
34133 ----------------------------------------------
34135 Support for these SMTP commands is disabled by default. If required, they can
34136 be enabled by defining suitable ACLs.
34139 54.9 Privileged users
34140 ---------------------
34142 Exim recognizes two sets of users with special privileges. Trusted users are
34143 able to submit new messages to Exim locally, but supply their own sender
34144 addresses and information about a sending host. For other users submitting
34145 local messages, Exim sets up the sender address from the uid, and doesn't
34146 permit a remote host to be specified.
34148 However, an untrusted user is permitted to use the -f command line option in
34149 the special form -f <> to indicate that a delivery failure for the message
34150 should not cause an error report. This affects the message's envelope, but it
34151 does not affect the Sender: header. Untrusted users may also be permitted to
34152 use specific forms of address with the -f option by setting the
34153 untrusted_set_sender option.
34155 Trusted users are used to run processes that receive mail messages from some
34156 other mail domain and pass them on to Exim for delivery either locally, or over
34157 the Internet. Exim trusts a caller that is running as root, as the Exim user,
34158 as any user listed in the trusted_users configuration option, or under any
34159 group listed in the trusted_groups option.
34161 Admin users are permitted to do things to the messages on Exim's queue. They
34162 can freeze or thaw messages, cause them to be returned to their senders, remove
34163 them entirely, or modify them in various ways. In addition, admin users can run
34164 the Exim monitor and see all the information it is capable of providing, which
34165 includes the contents of files on the spool.
34167 By default, the use of the -M and -q options to cause Exim to attempt delivery
34168 of messages on its queue is restricted to admin users. This restriction can be
34169 relaxed by setting the no_prod_requires_admin option. Similarly, the use of -bp
34170 (and its variants) to list the contents of the queue is also restricted to
34171 admin users. This restriction can be relaxed by setting
34172 no_queue_list_requires_admin.
34174 Exim recognizes an admin user if the calling process is running as root or as
34175 the Exim user or if any of the groups associated with the calling process is
34176 the Exim group. It is not necessary actually to be running under the Exim
34177 group. However, if admin users who are not root or the Exim user are to access
34178 the contents of files on the spool via the Exim monitor (which runs
34179 unprivileged), Exim must be built to allow group read access to its spool
34186 Exim's spool directory and everything it contains is owned by the Exim user and
34187 set to the Exim group. The mode for spool files is defined in the Local/
34188 Makefile configuration file, and defaults to 0640. This means that any user who
34189 is a member of the Exim group can access these files.
34192 54.11 Use of argv[0]
34193 --------------------
34195 Exim examines the last component of argv[0], and if it matches one of a set of
34196 specific strings, Exim assumes certain options. For example, calling Exim with
34197 the last component of argv[0] set to "rsmtp" is exactly equivalent to calling
34198 it with the option -bS. There are no security implications in this.
34201 54.12 Use of %f formatting
34202 --------------------------
34204 The only use made of "%f" by Exim is in formatting load average values. These
34205 are actually stored in integer variables as 1000 times the load average.
34206 Consequently, their range is limited and so therefore is the length of the
34210 54.13 Embedded Exim path
34211 ------------------------
34213 Exim uses its own path name, which is embedded in the code, only when it needs
34214 to re-exec in order to regain root privilege. Therefore, it is not root when it
34215 does so. If some bug allowed the path to get overwritten, it would lead to an
34216 arbitrary program's being run as exim, not as root.
34219 54.14 Dynamic module directory
34220 ------------------------------
34222 Any dynamically loadable modules must be installed into the directory defined
34223 in "LOOKUP_MODULE_DIR" in Local/Makefile for Exim to permit loading it.
34226 54.15 Use of sprintf()
34227 ----------------------
34229 A large number of occurrences of "sprintf" in the code are actually calls to
34230 string_sprintf(), a function that returns the result in malloc'd store. The
34231 intermediate formatting is done into a large fixed buffer by a function that
34232 runs through the format string itself, and checks the length of each conversion
34233 before performing it, thus preventing buffer overruns.
34235 The remaining uses of sprintf() happen in controlled circumstances where the
34236 output buffer is known to be sufficiently long to contain the converted string.
34239 54.16 Use of debug_printf() and log_write()
34240 -------------------------------------------
34242 Arbitrary strings are passed to both these functions, but they do their
34243 formatting by calling the function string_vformat(), which runs through the
34244 format string itself, and checks the length of each conversion.
34247 54.17 Use of strcat() and strcpy()
34248 ----------------------------------
34250 These are used only in cases where the output buffer is known to be large
34251 enough to hold the result.
34255 ===============================================================================
34256 55. FORMAT OF SPOOL FILES
34258 A message on Exim's queue consists of two files, whose names are the message id
34259 followed by -D and -H, respectively. The data portion of the message is kept in
34260 the -D file on its own. The message's envelope, status, and headers are all
34261 kept in the -H file, whose format is described in this chapter. Each of these
34262 two files contains the final component of its own name as its first line. This
34263 is insurance against disk crashes where the directory is lost but the files
34264 themselves are recoverable.
34266 Some people are tempted into editing -D files in order to modify messages. You
34267 need to be extremely careful if you do this; it is not recommended and you are
34268 on your own if you do it. Here are some of the pitfalls:
34270 * You must ensure that Exim does not try to deliver the message while you are
34271 fiddling with it. The safest way is to take out a write lock on the -D
34272 file, which is what Exim itself does, using fcntl(). If you update the file
34273 in place, the lock will be retained. If you write a new file and rename it,
34274 the lock will be lost at the instant of rename.
34276 * If you change the number of lines in the file, the value of $body_linecount
34277 , which is stored in the -H file, will be incorrect. At present, this value
34278 is not used by Exim, but there is no guarantee that this will always be the
34281 * If the message is in MIME format, you must take care not to break it.
34283 * If the message is cryptographically signed, any change will invalidate the
34286 All in all, modifying -D files is fraught with danger.
34288 Files whose names end with -J may also be seen in the input directory (or its
34289 subdirectories when split_spool_directory is set). These are journal files,
34290 used to record addresses to which the message has been delivered during the
34291 course of a delivery attempt. If there are still undelivered recipients at the
34292 end, the -H file is updated, and the -J file is deleted. If, however, there is
34293 some kind of crash (for example, a power outage) before this happens, the -J
34294 file remains in existence. When Exim next processes the message, it notices the
34295 -J file and uses it to update the -H file before starting the next delivery
34299 55.1 Format of the -H file
34300 --------------------------
34302 The second line of the -H file contains the login name for the uid of the
34303 process that called Exim to read the message, followed by the numerical uid and
34304 gid. For a locally generated message, this is normally the user who sent the
34305 message. For a message received over TCP/IP via the daemon, it is normally the
34308 The third line of the file contains the address of the message's sender as
34309 transmitted in the envelope, contained in angle brackets. The sender address is
34310 empty for bounce messages. For incoming SMTP mail, the sender address is given
34311 in the MAIL command. For locally generated mail, the sender address is created
34312 by Exim from the login name of the current user and the configured
34313 qualify_domain. However, this can be overridden by the -f option or a leading
34314 "From " line if the caller is trusted, or if the supplied address is "<>" or an
34315 address that matches untrusted_set_senders.
34317 The fourth line contains two numbers. The first is the time that the message
34318 was received, in the conventional Unix form - the number of seconds since the
34319 start of the epoch. The second number is a count of the number of messages
34320 warning of delayed delivery that have been sent to the sender.
34322 There follow a number of lines starting with a hyphen. These can appear in any
34323 order, and are omitted when not relevant:
34325 -acl <number> <length>
34327 This item is obsolete, and is not generated from Exim release 4.61 onwards;
34328 -aclc and -aclm are used instead. However, -acl is still recognized, to
34329 provide backward compatibility. In the old format, a line of this form is
34330 present for every ACL variable that is not empty. The number identifies the
34331 variable; the acl_cx variables are numbered 0-9 and the acl_mx variables
34332 are numbered 10-19. The length is the length of the data string for the
34333 variable. The string itself starts at the beginning of the next line, and
34334 is followed by a newline character. It may contain internal newlines.
34336 -aclc <rest-of-name> <length>
34338 A line of this form is present for every ACL connection variable that is
34339 defined. Note that there is a space between -aclc and the rest of the name.
34340 The length is the length of the data string for the variable. The string
34341 itself starts at the beginning of the next line, and is followed by a
34342 newline character. It may contain internal newlines.
34344 -aclm <rest-of-name> <length>
34346 A line of this form is present for every ACL message variable that is
34347 defined. Note that there is a space between -aclm and the rest of the name.
34348 The length is the length of the data string for the variable. The string
34349 itself starts at the beginning of the next line, and is followed by a
34350 newline character. It may contain internal newlines.
34352 -active_hostname <hostname>
34354 This is present if, when the message was received over SMTP, the value of
34355 $smtp_active_hostname was different to the value of $primary_hostname.
34357 -allow_unqualified_recipient
34359 This is present if unqualified recipient addresses are permitted in header
34360 lines (to stop such addresses from being qualified if rewriting occurs at
34361 transport time). Local messages that were input using -bnq and remote
34362 messages from hosts that match recipient_unqualified_hosts set this flag.
34364 -allow_unqualified_sender
34366 This is present if unqualified sender addresses are permitted in header
34367 lines (to stop such addresses from being qualified if rewriting occurs at
34368 transport time). Local messages that were input using -bnq and remote
34369 messages from hosts that match sender_unqualified_hosts set this flag.
34373 The id information for a message received on an authenticated SMTP
34374 connection - the value of the $authenticated_id variable.
34376 -auth_sender <address>
34378 The address of an authenticated sender - the value of the
34379 $authenticated_sender variable.
34381 -body_linecount <number>
34383 This records the number of lines in the body of the message, and is always
34386 -body_zerocount <number>
34388 This records the number of binary zero bytes in the body of the message,
34389 and is present if the number is greater than zero.
34393 This is written when a new message is first added to the spool. When the
34394 spool file is updated after a deferral, it is omitted.
34398 The message is frozen, and the freezing happened at <time>.
34402 This records the host name as specified by a remote host in a HELO or EHLO
34405 -host_address <address>.<port>
34407 This records the IP address of the host from which the message was received
34408 and the remote port number that was used. It is omitted for locally
34409 generated messages.
34413 If the message was received on an authenticated SMTP connection, this
34414 records the name of the authenticator - the value of the
34415 $sender_host_authenticated variable.
34417 -host_lookup_failed
34419 This is present if an attempt to look up the sending host's name from its
34420 IP address failed. It corresponds to the $host_lookup_failed variable.
34424 This records the name of the remote host from which the message was
34425 received, if the host name was looked up from the IP address when the
34426 message was being received. It is not present if no reverse lookup was
34431 For locally submitted messages, this records the login of the originating
34432 user, unless it was a trusted user and the -oMt option was used to specify
34433 an ident value. For messages received over TCP/IP, this records the ident
34434 string supplied by the remote host, if any.
34436 -interface_address <address>.<port>
34438 This records the IP address of the local interface and the port number
34439 through which a message was received from a remote host. It is omitted for
34440 locally generated messages.
34444 The message is from a local sender.
34448 The message is a locally-generated bounce message.
34450 -local_scan <string>
34452 This records the data string that was returned by the local_scan() function
34453 when the message was received - the value of the $local_scan_data variable.
34454 It is omitted if no data was returned.
34458 The message was frozen but has been thawed manually, that is, by an
34459 explicit Exim command rather than via the auto-thaw process.
34463 A testing delivery process was started using the -N option to suppress any
34464 actual deliveries, but delivery was deferred. At any further delivery
34465 attempts, -N is assumed.
34469 This records the value of the $received_protocol variable, which contains
34470 the name of the protocol by which the message was received.
34472 -sender_set_untrusted
34474 The envelope sender of this message was set by an untrusted local caller
34475 (used to ensure that the caller is displayed in queue listings).
34477 -spam_score_int <number>
34479 If a message was scanned by SpamAssassin, this is present. It records the
34480 value of $spam_score_int.
34482 -tls_certificate_verified
34484 A TLS certificate was received from the client that sent this message, and
34485 the certificate was verified by the server.
34487 -tls_cipher <cipher name>
34489 When the message was received over an encrypted connection, this records
34490 the name of the cipher suite that was used.
34492 -tls_peerdn <peer DN>
34494 When the message was received over an encrypted connection, and a
34495 certificate was received from the client, this records the Distinguished
34496 Name from that certificate.
34498 Following the options there is a list of those addresses to which the message
34499 is not to be delivered. This set of addresses is initialized from the command
34500 line when the -t option is used and extract_addresses_remove_arguments is set;
34501 otherwise it starts out empty. Whenever a successful delivery is made, the
34502 address is added to this set. The addresses are kept internally as a balanced
34503 binary tree, and it is a representation of that tree which is written to the
34504 spool file. If an address is expanded via an alias or forward file, the
34505 original address is added to the tree when deliveries to all its child
34506 addresses are complete.
34508 If the tree is empty, there is a single line in the spool file containing just
34509 the text "XX". Otherwise, each line consists of two letters, which are either Y
34510 or N, followed by an address. The address is the value for the node of the
34511 tree, and the letters indicate whether the node has a left branch and/or a
34512 right branch attached to it, respectively. If branches exist, they immediately
34513 follow. Here is an example of a three-node tree:
34515 YY darcy@austen.fict.example
34516 NN alice@wonderland.fict.example
34517 NN editor@thesaurus.ref.example
34519 After the non-recipients tree, there is a list of the message's recipients.
34520 This is a simple list, preceded by a count. It includes all the original
34521 recipients of the message, including those to whom the message has already been
34522 delivered. In the simplest case, the list contains one address per line. For
34526 editor@thesaurus.ref.example
34527 darcy@austen.fict.example
34529 alice@wonderland.fict.example
34531 However, when a child address has been added to the top-level addresses as a
34532 result of the use of the one_time option on a redirect router, each line is of
34533 the following form:
34535 <top-level address> <errors_to address> <length>,<parent number>#<flag bits>
34537 The 01 flag bit indicates the presence of the three other fields that follow
34538 the top-level address. Other bits may be used in future to support additional
34539 fields. The <parent number> is the offset in the recipients list of the
34540 original parent of the "one time" address. The first two fields are the
34541 envelope sender that is associated with this address and its length. If the
34542 length is zero, there is no special envelope sender (there are then two space
34543 characters in the line). A non-empty field can arise from a redirect router
34544 that has an errors_to setting.
34546 A blank line separates the envelope and status information from the headers
34547 which follow. A header may occupy several lines of the file, and to save effort
34548 when reading it in, each header is preceded by a number and an identifying
34549 character. The number is the number of characters in the header, including any
34550 embedded newlines and the terminating newline. The character is one of the
34553 <blank> header in which Exim has no special interest
34557 "I" Message-id: header
34558 "P" Received: header - P for "postmark"
34559 "R" Reply-To: header
34562 "*" replaced or deleted header
34564 Deleted or replaced (rewritten) headers remain in the spool file for debugging
34565 purposes. They are not transmitted when the message is delivered. Here is a
34566 typical set of headers:
34568 111P Received: by hobbit.fict.example with local (Exim 4.00)
34569 id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100
34570 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example>
34571 038* X-rewrote-sender: bb@hobbit.fict.example
34572 042* From: Bilbo Baggins <bb@hobbit.fict.example>
34573 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example>
34574 099* To: alice@wonderland.fict.example, rdo@foundation,
34575 darcy@austen.fict.example, editor@thesaurus.ref.example
34576 104T To: alice@wonderland.fict.example, rdo@foundation.example,
34577 darcy@austen.fict.example, editor@thesaurus.ref.example
34578 038 Date: Fri, 11 May 2001 10:28:59 +0100
34580 The asterisked headers indicate that the envelope sender, From: header, and To:
34581 header have been rewritten, the last one because routing expanded the
34582 unqualified domain foundation.
34586 ===============================================================================
34587 56. SUPPORT FOR DKIM (DOMAINKEYS IDENTIFIED MAIL)
34589 DKIM is a mechanism by which messages sent by some entity can be provably
34590 linked to a domain which that entity controls. It permits reputation to be
34591 tracked on a per-domain basis, rather than merely upon source IP address. DKIM
34592 is documented in RFC 4871.
34594 Since version 4.70, DKIM support is compiled into Exim by default. It can be
34595 disabled by setting DISABLE_DKIM=yes in Local/Makefile.
34597 Exim's DKIM implementation allows to
34599 1. Sign outgoing messages: This function is implemented in the SMTP transport.
34600 It can co-exist with all other Exim features (including transport filters)
34601 except cutthrough delivery.
34603 2. Verify signatures in incoming messages: This is implemented by an
34604 additional ACL (acl_smtp_dkim), which can be called several times per
34605 message, with different signature contexts.
34607 In typical Exim style, the verification implementation does not include any
34608 default "policy". Instead it enables you to build your own policy using Exim's
34611 Please note that verification of DKIM signatures in incoming mail is turned on
34612 by default for logging purposes. For each signature in incoming email, exim
34613 will log a line displaying the most important signature details, and the
34614 signature status. Here is an example (with line-breaks added for clarity):
34616 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
34617 d=facebookmail.com s=q1-2009b
34618 c=relaxed/relaxed a=rsa-sha1
34619 i=@facebookmail.com t=1252484542 [verification succeeded]
34621 You might want to turn off DKIM verification processing entirely for internal
34622 or relay mail sources. To do that, set the dkim_disable_verify ACL control
34623 modifier. This should typically be done in the RCPT ACL, at points where you
34624 accept mail from relay sources (internal hosts or authenticated senders).
34627 56.1 Signing outgoing messages
34628 ------------------------------
34630 Signing is implemented by setting private options on the SMTP transport. These
34631 options take (expandable) strings as arguments.
34633 +-----------+---------+-------------+--------------+
34634 |dkim_domain|Use: smtp|Type: string*|Default: unset|
34635 +-----------+---------+-------------+--------------+
34637 MANDATORY: The domain you want to sign with. The result of this expanded option
34638 is put into the $dkim_domain expansion variable.
34640 +-------------+---------+-------------+--------------+
34641 |dkim_selector|Use: smtp|Type: string*|Default: unset|
34642 +-------------+---------+-------------+--------------+
34644 MANDATORY: This sets the key selector string. You can use the $dkim_domain
34645 expansion variable to look up a matching selector. The result is put in the
34646 expansion variable $dkim_selector which should be used in the dkim_private_key
34647 option along with $dkim_domain.
34649 +----------------+---------+-------------+--------------+
34650 |dkim_private_key|Use: smtp|Type: string*|Default: unset|
34651 +----------------+---------+-------------+--------------+
34653 MANDATORY: This sets the private key to use. You can use the $dkim_domain and
34654 $dkim_selector expansion variables to determine the private key to use. The
34657 * be a valid RSA private key in ASCII armor, including line breaks.
34659 * start with a slash, in which case it is treated as a file that contains the
34662 * be "0", "false" or the empty string, in which case the message will not be
34663 signed. This case will not result in an error, even if dkim_strict is set.
34665 +----------+---------+-------------+--------------+
34666 |dkim_canon|Use: smtp|Type: string*|Default: unset|
34667 +----------+---------+-------------+--------------+
34669 OPTIONAL: This option sets the canonicalization method used when signing a
34670 message. The DKIM RFC currently supports two methods: "simple" and "relaxed".
34671 The option defaults to "relaxed" when unset. Note: the current implementation
34672 only supports using the same canonicalization method for both headers and body.
34674 +-----------+---------+-------------+--------------+
34675 |dkim_strict|Use: smtp|Type: string*|Default: unset|
34676 +-----------+---------+-------------+--------------+
34678 OPTIONAL: This option defines how Exim behaves when signing a message that
34679 should be signed fails for some reason. When the expansion evaluates to either
34680 "1" or "true", Exim will defer. Otherwise Exim will send the message unsigned.
34681 You can use the $dkim_domain and $dkim_selector expansion variables here.
34683 +-----------------+---------+-------------+--------------+
34684 |dkim_sign_headers|Use: smtp|Type: string*|Default: unset|
34685 +-----------------+---------+-------------+--------------+
34687 OPTIONAL: When set, this option must expand to (or be specified as) a
34688 colon-separated list of header names. Headers with these names will be included
34689 in the message signature. When unspecified, the header names recommended in
34690 RFC4871 will be used.
34693 56.2 Verifying DKIM signatures in incoming mail
34694 -----------------------------------------------
34696 Verification of DKIM signatures in incoming email is implemented via the
34697 acl_smtp_dkim ACL. By default, this ACL is called once for each syntactically
34698 (!) correct signature in the incoming message. A missing ACL definition
34699 defaults to accept. If any ACL call does not acccept, the message is not
34700 accepted. If a cutthrough delivery was in progress for the message it is
34701 summarily dropped (having wasted the transmission effort).
34703 To evaluate the signature in the ACL a large number of expansion variables
34704 containing the signature status and its details are set up during the runtime
34707 Calling the ACL only for existing signatures is not sufficient to build more
34708 advanced policies. For that reason, the global option dkim_verify_signers, and
34709 a global expansion variable $dkim_signers exist.
34711 The global option dkim_verify_signers can be set to a colon-separated list of
34712 DKIM domains or identities for which the ACL acl_smtp_dkim is called. It is
34713 expanded when the message has been received. At this point, the expansion
34714 variable $dkim_signers already contains a colon-separated list of signer
34715 domains and identities for the message. When dkim_verify_signers is not
34716 specified in the main configuration, it defaults as:
34718 dkim_verify_signers = $dkim_signers
34720 This leads to the default behaviour of calling acl_smtp_dkim for each DKIM
34721 signature in the message. Current DKIM verifiers may want to explicitly call
34722 the ACL for known domains or identities. This would be achieved as follows:
34724 dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
34726 This would result in acl_smtp_dkim always being called for "paypal.com" and
34727 "ebay.com", plus all domains and identities that have signatures in the
34728 message. You can also be more creative in constructing your policy. For
34731 dkim_verify_signers = $sender_address_domain:$dkim_signers
34733 If a domain or identity is listed several times in the (expanded) value of
34734 dkim_verify_signers, the ACL is only called once for that domain or identity.
34736 Inside the acl_smtp_dkim, the following expansion variables are available (from
34737 most to least important):
34741 The signer that is being evaluated in this ACL run. This can be a domain or
34742 an identity. This is one of the list items from the expanded main option
34743 dkim_verify_signers (see above).
34745 $dkim_verify_status
34747 A string describing the general status of the signature. One of
34749 * none: There is no signature in the message for the current domain or
34750 identity (as reflected by $dkim_cur_signer).
34752 * invalid: The signature could not be verified due to a processing error.
34753 More detail is available in $dkim_verify_reason.
34755 * fail: Verification of the signature failed. More detail is available in
34756 $dkim_verify_reason.
34758 * pass: The signature passed verification. It is valid.
34760 $dkim_verify_reason
34762 A string giving a litte bit more detail when $dkim_verify_status is either
34763 "fail" or "invalid". One of
34765 * pubkey_unavailable (when $dkim_verify_status="invalid"): The public key
34766 for the domain could not be retrieved. This may be a temporary problem.
34768 * pubkey_syntax (when $dkim_verify_status="invalid"): The public key
34769 record for the domain is syntactically invalid.
34771 * bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated
34772 body hash does not match the one specified in the signature header.
34773 This means that the message body was modified in transit.
34775 * signature_incorrect (when $dkim_verify_status="fail"): The signature
34776 could not be verified. This may mean that headers were modified,
34777 re-written or otherwise changed in a way which is incompatible with
34778 DKIM verification. It may of course also mean that the signature is
34783 The signing domain. IMPORTANT: This variable is only populated if there is
34784 an actual signature in the message for the current domain or identity (as
34785 reflected by $dkim_cur_signer).
34789 The signing identity, if present. IMPORTANT: This variable is only
34790 populated if there is an actual signature in the message for the current
34791 domain or identity (as reflected by $dkim_cur_signer).
34795 The key record selector string.
34799 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
34803 The body canonicalization method. One of 'relaxed' or 'simple'.
34807 The header canonicalization method. One of 'relaxed' or 'simple'.
34809 $dkim_copiedheaders
34811 A transcript of headers and their values which are included in the
34812 signature (copied from the 'z=' tag of the signature).
34816 The number of signed body bytes. If zero ("0"), the body is unsigned. If no
34817 limit was set by the signer, "9999999999999" is returned. This makes sure
34818 that this variable always expands to an integer value.
34822 UNIX timestamp reflecting the date and time when the signature was created.
34823 When this was not specified by the signer, "0" is returned.
34827 UNIX timestamp reflecting the date and time when the signer wants the
34828 signature to be treated as "expired". When this was not specified by the
34829 signer, "9999999999999" is returned. This makes it possible to do useful
34830 integer size comparisons against this value.
34834 A colon-separated list of names of headers included in the signature.
34838 "1" if the key record has the "testing" flag set, "0" if not.
34840 $dkim_key_nosubdomains
34842 "1" if the key record forbids subdomaining, "0" otherwise.
34846 Service type (tag s=) from the key record. Defaults to "*" if not specified
34849 $dkim_key_granularity
34851 Key granularity (tag g=) from the key record. Defaults to "*" if not
34852 specified in the key record.
34856 Notes from the key record (tag n=).
34858 In addition, two ACL conditions are provided:
34862 ACL condition that checks a colon-separated list of domains or identities
34863 for a match against the domain or identity that the ACL is currently
34864 verifying (reflected by $dkim_cur_signer). This is typically used to
34865 restrict an ACL verb to a group of domains or identities. For example:
34867 # Warn when Mail purportedly from GMail has no signature at all
34868 warn log_message = GMail sender without DKIM signature
34869 sender_domains = gmail.com
34870 dkim_signers = gmail.com
34875 ACL condition that checks a colon-separated list of possible DKIM
34876 verification results against the actual result of verification. This is
34877 typically used to restrict an ACL verb to a list of verification outcomes,
34880 deny message = Mail from Paypal with invalid/missing signature
34881 sender_domains = paypal.com:paypal.de
34882 dkim_signers = paypal.com:paypal.de
34883 dkim_status = none:invalid:fail
34885 The possible status keywords are: 'none','invalid','fail' and 'pass'.
34886 Please see the documentation of the $dkim_verify_status expansion variable
34887 above for more information of what they mean.
34891 ===============================================================================
34892 57. ADDING NEW DRIVERS OR LOOKUP TYPES
34894 The following actions have to be taken in order to add a new router, transport,
34895 authenticator, or lookup type to Exim:
34897 1. Choose a name for the driver or lookup type that does not conflict with any
34898 existing name; I will use "newdriver" in what follows.
34900 2. Add to src/EDITME the line:
34902 <type>_NEWDRIVER=yes
34904 where <type> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the code is not to
34905 be included in the binary by default, comment this line out. You should
34906 also add any relevant comments about the driver or lookup type.
34908 3. Add to src/config.h.defaults the line:
34910 #define <type>_NEWDRIVER
34912 4. Edit src/drtables.c, adding conditional code to pull in the private header
34913 and create a table entry as is done for all the other drivers and lookup
34916 5. Edit scripts/lookups-Makefile if this is a new lookup; there is a for-loop
34917 near the bottom, ranging the "name_mod" variable over a list of all
34918 lookups. Add your "NEWDRIVER" to that list. As long as the dynamic module
34919 would be named newdriver.so, you can use the simple form that most lookups
34922 6. Edit Makefile in the appropriate sub-directory (src/routers, src/transports
34923 , src/auths, or src/lookups); add a line for the new driver or lookup type
34924 and add it to the definition of OBJ.
34926 7. Create newdriver.h and newdriver.c in the appropriate sub-directory of src.
34928 8. Edit scripts/MakeLinks and add commands to link the .h and .c files as for
34929 other drivers and lookups.
34931 Then all you need to do is write the code! A good way to start is to make a
34932 proforma by copying an existing module of the same type, globally changing all
34933 occurrences of the name, and cutting out most of the code. Note that any
34934 options you create must be listed in alphabetical order, because the tables are
34935 searched using a binary chop procedure.
34937 There is a README file in each of the sub-directories of src describing the
34938 interface that is expected.