Exim Maintainers
-Copyright (c) 2014 University of Cambridge
+Copyright (c) 2018 University of Cambridge
-Revision 4.84.2 02 Mar 2016 EM
+Revision 4.92 10 Feb 2019 EM
-------------------------------------------------------------------------------
1. Introduction
1.1. Exim documentation
- 1.2. FTP and web sites
+ 1.2. FTP site and websites
1.3. Mailing lists
- 1.4. Exim training
- 1.5. Bug reports
- 1.6. Where to find the Exim distribution
- 1.7. Limitations
- 1.8. Run time configuration
- 1.9. Calling interface
- 1.10. Terminology
+ 1.4. Bug reports
+ 1.5. Where to find the Exim distribution
+ 1.6. Limitations
+ 1.7. Runtime configuration
+ 1.8. Calling interface
+ 1.9. Terminology
2. Incorporated code
3. How Exim receives and delivers mail
5.2. Trusted and admin users
5.3. Command line options
-6. The Exim run time configuration file
+6. The Exim runtime configuration file
6.1. Using a different configuration file
6.2. Configuration file format
6.6. Redefining macros
6.7. Overriding macro values
6.8. Example of macro usage
- 6.9. Conditional skips in the configuration file
- 6.10. Common option syntax
- 6.11. Boolean options
- 6.12. Integer values
- 6.13. Octal integer values
- 6.14. Fixed point numbers
- 6.15. Time intervals
- 6.16. String values
- 6.17. Expanded strings
- 6.18. User and group names
- 6.19. List construction
- 6.20. Changing list separators
- 6.21. Empty items in lists
- 6.22. Format of driver configurations
+ 6.9. Builtin macros
+ 6.10. Conditional skips in the configuration file
+ 6.11. Common option syntax
+ 6.12. Boolean options
+ 6.13. Integer values
+ 6.14. Octal integer values
+ 6.15. Fixed point numbers
+ 6.16. Time intervals
+ 6.17. String values
+ 6.18. Expanded strings
+ 6.19. User and group names
+ 6.20. List construction
+ 6.21. Changing list separators
+ 6.22. Empty items in lists
+ 6.23. Format of driver configurations
7. The default configuration file
- 7.1. Main configuration settings
- 7.2. ACL configuration
- 7.3. Router configuration
- 7.4. Transport configuration
- 7.5. Default retry rule
- 7.6. Rewriting configuration
- 7.7. Authenticators configuration
+ 7.1. Macros
+ 7.2. Main configuration settings
+ 7.3. ACL configuration
+ 7.4. Router configuration
+ 7.5. Transport configuration
+ 7.6. Default retry rule
+ 7.7. Rewriting configuration
+ 7.8. Authenticators configuration
8. Regular expressions
9. File and database lookups
9.8. Lookup caching
9.9. Quoting lookup data
9.10. More about dnsdb
- 9.11. Pseudo dnsdb record types
- 9.12. Multiple dnsdb lookups
- 9.13. More about LDAP
- 9.14. Format of LDAP queries
- 9.15. LDAP quoting
- 9.16. LDAP connections
- 9.17. LDAP authentication and control information
- 9.18. Format of data returned by LDAP
- 9.19. More about NIS+
- 9.20. SQL lookups
- 9.21. More about MySQL, PostgreSQL, Oracle, and InterBase
- 9.22. Specifying the server in the query
- 9.23. Special MySQL features
- 9.24. Special PostgreSQL features
- 9.25. More about SQLite
+ 9.11. Dnsdb lookup modifiers
+ 9.12. Pseudo dnsdb record types
+ 9.13. Multiple dnsdb lookups
+ 9.14. More about LDAP
+ 9.15. Format of LDAP queries
+ 9.16. LDAP quoting
+ 9.17. LDAP connections
+ 9.18. LDAP authentication and control information
+ 9.19. Format of data returned by LDAP
+ 9.20. More about NIS+
+ 9.21. SQL lookups
+ 9.22. More about MySQL, PostgreSQL, Oracle, InterBase, and Redis
+ 9.23. Specifying the server in the query
+ 9.24. Special MySQL features
+ 9.25. Special PostgreSQL features
+ 9.26. More about SQLite
+ 9.27. More about Redis
10. Domain, host, address, and local part lists
13.1. Starting a listening daemon
13.2. Special IP listening addresses
13.3. Overriding local_interfaces and daemon_smtp_ports
- 13.4. Support for the obsolete SSMTP (or SMTPS) protocol
+ 13.4. Support for the submissions (aka SSMTP or SMTPS) protocol
13.5. IPv6 address scopes
13.6. Disabling IPv6
13.7. Examples of starting a listening daemon
40.1. Using spa as a server
40.2. Using spa as a client
-41. Encrypted SMTP connections using TLS/SSL
-
- 41.1. Support for the legacy "ssmtp" (aka "smtps") protocol
- 41.2. OpenSSL vs GnuTLS
- 41.3. GnuTLS parameter computation
- 41.4. Requiring specific ciphers in OpenSSL
- 41.5. Requiring specific ciphers or other parameters in GnuTLS
- 41.6. Configuring an Exim server to use TLS
- 41.7. Requesting and verifying client certificates
- 41.8. Revoked certificates
- 41.9. Configuring an Exim client to use TLS
- 41.10. Use of TLS Server Name Indication
- 41.11. Multiple messages on the same encrypted TCP/IP connection
- 41.12. Certificates and all that
- 41.13. Certificate chains
- 41.14. Self-signed certificates
-
-42. Access control lists
-
- 42.1. Testing ACLs
- 42.2. Specifying when ACLs are used
- 42.3. The non-SMTP ACLs
- 42.4. The SMTP connect ACL
- 42.5. The EHLO/HELO ACL
- 42.6. The DATA ACLs
- 42.7. The SMTP DKIM ACL
- 42.8. The SMTP MIME ACL
- 42.9. The SMTP PRDR ACL
- 42.10. The QUIT ACL
- 42.11. The not-QUIT ACL
- 42.12. Finding an ACL to use
- 42.13. ACL return codes
- 42.14. Unset ACL options
- 42.15. Data for message ACLs
- 42.16. Data for non-message ACLs
- 42.17. Format of an ACL
- 42.18. ACL verbs
- 42.19. ACL variables
- 42.20. Condition and modifier processing
- 42.21. ACL modifiers
- 42.22. Use of the control modifier
- 42.23. Summary of message fixup control
- 42.24. Adding header lines in ACLs
- 42.25. Removing header lines in ACLs
- 42.26. ACL conditions
- 42.27. Using DNS lists
- 42.28. Specifying the IP address for a DNS list lookup
- 42.29. DNS lists keyed on domain names
- 42.30. Multiple explicit keys for a DNS list
- 42.31. Data returned by DNS lists
- 42.32. Variables set from DNS lists
- 42.33. Additional matching conditions for DNS lists
- 42.34. Negated DNS matching conditions
- 42.35. Handling multiple DNS records from a DNS list
- 42.36. Detailed information from merged DNS lists
- 42.37. DNS lists and IPv6
- 42.38. Rate limiting incoming messages
- 42.39. Ratelimit options for what is being measured
- 42.40. Ratelimit update modes
- 42.41. Ratelimit options for handling fast clients
- 42.42. Limiting the rate of different events
- 42.43. Using rate limiting
- 42.44. Address verification
- 42.45. Callout verification
- 42.46. Additional parameters for callouts
- 42.47. Callout caching
- 42.48. Sender address verification reporting
- 42.49. Redirection while verifying
- 42.50. Client SMTP authorization (CSA)
- 42.51. Bounce address tag validation
- 42.52. Using an ACL to control relaying
- 42.53. Checking a relay configuration
-
-43. Content scanning at ACL time
-
- 43.1. Scanning for viruses
- 43.2. Scanning with SpamAssassin
- 43.3. Calling SpamAssassin from an Exim ACL
- 43.4. Scanning MIME parts
- 43.5. Scanning with regular expressions
- 43.6. The demime condition
-
-44. Adding a local scan function to Exim
-
- 44.1. Building Exim to use a local scan function
- 44.2. API for local_scan()
- 44.3. Configuration options for local_scan()
- 44.4. Available Exim variables
- 44.5. Structure of header lines
- 44.6. Structure of recipient items
- 44.7. Available Exim functions
- 44.8. More about Exim's memory handling
-
-45. System-wide message filtering
-
- 45.1. Specifying a system filter
- 45.2. Testing a system filter
- 45.3. Contents of a system filter
- 45.4. Additional variable for system filters
- 45.5. Defer, freeze, and fail commands for system filters
- 45.6. Adding and removing headers in a system filter
- 45.7. Setting an errors address in a system filter
- 45.8. Per-address filtering
-
-46. Message processing
-
- 46.1. Submission mode for non-local messages
- 46.2. Line endings
- 46.3. Unqualified addresses
- 46.4. The UUCP From line
- 46.5. Resent- header lines
- 46.6. The Auto-Submitted: header line
- 46.7. The Bcc: header line
- 46.8. The Date: header line
- 46.9. The Delivery-date: header line
- 46.10. The Envelope-to: header line
- 46.11. The From: header line
- 46.12. The Message-ID: header line
- 46.13. The Received: header line
- 46.14. The References: header line
- 46.15. The Return-path: header line
- 46.16. The Sender: header line
- 46.17. Adding and removing header lines in routers and transports
- 46.18. Constructed addresses
- 46.19. Case of local parts
- 46.20. Dots in local parts
- 46.21. Rewriting addresses
-
-47. SMTP processing
-
- 47.1. Outgoing SMTP and LMTP over TCP/IP
- 47.2. Errors in outgoing SMTP
- 47.3. Incoming SMTP messages over TCP/IP
- 47.4. Unrecognized SMTP commands
- 47.5. Syntax and protocol errors in SMTP commands
- 47.6. Use of non-mail SMTP commands
- 47.7. The VRFY and EXPN commands
- 47.8. The ETRN command
- 47.9. Incoming local SMTP
- 47.10. Outgoing batched SMTP
- 47.11. Incoming batched SMTP
-
-48. Customizing bounce and warning messages
-
- 48.1. Customizing bounce messages
- 48.2. Customizing warning messages
-
-49. Some common configuration settings
-
- 49.1. Sending mail to a smart host
- 49.2. Using Exim to handle mailing lists
- 49.3. Syntax errors in mailing lists
- 49.4. Re-expansion of mailing lists
- 49.5. Closed mailing lists
- 49.6. Variable Envelope Return Paths (VERP)
- 49.7. Virtual domains
- 49.8. Multiple user mailboxes
- 49.9. Simplified vacation processing
- 49.10. Taking copies of mail
- 49.11. Intermittently connected hosts
- 49.12. Exim on the upstream server host
- 49.13. Exim on the intermittently connected client host
-
-50. Using Exim as a non-queueing client
-51. Log files
-
- 51.1. Where the logs are written
- 51.2. Logging to local files that are periodically "cycled"
- 51.3. Datestamped log files
- 51.4. Logging to syslog
- 51.5. Log line flags
- 51.6. Logging message reception
- 51.7. Logging deliveries
- 51.8. Discarded deliveries
- 51.9. Deferred deliveries
- 51.10. Delivery failures
- 51.11. Fake deliveries
- 51.12. Completion
- 51.13. Summary of Fields in Log Lines
- 51.14. Other log entries
- 51.15. Reducing or increasing what is logged
- 51.16. Message log
-
-52. Exim utilities
-
- 52.1. Finding out what Exim processes are doing (exiwhat)
- 52.2. Selective queue listing (exiqgrep)
- 52.3. Summarizing the queue (exiqsumm)
- 52.4. Extracting specific information from the log (exigrep)
- 52.5. Selecting messages by various criteria (exipick)
- 52.6. Cycling log files (exicyclog)
- 52.7. Mail statistics (eximstats)
- 52.8. Checking access policy (exim_checkaccess)
- 52.9. Making DBM files (exim_dbmbuild)
- 52.10. Finding individual retry times (exinext)
- 52.11. Hints database maintenance
- 52.12. exim_dumpdb
- 52.13. exim_tidydb
- 52.14. exim_fixdb
- 52.15. Mailbox maintenance (exim_lock)
-
-53. The Exim monitor
-
- 53.1. Running the monitor
- 53.2. The stripcharts
- 53.3. Main action buttons
- 53.4. The log display
- 53.5. The queue display
- 53.6. The queue menu
-
-54. Security considerations
-
- 54.1. Building a more "hardened" Exim
- 54.2. Root privilege
- 54.3. Running Exim without privilege
- 54.4. Delivering to local files
- 54.5. Running local commands
- 54.6. Trust in configuration data
- 54.7. IPv4 source routing
- 54.8. The VRFY, EXPN, and ETRN commands in SMTP
- 54.9. Privileged users
- 54.10. Spool files
- 54.11. Use of argv[0]
- 54.12. Use of %f formatting
- 54.13. Embedded Exim path
- 54.14. Dynamic module directory
- 54.15. Use of sprintf()
- 54.16. Use of debug_printf() and log_write()
- 54.17. Use of strcat() and strcpy()
-
-55. Format of spool files
-
- 55.1. Format of the -H file
-
-56. Support for DKIM (DomainKeys Identified Mail)
-
- 56.1. Signing outgoing messages
- 56.2. Verifying DKIM signatures in incoming mail
-
-57. Adding new drivers or lookup types
+41. The tls authenticator
+42. Encrypted SMTP connections using TLS/SSL
+
+ 42.1. Support for the "submissions" (aka "ssmtp" and "smtps") protocol
+ 42.2. OpenSSL vs GnuTLS
+ 42.3. GnuTLS parameter computation
+ 42.4. Requiring specific ciphers in OpenSSL
+ 42.5. Requiring specific ciphers or other parameters in GnuTLS
+ 42.6. Configuring an Exim server to use TLS
+ 42.7. Requesting and verifying client certificates
+ 42.8. Revoked certificates
+ 42.9. Configuring an Exim client to use TLS
+ 42.10. Use of TLS Server Name Indication
+ 42.11. Multiple messages on the same encrypted TCP/IP connection
+ 42.12. Certificates and all that
+ 42.13. Certificate chains
+ 42.14. Self-signed certificates
+ 42.15. DANE
+
+43. Access control lists
+
+ 43.1. Testing ACLs
+ 43.2. Specifying when ACLs are used
+ 43.3. The non-SMTP ACLs
+ 43.4. The SMTP connect ACL
+ 43.5. The EHLO/HELO ACL
+ 43.6. The DATA ACLs
+ 43.7. The SMTP DKIM ACL
+ 43.8. The SMTP MIME ACL
+ 43.9. The SMTP PRDR ACL
+ 43.10. The QUIT ACL
+ 43.11. The not-QUIT ACL
+ 43.12. Finding an ACL to use
+ 43.13. ACL return codes
+ 43.14. Unset ACL options
+ 43.15. Data for message ACLs
+ 43.16. Data for non-message ACLs
+ 43.17. Format of an ACL
+ 43.18. ACL verbs
+ 43.19. ACL variables
+ 43.20. Condition and modifier processing
+ 43.21. ACL modifiers
+ 43.22. Use of the control modifier
+ 43.23. Summary of message fixup control
+ 43.24. Adding header lines in ACLs
+ 43.25. Removing header lines in ACLs
+ 43.26. ACL conditions
+ 43.27. Using DNS lists
+ 43.28. Specifying the IP address for a DNS list lookup
+ 43.29. DNS lists keyed on domain names
+ 43.30. Multiple explicit keys for a DNS list
+ 43.31. Data returned by DNS lists
+ 43.32. Variables set from DNS lists
+ 43.33. Additional matching conditions for DNS lists
+ 43.34. Negated DNS matching conditions
+ 43.35. Handling multiple DNS records from a DNS list
+ 43.36. Detailed information from merged DNS lists
+ 43.37. DNS lists and IPv6
+ 43.38. Rate limiting incoming messages
+ 43.39. Ratelimit options for what is being measured
+ 43.40. Ratelimit update modes
+ 43.41. Ratelimit options for handling fast clients
+ 43.42. Limiting the rate of different events
+ 43.43. Using rate limiting
+ 43.44. Address verification
+ 43.45. Callout verification
+ 43.46. Additional parameters for callouts
+ 43.47. Callout caching
+ 43.48. Sender address verification reporting
+ 43.49. Redirection while verifying
+ 43.50. Client SMTP authorization (CSA)
+ 43.51. Bounce address tag validation
+ 43.52. Using an ACL to control relaying
+ 43.53. Checking a relay configuration
+
+44. Content scanning at ACL time
+
+ 44.1. Scanning for viruses
+ 44.2. Scanning with SpamAssassin and Rspamd
+ 44.3. Calling SpamAssassin from an Exim ACL
+ 44.4. Scanning MIME parts
+ 44.5. Scanning with regular expressions
+
+45. Adding a local scan function to Exim
+
+ 45.1. Building Exim to use a local scan function
+ 45.2. API for local_scan()
+ 45.3. Configuration options for local_scan()
+ 45.4. Available Exim variables
+ 45.5. Structure of header lines
+ 45.6. Structure of recipient items
+ 45.7. Available Exim functions
+ 45.8. More about Exim's memory handling
+
+46. System-wide message filtering
+
+ 46.1. Specifying a system filter
+ 46.2. Testing a system filter
+ 46.3. Contents of a system filter
+ 46.4. Additional variable for system filters
+ 46.5. Defer, freeze, and fail commands for system filters
+ 46.6. Adding and removing headers in a system filter
+ 46.7. Setting an errors address in a system filter
+ 46.8. Per-address filtering
+
+47. Message processing
+
+ 47.1. Submission mode for non-local messages
+ 47.2. Line endings
+ 47.3. Unqualified addresses
+ 47.4. The UUCP From line
+ 47.5. Resent- header lines
+ 47.6. The Auto-Submitted: header line
+ 47.7. The Bcc: header line
+ 47.8. The Date: header line
+ 47.9. The Delivery-date: header line
+ 47.10. The Envelope-to: header line
+ 47.11. The From: header line
+ 47.12. The Message-ID: header line
+ 47.13. The Received: header line
+ 47.14. The References: header line
+ 47.15. The Return-path: header line
+ 47.16. The Sender: header line
+ 47.17. Adding and removing header lines in routers and transports
+ 47.18. Constructed addresses
+ 47.19. Case of local parts
+ 47.20. Dots in local parts
+ 47.21. Rewriting addresses
+
+48. SMTP processing
+
+ 48.1. Outgoing SMTP and LMTP over TCP/IP
+ 48.2. Errors in outgoing SMTP
+ 48.3. Incoming SMTP messages over TCP/IP
+ 48.4. Unrecognized SMTP commands
+ 48.5. Syntax and protocol errors in SMTP commands
+ 48.6. Use of non-mail SMTP commands
+ 48.7. The VRFY and EXPN commands
+ 48.8. The ETRN command
+ 48.9. Incoming local SMTP
+ 48.10. Outgoing batched SMTP
+ 48.11. Incoming batched SMTP
+
+49. Customizing bounce and warning messages
+
+ 49.1. Customizing bounce messages
+ 49.2. Customizing warning messages
+
+50. Some common configuration settings
+
+ 50.1. Sending mail to a smart host
+ 50.2. Using Exim to handle mailing lists
+ 50.3. Syntax errors in mailing lists
+ 50.4. Re-expansion of mailing lists
+ 50.5. Closed mailing lists
+ 50.6. Variable Envelope Return Paths (VERP)
+ 50.7. Virtual domains
+ 50.8. Multiple user mailboxes
+ 50.9. Simplified vacation processing
+ 50.10. Taking copies of mail
+ 50.11. Intermittently connected hosts
+ 50.12. Exim on the upstream server host
+ 50.13. Exim on the intermittently connected client host
+
+51. Using Exim as a non-queueing client
+52. Log files
+
+ 52.1. Where the logs are written
+ 52.2. Logging to local files that are periodically "cycled"
+ 52.3. Datestamped log files
+ 52.4. Logging to syslog
+ 52.5. Log line flags
+ 52.6. Logging message reception
+ 52.7. Logging deliveries
+ 52.8. Discarded deliveries
+ 52.9. Deferred deliveries
+ 52.10. Delivery failures
+ 52.11. Fake deliveries
+ 52.12. Completion
+ 52.13. Summary of Fields in Log Lines
+ 52.14. Other log entries
+ 52.15. Reducing or increasing what is logged
+ 52.16. Message log
+
+53. Exim utilities
+
+ 53.1. Finding out what Exim processes are doing (exiwhat)
+ 53.2. Selective queue listing (exiqgrep)
+ 53.3. Summarizing the queue (exiqsumm)
+ 53.4. Extracting specific information from the log (exigrep)
+ 53.5. Selecting messages by various criteria (exipick)
+ 53.6. Cycling log files (exicyclog)
+ 53.7. Mail statistics (eximstats)
+ 53.8. Checking access policy (exim_checkaccess)
+ 53.9. Making DBM files (exim_dbmbuild)
+ 53.10. Finding individual retry times (exinext)
+ 53.11. Hints database maintenance
+ 53.12. exim_dumpdb
+ 53.13. exim_tidydb
+ 53.14. exim_fixdb
+ 53.15. Mailbox maintenance (exim_lock)
+
+54. The Exim monitor
+
+ 54.1. Running the monitor
+ 54.2. The stripcharts
+ 54.3. Main action buttons
+ 54.4. The log display
+ 54.5. The queue display
+ 54.6. The queue menu
+
+55. Security considerations
+
+ 55.1. Building a more "hardened" Exim
+ 55.2. Root privilege
+ 55.3. Running Exim without privilege
+ 55.4. Delivering to local files
+ 55.5. Running local commands
+ 55.6. Trust in configuration data
+ 55.7. IPv4 source routing
+ 55.8. The VRFY, EXPN, and ETRN commands in SMTP
+ 55.9. Privileged users
+ 55.10. Spool files
+ 55.11. Use of argv[0]
+ 55.12. Use of %f formatting
+ 55.13. Embedded Exim path
+ 55.14. Dynamic module directory
+ 55.15. Use of sprintf()
+ 55.16. Use of debug_printf() and log_write()
+ 55.17. Use of strcat() and strcpy()
+
+56. Format of spool files
+
+ 56.1. Format of the -H file
+ 56.2. Format of the -D file
+
+57. DKIM and SPF
+
+ 57.1. DKIM (DomainKeys Identified Mail)
+ 57.2. Signing outgoing messages
+ 57.3. Verifying DKIM signatures in incoming mail
+ 57.4. SPF (Sender Policy Framework)
+
+58. Proxies
+
+ 58.1. Inbound proxies
+ 58.2. Outbound proxies
+ 58.3. Logging
+
+59. Internationalisation
+
+ 59.1. MTA operations
+ 59.2. MDA operations
+
+60. Events
+61. Adding new drivers or lookup types
BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/
Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
-Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware.
+Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare.
Some of these operating systems are no longer current and cannot easily be
tested, so the configuration files may no longer work in practice.
the file NOTICE. Exim is distributed under the terms of the GNU General Public
Licence, a copy of which may be found in the file LICENCE.
-The use, supply or promotion of Exim for the purpose of sending bulk,
-unsolicited electronic mail is incompatible with the basic aims of the program,
-which revolve around the free provision of a service that enhances the quality
-of personal communications. The author of Exim regards indiscriminate
-mass-mailing as an antisocial, irresponsible abuse of the Internet.
+The use, supply, or promotion of Exim for the purpose of sending bulk,
+unsolicited electronic mail is incompatible with the basic aims of Exim, which
+revolve around the free provision of a service that enhances the quality of
+personal communications. The author of Exim regards indiscriminate mass-mailing
+as an antisocial, irresponsible abuse of the Internet.
Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
experience of running and working on the Smail 3 code, I could never have
1.1 Exim documentation
----------------------
-This edition of the Exim specification applies to version 4.84.2 of Exim.
-Substantive changes from the 4.83 edition are marked in some renditions of the
+This edition of the Exim specification applies to version 4.92 of Exim.
+Substantive changes from the 4.91 edition are marked in some renditions of this
document; this paragraph is so marked if the rendition is capable of showing a
change indicator.
with general Unix system administration. Although there are some discussions
and examples in places, the information is mostly organized in a way that makes
it easy to look up, rather than in a natural order for sequential reading.
-Furthermore, the manual aims to cover every aspect of Exim in detail, including
-a number of rarely-used, special-purpose features that are unlikely to be of
-very wide interest.
+Furthermore, this manual aims to cover every aspect of Exim in detail,
+including a number of rarely-used, special-purpose features that are unlikely
+to be of very wide interest.
An "easier" discussion of Exim which provides more in-depth explanatory,
introductory, and tutorial material can be found in a book entitled The Exim
-SMTP Mail Server (second edition, 2007), published by UIT Cambridge (http://
+SMTP Mail Server (second edition, 2007), published by UIT Cambridge (https://
www.uit.co.uk/exim-book/).
-This book also contains a chapter that gives a general introduction to SMTP and
+The book also contains a chapter that gives a general introduction to SMTP and
Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
with the latest release of Exim. (Note that the earlier book about Exim,
published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
The command man update-exim.conf is another source of Debian-specific
information.
-As the program develops, there may be features in newer versions that have not
-yet made it into this document, which is updated only when the most significant
+As Exim develops, there may be features in newer versions that have not yet
+made it into this document, which is updated only when the most significant
digit of the fractional part of the version number changes. Specifications of
new features that are not yet in this manual are placed in the file doc/
NewStuff in the Exim distribution.
they are not documented in this manual. Information about experimental features
can be found in the file doc/experimental.txt.
-All changes to the program (whether new features, bug fixes, or other kinds of
-change) are noted briefly in the file called doc/ChangeLog.
+All changes to Exim (whether new features, bug fixes, or other kinds of change)
+are noted briefly in the file called doc/ChangeLog.
This specification itself is available as an ASCII file in doc/spec.txt so that
it can easily be searched with a text editor. Other files in the doc directory
filter.txt specification of the filter language
Exim3.upgrade upgrade notes from release 2 to release 3
Exim4.upgrade upgrade notes from release 3 to release 4
+openssl.txt installing a current OpenSSL release
The main specification and the specification of the filtering language are also
-available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6
+available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.5
below tells you how to get hold of these.
-1.2 FTP and web sites
----------------------
+1.2 FTP site and websites
+-------------------------
-The primary site for Exim source distributions is currently the University of
-Cambridge's FTP site, whose contents are described in Where to find the Exim
-distribution below. In addition, there is a web site and an FTP site at
-exim.org. These are now also hosted at the University of Cambridge. The
-exim.org site was previously hosted for a number of years by Energis Squared,
-formerly Planet Online Ltd, whose support I gratefully acknowledge.
+The primary site for Exim source distributions is the exim.org FTP site,
+available over HTTPS, HTTP and FTP. These services, and the exim.org website,
+are hosted at the University of Cambridge.
-As well as Exim distribution tar files, the Exim web site contains a number of
+As well as Exim distribution tar files, the Exim website contains a number of
differently formatted versions of the documentation. A recent addition to the
-online information is the Exim wiki (http://wiki.exim.org), which contains what
-used to be a separate FAQ, as well as various other examples, tips, and
-know-how that have been contributed by Exim users.
+online information is the Exim wiki (https://wiki.exim.org), which contains
+what used to be a separate FAQ, as well as various other examples, tips, and
+know-how that have been contributed by Exim users. The wiki site should always
+redirect to the correct place, which is currently provided by GitHub, and is
+open to editing by anyone with a GitHub account.
-An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report
+An Exim Bugzilla exists at https://bugs.exim.org. You can use this to report
bugs, and also to add items to the wish list. Please search first to check that
-you are not duplicating a previous entry.
+you are not duplicating a previous entry. Please do not ask for configuration
+help in the bug-tracker.
1.3 Mailing lists
Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this
web page:
-http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users
+https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users
-Please ask Debian-specific questions on this list and not on the general Exim
+Please ask Debian-specific questions on that list and not on the general Exim
lists.
-1.4 Exim training
------------------
-
-Training courses in Cambridge (UK) used to be run annually by the author of
-Exim, before he retired. At the time of writing, there are no plans to run
-further Exim courses in Cambridge. However, if that changes, relevant
-information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/.
-
-
-1.5 Bug reports
+1.4 Bug reports
---------------
Reports of obvious bugs can be emailed to bugs@exim.org or reported via the
-Bugzilla (http://bugs.exim.org). However, if you are unsure whether some
+Bugzilla (https://bugs.exim.org). However, if you are unsure whether some
behaviour is a bug or not, the best thing to do is to post a message to the
exim-dev mailing list and have it discussed.
-1.6 Where to find the Exim distribution
+1.5 Where to find the Exim distribution
---------------------------------------
-The master ftp site for the Exim distribution is
+The master distribution site for the Exim distribution is
-ftp://ftp.csx.cam.ac.uk/pub/software/email/exim
+https://downloads.exim.org/
-This is mirrored by
+The service is available over HTTPS, HTTP and FTP. We encourage people to
+migrate to HTTPS.
-ftp://ftp.exim.org/pub/exim
+The content served at https://downloads.exim.org/ is identical to the content
+served at https://ftp.exim.org/pub/exim and ftp://ftp.exim.org/pub/exim.
-The file references that follow are relative to the exim directories at these
-sites. There are now quite a number of independent mirror sites around the
-world. Those that I know about are listed in the file called Mirrors.
+If accessing via a hostname containing ftp, then the file references that
+follow are relative to the exim directories at these sites. If accessing via
+the hostname downloads then the subdirectories described here are top-level
+directories.
-Within the exim directory there are subdirectories called exim3 (for previous
-Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing
-for testing versions. In the exim4 subdirectory, the current release can always
-be found in files called
+There are now quite a number of independent mirror sites around the world.
+Those that I know about are listed in the file called Mirrors.
+Within the top exim directory there are subdirectories called exim3 (for
+previous Exim 3 distributions), exim4 (for the latest Exim 4 distributions),
+and Testing for testing versions. In the exim4 subdirectory, the current
+release can always be found in files called
+
+exim-n.nn.tar.xz
exim-n.nn.tar.gz
exim-n.nn.tar.bz2
-where n.nn is the highest such version number in the directory. The two files
-contain identical data; the only difference is the type of compression. The
-.bz2 file is usually a lot smaller than the .gz file.
+where n.nn is the highest such version number in the directory. The three files
+contain identical data; the only difference is the type of compression. The .xz
+file is usually the smallest, while the .gz file is the most portable to old
+systems.
The distributions will be PGP signed by an individual key of the Release
Coordinator. This key will have a uid containing an email address in the
exim.org domain and will have signatures from other people, including other
Exim maintainers. We expect that the key will be in the "strong set" of PGP
-keys. There should be a trust path to that key from Nigel Metheringham's PGP
-key, a version of which can be found in the release directory in the file
-nigel-pubkey.asc. All keys used will be available in public keyserver pools,
-such as pool.sks-keyservers.net.
-
-At time of last update, releases were being made by Phil Pennock and signed
-with key 0x403043153903637F, although that key is expected to be replaced in
-2013. A trust path from Nigel's key to Phil's can be observed at https://
-www.security.spodhuis.org/exim-trustpath.
+keys. There should be a trust path to that key from the Exim Maintainer's PGP
+keys, a version of which can be found in the release directory in the file
+Exim-Maintainers-Keyring.asc. All keys used will be available in public
+keyserver pools, such as pool.sks-keyservers.net.
-Releases have also been authorized to be performed by Todd Lyons who signs with
-key 0xC4F4F94804D29EBA. A direct trust path exists between previous RE Phil
-Pennock and Todd Lyons through a common associate.
+At the time of the last update, releases were being made by Jeremy Harris and
+signed with key 0xBCE58C8CE41F32DF. Other recent keys used for signing are
+those of Heiko Schlittermann, 0x26101B62F69376CE, and of Phil Pennock,
+0x4D1E900E14C1CC04.
The signatures for the tar bundles are in:
+exim-n.nn.tar.xz.asc
exim-n.nn.tar.gz.asc
exim-n.nn.tar.bz2.asc
-For each released version, the log of changes is made separately available in a
-separate file in the directory ChangeLogs so that it is possible to find out
-what has changed without having to download the entire distribution.
+For each released version, the log of changes is made available in a separate
+file in the directory ChangeLogs so that it is possible to find out what has
+changed without having to download the entire distribution.
The main distribution contains ASCII versions of this specification and other
documentation; other formats of the documents are available in separate files
exim-texinfo-n.nn.tar.gz
These tar files contain only the doc directory, not the complete distribution,
-and are also available in .bz2 as well as .gz forms.
+and are also available in .bz2 and .xz forms.
-1.7 Limitations
+1.6 Limitations
---------------
* Exim is designed for use as an Internet MTA, and therefore handles
straightforward interfaces to a number of common scanners are provided.
-1.8 Run time configuration
---------------------------
+1.7 Runtime configuration
+-------------------------
-Exim's run time configuration is held in a single text file that is divided
-into a number of sections. The entries in this file consist of keywords and
-values, in the style of Smail 3 configuration files. A default configuration
-file which is suitable for simple online installations is provided in the
-distribution, and is described in chapter 7 below.
+Exim's runtime configuration is held in a single text file that is divided into
+a number of sections. The entries in this file consist of keywords and values,
+in the style of Smail 3 configuration files. A default configuration file which
+is suitable for simple online installations is provided in the distribution,
+and is described in chapter 7 below.
-1.9 Calling interface
+1.8 Calling interface
---------------------
Like many MTAs, Exim has adopted the Sendmail command line interface so that it
sending mail, but you do not need to know anything about Sendmail in order to
run Exim. For actions other than sending messages, Sendmail-compatible options
also exist, but those that produce output (for example, -bp, which lists the
-messages on the queue) do so in Exim's own format. There are also some
+messages in the queue) do so in Exim's own format. There are also some
additional options that are compatible with Smail 3, and some further options
that are new to Exim. Chapter 5 documents all Exim's command line options. This
information is automatically made into the man page that forms part of the Exim
distribution.
-Control of messages on the queue can be done via certain privileged command
+Control of messages in the queue can be done via certain privileged command
line options. There is also an optional monitor program called eximon, which
displays current information in an X window, and which contains a menu
interface to Exim's command line administration options.
-1.10 Terminology
-----------------
+1.9 Terminology
+---------------
The body of a message is the actual data that the sender wants to transmit. It
-is the last part of a message, and is separated from the header (see below) by
-a blank line.
+is the last part of a message and is separated from the header (see below) by a
+blank line.
When a message cannot be delivered, it is normally returned to the sender in a
delivery failure message or a "non-delivery report" (NDR). The term bounce is
Long header lines can be split over several text lines by indenting the
continuations. The header is separated from the body by a blank line.
-The term local part, which is taken from RFC 2822, is used to refer to that
-part of an email address that precedes the @ sign. The part that follows the @
-sign is called the domain or mail domain.
+The term local part, which is taken from RFC 2822, is used to refer to the part
+of an email address that precedes the @ sign. The part that follows the @ sign
+is called the domain or mail domain.
The terms local delivery and remote delivery are used to distinguish delivery
to a file or a pipe on the local host from delivery by SMTP over TCP/IP to
Return path is another name that is used for the sender address in a message's
envelope.
-The term queue is used to refer to the set of messages awaiting delivery,
+The term queue is used to refer to the set of messages awaiting delivery
because this term is in widespread use in the context of MTAs. However, in
-Exim's case the reality is more like a pool than a queue, because there is
+Exim's case, the reality is more like a pool than a queue, because there is
normally no ordering of waiting messages.
The term queue runner is used to describe a process that scans the queue and
attempts to deliver those messages whose retry times have come. This term is
-used by other MTAs, and also relates to the command runq, but in Exim the
+used by other MTAs and also relates to the command runq, but in Exim the
waiting messages are normally processed in an unpredictable order.
The term spool directory is used for a directory in which Exim keeps the
-messages on its queue - that is, those that it is in the process of delivering.
+messages in its queue - that is, those that it is in the process of delivering.
This should not be confused with the directory in which local mailboxes are
stored, which is called a "spool directory" by some people. In the Exim
documentation, "spool" is always used in the first sense.
Free Software Foundation; either version 2 of the License, or (at your
option) any later version. This code implements Dan Bernstein's
Constant DataBase (cdb) spec. Information, the spec and sample code for
- cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This
- implementation borrows some code from Dan Bernstein's implementation
- (which has no license restrictions applied to it).
+ cdb can be obtained from https://cr.yp.to/cdb.html. This implementation
+ borrows some code from Dan Bernstein's implementation (which has no
+ license restrictions applied to it).
* Client support for Microsoft's Secure Password Authentication is provided
by code contributed by Marc Prud'hommeaux. Server support was contributed
acknowledgment:
"This product includes software developed by Computing Services at
- Carnegie Mellon University (http://www.cmu.edu/computing/."
+ Carnegie Mellon University (https://www.cmu.edu/computing/."
CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
the distributed source code.
* Many people have contributed code fragments, some large, some small, that
- were not covered by any specific licence requirements. It is assumed that
+ were not covered by any specific license requirements. It is assumed that
the contributors are happy to see their code incorporated into Exim under
the GPL.
------------------
Policy controls are now an important feature of MTAs that are connected to the
-Internet. Perhaps their most important job is to stop MTAs being abused as
+Internet. Perhaps their most important job is to stop MTAs from being abused as
"open relays" by misguided individuals who send out vast amounts of unsolicited
-junk, and want to disguise its source. Exim provides flexible facilities for
+junk and want to disguise its source. Exim provides flexible facilities for
specifying policy controls on incoming mail:
* Exim 4 (unlike previous versions of Exim) implements policy controls on
remote host. However, the most common places are after each RCPT command,
and at the very end of the message. The sysadmin can specify conditions for
accepting or rejecting individual recipients or the entire message,
- respectively, at these two points (see chapter 42). Denial of access
+ respectively, at these two points (see chapter 43). Denial of access
results in an SMTP error code.
* An ACL is also available for locally generated, non-SMTP messages. In this
* When a message has been received, either from a remote host or from the
local host, but before the final acknowledgment has been sent, a locally
supplied C function called local_scan() can be run to inspect the message
- and decide whether to accept it or not (see chapter 44). If the message is
+ and decide whether to accept it or not (see chapter 45). If the message is
accepted, the list of recipients can be modified by the function.
* Using the local_scan() mechanism is another way of calling external scanner
Exim to be compiled with the content-scanning extension.
* After a message has been accepted, a further checking mechanism is
- available in the form of the system filter (see chapter 45). This runs at
+ available in the form of the system filter (see chapter 46). This runs at
the start of every delivery process.
encoding numbers in base 62. However, in the Darwin operating system (Mac OS X)
and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of
lower case letters) is used instead, because the message id is used to
-construct file names, and the names of files in those systems are not always
+construct filenames, and the names of files in those systems are not always
case-sensitive.
The detail of the contents of the message id have changed as Exim has evolved.
* If the process runs Exim with the -bS option, the message is also read
non-interactively, but in this case the recipients are listed at the start
of the message in a series of SMTP RCPT commands, terminated by a DATA
- command. This is so-called "batch SMTP" format, but it isn't really SMTP.
- The SMTP commands are just another way of passing envelope addresses in a
+ command. This is called "batch SMTP" format, but it isn't really SMTP. The
+ SMTP commands are just another way of passing envelope addresses in a
non-interactive submission.
* If the process runs Exim with the -bs option, the message is read
qualification domain (which can be set by the qualify_domain configuration
option). For local or batch SMTP, a sender address that is passed using the
SMTP MAIL command is ignored. However, the system administrator may allow
-certain users ("trusted users") to specify a different sender address
+certain users ("trusted users") to specify a different sender addresses
unconditionally, or all users to specify certain forms of different sender
address. The -f option or the SMTP MAIL command is used to specify these
different addresses. See section 5.2 for details of trusted users, and the
sender addresses.
Messages received by either of the non-interactive mechanisms are subject to
-checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
-(either over TCP/IP, or interacting with a local process) can be checked by a
+checking by the non-SMTP ACL if one is defined. Messages received using SMTP
+(either over TCP/IP or interacting with a local process) can be checked by a
number of ACLs that operate at different times during the SMTP session. Either
-individual recipients, or the entire message, can be rejected if local policy
-requirements are not met. The local_scan() function (see chapter 44) is run for
+individual recipients or the entire message can be rejected if local policy
+requirements are not met. The local_scan() function (see chapter 45) is run for
all incoming messages.
Exim can be configured not to start a delivery process when a message is
the two spool files consist of the message id, followed by "-H" for the file
containing the envelope and header, and "-D" for the data file.
-By default all these message files are held in a single directory called input
+By default, all these message files are held in a single directory called input
inside the general Exim spool directory. Some operating systems do not perform
very well if the number of files in a directory gets large; to improve
performance in such cases, the split_spool_directory option can be used. This
the addresses of the recipients. This information is entirely separate from any
addresses contained in the header lines. The status of the message includes a
list of recipients who have already received the message. The format of the
-first spool file is described in chapter 55.
+first spool file is described in chapter 56.
Address rewriting that is specified in the rewrite section of the configuration
(see chapter 31) is done once and for all on incoming addresses, both in the
A message remains in the spool directory until it is completely delivered to
its recipients or to an error address, or until it is deleted by an
administrator or by the user who originally created it. In cases when delivery
-cannot proceed - for example, when a message can neither be delivered to its
+cannot proceed - for example when a message can neither be delivered to its
recipients nor returned to its sender, the message is marked "frozen" on the
spool, and no more deliveries are attempted.
There are options called ignore_bounce_errors_after and timeout_frozen_after,
which discard frozen messages after a certain time. The first applies only to
-frozen bounces, the second to any frozen messages.
+frozen bounces, the second to all frozen messages.
While Exim is working on a message, it writes information about each delivery
attempt to its main log file. This includes successful, unsuccessful, and
-delayed deliveries for each recipient (see chapter 51). The log lines are also
+delayed deliveries for each recipient (see chapter 52). The log lines are also
written to a separate message log file for each message. These logs are solely
-for the benefit of the administrator, and are normally deleted along with the
+for the benefit of the administrator and are normally deleted along with the
spool files when processing of a message is complete. The use of individual
message logs can be disabled by setting no_message_logs; this might give an
improvement in performance on very busy systems.
Updating the spool file is done by writing a new file and renaming it, to
minimize the possibility of data loss.
-Should the system or the program crash after a successful delivery but before
-the spool file has been updated, the journal is left lying around. The next
-time Exim attempts to deliver the message, it reads the journal file and
-updates the spool file before proceeding. This minimizes the chances of double
-deliveries caused by crashes.
+Should the system or Exim crash after a successful delivery but before the
+spool file has been updated, the journal is left lying around. The next time
+Exim attempts to deliver the message, it reads the journal file and updates the
+spool file before proceeding. This minimizes the chances of double deliveries
+caused by crashes.
3.8 Processing an address for delivery
The main delivery processing elements of Exim are called routers and transports
, and collectively these are known as drivers. Code for a number of them is
provided in the source distribution, and compile-time options specify which
-ones are included in the binary. Run time options specify which ones are
+ones are included in the binary. Runtime options specify which ones are
actually used for delivering messages.
-Each driver that is specified in the run time configuration is an instance of
+Each driver that is specified in the runtime configuration is an instance of
that particular driver type. Multiple instances are allowed; for example, you
can set up several different smtp transports, each with different option values
that might specify different ports or different timeouts. Each instance has its
configuration.
The first router that is specified in a configuration is often one that handles
-addresses in domains that are not recognized specially by the local host. These
-are typically addresses for arbitrary domains on the Internet. A precondition
-is set up which looks for the special domains known to the host (for example,
-its own domain name), and the router is run for addresses that do not match.
-Typically, this is a router that looks up domains in the DNS in order to find
-the hosts to which this address routes. If it succeeds, the address is assigned
-to a suitable SMTP transport; if it does not succeed, the router is configured
-to fail the address.
+addresses in domains that are not recognized specifically by the local host.
+Typically these are addresses for arbitrary domains on the Internet. A
+precondition is set up which looks for the special domains known to the host
+(for example, its own domain name), and the router is run for addresses that do
+not match. Typically, this is a router that looks up domains in the DNS in
+order to find the hosts to which this address routes. If it succeeds, the
+address is assigned to a suitable SMTP transport; if it does not succeed, the
+router is configured to fail the address.
The second router is reached only when the domain is recognized as one that
"belongs" to the local host. This router does redirection - also known as
does not affect the way the routers work, but it is a state that can be
detected. By this means, a router can be skipped or made to behave differently
when verifying. A common example is a configuration in which the first router
-sends all messages to a message-scanning program, unless they have been
+sends all messages to a message-scanning program unless they have been
previously scanned. Thus, the first router accepts all addresses without any
checking, making it useless for verifying. Normally, the no_verify option would
be set for such a router, causing it to be skipped in verify mode.
following:
* accept: The router accepts the address, and either assigns it to a
- transport, or generates one or more "child" addresses. Processing the
- original address ceases, unless the unseen option is set on the router.
- This option can be used to set up multiple deliveries with different
- routing (for example, for keeping archive copies of messages). When unseen
- is set, the address is passed to the next router. Normally, however, an
- accept return marks the end of routing.
+ transport or generates one or more "child" addresses. Processing the
+ original address ceases unless the unseen option is set on the router. This
+ option can be used to set up multiple deliveries with different routing
+ (for example, for keeping archive copies of messages). When unseen is set,
+ the address is passed to the next router. Normally, however, an accept
+ return marks the end of routing.
Any child addresses generated by the router are processed independently,
starting with the first router by default. It is possible to change this by
redirect_router may be anywhere in the router configuration.
* pass: The router recognizes the address, but cannot handle it itself. It
- requests that the address be passed to another router. By default the
+ requests that the address be passed to another router. By default, the
address is passed to the next router, but this can be changed by setting
the pass_router option. However, (unlike redirect_router) the named router
must be below the current router (to avoid loops).
------------------------
Once routing is complete, Exim scans the addresses that are assigned to local
-and remote transports, and discards any duplicates that it finds. During this
-check, local parts are treated as case-sensitive. This happens only when
+and remote transports and discards any duplicates that it finds. During this
+check, local parts are treated case-sensitively. This happens only when
actually delivering a message; when testing routers with -bt, all the routed
addresses are shown.
interfaces to mail filtering. (Note: Sieve cannot be used for system filter
files.)
- Some additional features are available in system filters - see chapter 45
+ Some additional features are available in system filters - see chapter 46
for details. Note that a message is passed to the system filter only once
per delivery attempt, however many recipients it has. However, if there are
several delivery attempts because one or more addresses could not be
condition first_delivery can be used to detect the first run of the system
filter.
- * Each recipient address is offered to each configured router in turn,
+ * Each recipient address is offered to each configured router, in turn,
subject to its preconditions, until one is able to handle it. If no router
can handle the address, that is, if they all decline, the address is
failed. Because routers can be targeted at particular domains, several
Exim's mechanism for retrying messages that fail to get delivered at the first
attempt is the queue runner process. You must either run an Exim daemon that
uses the -q option with a time interval to start queue runners at regular
-intervals, or use some other means (such as cron) to start them. If you do not
+intervals or use some other means (such as cron) to start them. If you do not
arrange for queue runners to be run, messages that fail temporarily at the
-first attempt will remain on your queue for ever. A queue runner process works
+first attempt will remain in your queue forever. A queue runner process works
its way through the queue, one message at a time, trying each delivery that has
passed its retry time. You can run several queue runners at once.
many recipients, it is possible for some addresses to fail in one delivery
attempt and others to fail subsequently, giving rise to more than one bounce
message. The wording of bounce messages can be customized by the administrator.
-See chapter 48 for details.
+See chapter 49 for details.
Bounce messages contain an X-Failed-Recipients: header line that lists the
failed addresses, for the benefit of programs that try to analyse such messages
address given in the MAIL command. However, when an address is expanded via a
forward or alias file, an alternative address can be specified for delivery
failures of the generated addresses. For a mailing list expansion (see section
-49.2) it is common to direct bounce messages to the manager of the list.
+50.2) it is common to direct bounce messages to the manager of the list.
3.17 Failures to deliver bounce messages
----------------------------------------
If a bounce message (either locally generated or received from a remote host)
-itself suffers a permanent delivery failure, the message is left on the queue,
+itself suffers a permanent delivery failure, the message is left in the queue,
but it is frozen, awaiting the attention of an administrator. There are options
that can be used to make Exim discard such failed messages, or to keep them for
only a short time (see timeout_frozen_after and ignore_bounce_errors_after).
Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
creates a directory with the name of the current release (for example,
-exim-4.84.2) into which the following files are placed:
+exim-4.92) into which the following files are placed:
ACKNOWLEDGMENTS contains some acknowledgments
CHANGES contains a reference to where changes are documented
src remaining source files
util independent utilities
-The main utility programs are contained in the src directory, and are built
-with the Exim binary. The util directory contains a few optional scripts that
-may be useful to some sites.
+The main utility programs are contained in the src directory and are built with
+the Exim binary. The util directory contains a few optional scripts that may be
+useful to some sites.
4.2 Multiple machine architectures and operating systems
links to the sources are installed in this directory, which is where the actual
building takes place. In most cases, Exim can discover the machine architecture
and operating system for itself, but the defaults can be overridden if
-necessary.
+necessary. A C99-capable compiler will be required for the build.
4.3 PCRE library
Exim no longer has an embedded PCRE library as the vast majority of modern
systems include PCRE as a system library, although you may need to install the
-PCRE or PCRE development package for your operating system. If your system has
-a normal PCRE installation the Exim build process will need no further
-configuration. If the library or the headers are in an unusual location you
-will need to either set the PCRE_LIBS and INCLUDE directives appropriately, or
-set PCRE_CONFIG=yes to use the installed pcre-config command. If your operating
-system has no PCRE support then you will need to obtain and build the current
-PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More
-information on PCRE is available at http://www.pcre.org/.
+PCRE package or the PCRE development package for your operating system. If your
+system has a normal PCRE installation the Exim build process will need no
+further configuration. If the library or the headers are in an unusual location
+you will need to either set the PCRE_LIBS and INCLUDE directives appropriately,
+or set PCRE_CONFIG=yes to use the installed pcre-config command. If your
+operating system has no PCRE support then you will need to obtain and build the
+current PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More
+information on PCRE is available at https://www.pcre.org/.
4.4 DBM libraries
2. The GNU library, gdbm, operates on a single file. If used via its ndbm
compatibility interface it makes two different hard links to it with names
- dbmfile.dir and dbmfile.pag, but if used via its native interface, the file
- name is used unmodified.
+ dbmfile.dir and dbmfile.pag, but if used via its native interface, the
+ filename is used unmodified.
3. The Berkeley DB package, if called via its ndbm compatibility interface,
operates on a single file called dbmfile.db, but otherwise looks to the
5. To complicate things further, there are several very different versions of
the Berkeley DB package. Version 1.85 was stable for a very long time,
- releases 2.x and 3.x were current for a while, but the latest versions are
- now numbered 4.x. Maintenance of some of the earlier releases has ceased.
- All versions of Berkeley DB can be obtained from http://www.sleepycat.com/.
-
- 6. Yet another DBM library, called tdb, is available from http://
- download.sourceforge.net/tdb. It has its own interface, and also operates
- on a single file.
+ releases 2.x and 3.x were current for a while, but the latest versions when
+ Exim last revamped support were numbered 4.x. Maintenance of some of the
+ earlier releases has ceased. All versions of Berkeley DB could be obtained
+ from http://www.sleepycat.com/, which is now a redirect to their new
+ owner's page with far newer versions listed. It is probably wise to plan to
+ move your storage configurations away from Berkeley DB format, as today
+ there are smaller and simpler alternatives more suited to Exim's usage
+ model.
+
+ 6. Yet another DBM library, called tdb, is available from https://
+ sourceforge.net/projects/tdb/files/. It has its own interface, and also
+ operates on a single file.
Exim and its utilities can be compiled to use any of these interfaces. In order
to use any version of the Berkeley DB package in native mode, you must set
then read it and edit it appropriately.
There are three settings that you must supply, because Exim will not build
-without them. They are the location of the run time configuration file
+without them. They are the location of the runtime configuration file
(CONFIGURE_FILE), the directory in which Exim binaries will be installed
(BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe
EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a
-colon-separated list of file names; Exim uses the first of them that exists.
+colon-separated list of filenames; Exim uses the first of them that exists.
There are a few other parameters that can be specified either at build time or
-at run time, to enable the same binary to be used on a number of different
+at runtime, to enable the same binary to be used on a number of different
machines. However, if the locations of Exim's spool directory and log file
directory (if not within the spool directory) are fixed, it is recommended that
-you specify them in Local/Makefile instead of at run time, so that errors
+you specify them in Local/Makefile instead of at runtime, so that errors
detected early in Exim's execution (such as a malformed configuration file) can
be logged.
WITH_CONTENT_SCAN=yes
in your Local/Makefile. For details of the facilities themselves, see chapter
-43.
+44.
If you are going to build the Exim monitor, a similar configuration process is
required. The file exim_monitor/EDITME must be edited appropriately for your
This is all the configuration that is needed in straightforward cases for known
operating systems. However, the building process is set up so that it is easy
to override options that are set by default or by operating-system-specific
-configuration files, for example to change the name of the C compiler, which
-defaults to gcc. See section 4.13 below for details of how to do this.
+configuration files, for example, to change the C compiler, which defaults to
+gcc. See section 4.13 below for details of how to do this.
4.6 Support for iconv()
in the ASCII character set, and to label them as being in a particular
character set. When Exim is inspecting header lines by means of the $h_
mechanism, it decodes them, and translates them into a specified character set
-(default ISO-8859-1). The translation is possible only if the operating system
-supports the iconv() function.
+(default is set at build time). The translation is possible only if the
+operating system supports the iconv() function.
However, some of the operating systems that supply iconv() do not support very
-many conversions. The GNU libiconv library (available from http://www.gnu.org/
+many conversions. The GNU libiconv library (available from https://www.gnu.org/
software/libiconv/) can be installed on such systems to remedy this deficiency,
as well as on systems that do not supply iconv() at all. After installing
libiconv, you should add
You do not need to set TLS_INCLUDE if the relevant directory is already
specified in INCLUDE. Details of how to configure Exim to make use of TLS are
-given in chapter 41.
+given in chapter 42.
4.8 Use of tcpwrappers
defined. AAAA records (analogous to A records for IPv4) are in use, and are
currently seen as the mainstream. Another record type called A6 was proposed as
better than AAAA because it had more flexibility. However, it was felt to be
-over-complex, and its status was reduced to "experimental". It is not known if
-anyone is actually using A6 records. Exim has support for A6 records, but this
-is included only if you set "SUPPORT_A6=YES" in Local/Makefile. The support has
-not been tested for some time.
+over-complex, and its status was reduced to "experimental". Exim used to have a
+compile option for including A6 record support but this has now been withdrawn.
4.10 Dynamically loaded lookup module support
Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created.
Symbolic links to relevant source files are installed in the build directory.
-Warning: The -j (parallel) flag must not be used with make; the building
-process fails if it is set.
-
If this is the first time make has been run, it calls a script that builds a
make file inside the build directory, using the configuration files from the
Local directory. The new make file is then passed to another instance of make.
lookup types (such as cdb) for which the code is entirely contained within
Exim, and no external include files or libraries are required. When a lookup
type is not included in the binary, attempts to configure Exim to use it cause
-run time configuration errors.
+runtime configuration errors.
Many systems now use a tool called pkg-config to encapsulate information about
how to compile against a library; Exim has some initial support for being able
OS/eximon.conf-<ostype> file is also optional. The default values in OS/
eximon.conf-Default can be overridden dynamically by setting environment
variables of the same name, preceded by EXIMON_. For example, setting
-EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run
-time.
+EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at
+runtime.
4.16 Installing Exim binaries and scripts
for normal configurations. Therefore, you must run "make install" as root so
that it can set up the Exim binary in this way. However, in some special
situations (for example, if a host is doing no local deliveries) it may be
-possible to run Exim without making the binary setuid root (see chapter 54 for
+possible to run Exim without making the binary setuid root (see chapter 55 for
details).
-Exim's run time configuration file is named by the CONFIGURE_FILE setting in
+Exim's runtime configuration file is named by the CONFIGURE_FILE setting in
Local/Makefile. If this names a single file, and the file does not exist, the
default configuration file src/configure.default is copied there by the
-installation script. If a run time configuration file already exists, it is
-left alone. If CONFIGURE_FILE is a colon-separated list, naming several
-alternative files, no default is installed.
+installation script. If a runtime configuration file already exists, it is left
+alone. If CONFIGURE_FILE is a colon-separated list, naming several alternative
+files, no default is installed.
One change is made to the default configuration file when it is installed: the
default configuration contains a router that references a system aliases file.
For the utility programs, old versions are renamed by adding the suffix .O to
their names. The Exim binary itself, however, is handled differently. It is
installed under a name that includes the version number and the compile number,
-for example exim-4.84.2-1. The script then arranges for a symbolic link called
+for example, exim-4.92-1. The script then arranges for a symbolic link called
exim to point to the binary. If you are updating a previous version of Exim,
the script takes care to ensure that the name exim is never absent from the
directory (as seen by other processes).
Not all systems use the GNU info system for documentation, and for this reason,
the Texinfo source of Exim's documentation is not included in the main
-distribution. Instead it is available separately from the ftp site (see section
-1.6).
+distribution. Instead it is available separately from the FTP site (see section
+1.5).
If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of
the documentation is found in the source tree, running "make install"
4.19 Testing
------------
-Having installed Exim, you can check that the run time configuration file is
+Having installed Exim, you can check that the runtime configuration file is
syntactically valid by running the following command, which assumes that the
Exim binary directory is within your PATH environment variable:
Testing a new version on a system that is already running Exim can most easily
be done by building a binary with a different CONFIGURE_FILE setting. From
-within the run time configuration, all other file and directory names that Exim
+within the runtime configuration, all other file and directory names that Exim
uses can be altered, in order to keep it entirely clear of the production
version.
data. A line history is supported.
Long expansion expressions can be split over several lines by using
- backslash continuations. As in Exim's run time configuration, white space
- at the start of continuation lines is ignored. Each argument or data line
- is passed through the string expansion mechanism, and the result is output.
+ backslash continuations. As in Exim's runtime configuration, white space at
+ the start of continuation lines is ignored. Each argument or data line is
+ passed through the string expansion mechanism, and the result is output.
Variable values from the configuration file (for example, $qualify_domain)
- are available, but no message-specific values (such as $sender_domain) are
- set, because no message is being processed (but see -bem and -Mset).
+ are available, but no message-specific values (such as $message_exim_id)
+ are set, because no message is being processed (but see -bem and -Mset).
Note: If you use this mechanism to test lookups, and you change the data
files or databases you are using, you must exit and restart Exim before
trying the same lookup again. Otherwise, because each Exim process caches
the results of lookups, you will just get the same result as before.
+ Macro processing is done on lines before string-expansion: new macros can
+ be defined and macros will be expanded. Because macros in the config file
+ are often used for secrets, those are only available to admin users.
+
-bem <filename>
This option operates like -be except that it must be followed by the name
actually perform an ident callout when testing using -bh because there is
no incoming SMTP connection.
- Warning 2: Address verification callouts (see section 42.45) are also
+ Warning 2: Address verification callouts (see section 43.45) are also
skipped when testing using -bh. If you want these callouts to occur, use
-bhc instead.
The exim_checkaccess utility is a "packaged" version of -bh whose output
just states whether a given recipient address from a given host is
- acceptable or not. See section 52.8.
+ acceptable or not. See section 53.8.
Features such as authentication and encryption, where the client input is
not plain text, cannot easily be tested with -bh. Instead, you should use a
this for special cases.
Policy checks on the contents of local messages can be enforced by means of
- the non-SMTP ACL. See chapter 42 for details.
+ the non-SMTP ACL. See chapter 43 for details.
The return code is zero if the message is successfully accepted. Otherwise,
the action is controlled by the -oex option setting - see below.
-bmalware <filename>
- This debugging option causes Exim to scan the given file, using the malware
- scanning framework. The option of av_scanner influences this option, so if
+ This debugging option causes Exim to scan the given file or directory
+ (depending on the used scanner interface), using the malware scanning
+ framework. The option of av_scanner influences this option, so if
av_scanner's value is dependent upon an expansion then the expansion should
have defaults which apply to this invocation. ACLs are not invoked, so if
av_scanner references an ACL variable then that variable will never be
mysql_servers = <value not displayable>
- If configure_file is given as an argument, the name of the run time
- configuration file is output. If a list of configuration files was
- supplied, the value that is output here is the name of the file that was
- actually used.
+ If config is given as an argument, the config is output, as it was parsed,
+ any include file resolved, any comment removed.
+
+ If config_file is given as an argument, the name of the runtime
+ configuration file is output. (configure_file works too, for backward
+ compatibility.) If a list of configuration files was supplied, the value
+ that is output here is the name of the file that was actually used.
If the -n flag is given, then for most modes of -bP operation the name will
not be output.
settings can be obtained by using routers, transports, or authenticators.
If environment is given as an argument, the set of environment variables is
- output, line by line. Using the -n flag supresses the value of the
+ output, line by line. Using the -n flag suppresses the value of the
variables.
If invoked by an admin user, then macro, macro_list and macros are
available, similarly to the drivers. Because macros are sometimes used for
storing passwords, this option is restricted. The output format is one item
- per line.
+ per line. For the "-bP macro <name>" form, if no such macro is found the
+ exit status will be nonzero.
-bp
an admin user. However, the queue_list_requires_admin option can be set
false to allow any user to see the queue.
- Each message on the queue is displayed as in the following example:
+ Each message in the queue is displayed as in the following example:
25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
red.king@looking-glass.fict.example
<other addresses>
- The first line contains the length of time the message has been on the
+ The first line contains the length of time the message has been in the
queue (in this case 25 minutes), the size of the message (2.9K), the unique
local identifier for the message, and the message sender, as contained in
the envelope. For bounce messages, the sender address is empty, and appears
-bpc
- This option counts the number of messages on the queue, and writes the
+ This option counts the number of messages in the queue, and writes the
total to the standard output. It is restricted to admin users, unless
queue_list_requires_admin is set false.
This option operates like -bp, but the output is not sorted into
chronological order of message arrival. This can speed it up when there are
- lots of messages on the queue, and is particularly useful if the output is
+ lots of messages in the queue, and is particularly useful if the output is
going to be post-processed in a way that doesn't need the sorting.
-bpra
follow.
As for other local message submissions, the contents of incoming batch SMTP
- messages can be checked using the non-SMTP ACL (see chapter 42).
+ messages can be checked using the non-SMTP ACL (see chapter 43).
Unqualified addresses are automatically qualified using qualify_domain and
qualify_recipient, as appropriate, unless the -bnq option is used.
error was detected; it is 1 if one or more messages were accepted before
the error was detected; otherwise it is 2.
- More details of input using batched SMTP are given in section 47.11.
+ More details of input using batched SMTP are given in section 48.11.
-bs
This option causes Exim to accept one or more messages by reading SMTP
commands on the standard input, and producing SMTP replies on the standard
- output. SMTP policy controls, as defined in ACLs (see chapter 42) are
+ output. SMTP policy controls, as defined in ACLs (see chapter 43) are
applied. Some user agents use this interface as a way of passing
locally-generated messages to the MTA.
number, and compilation date of the exim binary to the standard output. It
also lists the DBM library that is being used, the optional modules (such
as specific lookup types), the drivers that are included in the binary, and
- the name of the run time configuration file that is in use.
+ the name of the runtime configuration file that is in use.
As part of its operation, -bV causes Exim to read and syntax check its
configuration file. However, this is a static check only. It cannot check
is taken as a recipient address to be verified by the routers. (This does
not involve any verification callouts). During normal operation,
verification happens mostly as a consequence processing a verify condition
- in an ACL (see chapter 42). If you want to test an entire ACL, possibly
+ in an ACL (see chapter 43). If you want to test an entire ACL, possibly
including callouts, see the -bh and -bhc options.
If verification fails, and the caller is not an admin user, no details of
-C <filelist>
- This option causes Exim to find the run time configuration file from the
+ This option causes Exim to find the runtime configuration file from the
given list instead of from the list specified by the CONFIGURE_FILE
- compile-time setting. Usually, the list will consist of just a single file
- name, but it can be a colon-separated list of names. In this case, the
+ compile-time setting. Usually, the list will consist of just a single
+ filename, but it can be a colon-separated list of names. In this case, the
first file that exists is used. Failure to open an existing file stops Exim
from proceeding any further along the list, and an error is generated.
- The file names need to be absolute names.
-
When this option is used by a caller other than root, and the list is
different from the compiled-in list, Exim gives up its root privilege
immediately, and runs with the real and effective uid and gid set to those
running as the Exim user, so when it re-executes to regain privilege for
the delivery, the use of -C causes privilege to be lost. However, root can
test reception and delivery using two separate commands (one to put a
- message on the queue, using -odq, and another to do the delivery, using -M
+ message in the queue, using -odq, and another to do the delivery, using -M
).
If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix
string with which any file named in a -C command line option must start. In
- addition, the file name must not contain the sequence "/../". However, if
+ addition, the filename must not contain the sequence "/../". However, if
the value of the -C option is identical to the value of CONFIGURE_FILE in
Local/Makefile, Exim ignores -C and proceeds as usual. There is no default
- setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used
+ setting for ALT_CONFIG_PREFIX; when it is unset, any filename can be used
with -C.
ALT_CONFIG_PREFIX can be used to confine alternative configuration files to
exim '-D ABC = something' ...
- -D may be repeated up to 10 times on a command line.
+ -D may be repeated up to 10 times on a command line. Only macro names up to
+ 22 letters long can be set.
-d<debug options>
interface lists of local interfaces
lists matching things in lists
load system load checks
- local_scan can be used by local_scan() (see chapter 44)
+ local_scan can be used by local_scan() (see chapter 45)
lookup general lookup code and all lookups
memory memory handling
- pid add pid to debug output lines
+ noutf8 modifier: avoid UTF-8 line-drawing
+ pid modifier: add pid to debug output lines
process_info setting info for the process log
queue_run queue runs
receive general message reception logic
retry retry handling
rewrite address rewriting
route address routing
- timestamp add timestamp to debug output lines
+ timestamp modifier: add timestamp to debug output lines
tls TLS logic
transport transports
uid changes of uid/gid and looking up uid/gid
start of all debug output lines. This can be useful when trying to track
down delays in processing.
+ The "noutf8" selector disables the use of UTF-8 line-drawing characters to
+ group related information. When disabled. ascii-art is used instead. Using
+ the "+all" option does not set this modifier,
+
If the debug_print option is set in any driver, it produces output whenever
any debugging is selected, or if -v is used.
This is an obsolete option that is now a no-op. It used to affect the way
Exim handled CR and LF characters in incoming messages. What happens now is
- described in section 46.2.
+ described in section 47.2.
-E
This option is not intended for use by external callers. It is used
internally by Exim to invoke another instance of itself to deliver a
waiting message using an existing SMTP connection, which is passed as the
- standard input. Details are given in chapter 47. This must be the final
+ standard input. Details are given in chapter 48. This must be the final
option, and the caller must be root or the Exim user in order to use it.
-MCA
internally by Exim in conjunction with the -MC option. It signifies that
the connection to the remote host has been authenticated.
+-MCD
+
+ This option is not intended for use by external callers. It is used
+ internally by Exim in conjunction with the -MC option. It signifies that
+ the remote host supports the ESMTP DSN extension.
+
+-MCG <queue name>
+
+ This option is not intended for use by external callers. It is used
+ internally by Exim in conjunction with the -MC option. It signifies that an
+ alternate queue is used, named by the following argument.
+
+-MCK
+
+ This option is not intended for use by external callers. It is used
+ internally by Exim in conjunction with the -MC option. It signifies that a
+ remote host supports the ESMTP CHUNKING extension.
+
-MCP
This option is not intended for use by external callers. It is used
internally by Exim in conjunction with the -MC option, and passes on the
fact that the host to which Exim is connected supports TLS encryption.
+-MCt <IP address> <port> <cipher>
+
+ This option is not intended for use by external callers. It is used
+ internally by Exim in conjunction with the -MC option, and passes on the
+ fact that the connection is being proxied by a parent process for handling
+ TLS encryption. The arguments give the local address and port being
+ proxied, and the TLS cipher.
+
-Mc <message id> <message id> ...
- This option requests Exim to run a delivery attempt on each message in
+ This option requests Exim to run a delivery attempt on each message, in
turn, but unlike the -M option, it does check for retry hints, and respects
any that are found. This option is not very useful to external callers. It
is provided mainly for internal use by Exim when it needs to re-invoke
- itself in order to regain root privilege for a delivery (see chapter 54).
+ itself in order to regain root privilege for a delivery (see chapter 55).
However, -Mc can be useful when testing, in order to run a delivery that
respects retry times and other options such as hold_domains that are
overridden when -M is used. Such a delivery does not count as a queue run.
bounce messages are sent; each message is simply forgotten. However, if any
of the messages are active, their status is not altered. This option can be
used only by an admin user or by the user who originally caused the message
- to be placed on the queue.
+ to be placed in the queue.
-Mset <message id>
-n
This option is interpreted by Sendmail to mean "no aliasing". For normal
- modes of operation, it is ignored by Exim. When combined with -bP it
- suppresses the name of an option from being output.
+ modes of operation, it is ignored by Exim. When combined with -bP it makes
+ the output more terse (suppresses option names, environment values and
+ config pretty printing).
-O <data>
-oA <file name>
This option is used by Sendmail in conjunction with -bi to specify an
- alternative alias file name. Exim handles -bi differently; see the
+ alternative alias filename. Exim handles -bi differently; see the
description above.
-oB <n>
effect.
If there is a temporary delivery error during foreground delivery, the
- message is left on the queue for later delivery, and the original reception
- process exits. See chapter 50 for a way of setting up a restricted
+ message is left in the queue for later delivery, and the original reception
+ process exits. See chapter 51 for a way of setting up a restricted
configuration that never queues messages.
-odi
This option applies to all modes in which Exim accepts incoming messages,
including the listening daemon. It specifies that the accepting process
should not automatically start a delivery process for each message
- received. Messages are placed on the queue, and remain there until a
+ received. Messages are placed in the queue, and remain there until a
subsequent queue runner process encounters them. There are several
configuration options (such as queue_only) that can be used to queue
incoming messages under certain conditions. This option overrides all of
message, in the background by default, but in the foreground if -odi is
also present. The recipient addresses are routed, and local deliveries are
done in the normal way. However, if any SMTP deliveries are required, they
- are not done at this time, so the message remains on the queue until a
+ are not done at this time, so the message remains in the queue until a
subsequent queue runner process encounters it. Because routing was done,
Exim knows which messages are waiting for which hosts, and so a number of
messages for the same host can be sent in a single SMTP connection. The
-bh, the protocol is forced to one of the standard SMTP protocol names (see
the description of $received_protocol in section 11.9). For -bs, the
protocol is always "local-" followed by one of those same names. For -bS
- (batched SMTP) however, the protocol can be set by -oMr.
+ (batched SMTP) however, the protocol can be set by -oMr. Repeated use of
+ this option is not supported.
-oMs <host name>
This option sets a timeout value for incoming non-SMTP messages. If it is
not set, Exim will wait forever for the standard input. The value can also
be set by the receive_timeout option. The format used for specifying times
- is described in section 6.15.
+ is described in section 6.16.
-os <time>
This option sets a timeout value for incoming SMTP messages. The timeout
applies to each SMTP command and block of data. The value can also be set
by the smtp_receive_timeout option; it defaults to 5 minutes. The format
- used for specifying times is described in section 6.15.
+ used for specifying times is described in section 6.16.
-ov
is also given. It controls which ports and interfaces the daemon uses.
Details of the syntax, and how it interacts with configuration file
options, are given in chapter 13. When -oX is used to start a daemon, no
- pid file is written unless -oP is also present to specify a pid file name.
+ pid file is written unless -oP is also present to specify a pid filename.
-pd
name and its colon can be omitted when only the protocol is to be set. Note
the Exim already has two private options, -pd and -ps, that refer to
embedded Perl. It is therefore impossible to set a protocol value of "d" or
- "s" using this option (but that does not seem a real limitation).
+ "s" using this option (but that does not seem a real limitation). Repeated
+ use of this option is not supported.
-q
relax this restriction (and also the same requirement for the -M, -R, and
-S options).
- The -q option starts one queue runner process. This scans the queue of
- waiting messages, and runs a delivery process for each one in turn. It
- waits for each delivery process to finish before starting the next one. A
- delivery process may not actually do any deliveries if the retry times for
- the addresses have not been reached. Use -qf (see below) if you want to
- override this.
+ If other commandline options do not specify an action, the -q option starts
+ one queue runner process. This scans the queue of waiting messages, and
+ runs a delivery process for each one in turn. It waits for each delivery
+ process to finish before starting the next one. A delivery process may not
+ actually do any deliveries if the retry times for the addresses have not
+ been reached. Use -qf (see below) if you want to override this.
If the delivery process spawns other processes to deliver other messages
down passed SMTP connections, the queue runner waits for these to finish
If the i flag is present, the queue runner runs delivery processes only for
those messages that haven't previously been tried. (i stands for "initial
- delivery".) This can be helpful if you are putting messages on the queue
+ delivery".) This can be helpful if you are putting messages in the queue
using -odq and want a queue runner just to process the new messages.
-q[q][i]f...
-q[q][i][f[f]]l
The l (the letter "ell") flag specifies that only local deliveries are to
- be done. If a message requires any remote deliveries, it remains on the
+ be done. If a message requires any remote deliveries, it remains in the
queue for later delivery.
+-q[q][i][f[f]][l][G<name>[/<time>]]]
+
+ If the G flag and a name is present, the queue runner operates on the queue
+ with the given name rather than the default queue. The name should not
+ contain a / character. For a periodic queue run (see below) append to the
+ name a slash and a time value.
+
+ If other commandline options specify an action, a -qG<name> option will
+ specify a queue to operate on. For example:
+
+ exim -bp -qGquarantine
+ mailq -qGquarantine
+ exim -qGoffpeak -Rf @special.domain.example
+
-q<qflags> <start id> <end id>
When scanning the queue, Exim can be made to skip over messages whose ids
When a time value is present, the -q option causes Exim to run as a daemon,
starting a queue runner process at intervals specified by the given time
- value (whose format is described in section 6.15). This form of the -q
+ value (whose format is described in section 6.16). This form of the -q
option is commonly combined with the -bd option, in which case a single
daemon process handles both functions. A common way of starting up a
combined daemon at system boot time is to use a command such as
The -R option makes it straightforward to initiate delivery of all messages
to a given domain after a host has been down for some time. When the SMTP
- command ETRN is accepted by its ACL (see chapter 42), its default effect is
+ command ETRN is accepted by its ACL (see chapter 43), its default effect is
to run Exim with the -R option, but it can be configured to run an
arbitrary command instead.
This option is available when Exim is compiled with TLS support. It forces
all incoming SMTP connections to behave as if the incoming port is listed
- in the tls_on_connect_ports option. See section 13.4 and chapter 41 for
+ in the tls_on_connect_ports option. See section 13.4 and chapter 42 for
further details.
-U
This option is interpreted by Sendmail to cause debug information to be
sent to the named file. It is ignored by Exim.
+-z <log-line>
+
+ This option writes its argument to Exim's logfile. Use is restricted to
+ administrators; the intent is for operational notes. Quotes should be used
+ to maintain a multi-word item as a single argument, under most shells.
+
===============================================================================
-6. THE EXIM RUN TIME CONFIGURATION FILE
+6. THE EXIM RUNTIME CONFIGURATION FILE
-Exim uses a single run time configuration file that is read whenever an Exim
+Exim uses a single runtime configuration file that is read whenever an Exim
binary is executed. Note that in normal operation, this happens frequently,
because Exim is designed to operate in a distributed manner, without central
control.
The name of the configuration file is compiled into the binary for security
reasons, and is specified by the CONFIGURE_FILE compilation option. In most
configurations, this specifies a single file. However, it is permitted to give
-a colon-separated list of file names, in which case Exim uses the first
-existing file in the list.
+a colon-separated list of filenames, in which case Exim uses the first existing
+file in the list.
-The run time configuration file must be owned by root or by the user that is
+The runtime configuration file must be owned by root or by the user that is
specified at compile time by the CONFIGURE_OWNER option (if set). The
configuration file must not be world-writeable, or group-writeable unless its
group is the root group or the one specified at compile time by the
CONFIGURE_GROUP option.
Warning: In a conventional configuration, where the Exim binary is setuid to
-root, anybody who is able to edit the run time configuration file has an easy
+root, anybody who is able to edit the runtime configuration file has an easy
way to run commands as root. If you specify a user or group in the
CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who
are members of that group will trivially be able to obtain root privileges.
-Up to Exim version 4.72, the run time configuration file was also permitted to
+Up to Exim version 4.72, the runtime configuration file was also permitted to
be writeable by the Exim user and/or group. That has been changed in Exim 4.73
since it offered a simple privilege escalation for any attacker who managed to
compromise the Exim user account.
A default configuration file, which will work correctly in simple situations,
is provided in the file src/configure.default. If CONFIGURE_FILE defines just
-one file name, the installation process copies the default configuration to a
+one filename, the installation process copies the default configuration to a
new file of that name if it did not previously exist. If CONFIGURE_FILE is a
list, no default is automatically installed. Chapter 7 is a "walk-through"
discussion of the default configuration.
the caller is root. The reception works, but by that time, Exim is running as
the Exim user, so when it re-execs to regain privilege for the delivery, the
use of -C causes privilege to be lost. However, root can test reception and
-delivery using two separate commands (one to put a message on the queue, using
+delivery using two separate commands (one to put a message in the queue, using
-odq, and another to do the delivery, using -M).
If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string
with which any file named in a -C command line option must start. In addition,
-the file name must not contain the sequence "/../". There is no default setting
-for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C.
+the filename must not contain the sequence "/../". There is no default setting
+for ALT_CONFIG_PREFIX; when it is unset, any filename can be used with -C.
One-off changes to a configuration can be specified by the -D command line
option, which defines and overrides values for macros used inside the
Some sites may wish to use the same Exim binary on different machines that
share a file system, but to use different configuration files on each machine.
If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a
-file whose name is the configuration file name followed by a dot and the
+file whose name is the configuration filename followed by a dot and the
machine's node name, as obtained from the uname() function. If this file does
-not exist, the standard name is tried. This processing occurs for each file
-name in the list given by CONFIGURE_FILE or -C.
+not exist, the standard name is tried. This processing occurs for each filename
+in the list given by CONFIGURE_FILE or -C.
In some esoteric situations different versions of Exim may be run under
different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help
Exim's configuration file is divided into a number of different parts. General
option settings must always appear at the start of the file. The other parts
are all optional, and may appear in any order. Each part other than the first
-is introduced by the word "begin" followed by the name of the part. The
-optional parts are:
+is introduced by the word "begin" followed by at least one literal space, and
+the name of the part. The optional parts are:
* ACL: Access control lists for controlling incoming SMTP mail (see chapter
- 42).
+ 43).
* authenticators: Configuration settings for the authenticator drivers. These
are concerned with the SMTP AUTH command (see chapter 33).
LOCAL_SCAN_HAS_OPTIONS=yes
in Local/Makefile before building Exim. Details of the local_scan()
- facility are given in chapter 44.
+ facility are given in chapter 45.
Leading and trailing white space in configuration lines is always ignored.
as required.
The ACLs, retry rules, and rewriting rules have their own syntax which is
-described in chapters 42, 32, and 31, respectively. The other parts of the
+described in chapters 43, 32, and 31, respectively. The other parts of the
configuration file have some syntactic items in common, and these are described
-below, from section 6.10 onwards. Before that, the inclusion, macro, and
+below, from section 6.11 onwards. Before that, the inclusion, macro, and
conditional facilities are described.
6.3 File inclusions in the configuration file
---------------------------------------------
-You can include other files inside Exim's run time configuration file by using
+You can include other files inside Exim's runtime configuration file by using
this syntax:
-.include <file name>
-.include_if_exists <file name>
+.include <filename>
+.include_if_exists <filename>
-on a line by itself. Double quotes round the file name are optional. If you use
+on a line by itself. Double quotes round the filename are optional. If you use
the first form, a configuration error occurs if the file does not exist; the
-second form does nothing for non-existent files. In all cases, an absolute file
-name is required.
+second form does nothing for non-existent files. The first form allows a
+relative name. It is resolved relative to the directory of the including file.
+For the second form an absolute filename is required.
Includes may be nested to any depth, but remember that Exim reads its
configuration file often, so it is a good idea to keep them to a minimum. If
Once a macro is defined, all subsequent lines in the file (and any included
files) are scanned for the macro name; if there are several macros, the line is
-scanned for each in turn, in the order in which the macros are defined. The
+scanned for each, in turn, in the order in which the macros are defined. The
replacement text is not re-scanned for the current macro, though it is scanned
for subsequently defined macros. For this reason, a macro name may not contain
the name of a previously defined macro as a substring. You could, for example,
10.5.
-6.9 Conditional skips in the configuration file
------------------------------------------------
+6.9 Builtin macros
+------------------
+
+Exim defines some macros depending on facilities available, which may differ
+due to build-time definitions and from one release to another. All of these
+macros start with an underscore. They can be used to conditionally include
+parts of a configuration (see below).
+
+The following classes of macros are defined:
+
+ _HAVE_* build-time defines
+ _DRIVER_ROUTER_* router drivers
+ _DRIVER_TRANSPORT_* transport drivers
+ _DRIVER_AUTHENTICATOR_* authenticator drivers
+ _LOG_* log_selector values
+ _OPT_MAIN_* main config options
+ _OPT_ROUTERS_* generic router options
+ _OPT_TRANSPORTS_* generic transport options
+ _OPT_AUTHENTICATORS_* generic authenticator options
+ _OPT_ROUTER_*_* private router options
+ _OPT_TRANSPORT_*_* private transport options
+ _OPT_AUTHENTICATOR_*_* private authenticator options
+
+Use an "exim -bP macros" command to get the list of macros.
+
+
+6.10 Conditional skips in the configuration file
+------------------------------------------------
You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef",
".else", and ".endif" to dynamically include or exclude portions of the
message_size_limit = 100M
.endif
-sets a message size limit of 50M if the macro "AAA" is defined, and 100M
-otherwise. If there is more than one macro named on the line, the condition is
-true if any of them are defined. That is, it is an "or" condition. To obtain an
-"and" condition, you need to use nested ".ifdef"s.
+sets a message size limit of 50M if the macro "AAA" is defined (or "A" or
+"AA"), and 100M otherwise. If there is more than one macro named on the line,
+the condition is true if any of them are defined. That is, it is an "or"
+condition. To obtain an "and" condition, you need to use nested ".ifdef"s.
Although you can use a macro expansion to generate one of these directives, it
is not very useful, because the condition "there was a macro substitution in
clarify complicated nestings.
-6.10 Common option syntax
+6.11 Common option syntax
-------------------------
For the main set of options, driver options, and local_scan() options, each
that are found in option settings.
-6.11 Boolean options
+6.12 Boolean options
--------------------
Options whose type is given as boolean are on/off switches. There are two
You can use whichever syntax you prefer.
-6.12 Integer values
+6.13 Integer values
-------------------
If an option's type is given as "integer", the value can be given in decimal,
hexadecimal number.
If an integer value is followed by the letter K, it is multiplied by 1024; if
-it is followed by the letter M, it is multiplied by 1024x1024. When the values
-of integer option settings are output, values which are an exact multiple of
-1024 or 1024x1024 are sometimes, but not always, printed using the letters K
-and M. The printing style is independent of the actual input format that was
-used.
+it is followed by the letter M, it is multiplied by 1024x1024; if by the letter
+G, 1024x1024x1024. When the values of integer option settings are output,
+values which are an exact multiple of 1024 or 1024x1024 are sometimes, but not
+always, printed using the letters K and M. The printing style is independent of
+the actual input format that was used.
-6.13 Octal integer values
+6.14 Octal integer values
-------------------------
If an option's type is given as "octal integer", its value is always
Such options are always output in octal.
-6.14 Fixed point numbers
+6.15 Fixed point numbers
------------------------
If an option's type is given as "fixed-point", its value must be a decimal
integer, optionally followed by a decimal point and up to three further digits.
-6.15 Time intervals
+6.16 Time intervals
-------------------
A time interval is specified as a sequence of numbers, each followed by one of
is perfectly acceptable, for example, to specify "90m" instead of "1h30m".
-6.16 String values
+6.17 String values
------------------
If an option's type is specified as "string", the value can be specified with
and examples that apparently quote unnecessarily.
-6.17 Expanded strings
+6.18 Expanded strings
---------------------
Some strings in the configuration file are subjected to string expansion, by
configuration string.
-6.18 User and group names
+6.19 User and group names
-------------------------
User and group names are specified as strings, using the syntax described
getpwnam() or getgrnam() function, as appropriate.
-6.19 List construction
+6.20 List construction
----------------------
The data for some configuration options is a list of items, with colon as the
kinds of interpretation, as described in chapter 10.
In all these cases, the entire list is treated as a single string as far as the
-input syntax is concerned. The trusted_users setting in section 6.16 above is
+input syntax is concerned. The trusted_users setting in section 6.17 above is
an example. If a colon is actually needed in an item in a list, it must be
entered as two colons. Leading and trailing white space on each item in a list
is ignored. This makes it possible to include items that start with a colon,
interpreted as the two items 127.0.0.1:: and 1.
-6.20 Changing list separators
+6.21 Changing list separators
-----------------------------
Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
enclosing an empty list item.
-6.21 Empty items in lists
+6.22 Empty items in lists
-------------------------
An empty item at the end of a list is always ignored. In other words, trailing
is at the end of the list.
-6.22 Format of driver configurations
+6.23 Format of driver configurations
------------------------------------
There are separate parts in the configuration for defining routers, transports,
all in the default configuration.
-7.1 Main configuration settings
+7.1 Macros
+----------
+
+All macros should be defined before any options.
+
+One macro is specified, but commented out, in the default configuration:
+
+# ROUTER_SMARTHOST=MAIL.HOSTNAME.FOR.CENTRAL.SERVER.EXAMPLE
+
+If all off-site mail is expected to be delivered to a "smarthost", then set the
+hostname here and uncomment the macro. This will affect which router is used
+later on. If this is left commented out, then Exim will perform direct-to-MX
+deliveries using a dnslookup router.
+
+In addition to macros defined here, Exim includes a number of built-in macros
+to enable configuration to be guarded by a binary built with support for a
+given feature. See section 6.9 for more details.
+
+
+7.2 Main configuration settings
-------------------------------
-The main (global) configuration option settings must always come first in the
-file. The first thing you'll see in the file, after some initial comments, is
-the line
+The main (global) configuration option settings section must always come first
+in the file, after the macros. The first thing you'll see in the file, after
+some initial comments, is the line
# primary_hostname =
These are example settings that can be used when Exim is compiled with the
content-scanning extension. The first specifies the interface to the virus
scanner, and the second specifies the interface to SpamAssassin. Further
-details are given in chapter 43.
+details are given in chapter 44.
Three more commented-out option settings follow:
These are example settings that can be used when Exim is compiled with support
for TLS (aka SSL) as described in section 4.7. The first one specifies the list
of clients that are allowed to use TLS when connecting to this server; in this
-case the wildcard means all clients. The other options specify where Exim
+case, the wildcard means all clients. The other options specify where Exim
should find its TLS certificate and private key, which together prove the
server's identity to any clients that connect. More details are given in
-chapter 41.
+chapter 42.
Another two commented-out option settings follow:
These options provide better support for roaming users who wish to use this
server for message submission. They are not much use unless you have turned on
TLS (as described in the previous paragraph) and authentication (about which
-more in section 7.7). The usual SMTP port 25 is often blocked on end-user
-networks, so RFC 4409 specifies that message submission should use port 587
-instead. However some software (notably Microsoft Outlook) cannot be configured
-to use port 587 correctly, so these settings also enable the non-standard
-"smtps" (aka "ssmtp") port 465 (see section 13.4).
+more in section 7.8). Mail submission from mail clients (MUAs) should be
+separate from inbound mail to your domain (MX delivery) for various good
+reasons (eg, ability to impose much saner TLS protocol and ciphersuite
+requirements without unintended consequences). RFC 6409 (previously 4409)
+specifies use of port 587 for SMTP Submission, which uses STARTTLS, so this is
+the "submission" port. RFC 8314 specifies use of port 465 as the "submissions"
+protocol, which should be used in preference to 587. You should also consider
+deploying SRV records to help clients find these ports. Older names for
+"submissions" are "smtps" and "ssmtp".
Two more commented-out options settings follow:
If you have hosts for which you trust RFC1413 and need this information, you
can change this.
-This line enables an efficiency SMTP option. It is negociated by clients and
+This line enables an efficiency SMTP option. It is negotiated by clients and
not expected to cause problems but can be disabled if needed.
prdr_enable = true
show how you can specify hosts that are permitted to send unqualified sender
and recipient addresses, respectively.
+The log_selector option is used to increase the detail of logging over the
+default:
+
+log_selector = +smtp_protocol_error +smtp_syntax_error \
+ +tls_certificate_verified
+
The percent_hack_domains option is also commented out:
# percent_hack_domains =
is an almost obsolete form of explicit email routing. If you do not know
anything about it, you can safely ignore this topic.
-The last two settings in the main part of the default configuration are
+The next two settings in the main part of the default configuration are
concerned with messages that have been "frozen" on Exim's queue. When a message
is frozen, Exim no longer continues to try to deliver it. Freezing occurs when
a bounce message encounters a permanent failure because the sender address of
timeout_frozen_after = 7d
The first of these options specifies that failing bounce messages are to be
-discarded after 2 days on the queue. The second specifies that any frozen
+discarded after 2 days in the queue. The second specifies that any frozen
message (whether a bounce message or not) is to be timed out (and discarded)
after a week. In this configuration, the first setting ensures that no failing
bounce message ever lasts a week.
+Exim queues it's messages in a spool directory. If you expect to have large
+queues, you may consider using this option. It splits the spool directory into
+subdirectories to avoid file system degradation from many files in a single
+directory, resulting in better performance. Manual manipulation of queued
+messages becomes more complex (though fortunately not often needed).
+
+# split_spool_directory = true
+
+In an ideal world everybody follows the standards. For non-ASCII messages RFC
+2047 is a standard, allowing a maximum line length of 76 characters. Exim
+adheres that standard and won't process messages which violate this standard.
+(Even ${rfc2047:...} expansions will fail.) In particular, the Exim maintainers
+have had multiple reports of problems from Russian administrators of issues
+until they disable this check, because of some popular, yet buggy, mail
+composition software.
+
+# check_rfc2047_length = false
-7.2 ACL configuration
+If you need to be strictly RFC compliant you may wish to disable the 8BITMIME
+advertisement. Use this, if you exchange mails with systems that are not 8-bit
+clean.
+
+# accept_8bitmime = false
+
+Libraries you use may depend on specific environment settings. This imposes a
+security risk (e.g. PATH). There are two lists: keep_environment for the
+variables to import as they are, and add_environment for variables we want to
+set to a fixed value. Note that TZ is handled separately, by the $%timezone%$
+runtime option and by the TIMEZONE_DEFAULT buildtime option.
+
+# keep_environment = ^LDAP
+# add_environment = PATH=/usr/bin::/bin
+
+
+7.3 ACL configuration
---------------------
In the default configuration, the ACL section follows the main configuration.
convention of local parts constructed as "
first-initial.second-initial.family-name" when applied to someone like the
author of Exim, who has no second initial.) However, a local part starting with
-a dot or containing "/../" can cause trouble if it is used as part of a file
-name (for example, for a mailing list). This is also true for local parts that
-contain slashes. A pipe symbol can also be troublesome if the local part is
-incorporated unthinkingly into a shell command line.
+a dot or containing "/../" can cause trouble if it is used as part of a
+filename (for example, for a mailing list). This is also true for local parts
+that contain slashes. A pipe symbol can also be troublesome if the local part
+is incorporated unthinkingly into a shell command line.
The second rule above applies to all other domains, and is less strict. This
allows your own users to send outgoing messages to sites that use slashes and
address is refused. Verification consists of trying to route the address, to
see if a bounce message could be delivered to it. In the case of remote
addresses, basic verification checks only the domain, but callouts can be used
-for more verification if required. Section 42.44 discusses the details of
+for more verification if required. Section 43.44 discusses the details of
address verification.
accept hosts = +relay_from_hosts
verification is omitted here, because in many cases the clients are dumb MUAs
that do not cope well with SMTP error responses. For the same reason, the
second line specifies "submission mode" for messages that are accepted. This is
-described in detail in section 46.1; it causes Exim to fix messages that are
+described in detail in section 47.1; it causes Exim to fix messages that are
deficient in some way, for example, because they lack a Date: header line. If
you are actually relaying out from MTAs, you should probably add recipient
verification here, and disable submission mode.
Submission mode is again specified, on the grounds that such messages are most
likely to come from MUAs. The default configuration does not define any
authenticators, though it does include some nearly complete commented-out
-examples described in 7.7. This means that no client can in fact authenticate
+examples described in 7.8. This means that no client can in fact authenticate
until you complete the authenticator definitions.
require message = relay not permitted
This final line in the DATA ACL accepts the message unconditionally.
-7.3 Router configuration
+7.4 Router configuration
------------------------
The router configuration comes next in the default configuration, introduced by
begin routers
Routers are the modules in Exim that make decisions about where to send
-messages. An address is passed to each router in turn, until it is either
+messages. An address is passed to each router, in turn, until it is either
accepted, or failed. This means that the order in which you define the routers
matters. Each router is fully described in its own chapter later in this
manual. Here we give only brief overviews.
uncomment this router, you also need to uncomment the setting of
allow_domain_literals in the main part of the configuration.
+Which router is used next depends upon whether or not the ROUTER_SMARTHOST
+macro has been defined, per
+
+.ifdef ROUTER_SMARTHOST
+smarthost:
+#...
+.else
dnslookup:
- driver = dnslookup
+#...
+.endif
+
+If ROUTER_SMARTHOST has been defined, either at the top of the file or on the
+command-line, then we route all non-local mail to that smarthost; otherwise,
+we'll perform DNS lookups for direct-to-MX lookup. Any mail which is to a local
+domain will skip these routers because of the domains option.
+
+smarthost:
+ driver = manualroute
domains = ! +local_domains
- transport = remote_smtp
- ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
+ transport = smarthost_smtp
+ route_data = ROUTER_SMARTHOST
+ ignore_target_hosts = <; 0.0.0.0 ; 127.0.0.0/8 ; ::1
no_more
-The first uncommented router handles addresses that do not involve any local
-domains. This is specified by the line
+This router only handles mail which is not to any local domains; this is
+specified by the line
domains = ! +local_domains
it is referring to a named list. Addresses in other domains are passed on to
the following routers.
+The name of the router driver is manualroute because we are manually specifying
+how mail should be routed onwards, instead of using DNS MX. While the name of
+this router instance is arbitrary, the driver option must be one of the driver
+modules that is in the Exim binary.
+
+With no pre-conditions other than domains, all mail for non-local domains will
+be handled by this router, and the no_more setting will ensure that no other
+routers will be used for messages matching the pre-conditions. See 3.12 for
+more on how the pre-conditions apply. For messages which are handled by this
+router, we provide a hostname to deliver to in route_data and the macro
+supplies the value; the address is then queued for the smarthost_smtp
+transport.
+
+dnslookup:
+ driver = dnslookup
+ domains = ! +local_domains
+ transport = remote_smtp
+ ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
+ no_more
+
+The domains option behaves as per smarthost, above.
+
The name of the router driver is dnslookup, and is specified by the driver
option. Do not be confused by the fact that the name of this router instance is
the same as the name of the driver. The instance name is arbitrary, but the
same purpose as they do for the userforward router.
-7.4 Transport configuration
+7.5 Transport configuration
---------------------------
Transports define mechanisms for actually delivering messages. They operate
begin transports
-One remote transport and four local transports are defined.
+Two remote transports and four local transports are defined.
remote_smtp:
driver = smtp
+ message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}}
+.ifdef _HAVE_DANE
+ dnssec_request_domains = *
+ hosts_try_dane = *
+.endif
+.ifdef _HAVE_PRDR
hosts_try_prdr = *
+.endif
This transport is used for delivering messages over SMTP connections. The list
-of remote hosts comes from the router. The hosts_try_prdr option enables an
-efficiency SMTP option. It is negotiated between client and server and not
-expected to cause problems but can be disabled if needed. All other options are
-defaulted.
+of remote hosts comes from the router. The message_size_limit usage is a hack
+to avoid sending on messages with over-long lines. The built-in macro
+_HAVE_DANE guards configuration to try to use DNSSEC for all queries and to use
+DANE for delivery; see section 42.15 for more details.
+
+The hosts_try_prdr option enables an efficiency SMTP option. It is negotiated
+between client and server and not expected to cause problems but can be
+disabled if needed. The built-in macro _HAVE_PRDR guards the use of the
+hosts_try_prdr configuration option.
+
+The other remote transport is used when delivering to a specific smarthost with
+whom there must be some kind of existing relationship, instead of the usual
+federated system.
+
+smarthost_smtp:
+ driver = smtp
+ message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}}
+ multi_domain
+ #
+.ifdef _HAVE_TLS
+ # Comment out any of these which you have to, then file a Support
+ # request with your smarthost provider to get things fixed:
+ hosts_require_tls = *
+ tls_verify_hosts = *
+ # As long as tls_verify_hosts is enabled, this won't matter, but if you
+ # have to comment it out then this will at least log whether you succeed
+ # or not:
+ tls_try_verify_hosts = *
+ #
+ # The SNI name should match the name which we'll expect to verify;
+ # many mail systems don't use SNI and this doesn't matter, but if it does,
+ # we need to send a name which the remote site will recognize.
+ # This _should_ be the name which the smarthost operators specified as
+ # the hostname for sending your mail to.
+ tls_sni = ROUTER_SMARTHOST
+ #
+.ifdef _HAVE_OPENSSL
+ tls_require_ciphers = HIGH:!aNULL:@STRENGTH
+.endif
+.ifdef _HAVE_GNUTLS
+ tls_require_ciphers = SECURE192:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1
+.endif
+.endif
+.ifdef _HAVE_PRDR
+ hosts_try_prdr = *
+.endif
+
+After the same message_size_limit hack, we then specify that this Transport can
+handle messages to multiple domains in one run. The assumption here is that
+you're routing all non-local mail to the same place and that place is happy to
+take all messages from you as quickly as possible. All other options depend
+upon built-in macros; if Exim was built without TLS support then no other
+options are defined. If TLS is available, then we configure "stronger than
+default" TLS ciphersuites and versions using the tls_require_ciphers option,
+where the value to be used depends upon the library providing TLS. Beyond that,
+the options adopt the stance that you should have TLS support available from
+your smarthost on today's Internet, so we turn on requiring TLS for the mail to
+be delivered, and requiring that the certificate be valid, and match the
+expected hostname. The tls_sni option can be used by service providers to
+select an appropriate certificate to present to you and here we re-use the
+ROUTER_SMARTHOST macro, because that is unaffected by CNAMEs present in DNS.
+You want to specify the hostname which you'll expect to validate for, and that
+should not be subject to insecure tampering via DNS results.
+
+For the hosts_try_prdr option see the previous transport.
+
+All other options are defaulted.
local_delivery:
driver = appendfile
This transport is used for handling deliveries to pipes that are generated by
redirection (aliasing or users' .forward files). The return_output option
-specifies that any output generated by the pipe is to be returned to the
-sender.
+specifies that any output on stdout or stderr generated by the pipe is to be
+returned to the sender.
address_file:
driver = appendfile
filter files.
-7.5 Default retry rule
+7.6 Default retry rule
----------------------
The retry section of the configuration file contains rules which affect the way
This causes any temporarily failing address to be retried every 15 minutes for
2 hours, then at intervals starting at one hour and increasing by a factor of
1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
-is not delivered after 4 days of temporary failure, it is bounced.
+is not delivered after 4 days of temporary failure, it is bounced. The time is
+measured from first failure, not from the time the message was received.
If the retry section is removed from the configuration, or is empty (that is,
if no retry rules are defined), Exim will not retry deliveries. This turns
temporary errors into permanent errors.
-7.6 Rewriting configuration
+7.7 Rewriting configuration
---------------------------
The rewriting section of the configuration, introduced by
rewriting rules in the default configuration file.
-7.7 Authenticators configuration
+7.8 Authenticators configuration
--------------------------------
The authenticators section of the configuration, introduced by
LOGIN. The server_advertise_condition setting controls when Exim offers
authentication to clients; in the examples, this is only when TLS or SSL has
been started, so to enable the authenticators you also need to add support for
-TLS as described in section 7.1.
+TLS as described in section 7.2.
The server_condition setting defines how to verify that the username and
password are correct. In the examples it just produces an error message. To
Exim supports the use of regular expressions in many of its options. It uses
the PCRE regular expression library; this provides regular expression matching
that is compatible with Perl 5. The syntax and semantics of regular expressions
-is discussed in many Perl reference books, and also in Jeffrey Friedl's
-Mastering Regular Expressions, which is published by O'Reilly (see http://
-www.oreilly.com/catalog/regex2/).
+is discussed in online Perl manpages, in many Perl reference books, and also in
+Jeffrey Friedl's Mastering Regular Expressions, which is published by O'Reilly
+(see http://www.oreilly.com/catalog/regex2/).
The documentation for the syntax and semantics of the regular expressions that
are supported by PCRE is included in the PCRE distribution, and no further
cause parts of the string to be replaced by data that is obtained from the
lookup. Lookups of this type are conditional expansion items. Different
results can be defined for the cases of lookup success and failure. See
- chapter 11, where string expansions are described in detail.
+ chapter 11, where string expansions are described in detail. The key for
+ the lookup is specified as part of the string expansion.
2. Lists of domains, hosts, and email addresses can contain lookup requests as
a way of avoiding excessively long linear lists. In this case, the data
that is returned by the lookup is often (but not always) discarded; whether
the lookup succeeds or fails is what really counts. These kinds of list are
- described in chapter 10.
+ described in chapter 10. The key for the lookup is given by the context in
+ which the list is expanded.
String expansions, lists, and lookups interact with each other in such a way
that there is no order in which to describe any one of them that does not
indexed files that are read frequently and never updated, except by total
re-creation. As such, it is particularly suitable for large files
containing aliases or other indexed data referenced by an MTA. Information
- about cdb can be found in several places:
+ about cdb and tools for building the files can be found in several places:
- http://www.pobox.com/~djb/cdb.html
- ftp://ftp.corpit.ru/pub/tinycdb/
- http://packages.debian.org/stable/utils/freecdb.html
+ https://cr.yp.to/cdb.html
+ http://www.corpit.ru/mjt/tinycdb.html
+ https://packages.debian.org/stable/utils/freecdb
+ https://github.com/philpennock/cdbtools (in Go)
A cdb distribution is not needed in order to build Exim with cdb support,
because the code for reading cdb files is included directly in Exim itself.
incoming SMTP calls using the passwords from Courier's /etc/
userdbshadow.dat file. Exim's utility program for creating DBM files (
exim_dbmbuild) includes the zeros by default, but has an option to omit
- them (see section 52.9).
+ them (see section 53.9).
* dsearch: The given file must be a directory; this is searched for an entry
whose name is the key by calling the lstat() function. The key may not
contain any forward slash characters. If lstat() succeeds, the result of
the lookup is the name of the entry, which may be a file, directory,
symbolic link, or any other kind of directory entry. An example of how this
- lookup can be used to support virtual domains is given in section 49.7.
+ lookup can be used to support virtual domains is given in section 50.7.
* iplsearch: The given file is a text file containing keys and data. A key is
terminated by a colon or white space or the end of the line. The keys in
characters, or white space. However, if you need this feature, it is
available. If a key begins with a doublequote character, it is terminated
only by a matching quote (or end of line), and the normal escaping rules
- apply to its contents (see section 6.16). An optional colon is permitted
+ apply to its contents (see section 6.17). An optional colon is permitted
after quoted keys (exactly as for unquoted keys). There is no special
handling of quotes for the data part of an lsearch line.
wildlsearch can not be turned into a DBM or cdb file, because those lookup
types support only literal keys.
+ * If Exim is built with SPF support, manual lookups can be done (as opposed
+ to the standard ACL condition method. For details see section 57.4.
+
9.4 Query-style lookup types
----------------------------
returns attributes from a single entry. There is a variant called ldapm
that permits values from multiple entries to be returned. A third variant
called ldapdn returns the Distinguished Name of a single entry instead of
- any attribute values. See section 9.13.
+ any attribute values. See section 9.14.
* mysql: The format of the query is an SQL statement that is passed to a
- MySQL database. See section 9.20.
+ MySQL database. See section 9.21.
* nisplus: This does a NIS+ lookup using a query that can specify the name of
- the field to be returned. See section 9.19.
+ the field to be returned. See section 9.20.
* oracle: The format of the query is an SQL statement that is passed to an
- Oracle database. See section 9.20.
+ Oracle database. See section 9.21.
* passwd is a query-style lookup with queries that are just user names. The
lookup calls getpwnam() to interrogate the system password data, and on
*:42:42:King Rat:/home/kr:/bin/bash
* pgsql: The format of the query is an SQL statement that is passed to a
- PostgreSQL database. See section 9.20.
+ PostgreSQL database. See section 9.21.
+
+ * redis: The format of the query is either a simple get or simple set, passed
+ to a Redis database. See section 9.21.
- * sqlite: The format of the query is a file name followed by an SQL statement
- that is passed to an SQLite database. See section 9.25.
+ * sqlite: The format of the query is a filename followed by an SQL statement
+ that is passed to an SQLite database. See section 9.26.
* testdb: This is a lookup type that is used for testing Exim. It is not
likely to be useful in normal operation.
keyword causes a forced expansion failure - see section 11.4 for an explanation
of what this means.
-The supported DNS record types are A, CNAME, MX, NS, PTR, SPF, SRV, TLSA and
-TXT, and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
-configured). If no type is given, TXT is assumed. When the type is PTR, the
-data can be an IP address, written as normal; inversion and the addition of
-in-addr.arpa or ip6.arpa happens automatically. For example:
-
-${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
-
-If the data for a PTR record is not a syntactically valid IP address, it is not
-altered and nothing is added.
-
-For an MX lookup, both the preference value and the host name are returned for
-each record, separated by a space. For an SRV lookup, the priority, weight,
-port, and host name are returned for each record, separated by spaces.
+The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA
+and TXT, and, when Exim is compiled with IPv6 support, AAAA. If no type is
+given, TXT is assumed.
-For any record type, if multiple records are found (or, for A6 lookups, if a
-single record leads to multiple addresses), the data is returned as a
+For any record type, if multiple records are found, the data is returned as a
concatenation, with newline as the default separator. The order, of course,
depends on the DNS resolver. You can specify a different separator character
between multiple records by putting a right angle-bracket followed immediately
${lookup dnsdb{>: a=host1.example}}
It is permitted to specify a space as the separator character. Further white
-space is ignored.
+space is ignored. For lookup types that return multiple fields per record, an
+alternate field separator can be specified using a comma after the main
+separator character, followed immediately by the field separator.
+
+When the type is PTR, the data can be an IP address, written as normal;
+inversion and the addition of in-addr.arpa or ip6.arpa happens automatically.
+For example:
+
+${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
+
+If the data for a PTR record is not a syntactically valid IP address, it is not
+altered and nothing is added.
+
+For an MX lookup, both the preference value and the host name are returned for
+each record, separated by a space. For an SRV lookup, the priority, weight,
+port, and host name are returned for each record, separated by spaces. The
+field separator can be modified as above.
For TXT records with multiple items of data, only the first item is returned,
-unless a separator for them is specified using a comma after the separator
-character followed immediately by the TXT record item separator. To concatenate
-items without a separator, use a semicolon instead. For SPF records the default
-behaviour is to concatenate multiple items without using a separator.
+unless a field separator is specified. To concatenate items without a
+separator, use a semicolon instead. For SPF records the default behaviour is to
+concatenate multiple items without using a separator.
${lookup dnsdb{>\n,: txt=a.b.example}}
${lookup dnsdb{>\n; txt=a.b.example}}
It is permitted to specify a space as the separator character. Further white
space is ignored.
+For an SOA lookup, while no result is obtained the lookup is redone with
+successively more leading components dropped from the given domain. Only the
+primary-nameserver field is returned unless a field separator is specified.
+
+${lookup dnsdb{>:,; soa=a.b.example.com}}
+
+
+9.11 Dnsdb lookup modifiers
+---------------------------
+
+Modifiers for dnsdb lookups are given by optional keywords, each followed by a
+comma, that may appear before the record type.
+
+The dnsdb lookup fails only if all the DNS lookups fail. If there is a
+temporary DNS error for any of them, the behaviour is controlled by a
+defer-option modifier. The possible keywords are "defer_strict", "defer_never",
+and "defer_lax". With "strict" behaviour, any temporary DNS error causes the
+whole lookup to defer. With "never" behaviour, a temporary DNS error is
+ignored, and the behaviour is as if the DNS lookup failed to find anything.
+With "lax" behaviour, all the queries are attempted, but a temporary DNS error
+causes the whole lookup to defer only if none of the other lookups succeed. The
+default is "lax", so the following lookups are equivalent:
+
+${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
+${lookup dnsdb{a=one.host.com:two.host.com}}
+
+Thus, in the default case, as long as at least one of the DNS lookups yields
+some data, the lookup succeeds.
+
+Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are
+"dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax"
+DNSSEC information is requested with the lookup. With "strict" a response from
+the DNS resolver that is not labelled as authenticated data is treated as
+equivalent to a temporary DNS error. The default is "never".
+
+See also the $lookup_dnssec_authenticated variable.
+
+Timeout for the dnsdb lookup can be controlled by a retrans modifier. The form
+is "retrans_VAL" where VAL is an Exim time specification (e.g. "5s"). The
+default value is set by the main configuration option dns_retrans.
-9.11 Pseudo dnsdb record types
+Retries for the dnsdb lookup can be controlled by a retry modifier. The form if
+"retry_VAL" where VAL is an integer. The default count is set by the main
+configuration option dns_retry.
+
+Dnsdb lookup results are cached within a single process (and its children). The
+cache entry lifetime is limited to the smallest time-to-live (TTL) value of the
+set of returned DNS records.
+
+
+9.12 Pseudo dnsdb record types
------------------------------
By default, both the preference value and the host name are returned for each
list.
A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV
-records according to the CSA rules, which are described in section 42.50.
+records according to the CSA rules, which are described in section 43.50.
Although dnsdb supports SRV lookups directly, this is not sufficient because of
the extra parent domain search behaviour of CSA. The result of a successful
lookup such as:
The authorization code can be "Y" for yes, "N" for no, "X" for explicit
authorization required but absent, or "?" for unknown.
-The pseudo-type A+ performs an A6 lookup (if configured) followed by an AAAA
-and then an A lookup. All results are returned; defer processing (see below) is
-handled separately for each lookup. Example:
+The pseudo-type A+ performs an AAAA and then an A lookup. All results are
+returned; defer processing (see below) is handled separately for each lookup.
+Example:
${lookup dnsdb {>; a+=$sender_helo_name}}
-9.12 Multiple dnsdb lookups
+9.13 Multiple dnsdb lookups
---------------------------
In the previous sections, dnsdb lookups for a single domain are described.
in the same way that multiple DNS records for a single item are handled. A
different separator can be specified, as described above.
-Modifiers for dnsdb lookups are givien by optional keywords, each followed by a
-comma, that may appear before the record type.
-
-The dnsdb lookup fails only if all the DNS lookups fail. If there is a
-temporary DNS error for any of them, the behaviour is controlled by a
-defer-option modifier. The possible keywords are "defer_strict", "defer_never",
-and "defer_lax". With "strict" behaviour, any temporary DNS error causes the
-whole lookup to defer. With "never" behaviour, a temporary DNS error is
-ignored, and the behaviour is as if the DNS lookup failed to find anything.
-With "lax" behaviour, all the queries are attempted, but a temporary DNS error
-causes the whole lookup to defer only if none of the other lookups succeed. The
-default is "lax", so the following lookups are equivalent:
-
-${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
-${lookup dnsdb{a=one.host.com:two.host.com}}
-
-Thus, in the default case, as long as at least one of the DNS lookups yields
-some data, the lookup succeeds.
-
-Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are
-"dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax"
-DNSSEC information is requested with the lookup. With "strict" a response from
-the DNS resolver that is not labelled as authenticated data is treated as
-equivalent to a temporary DNS error. The default is "never".
-
-See also the $lookup_dnssec_authenticated variable.
-
-9.13 More about LDAP
+9.14 More about LDAP
--------------------
The original LDAP implementation came from the University of Michigan; this has
explain how LDAP queries are coded.
-9.14 Format of LDAP queries
+9.15 Format of LDAP queries
---------------------------
An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
optional, only taking effect if not specifically set in exim.conf.
-9.15 LDAP quoting
+9.16 LDAP quoting
-----------------
Two levels of quoting are required in LDAP queries, the first for LDAP itself
authentication below.
-9.16 LDAP connections
+9.17 LDAP connections
---------------------
The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
ldap_default_servers, does whatever the library does by default.
-9.17 LDAP authentication and control information
+9.18 LDAP authentication and control information
------------------------------------------------
The LDAP URL syntax provides no way of passing authentication and other control
server-side limit on the time taken to complete a search.
The SERVERS parameter allows you to specify an alternate list of ldap servers
-to use for an individual lookup. The global ldap_servers option provides a
-default list of ldap servers, and a single lookup can specify a single ldap
-server to use. But when you need to do a lookup with a list of servers that is
-different than the default list (maybe different order, maybe a completely
-different set of servers), the SERVERS parameter allows you to specify this
-alternate list.
+to use for an individual lookup. The global ldap_default_servers option
+provides a default list of ldap servers, and a single lookup can specify a
+single ldap server to use. But when you need to do a lookup with a list of
+servers that is different than the default list (maybe different order, maybe a
+completely different set of servers), the SERVERS parameter allows you to
+specify this alternate list (colon-separated).
Here is an example of an LDAP query in an Exim lookup that uses some of these
values. This is a single line, folded to fit on the page:
SMTP authentication. See the ldapauth expansion string condition in chapter 11.
-9.18 Format of data returned by LDAP
+9.19 Format of data returned by LDAP
------------------------------------
The ldapdn lookup type returns the Distinguished Name from a single entry as a
sequence of values, for example
-cn=manager, o=University of Cambridge, c=UK
+cn=manager,o=University of Cambridge,c=UK
The ldap lookup type generates an error if more than one entry matches the
search filter, whereas ldapm permits this case, and inserts a newline in the
In the common case where you specify a single attribute in your LDAP query, the
result is not quoted, and does not contain the attribute name. If the attribute
-has multiple values, they are separated by commas.
+has multiple values, they are separated by commas. Any comma that is part of an
+attribute's value is doubled.
If you specify multiple attributes, the result contains space-separated, quoted
strings, each preceded by the attribute name and an equals sign. Within the
quotes, the quote character, backslash, and newline are escaped with
backslashes, and commas are used to separate multiple values for the attribute.
-Apart from the escaping, the string within quotes takes the same form as the
-output when a single attribute is requested. Specifying no attributes is the
-same as specifying all of an entry's attributes.
+Any commas in attribute values are doubled (permitting treatment of the values
+as a comma-separated list). Apart from the escaping, the string within quotes
+takes the same form as the output when a single attribute is requested.
+Specifying no attributes is the same as specifying all of an entry's
+attributes.
Here are some examples of the output format. The first line of each pair is an
LDAP query, and the second is the data that is returned. The attribute called
-attr1 has two values, whereas attr2 has only one value:
+attr1 has two values, one of them with an embedded comma, whereas attr2 has
+only one value. Both attributes are derived from attr (they have SUP attr in
+their schema definitions).
ldap:///o=base?attr1?sub?(uid=fred)
-value1.1, value1.2
+value1.1,value1,,2
ldap:///o=base?attr2?sub?(uid=fred)
value two
+ldap:///o=base?attr?sub?(uid=fred)
+value1.1,value1,,2,value two
+
ldap:///o=base?attr1,attr2?sub?(uid=fred)
-attr1="value1.1, value1.2" attr2="value two"
+attr1="value1.1,value1,,2" attr2="value two"
ldap:///o=base??sub?(uid=fred)
-objectClass="top" attr1="value1.1, value1.2" attr2="value two"
+objectClass="top" attr1="value1.1,value1,,2" attr2="value two"
-The extract operator in string expansions can be used to pick out individual
-fields from data that consists of key=value pairs. You can make use of Exim's
--be option to run expansion tests and thereby check the results of LDAP
-lookups.
+You can make use of Exim's -be option to run expansion tests and thereby check
+the results of LDAP lookups. The extract operator in string expansions can be
+used to pick out individual fields from data that consists of key=value pairs.
+The listextract operator should be used to pick out individual values of
+attributes, even when only a single value is expected. The doubling of embedded
+commas allows you to use the returned data as a comma separated list (using the
+"<," syntax for changing the input list separator).
-9.19 More about NIS+
+9.20 More about NIS+
--------------------
NIS+ queries consist of a NIS+ indexed name followed by an optional colon and
is to double any quote characters within the text.
-9.20 SQL lookups
+9.21 SQL lookups
----------------
-Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite
-databases. Queries for these databases contain SQL statements, so an example
-might be
+Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, Redis, and
+SQLite databases. Queries for these databases contain SQL statements, so an
+example might be
${lookup mysql{select mailbox from users where id='userx'}\
{$value}fail}
with a newline between the data for each row.
-9.21 More about MySQL, PostgreSQL, Oracle, and InterBase
---------------------------------------------------------
+9.22 More about MySQL, PostgreSQL, Oracle, InterBase, and Redis
+---------------------------------------------------------------
-If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the
-mysql_servers, pgsql_servers, oracle_servers, or ibase_servers option (as
-appropriate) must be set to a colon-separated list of server information. (For
-MySQL and PostgreSQL only, the global option need not be set if all queries
-contain their own server information - see section 9.22.) Each item in the list
-is a slash-separated list of four items: host name, database name, user name,
-and password. In the case of Oracle, the host name field is used for the
-"service name", and the database name field is not used and should be empty.
-For example:
+If any MySQL, PostgreSQL, Oracle, InterBase or Redis lookups are used, the
+mysql_servers, pgsql_servers, oracle_servers, ibase_servers, or redis_servers
+option (as appropriate) must be set to a colon-separated list of server
+information. (For MySQL and PostgreSQL, the global option need not be set if
+all queries contain their own server information - see section 9.23.) For all
+but Redis each item in the list is a slash-separated list of four items: host
+name, database name, user name, and password. In the case of Oracle, the host
+name field is used for the "service name", and the database name field is not
+used and should be empty. For example:
hide oracle_servers = oracle.plc.example//userx/abcdwxyz
found, but that is still a successful query. In other words, the list of
servers provides a backup facility, not a list of different places to look.
+For Redis the global option need not be specified if all queries contain their
+own server information - see section 9.23. If specified, the option must be set
+to a colon-separated list of server information. Each item in the list is a
+slash-separated list of three items: host, database number, and password.
+
+ 1. The host is required and may be either an IPv4 address and optional port
+ number (separated by a colon, which needs doubling due to the higher-level
+ list), or a Unix socket pathname enclosed in parentheses
+
+ 2. The database number is optional; if present that number is selected in the
+ backend
+
+ 3. The password is optional; if present it is used to authenticate to the
+ backend
+
The quote_mysql, quote_pgsql, and quote_oracle expansion operators convert
newline, tab, carriage return, and backspace to \n, \t, \r, and \b
respectively, and the characters single-quote, double-quote, and backslash
-itself are escaped with backslashes. The quote_pgsql expansion operator, in
-addition, escapes the percent and underscore characters. This cannot be done
-for MySQL because these escapes are not recognized in contexts where these
-characters are not special.
+itself are escaped with backslashes.
+The quote_redis expansion operator escapes whitespace and backslash characters
+with a backslash.
-9.22 Specifying the server in the query
+
+9.23 Specifying the server in the query
---------------------------------------
-For MySQL and PostgreSQL lookups (but not currently for Oracle and InterBase),
-it is possible to specify a list of servers with an individual query. This is
-done by starting the query with
+For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and
+InterBase), it is possible to specify a list of servers with an individual
+query. This is done by starting the query with
servers=server1:server2:server3:...;
${lookup pgsql{servers=master/db/name/pw; UPDATE ...} }
-9.23 Special MySQL features
+9.24 Special MySQL features
---------------------------
For MySQL, an empty host name or the use of "localhost" in mysql_servers causes
a connection to the server on the local host by means of a Unix domain socket.
-An alternate socket can be specified in parentheses. The full syntax of each
-item in mysql_servers is:
+An alternate socket can be specified in parentheses. An option group name for
+MySQL option files can be specified in square brackets; the default value is
+"exim". The full syntax of each item in mysql_servers is:
-<hostname>::<port>(<socket name>)/<database>/<user>/<password>
+<hostname>::<port>(<socket name>)
[<option group>]/<database>/<user>/<password>
-Any of the three sub-parts of the first field can be omitted. For normal use on
+Any of the four sub-parts of the first field can be omitted. For normal use on
the local host it can be left blank or set to just "localhost".
No database need be supplied - but if it is absent here, it must be given in
because no rows are affected.
-9.24 Special PostgreSQL features
+9.25 Special PostgreSQL features
--------------------------------
PostgreSQL lookups can also use Unix domain socket connections to the database.
affected.
-9.25 More about SQLite
+9.26 More about SQLite
----------------------
-SQLite is different to the other SQL lookups because a file name is required in
+SQLite is different to the other SQL lookups because a filename is required in
addition to the SQL query. An SQLite database is a single file, and there is no
daemon as in the other SQL databases. The interface to Exim requires the name
of the file, as an absolute path, to be given at the start of the query. It is
changed by means of the sqlite_lock_timeout option.
+9.27 More about Redis
+---------------------
+
+Redis is a non-SQL database. Commands are simple get and set. Examples:
+
+${lookup redis{set keyname ${quote_redis:objvalue plus}}}
+${lookup redis{get keyname}}
+
+As of release 4.91, "lightweight" support for Redis Cluster is available.
+Requires redis_servers list to contain all the servers in the cluster, all of
+which must be reachable from the running exim instance. If the cluster has
+master/slave replication, the list must contain all the master and slave
+servers.
+
+When the Redis Cluster returns a "MOVED" response to a query, Exim does not
+immediately follow the redirection but treats the response as a DEFER, moving
+on to the next server in the redis_servers list until the correct server is
+reached.
+
+
===============================================================================
10. DOMAIN, HOST, ADDRESS, AND LOCAL PART LISTS
A number of Exim configuration options contain lists of domains, hosts, email
addresses, or local parts. For example, the hold_domains option contains a list
of domains whose delivery is currently suspended. These lists are also used as
-data in ACL statements (see chapter 42), and as arguments to expansion
+data in ACL statements (see chapter 43), and as arguments to expansion
conditions such as match_domain.
Each item in one of these lists is a pattern to be matched against a domain,
different types of pattern for each case are described, but first we cover some
general facilities that apply to all four kinds of list.
+Note that other parts of Exim use a string list which does not support all the
+complexity available in domain, host, address and local part lists.
+
10.1 Expansion of lists
-----------------------
-Each list is expanded as a single string before it is used. The result of
-expansion must be a list, possibly containing empty items, which is split up
-into separate items for matching. By default, colon is the separator character,
-but this can be varied if necessary. See sections 6.19 and 6.21 for details of
-the list syntax; the second of these discusses the way to specify empty list
-items.
+Each list is expanded as a single string before it is used.
+
+Exception: the router headers_remove option, where list-item splitting is done
+before string-expansion.
+
+The result of expansion must be a list, possibly containing empty items, which
+is split up into separate items for matching. By default, colon is the
+separator character, but this can be varied if necessary. See sections 6.20 and
+6.22 for details of the list syntax; the second of these discusses the way to
+specify empty list items.
If the string expansion is forced to fail, Exim behaves as if the item it is
testing (domain, host, address, or local part) is not in the list. Other
10.3 File names in lists
------------------------
-If an item in a domain, host, address, or local part list is an absolute file
-name (beginning with a slash character), each line of the file is read and
+If an item in a domain, host, address, or local part list is an absolute
+filename (beginning with a slash character), each line of the file is read and
processed as if it were an independent item in the list, except that further
-file names are not allowed, and no expansion of the data from the file takes
+filenames are not allowed, and no expansion of the data from the file takes
place. Empty lines in the file are ignored, and the file may also contain
comment lines:
not#comment@x.y.z # but this is a comment
-Putting a file name in a list has the same effect as inserting each line of the
+Putting a filename in a list has the same effect as inserting each line of the
file as an item in the list (blank lines and comments excepted). However, there
is one important difference: the file is read each time the list is processed,
so if its contents vary over time, Exim's behaviour changes.
-If a file name is preceded by an exclamation mark, the sense of any match
-within the file is inverted. For example, if
+If a filename is preceded by an exclamation mark, the sense of any match within
+the file is inverted. For example, if
hold_domains = !/etc/nohold-domains
just as for any other single-key lookup type.
If you want to use a file to contain wild-card patterns that form part of a
-list, just give the file name on its own, without a search type, as described
-in the previous section. You could also use the wildlsearch or nwildlsearch,
-but there is no advantage in doing this.
+list, just give the filename on its own, without a search type, as described in
+the previous section. You could also use the wildlsearch or nwildlsearch, but
+there is no advantage in doing this.
10.5 Named lists
* If a pattern starts with the name of a single-key lookup type followed by a
semicolon (for example, "dbm;" or "lsearch;"), the remainder of the pattern
- must be a file name in a suitable format for the lookup type. For example,
+ must be a filename in a suitable format for the lookup type. For example,
for "cdb;" it must be an absolute path:
domains = cdb;/etc/mail/local_domains.cdb
accept hosts = 10.9.8.7
If the first accept fails, Exim goes on to try the second one. See chapter
- 42 for details of ACLs. Alternatively, you can use "+ignore_unknown", which
+ 43 for details of ACLs. Alternatively, you can use "+ignore_unknown", which
was discussed in depth in the first example in this section.
A temporary DNS lookup failure normally causes a defer action (except when
dns_again_means_nonexist converts it into a permanent error). However, host
-lists can include "+ignore_defer" and "+include_defer", analagous to
+lists can include "+ignore_defer" and "+include_defer", analogous to
"+ignore_unknown" and "+include_unknown", as described in the previous section.
These options should be used with care, probably only in non-critical host
lists such as whitelists.
The domain portion of an address is always lowercased before matching it to an
address list. The local part is lowercased by default, and any string
comparisons that take place are done caselessly. This means that the data in
-the address list itself, in files included as plain file names, and in any file
+the address list itself, in files included as plain filenames, and in any file
that is looked up using the "@@" mechanism, can be in any case. However, the
keys in files that are looked up by a search type other than lsearch (which
works caselessly) must be in lower case, because these lookups are not
===============================================================================
11. STRING EXPANSIONS
-Many strings in Exim's run time configuration are expanded before use. Some of
+Many strings in Exim's runtime configuration are expanded before use. Some of
them are expanded every time they are used; others are expanded only once.
When a string is being expanded it is copied verbatim from left to right except
character being treated specially in an expansion, including backslash itself.
If the string appears in quotes in the configuration file, two backslashes are
required because the quotes themselves cause interpretation of backslashes when
-the string is read in (see section 6.16).
+the string is read in (see section 6.17).
A portion of the string can specified as non-expandable by placing it between
two occurrences of "\N". This is particularly useful for protecting regular
If you want to test expansions that include variables whose values are taken
from a message, there are two other options that can be used. The -bem option
-is like -be except that it is followed by a file name. The file is read as a
+is like -be except that it is followed by a filename. The file is read as a
message before doing the test expansions. For example:
exim -bem /tmp/test.message '$h_subject:'
The name and zero to nine argument strings are first expanded separately.
The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
in order. Any unused are made empty. The variable $acl_narg is set to the
- number of arguments. The named ACL (see chapter 42) is called and may use
+ number of arguments. The named ACL (see chapter 43) is called and may use
the variables; if another acl expansion is used the values are restored
after it returns. If the ACL sets a value using a "message =" modifier and
returns accept or deny, the value becomes the result of the expansion. If
is an empty string. If the ACL returns defer the result is a forced-fail.
Otherwise the expansion fails.
+${authresults{<authserv-id>}}
+
+ This item returns a string suitable for insertion as an
+ Authentication-Results" header line. The given <authserv-id> is included in
+ the result; typically this will be a domain name identifying the system
+ performing the authentications. Methods that might be present in the result
+ include:
+
+ none
+ iprev
+ auth
+ spf
+ dkim
+
+ Example use (as an ACL modifier):
+
+ add_header = :at_start:${authresults {$primary_hostname}}
+
+ This is safe even if no authentication results are available.
+
${certextract{<field>}{<certificate>}{<string2>}{<string3>}}
The <certificate> must be a variable of type certificate. The field name is
- expanded and used to retrive the relevant field from the certificate.
+ expanded and used to retrieve the relevant field from the certificate.
Supported fields are:
version
The field selectors marked as "RFC4514" above output a Distinguished Name
string which is not quite parseable by Exim as a comma-separated tagged
- list (the exceptions being elements containin commas). RDN elements of a
+ list (the exceptions being elements containing commas). RDN elements of a
single type may be selected by a modifier of the type label; if so the
expansion result is a list (newline-separated by default). The separator
- may be changed by another modifer of a right angle-bracket followed
+ may be changed by another modifier of a right angle-bracket followed
immediately by the new separator. Recognised RDN type labels include "CN",
"O", "OU" and "DC".
- The field selectors marked as "time" above may output a number of seconds
- since epoch if the modifier "int" is used.
+ The field selectors marked as "time" above take an optional modifier of
+ "int" for which the result is the number of seconds since epoch. Otherwise
+ the result is a human-readable string in the timezone selected by the main
+ "timezone" option.
The field selectors marked as "list" above return a list, newline-separated
by default, (embedded separator characters in elements are doubled). The
The field selectors marked as "tagged" above prefix each list element with
a type string and an equals sign. Elements of only one type may be selected
- by a modifier which is one of "dns", "uri" or "mail"; if so the elenment
+ by a modifier which is one of "dns", "uri" or "mail"; if so the element
tags are omitted.
If not otherwise noted field values are presented in human-readable form.
to add -shared to the gcc command. Also, in the Exim build-time
configuration, you must add -export-dynamic to EXTRALIBS.
+${env{<key>}{<string1>}{<string2>}}
+
+ The key is first expanded separately, and leading and trailing white space
+ removed. This is then searched for as a name in the environment. If a
+ variable is found then its value is placed in $value and <string1> is
+ expanded, otherwise <string2> is expanded.
+
+ Instead of {<string2>} the word "fail" (not in curly brackets) can appear,
+ for example:
+
+ ${env{USER}{$value} fail }
+
+ This forces an expansion failure (see section 11.4); {<string1>} must be
+ present for "fail" to be recognized.
+
+ If {<string2>} is omitted an empty string is substituted on search failure.
+ If {<string1>} is omitted the search result is substituted on search
+ success.
+
+ The environment is adjusted by the keep_environment and add_environment
+ main section options.
+
${extract{<key>}{<string1>}{<string2>}{<string3>}}
The key and <string1> are first expanded separately. Leading and trailing
white space is removed from the key (but not from any of the strings). The
- key must not consist entirely of digits. The expanded <string1> must be of
- the form:
+ key must not be empty and must not consist entirely of digits. The expanded
+ <string1> must be of the form:
<key1> = <value1> <key2> = <value2> ...
where the equals signs and spaces (but not both) are optional. If any of
the values contain white space, they must be enclosed in double quotes, and
any values that are enclosed in double quotes are subject to escape
- processing as described in section 6.16. The expanded <string1> is searched
+ processing as described in section 6.17. The expanded <string1> is searched
for the value that corresponds to the key. The search is case-insensitive.
If the key is found, <string2> is expanded, and replaces the whole item;
otherwise <string3> is used. During the expansion of <string2> the variable
This forces an expansion failure (see section 11.4); {<string2>} must be
present for "fail" to be recognized.
+${extract json{<key>}{<string1>}{<string2>}{<string3>}}
+
+ The key and <string1> are first expanded separately. Leading and trailing
+ white space is removed from the key (but not from any of the strings). The
+ key must not be empty and must not consist entirely of digits. The expanded
+ <string1> must be of the form:
+
+ { <"key1"> : <value1> , <"key2"> , <value2> ... }
+
+ The braces, commas and colons, and the quoting of the member name are
+ required; the spaces are optional. Matching of the key against the member
+ names is done case-sensitively.
+
+ The results of matching are handled as above.
+
${extract{<number>}{<separators>}{<string1>}{<string2>}{<string3>}}
The <number> argument must consist entirely of decimal digits, apart from
yields "99". Two successive separators mean that the field between them is
empty (for example, the fifth field above).
+${extract json{<number>}}{<string1>}{<string2>}{<string3>}}
+
+ The <number> argument must consist entirely of decimal digits, apart from
+ leading and trailing white space, which is ignored.
+
+ Field selection and result handling is as above; there is no choice of
+ field separator.
+
${filter{<string>}{<condition>}}
After expansion, <string> is interpreted as a list, colon-separated by
- default, but the separator can be changed in the usual way. For each item
- in this list, its value is place in $item, and then the condition is
+ default, but the separator can be changed in the usual way (6.21). For each
+ item in this list, its value is place in $item, and then the condition is
evaluated. If the condition is true, $item is added to the output as an
item in a new list; if the condition is false, the item is discarded. The
separator used for the output list is the same as the one used for the
input, but a separator setting is not included in the output. For example:
- ${filter{a:b:c}{!eq{$item}{b}}
+ ${filter{a:b:c}{!eq{$item}{b}}}
yields "a:c". At the end of the expansion, the value of $item is restored
to what it was before. See also the map and reduce expansion items.
$hash{4}{62}{monty python}} yields fbWx
$header_<header name>: or $h_<header name>:, $bheader_<header name>: or $bh_<
- header name>:, $rheader_<header name>: or $rh_<header name>:
+ header name>:, $lheader_<header name>: or $lh_<header name>:
- Substitute the contents of the named message header line, for example
+ "$rheader_<header name>: or $rh_<header name>:" Substitute the contents of
+ the named message header line, for example
$header_reply-to:
but internal newlines (caused by splitting the header line over several
physical lines) may be present.
- The difference between rheader, bheader, and header is in the way the data
+ The difference between the four pairs of expansions is in the way the data
in the header line is interpreted.
- * rheader gives the original "raw" content of the header line, with no
+ + rheader gives the original "raw" content of the header line, with no
processing at all, and without the removal of leading and trailing
white space.
- * bheader removes leading and trailing white space, and then decodes
+ + lheader gives a colon-separated list, one element per header when there
+ are multiple headers with a given name. Any embedded colon characters
+ within an element are doubled, so normal Exim list-processing
+ facilities can be used. The terminating newline of each element is
+ removed; in other respects the content is "raw".
+
+ + bheader removes leading and trailing white space, and then decodes
base64 or quoted-printable MIME "words" within the header text, but
does no character set translation. If decoding of what looks
superficially like a MIME "word" fails, the raw string is returned. If
mark - this is what Exim does for binary zeros that are actually
received in header lines.
- * header tries to translate the string as decoded by bheader to a
+ + header tries to translate the string as decoded by bheader to a
standard character set. This is an attempt to produce the same string
as would be displayed on a user's MUA. If translation fails, the
bheader string is returned. Translation is attempted only on operating
router or transport are not accessible.
For incoming SMTP messages, no header lines are visible in ACLs that are
- obeyed before the DATA ACL, because the header structure is not set up
- until the message is received. Header lines that are added in a RCPT ACL
- (for example) are saved until the message's incoming header lines are
- available, at which point they are added. When a DATA ACL is running,
- however, header lines added by earlier ACLs are visible.
+ obeyed before the data phase completes, because the header structure is not
+ set up until the message is received. They are visible in DKIM, PRDR and
+ DATA ACLs. Header lines that are added in a RCPT ACL (for example) are
+ saved until the message's incoming header lines are available, at which
+ point they are added. When any of the above ACLs ar running, however,
+ header lines added by earlier ACLs are visible.
Upper case and lower case letters are synonymous in header names. If the
following character is white space, the terminating colon may be omitted,
but this is not recommended, because you may then forget it when it is
- needed. When white space terminates the header name, it is included in the
- expanded string. If the message does not contain the given header, the
- expansion item is replaced by an empty string. (See the def condition in
- section 11.7 for a means of testing for the existence of a header.)
+ needed. When white space terminates the header name, this white space is
+ included in the expanded string. If the message does not contain the given
+ header, the expansion item is replaced by an empty string. (See the def
+ condition in section 11.7 for a means of testing for the existence of a
+ header.)
If there is more than one header with the same name, they are all
concatenated to form the substitution string, up to a maximum length of
X-Spam-Scanned: header line. If you know the secret, you can check that
this header line is authentic by recomputing the authentication code from
the host name, message ID and the Message-id: header line. This can be done
- using Exim's -be option, or by other means, for example by using the
+ using Exim's -be option, or by other means, for example, by using the
hmac_md5_hex() function in Perl.
${if <condition> {<string1>}{<string2>}}
condition = ${if >{$acl_m4}{3}}
+${imapfolder{<foldername>}}
+
+ This item converts a (possibly multilevel, or with non-ASCII characters)
+ folder specification to a Maildir name for filesystem use. For information
+ on internationalisation support see 59.2.
+
${length{<string1>}{<string2>}}
The length item is used to extract the initial portion of a string. Both
${length_<n>:<string>}
- The result of this item is either the first <n> characters or the whole of
- <string2>, whichever is the shorter. Do not confuse length with strlen,
- which gives the length of a string.
+ The result of this item is either the first <n> bytes or the whole of <
+ string2>, whichever is the shorter. Do not confuse length with strlen,
+ which gives the length of a string. All measurement is done in bytes and is
+ not UTF-8 aware.
${listextract{<number>}{<string1>}{<string2>}{<string3>}}
ignored).
After expansion, <string1> is interpreted as a list, colon-separated by
- default, but the separator can be changed in the usual way.
+ default, but the separator can be changed in the usual way (6.21).
The first field of the list is numbered one. If the number is negative, the
fields are counted from the end of the list, with the rightmost one
${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
- yields "result: 99".
+ yields "result: 42".
If {<string3>} is omitted, an empty string is used for string3. If {<
string2>} is also omitted, the value that was extracted is used. You can
${map{<string1>}{<string2>}}
After expansion, <string1> is interpreted as a list, colon-separated by
- default, but the separator can be changed in the usual way. For each item
- in this list, its value is place in $item, and then <string2> is expanded
- and added to the output as an item in a new list. The separator used for
- the output list is the same as the one used for the input, but a separator
- setting is not included in the output. For example:
+ default, but the separator can be changed in the usual way (6.21). For each
+ item in this list, its value is place in $item, and then <string2> is
+ expanded and added to the output as an item in a new list. The separator
+ used for the output list is the same as the one used for the input, but a
+ separator setting is not included in the output. For example:
${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}}
absent, it defaults to 0. The result of the expansion is a prvs-signed
email address, to be typically used with the return_path option on an smtp
transport as part of a bounce address tag validation (BATV) scheme. For
- more discussion and an example, see section 42.51.
+ more discussion and an example, see section 43.51.
${prvscheck{<address>}{<secret>}{<string>}}
All three variables can be used in the expansion of the third argument.
However, once the expansion is complete, only $prvscheck_result remains
- set. For more discussion and an example, see section 42.51.
+ set. For more discussion and an example, see section 43.51.
${readfile{<file name>}{<eol string>}}
- The file name and end-of-line string are first expanded separately. The
- file is then read, and its contents replace the entire item. All newline
+ The filename and end-of-line string are first expanded separately. The file
+ is then read, and its contents replace the entire item. All newline
characters in the file are replaced by the end-of-line string if it is
present. Otherwise, newlines are left in the string. String expansion is
not applied to the contents of the file. If you want this, you must wrap
The redirect router has an option called forbid_filter_readfile which locks
out the use of this expansion item in filter files.
-${readsocket{<name>}{<request>}{<timeout>}{<eol string>}{<fail string>}}
+${readsocket{<name>}{<request>}{<options>}{<eol string>}{<fail string>}}
- This item inserts data from a Unix domain or Internet socket into the
- expanded string. The minimal way of using it uses just two arguments, as in
- these examples:
+ This item inserts data from a Unix domain or TCP socket into the expanded
+ string. The minimal way of using it uses just two arguments, as in these
+ examples:
${readsocket{/socket/name}{request string}}
${readsocket{inet:some.host:1234}{request string}}
Only a single host name may be given, but if looking it up yields more than
one IP address, they are each tried in turn until a connection is made. For
both kinds of socket, Exim makes a connection, writes the request string
- (unless it is an empty string) and reads from the socket until an
- end-of-file is read. A timeout of 5 seconds is applied. Additional,
- optional arguments extend what can be done. Firstly, you can vary the
- timeout. For example:
+ unless it is an empty string; and no terminating NUL is ever sent) and
+ reads from the socket until an end-of-file is read. A timeout of 5 seconds
+ is applied. Additional, optional arguments extend what can be done.
+ Firstly, you can vary the timeout. For example:
${readsocket{/socket/name}{request string}{3s}}
+ The third argument is a list of options, of which the first element is the
+ timeout and must be present if the argument is given. Further elements are
+ options of form name=value. Two option types is currently recognised:
+ shutdown and tls. The first defines whether (the default) or not a shutdown
+ is done on the connection after sending the request. Example, to not do so
+ (preferred, eg. by some webservers):
+
+ ${readsocket{/socket/name}{request string}{3s:shutdown=no}}
+
+ The second, tls, controls the use of TLS on the connection. Example:
+
+ ${readsocket{/socket/name}{request string}{3s:tls=yes}}
+
+ The default is to not use TLS. If it is enabled, a shutdown as descripbed
+ above is never done.
+
A fourth argument allows you to change any newlines that are in the data
that is read, in the same way as for readfile (see above). This example
turns them into spaces:
happens. Errors in these sub-expansions cause the expansion to fail. In
addition, the following errors can occur:
- * Failure to create a socket file descriptor;
+ + Failure to create a socket file descriptor;
- * Failure to connect the socket;
+ + Failure to connect the socket;
- * Failure to write the request string;
+ + Failure to write the request string;
- * Timeout on reading from the socket.
+ + Timeout on reading from the socket.
By default, any of these errors causes the expansion to fail. However, if
you supply a fifth substring, it is expanded and used when any of the above
This operation reduces a list to a single, scalar string. After expansion,
<string1> is interpreted as a list, colon-separated by default, but the
- separator can be changed in the usual way. Then <string2> is expanded and
- assigned to the $value variable. After this, each item in the <string1>
- list is assigned to $item in turn, and <string3> is expanded for each of
- them. The result of that expansion is assigned to $value before the next
- iteration. When the end of the list is reached, the final value of $value
- is added to the expansion output. The reduce expansion item can be used in
- a number of ways. For example, to add up a list of numbers:
+ separator can be changed in the usual way (6.21). Then <string2> is
+ expanded and assigned to the $value variable. After this, each item in the
+ <string1> list is assigned to $item, in turn, and <string3> is expanded for
+ each of them. The result of that expansion is assigned to $value before the
+ next iteration. When the end of the list is reached, the final value of
+ $value is added to the expansion output. The reduce expansion item can be
+ used in a number of ways. For example, to add up a list of numbers:
${reduce {<, 1,2,3}{0}{${eval:$value+$item}}}
$rheader_<header name>: or $rh_<header name>:
This item inserts "raw" header lines. It is described with the header
- expansion item above.
+ expansion item in section 11.5 above.
${run{<command> <args>}{<string1>}{<string2>}}
${sg{abcdefabcdef}{abc}{xyz}}
yields "xyzdefxyzdef". Because all three arguments are expanded before use,
- if any $ or \ characters are required in the regular expression or in the
- substitution string, they have to be escaped. For example:
+ if any $, } or \ characters are required in the regular expression or in
+ the substitution string, they have to be escaped. For example:
${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of
the regular expression from string expansion.
+ The regular expression is compiled in 8-bit mode, working against bytes
+ rather than any Unicode-aware character handling.
+
+${sort{<string>}{<comparator>}{<extractor>}}
+
+ After expansion, <string> is interpreted as a list, colon-separated by
+ default, but the separator can be changed in the usual way (6.21). The <
+ comparator> argument is interpreted as the operator of a two-argument
+ expansion condition. The numeric operators plus ge, gt, le, lt (and ~i
+ variants) are supported. The comparison should return true when applied to
+ two values if the first value should sort before the second value. The <
+ extractor> expansion is applied repeatedly to elements of the list, the
+ element being placed in $item, to give values for comparison.
+
+ The item result is a sorted list, with the original list separator, of the
+ list elements (in full) of the original.
+
+ Examples:
+
+ ${sort{3:2:1:4}{<}{$item}}
+
+ sorts a list of numbers, and
+
+ ${sort {${lookup dnsdb{>:,,mx=example.com}}} {<} {${listextract{1}{<,$item}}}}
+
+ will sort an MX lookup into priority order.
+
${substr{<string1>}{<string2>}{<string3>}}
The three strings are expanded; the first two must yield numbers. Call them
If the starting offset is greater than the string length the result is the
null string; if the length plus starting offset is greater than the string
length, the result is the right-hand part of the string, starting from the
- given offset. The first character in the string has offset zero.
+ given offset. The first byte (character) in the string has offset zero.
The substr expansion item can take negative offset values to count from the
- right-hand end of its operand. The last character is offset -1, the
+ right-hand end of its operand. The last byte (character) is offset -1, the
second-last is offset -2, and so on. Thus, for example,
${substr{-5}{2}{1234567}}
yields "1".
When the second number is omitted from substr, the remainder of the string
- is taken if the offset is positive. If it is negative, all characters in
- the string preceding the offset point are taken. For example, an offset of
- -1 and no length, as in these semantically identical examples:
+ is taken if the offset is positive. If it is negative, all bytes
+ (characters) in the string preceding the offset point are taken. For
+ example, an offset of -1 and no length, as in these semantically identical
+ examples:
${substr_-1:abcde}
${substr{-1}{abcde}}
yields all but the last character of the string, that is, "abcd".
+ All measurement is done in bytes and is not UTF-8 aware.
+
${tr{<subject>}{<characters>}{<replacements>}}
- This item does single-character translation on its subject string. The
- second argument is a list of characters to be translated in the subject
- string. Each matching character is replaced by the corresponding character
- from the replacement list. For example
+ This item does single-character (in bytes) translation on its subject
+ string. The second argument is a list of characters to be translated in the
+ subject string. Each matching character is replaced by the corresponding
+ character from the replacement list. For example
${tr{abcdea}{ac}{13}}
second, its last character is replicated. However, if it is empty, no
translation takes place.
+ All character handling is done in bytes and is not UTF-8 aware.
+
11.6 Expansion operators
------------------------
header line, and the effective address is extracted from it. If the string
does not parse successfully, the result is empty.
+ The parsing correctly handles SMTPUTF8 Unicode in the string.
+
${addresses:<string>}
The string (after expansion) is interpreted as a list of addresses in RFC
${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
- expands to "ceo@up.stairs&sec@base.ment". Compare the address (singular)
- expansion item, which extracts the working address from a single RFC2822
- address. See the filter, map, and reduce items for ways of processing
- lists.
+ expands to "ceo@up.stairs&sec@base.ment". The string is expanded first, so
+ if the expanded string starts with >, it may change the output separator
+ unintentionally. This can be avoided by setting the output separator
+ explicitly:
+
+ ${addresses:>:$h_from:}
+
+ Compare the address (singular) expansion item, which extracts the working
+ address from a single RFC2822 address. See the filter, map, and reduce
+ items for ways of processing lists.
To clarify "list of addresses in RFC 2822 format" mentioned above, Exim
follows a strict interpretation of header line formatting. Exim parses the
bare, unquoted portion of an email address and if it finds a comma, treats
- it as an email address seperator. For the example header line:
+ it as an email address separator. For the example header line:
From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com>
"=2C". The second example below is passed the contents of "$header_from:",
meaning it gets de-mimed. Exim sees the decoded "," so it treats it as two
email addresses. The third example shows that the presence of a comma is
- skipped when it is quoted.
+ skipped when it is quoted. The fourth example shows SMTPUTF8 handling.
# exim -be '${addresses:From: \
=?iso-8859-2?Q?Last=2C_First?= <user@example.com>}'
Last:user@example.com
# exim -be '${addresses:From: "Last, First" <user@example.com>}'
user@example.com
+ # exim -be '${addresses:?????? <??????????@example.jp>}'
+ ??????????@example.jp
+
+${base32:<digits>}
+
+ The string must consist entirely of decimal digits. The number is converted
+ to base 32 and output as a (empty, for zero) string of characters. Only
+ lowercase letters are used.
+
+${base32d:<base-32 digits>}
+
+ The string must consist entirely of base-32 digits. The number is converted
+ to decimal and output as a string.
${base62:<digits>}
to base 62 and output as a string of six characters, including leading
zeros. In the few operating environments where Exim uses base 36 instead of
base 62 for its message identifiers (because those systems do not have
- case-sensitive file names), base 36 is used by this operator, despite its
+ case-sensitive filenames), base 36 is used by this operator, despite its
name. Note: Just to be absolutely clear: this is not base64 encoding.
${base62d:<base-62 digits>}
identifiers, base-36 digits. The number is converted to decimal and output
as a string.
+${base64:<string>}
+
+ This operator converts a string into one that is base64 encoded.
+
+ If the string is a single variable of type certificate, returns the base64
+ encoding of the DER form of the certificate.
+
+${base64d:<string>}
+
+ This operator converts a base64-encoded string into the un-coded form.
+
${domain:<string>}
The string is interpreted as an RFC 2822 address and the domain is
most significant bit set (so-called "8-bit characters") count as printing
or not is controlled by the print_topbitchars option.
+${escape8bit:<string>}
+
+ If the string contains and characters with the most significant bit set,
+ they are converted to escape sequences starting with a backslash.
+ Backslashes and DEL characters are also converted.
+
${eval:<string>} and ${eval10:<string>}
These items supports simple arithmetic and bitwise logical operations in
${hex2b64:<hexstring>}
This operator converts a hex string into one that is base64 encoded. This
- can be useful for processing the output of the MD5 and SHA-1 hashing
- functions.
+ can be useful for processing the output of the various hashing functions.
${hexquote:<string>}
This operator converts non-printable characters in a string into a hex
escape form. Byte values between 33 (!) and 126 (~) inclusive are left as
- is, and other byte values are converted to "\xNN", for example a byte value
- 127 is converted to "\x7f".
+ is, and other byte values are converted to "\xNN", for example, a byte
+ value 127 is converted to "\x7f".
+
+${ipv6denorm:<string>}
+
+ This expands an IPv6 address to a full eight-element colon-separated set of
+ hex digits including leading zeroes. A trailing ipv4-style dotted-decimal
+ set is converted to hex. Pure IPv4 addresses are converted to IPv4-mapped
+ IPv6.
+
+${ipv6norm:<string>}
+
+ This converts an IPv6 address to canonical form. Leading zeroes of groups
+ are omitted, and the longest set of zero-valued groups is replaced with a
+ double colon. A trailing ipv4-style dotted-decimal set is converted to hex.
+ Pure IPv4 addresses are converted to IPv4-mapped IPv6.
${lc:<string>}
${lc:$local_part}
+ Case is defined per the system C locale.
+
${length_<number>:<string>}
The length operator is a simpler interface to the length function that can
See the description of the general length item above for details. Note that
length is not the same as strlen. The abbreviation l can be used when
- length is used as an operator.
+ length is used as an operator. All measurement is done in bytes and is not
+ UTF-8 aware.
${listcount:<string>}
The string is interpreted as an RFC 2822 address and the local part is
extracted from it. If the string does not parse successfully, the result is
- empty.
+ empty. The parsing correctly handles SMTPUTF8 Unicode in the string.
${mask:<IP address>/<bit count>}
The md5 operator computes the MD5 hash value of the string, and returns it
as a 32-digit hexadecimal number, in which any letters are in lower case.
+ If the string is a single variable of type certificate, returns the MD5
+ hash fingerprint of the certificate.
+
${nhash_<n>_<m>:<string>}
The nhash operator is a simpler interface to the numeric hashing function
you are creating a new email address from the contents of $local_part (or
any other unknown data), you should always use this operator.
+ This quoting determination is not SMTPUTF8-aware, thus quoting non-ASCII
+ data will likely use the quoting form. Thus ${quote_local_part:??????} will
+ always become "??????".
+
${quote_<lookup-type>:<string>}
This operator applies lookup-specific quoting rules to the string. Each
${reverse_ip:<ipaddr>}
This operator reverses an IP address; for IPv4 addresses, the result is in
- dotted-quad decimal form, while for IPv6 addreses the result is in
+ dotted-quad decimal form, while for IPv6 addresses the result is in
dotted-nibble hexadecimal form. In both cases, this is the "natural" form
for DNS. For example,
This operator encodes text according to the rules of RFC 2047. This is an
encoding that is used in header lines to encode non-ASCII characters. It is
assumed that the input string is in the encoding specified by the
- headers_charset option, which defaults to ISO-8859-1. If the string
+ headers_charset option, which gets its default at build time. If the string
contains only characters in the range 33-126, and no instances of the
characters
it as a 40-digit hexadecimal number, in which any letters are in upper
case.
-${sha256:<certificate>}
+ If the string is a single variable of type certificate, returns the SHA-1
+ hash fingerprint of the certificate.
- The sha256 operator computes the SHA-256 hash fingerprint of the
- certificate, and returns it as a 64-digit hexadecimal number, in which any
- letters are in upper case. Only arguments which are a single variable of
- certificate type are supported.
+${sha256:<string>}
+
+ The sha256 operator computes the SHA-256 hash value of the string and
+ returns it as a 64-digit hexadecimal number, in which any letters are in
+ upper case.
+
+ If the string is a single variable of type certificate, returns the SHA-256
+ hash fingerprint of the certificate.
+
+${sha3:<string>}, ${sha3_<n>:<string>}
+
+ The sha3 operator computes the SHA3-256 hash value of the string and
+ returns it as a 64-digit hexadecimal number, in which any letters are in
+ upper case.
+
+ If a number is appended, separated by an underbar, it specifies the output
+ length. Values of 224, 256, 384 and 512 are accepted; with 256 being the
+ default.
+
+ The sha3 expansion item is only supported if Exim has been compiled with
+ GnuTLS 3.5.0 or later, or OpenSSL 1.1.1 or later. The macro
+ "_CRYPTO_HASH_SHA3" will be defined if it is supported.
${stat:<string>}
${str2b64:<string>}
- This operator converts a string into one that is base64 encoded.
+ Now deprecated, a synonym for the base64 expansion operator.
${strlen:<string>}
The item is replace by the length of the expanded string, expressed as a
- decimal number. Note: Do not confuse strlen with length.
+ decimal number. Note: Do not confuse strlen with length. All measurement is
+ done in bytes and is not UTF-8 aware.
${substr_<start>_<length>:<string>}
${substr{<start>}{<length>}{<string>}}
See the description of the general substr item above for details. The
- abbreviation s can be used when substr is used as an operator.
+ abbreviation s can be used when substr is used as an operator. All
+ measurement is done in bytes and is not UTF-8 aware.
${time_eval:<string>}
${uc:<string>}
- This forces the letters in the string into upper-case.
+ This forces the letters in the string into upper-case. Case is defined per
+ the system C locale.
${utf8clean:<string>}
This replaces any invalid utf-8 sequence in the string by the character "?
".
+ In versions of Exim before 4.92, this did not correctly do so for a
+ truncated final codepoint's encoding, and the character would be silently
+ dropped. If you must handle detection of this scenario across both sets of
+ Exim behavior, the complexity will depend upon the task. For instance, to
+ detect if the first character is multibyte and a 1-byte extraction can be
+ successfully used as a path component (as is common for dividing up
+ delivery folders), you might use:
+
+ condition = ${if inlist{${utf8clean:${length_1:$local_part}}}{:?}{yes}{no}}
+
+ (which will false-positive if the first character of the local part is a
+ literal question mark).
+
+${utf8_domain_to_alabel:<string>}, ${utf8_domain_from_alabel:<string>}, $
+ {utf8_localpart_to_alabel:<string>}, ${utf8_localpart_from_alabel:<string>}
+
+ These convert EAI mail name components between UTF-8 and a-label forms. For
+ information on internationalisation support see 59.1.
+
11.7 Expansion conditions
-------------------------
The name and zero to nine argument strings are first expanded separately.
The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9
in order. Any unused are made empty. The variable $acl_narg is set to the
- number of arguments. The named ACL (see chapter 42) is called and may use
+ number of arguments. The named ACL (see chapter 43) is called and may use
the variables; if another acl expansion is used the values are restored
after it returns. If the ACL sets a value using a "message =" modifier the
variable $value becomes the result of the expansion, otherwise it is empty.
The following encryption types (whose names are matched case-independently)
are supported:
- * {md5} computes the MD5 digest of the first string, and expresses this
+ + {md5} computes the MD5 digest of the first string, and expresses this
as printable characters to compare with the remainder of the second
string. If the length of the comparison string is 24, Exim assumes that
it is base64 encoded (as in the above example). If the length is 32,
Exim assumes that it is a hexadecimal encoding of the MD5 digest. If
the length not 24 or 32, the comparison fails.
- * {sha1} computes the SHA-1 digest of the first string, and expresses
+ + {sha1} computes the SHA-1 digest of the first string, and expresses
this as printable characters to compare with the remainder of the
second string. If the length of the comparison string is 28, Exim
assumes that it is base64 encoded. If the length is 40, Exim assumes
that it is a hexadecimal encoding of the SHA-1 digest. If the length is
not 28 or 40, the comparison fails.
- * {crypt} calls the crypt() function, which traditionally used to use
+ + {crypt} calls the crypt() function, which traditionally used to use
only the first eight characters of the password. However, in modern
operating systems this is no longer true, and in many cases the entire
password is used, whatever its length.
- * {crypt16} calls the crypt16() function, which was originally created to
+ + {crypt16} calls the crypt16() function, which was originally created to
use up to 16 characters of the password in some operating systems.
Again, in modern operating systems, more characters may be used.
The two substrings are first expanded. The condition is true if the two
resulting strings are identical. For eq the comparison includes the case of
- letters, whereas for eqi the comparison is case-independent.
+ letters, whereas for eqi the comparison is case-independent, where case is
+ defined per the system C locale.
exists {<file name>}
These conditions iterate over a list. The first argument is expanded to
form the list. By default, the list separator is a colon, but it can be
- changed by the normal method. The second argument is interpreted as a
- condition that is to be applied to each item in the list in turn. During
+ changed by the normal method (6.21). The second argument is interpreted as
+ a condition that is to be applied to each item in the list in turn. During
the interpretation of the condition, the current list item is placed in a
variable called $item.
- * For forany, interpretation stops if the condition is true for any item,
+ + For forany, interpretation stops if the condition is true for any item,
and the result of the whole condition is true. If the condition is
false for all items in the list, the overall condition is false.
- * For forall, interpretation stops if the condition is false for any
+ + For forall, interpretation stops if the condition is false for any
item, and the result of the whole condition is false. If the condition
is true for all items in the list, the overall condition is true.
The two substrings are first expanded. The condition is true if the first
string is lexically greater than or equal to the second string. For ge the
comparison includes the case of letters, whereas for gei the comparison is
- case-independent.
+ case-independent. Case and collation order are defined per the system C
+ locale.
gt {<string1>}{<string2>}, gti {<string1>}{<string2>}
The two substrings are first expanded. The condition is true if the first
string is lexically greater than the second string. For gt the comparison
includes the case of letters, whereas for gti the comparison is
- case-independent.
+ case-independent. Case and collation order are defined per the system C
+ locale.
inlist {<string1>}{<string2>}, inlisti {<string1>}{<string2>}
Both strings are expanded; the second string is treated as a list of simple
strings; if the first string is a member of the second, then the condition
- is true.
+ is true. For the case-independent inlisti condition, case is defined per
+ the system C locale.
These are simpler to use versions of the more powerful forany condition.
Examples, and the forany equivalents:
empty component (adjacent colons) is present. Only one empty component is
permitted.
- Note: The checks are just on the form of the address; actual numerical
- values are not considered. Thus, for example, 999.999.999.999 passes the
- IPv4 check. The main use of these tests is to distinguish between IP
- addresses and host names, or between IPv4 and IPv6 addresses. For example,
- you could use
+ Note: The checks used to be just on the form of the address; actual
+ numerical values were not considered. Thus, for example, 999.999.999.999
+ passed the IPv4 check. This is no longer the case.
+
+ The main use of these tests is to distinguish between IP addresses and host
+ names, or between IPv4 and IPv6 addresses. For example, you could use
${if isip4{$sender_host_address}...
ldapauth {<ldap query>}
- This condition supports user authentication using LDAP. See section 9.13
+ This condition supports user authentication using LDAP. See section 9.14
for details of how to use LDAP in lookups and the syntax of queries. For
this use, the query must contain a user name and password. The query itself
is not used, and can be empty. The condition is true if the password is not
The two substrings are first expanded. The condition is true if the first
string is lexically less than or equal to the second string. For le the
comparison includes the case of letters, whereas for lei the comparison is
- case-independent.
+ case-independent. Case and collation order are defined per the system C
+ locale.
lt {<string1>}{<string2>}, lti {<string1>}{<string2>}
The two substrings are first expanded. The condition is true if the first
string is lexically less than the second string. For lt the comparison
includes the case of letters, whereas for lti the comparison is
- case-independent.
+ case-independent. Case and collation order are defined per the system C
+ locale.
match {<string1>}{<string2>}
there is no circumflex, the expression is not anchored, and it may match
anywhere in the subject, not just at the start. If you want the pattern to
match at the end of the subject, you must include the "$" metacharacter at
- an appropriate point.
+ an appropriate point. All character handling is done in bytes and is not
+ UTF-8 aware, but we might change this in a future Exim release.
At the start of an if expansion the values of the numeric variable
substitutions $1 etc. are remembered. Obeying a match condition that
The specific types of host list item that are permitted in the list are:
- * An IP address, optionally with a CIDR mask.
+ + An IP address, optionally with a CIDR mask.
- * A single asterisk, which matches any IP address.
+ + A single asterisk, which matches any IP address.
- * An empty item, which matches only if the IP address is empty. This
+ + An empty item, which matches only if the IP address is empty. This
could be useful for testing for a locally submitted message or one from
specific hosts in a single test such as
where the first item in the list is the empty string.
- * The item @[] matches any of the local host's interface addresses.
+ + The item @[] matches any of the local host's interface addresses.
- * Single-key lookups are assumed to be like "net-" style lookups in host
+ + Single-key lookups are assumed to be like "net-" style lookups in host
lists, even if "net-" is not specified. There is never any attempt to
turn the IP address into a host name. The most common type of linear
search for match_ip is likely to be iplsearch, in which the file can
${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
In each case, the second argument may contain any of the allowable items
- for a list of the appropriate type. Also, because the second argument
- (after expansion) is a standard form of list, it is possible to refer to a
- named list. Thus, you can use conditions like this:
+ for a list of the appropriate type. Also, because the second argument is a
+ standard form of list, it is possible to refer to a named list. Thus, you
+ can use conditions like this:
${if match_domain{$domain}{+local_domains}{...
pam {<string1>:<string2>:...}
- Pluggable Authentication Modules (http://www.kernel.org/pub/linux/libs/pam/
- ) are a facility that is available in the latest releases of Solaris and in
- some GNU/Linux distributions. The Exim support, which is intended for use
- in conjunction with the SMTP AUTH command, is available only if Exim is
- compiled with
+ Pluggable Authentication Modules (https://mirrors.edge.kernel.org/pub/linux
+ /libs/pam/) are a facility that is available in the latest releases of
+ Solaris and in some GNU/Linux distributions. The Exim support, which is
+ intended for use in conjunction with the SMTP AUTH command, is available
+ only if Exim is compiled with
SUPPORT_PAM=yes
In some operating systems, PAM authentication can be done only from a
process running as root. Since Exim is running as the Exim user when
receiving messages, this means that PAM cannot be used directly in those
- systems. A patched version of the pam_unix module that comes with the Linux
- PAM package is available from http://www.e-admin.de/pam_exim/. The patched
- module allows one special uid/gid combination, in addition to root, to
- authenticate. If you build the patched module to allow the Exim user and
- group, PAM can then be used from an Exim authenticator.
+ systems.
pwcheck {<string1>:<string2>}
When a match expansion condition succeeds, these variables contain the
captured substrings identified by the regular expression during subsequent
- processing of the success string of the containing if expansion item.
- However, they do not retain their values afterwards; in fact, their
- previous values are restored at the end of processing an if item. The
- numerical variables may also be set externally by some other matching
- process which precedes the expansion of the string. For example, the
- commands available in Exim filter files include an if command with its own
- regular expression matching condition.
+ processing of the success string of the containing if expansion item. In
+ the expansion condition case they do not retain their values afterwards; in
+ fact, their previous values are restored at the end of processing an if
+ item. The numerical variables may also be set externally by some other
+ matching process which precedes the expansion of the string. For example,
+ the commands available in Exim filter files include an if command with its
+ own regular expression matching condition.
$acl_arg1, $acl_arg2, etc
$auth1 - $auth3
- These variables are used in SMTP authenticators (see chapters 34-40).
+ These variables are used in SMTP authenticators (see chapters 34-41).
Elsewhere, they are empty.
$authenticated_id
$authenticated_id (see chapter 33). For example, a user/password
authenticator configuration might preserve the user name for use in the
routers. Note that this is not the same information that is saved in
- $sender_host_authenticated. When a message is submitted locally (that is,
- not over a TCP connection) the value of $authenticated_id is normally the
- login name of the calling process. However, a trusted user can override
- this by means of the -oMai command line option.
+ $sender_host_authenticated.
+
+ When a message is submitted locally (that is, not over a TCP connection)
+ the value of $authenticated_id is normally the login name of the calling
+ process. However, a trusted user can override this by means of the -oMai
+ command line option. This second case also sets up information used by the
+ $authresults expansion item.
$authenticated_fail_id
This is set to the recipient address of a bounce message while Exim is
creating it. It is useful if a customized bounce message text file is in
- use (see chapter 48).
+ use (see chapter 49).
$bounce_return_size_limit
This contains the value set in the bounce_return_size_limit option, rounded
up to a multiple of 1000. It is useful when a customized error message text
- file is in use (see chapter 48).
+ file is in use (see chapter 49).
$caller_gid
$originator_uid). If Exim re-execs itself, this variable in the new
incarnation normally contains the Exim uid.
-$compile_date
+$callout_address
- The date on which the Exim binary was compiled.
+ After a callout for verification, spamd or malware daemon service, the
+ address that was connected to.
$compile_number
The building process for Exim keeps a count of the number of times it has
been compiled. This serves to distinguish different compilations of the
- same version of the program.
+ same version of Exim.
-$demime_errorlevel
+$config_dir
- This variable is available when Exim is compiled with the content-scanning
- extension and the obsolete demime condition. For details, see section 43.6.
+ The directory name of the main configuration file. That is, the content of
+ $config_file with the last component stripped. The value does not contain
+ the trailing slash. If $config_file does not contain a slash, $config_dir
+ is ".".
-$demime_reason
+$config_file
- This variable is available when Exim is compiled with the content-scanning
- extension and the obsolete demime condition. For details, see section 43.6.
+ The name of the main configuration file Exim is using.
+
+$dkim_verify_status
+
+ Results of DKIM verification. For details see section 57.3.
+
+$dkim_cur_signer, $dkim_verify_reason, $dkim_domain, $dkim_identity,
+ $dkim_selector, $dkim_algo, $dkim_canon_body, $dkim_canon_headers,
+ $dkim_copiedheaders, $dkim_bodylength, $dkim_created, $dkim_expires,
+ $dkim_headernames, $dkim_key_testing, $dkim_key_nosubdomains,
+ $dkim_key_srvtype, $dkim_key_granularity, $dkim_key_notes, $dkim_key_length
+
+ These variables are only available within the DKIM ACL. For details see
+ section 57.3.
+
+$dkim_signers
+
+ When a message has been received this variable contains a colon-separated
+ list of signer domains and identities for the message. For details see
+ section 57.3.
$dnslist_domain, $dnslist_matched, $dnslist_text, $dnslist_value
When a DNS (black) list lookup succeeds, these variables are set to contain
the following data from the lookup: the list's domain name, the key that
was looked up, the contents of any associated TXT record, and the value
- from the main A record. See section 42.32 for more details.
+ from the main A record. See section 43.32 for more details.
$domain
The $domain variable is also used in some other circumstances:
- * When an ACL is running for a RCPT command, $domain contains the domain
+ + When an ACL is running for a RCPT command, $domain contains the domain
of the recipient address. The domain of the sender address is in
$sender_address_domain at both MAIL time and at RCPT time. $domain is
not normally set during the running of the MAIL ACL. However, if the
sender domain is placed in $domain during the expansions of hosts,
interface, and port in the smtp transport.
- * When a rewrite item is being processed (see chapter 31), $domain
+ + When a rewrite item is being processed (see chapter 31), $domain
contains the domain portion of the address that is being rewritten; it
can be used in the expansion of the replacement address, for example,
to rewrite domains by file lookup.
- * With one important exception, whenever a domain list is being scanned,
+ + With one important exception, whenever a domain list is being scanned,
$domain contains the subject domain. Exception: When a domain list in a
sender_domains condition in an ACL is being processed, the subject
domain is in $sender_address_domain and not in $domain. It works this
way so that, in a RCPT ACL, the sender domain list can be dependent on
the recipient domain (which is what is in $domain at this time).
- * When the smtp_etrn_command option is being expanded, $domain contains
- the complete argument of the ETRN command (see section 47.8).
+ + When the smtp_etrn_command option is being expanded, $domain contains
+ the complete argument of the ETRN command (see section 48.8).
$domain_data
This variable contains the numerical value of the Exim user id.
-$found_extension
+$exim_version
- This variable is available when Exim is compiled with the content-scanning
- extension and the obsolete demime condition. For details, see section 43.6.
+ This variable contains the version string of the Exim build. The first
+ character is a major version number, currently 4. Then after a dot, the
+ next group of digits is a minor version number. There may be other
+ characters following the minor version.
$header_<name>
This is not strictly an expansion variable. It is expansion syntax for
inserting the message header line with the given name. Note that the name
must be terminated by colon or white space, because it may contain a wide
- variety of characters. Note also that braces must not be used.
+ variety of characters. Note also that braces must not be used. See the full
+ description in section 11.5 above.
$headers_added
Within an ACL this variable contains the headers added so far by the ACL
- modifier add_header (section 42.24). The headers are a newline-separated
+ modifier add_header (section 43.24). The headers are a newline-separated
list.
$home
overridden by a setting on the transport itself.
When running a filter test via the -bf option, $home is set to the value of
- the environment variable HOME.
+ the environment variable HOME, which is subject to the keep_environment and
+ add_environment main config options.
$host
host's name from its IP address, and the attempt is not successful, one of
these variables is set to "1".
- * If the lookup receives a definite negative response (for example, a DNS
+ + If the lookup receives a definite negative response (for example, a DNS
lookup succeeded, but no records were found), $host_lookup_failed is
set to "1".
- * If there is any kind of problem during the lookup, such that Exim
+ + If there is any kind of problem during the lookup, such that Exim
cannot tell whether or not the host name is defined (for example, a
timeout for a DNS lookup), $host_lookup_deferred is set to "1".
checking the result, the name is not accepted, and $host_lookup_deferred is
set to "1". See also $sender_host_name.
+ Performing these checks sets up information used by the $authresults
+ expansion item.
+
$host_lookup_failed
See $host_lookup_deferred.
+$host_port
+
+ This variable is set to the remote host's TCP port whenever $host is set
+ for an outbound connection.
+
+$initial_cwd
+
+ This variable contains the full path name of the initial working directory
+ of the current Exim process. This may differ from the current working
+ directory, as Exim changes this to "/" during early startup, and to
+ $spool_directory later.
+
$inode
The only time this variable is set is while expanding the directory_file
When a message is being delivered to a file, pipe, or autoreply transport
as a result of aliasing or forwarding, $local_part is set to the local part
- of the parent address, not to the file name or command (see $address_file
+ of the parent address, not to the filename or command (see $address_file
and $address_pipe).
When an ACL is running for a RCPT command, $local_part contains the local
$local_scan_data
This variable contains the text returned by the local_scan() function when
- a message is received. See chapter 44 for more details.
+ a message is received. See chapter 45 for more details.
$local_user_gid
This variable is set after a DNS lookup done by a dnsdb lookup expansion,
dnslookup router or smtp transport. It will be empty if DNSSEC was not
requested, "no" if the result was not labelled as authenticated data and
- "yes" if it was.
+ "yes" if it was. Results that are labelled as authoritative answer that
+ match the dns_trust_aa configuration variable count also as authenticated
+ data.
$mailstore_basename
This variable is available when Exim is compiled with the content-scanning
extension. It is set to the name of the virus that was found when the ACL
- malware condition is true (see section 43.1).
+ malware condition is true (see section 44.1).
$max_received_linelength
This variable contains the number of bytes in the longest line that was
received as part of the message, not counting the line termination
- character(s).
+ character(s). It is not valid if the spool_files_wireformat option is used.
$message_age
that separates the body from the header. Newlines are included in the
count. See also $message_size, $body_linecount, and $body_zerocount.
+ If the spool file is wireformat (see the spool_files_wireformat main
+ option) the CRLF line-terminators are included in the count.
+
$message_exim_id
When a message is being received or delivered, this variable contains the
$message_id
- This is an old name for $message_exim_id, which is now deprecated.
+ This is an old name for $message_exim_id. It is now deprecated.
$message_linecount
In the MAIL and RCPT ACLs, the value is zero because at that stage the
message has not yet been received.
+ This variable is not valid if the spool_files_wireformat option is used.
+
$message_size
When a message is being processed, this variable contains its size in
A number of variables whose names start with $mime are available when Exim
is compiled with the content-scanning extension. For details, see section
- 43.4.
+ 44.4.
$n0 - $n9
where available) in an attempt to acquire a fully qualified host name. See
also $smtp_active_hostname.
+$proxy_external_address, $proxy_external_port, $proxy_local_address,
+ $proxy_local_port, $proxy_session
+
+ These variables are only available when built with Proxy Protocol or SOCKS5
+ support. For details see chapter 58.1.
+
+$prdr_requested
+
+ This variable is set to "yes" if PRDR was requested by the client for the
+ current message, otherwise "no".
+
$prvscheck_address
This variable is used in conjunction with the prvscheck expansion item,
- which is described in sections 11.5 and 42.51.
+ which is described in sections 11.5 and 43.51.
$prvscheck_keynum
This variable is used in conjunction with the prvscheck expansion item,
- which is described in sections 11.5 and 42.51.
+ which is described in sections 11.5 and 43.51.
$prvscheck_result
This variable is used in conjunction with the prvscheck expansion item,
- which is described in sections 11.5 and 42.51.
+ which is described in sections 11.5 and 43.51.
$qualify_domain
The value set for the qualify_recipient option in the configuration file,
or if not set, the value of $qualify_domain.
+$queue_name
+
+ The name of the spool queue in use; empty for the default queue.
+
$rcpt_count
When a message is being received by SMTP, this variable contains the number
line option.
As well as being useful in ACLs (including the "connect" ACL), these
- variable could be used, for example, to make the file name for a TLS
+ variable could be used, for example, to make the filename for a TLS
certificate depend on which interface and/or port is being used for the
incoming connection. The values of $received_ip_address and $received_port
are saved with any messages that are received, thus making these variables
- available at delivery time.
-
- Note: There are no equivalent variables for outgoing connections, because
- the values are unknown (unless they are explicitly set by options of the
- smtp transport).
+ available at delivery time. For outbound connections see
+ $sending_ip_address.
$received_port
In an ACL, when a recipient verification fails, this variable contains
information about the failure. It is set to one of the following words:
- * "qualify": The address was unqualified (no domain), and the message was
+ + "qualify": The address was unqualified (no domain), and the message was
neither local nor came from an exempted host.
- * "route": Routing failed.
+ + "route": Routing failed.
- * "mail": Routing succeeded, and a callout was attempted; rejection
+ + "mail": Routing succeeded, and a callout was attempted; rejection
occurred at or before the MAIL command (that is, on initial connection,
HELO, or MAIL).
- * "recipient": The RCPT command in a callout was rejected.
+ + "recipient": The RCPT command in a callout was rejected.
- * "postmaster": The postmaster check in a callout was rejected.
+ + "postmaster": The postmaster check in a callout was rejected.
The main use of this variable is expected to be to distinguish between
rejections of MAIL and rejections of RCPT.
$regex_match_string
This variable is set to contain the matching regular expression after a
- regex ACL condition has matched (see section 43.5).
+ regex ACL condition has matched (see section 44.5).
+
+$regex1, $regex2, etc
+
+ When a regex or mime_regex ACL condition succeeds, these variables contain
+ the captured substrings identified by the regular expression.
$reply_address
if it is identical to the verified host name or to the host's IP address in
square brackets.
+$sender_helo_dnssec
+
+ This boolean variable is true if a successful HELO verification was done
+ using DNS information the resolver library stated was authenticated data.
+
$sender_helo_name
When a message is received from a remote host that has issued a HELO or
$sender_host_address
- When a message is received from a remote host, this variable contains that
- host's IP address. For locally submitted messages, it is empty.
+ When a message is received from a remote host using SMTP, this variable
+ contains that host's IP address. For locally non-SMTP submitted messages,
+ it is empty.
$sender_host_authenticated
If an attempt to populate $sender_host_name has been made (by reference,
hosts_lookup or otherwise) then this boolean will have been set true if,
- and only if, the resolver library states that the reverse DNS was
- authenticated data. At all other times, this variable is false.
+ and only if, the resolver library states that both the reverse and forward
+ DNS were authenticated data. At all other times, this variable is false.
It is likely that you will need to coerce DNSSEC support on in the resolver
library, by setting:
dns_dnssec_ok = 1
Exim does not perform DNSSEC validation itself, instead leaving that to a
- validating resolver (eg, unbound, or bind with suitable configuration).
-
- Exim does not (currently) check to see if the forward DNS was also secured
- with DNSSEC, only the reverse DNS.
+ validating resolver (e.g. unbound, or bind with suitable configuration).
If you have changed host_lookup_order so that "bydns" is not the first
mechanism in the list, then this variable will be false.
+ This requires that your system resolver library support EDNS0 (and that
+ DNSSEC flags exist in the system headers). If the resolver silently drops
+ all EDNS0 options, then this will have no effect. OpenBSD's asr resolver is
+ known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
+
$sender_host_name
When a message is received from a remote host, this variable contains the
these lookups altogether. The lookup happens only if one or more of the
following are true:
- * A string containing $sender_host_name is expanded.
+ + A string containing $sender_host_name is expanded.
- * The calling host matches the list in host_lookup. In the default
+ + The calling host matches the list in host_lookup. In the default
configuration, this option is set to *, so it must be changed if
lookups are to be avoided. (In the code, the default for host_lookup is
unset.)
- * Exim needs the host name in order to test an item in a host list. The
+ + Exim needs the host name in order to test an item in a host list. The
items that require this are described in sections 10.13 and 10.17.
- * The calling host matches helo_try_verify_hosts or helo_verify_hosts. In
+ + The calling host matches helo_try_verify_hosts or helo_verify_hosts. In
this case, the host name is required to compare with the name quoted in
any EHLO or HELO commands that the client issues.
- * The remote host issues a EHLO or HELO command that quotes one of the
+ + The remote host issues a EHLO or HELO command that quotes one of the
domains in helo_lookup_domains. The default value of this option is
helo_lookup_domains = @ : @[]
$sender_rate_xxx
A number of variables whose names begin $sender_rate_ are set as part of
- the ratelimit ACL condition. Details are given in section 42.38.
+ the ratelimit ACL condition. Details are given in section 43.38.
$sender_rcvhost
variable is somewhat redundant, but is retained for backwards
compatibility.
+$smtp_command_history
+
+ A comma-separated list (with no whitespace) of the most-recent SMTP
+ commands received, in time-order left to right. Only a limited number of
+ commands are remembered.
+
$smtp_count_at_connection_start
This variable is set greater than zero only in processes spawned by the
A number of variables whose names start with $spam are available when Exim
is compiled with the content-scanning extension. For details, see section
- 43.2.
+ 44.2.
+
+$spf_header_comment, $spf_received, $spf_result, $spf_result_guessed,
+ $spf_smtp_comment
+
+ These variables are only available if Exim is built with SPF support. For
+ details see section 57.4.
$spool_directory
This variable refers to the certificate presented to the peer of an inbound
connection when the message was received. It is only useful as the argument
- of a certextract expansion item, md5 or sha1 operator, or a def condition.
+ of a certextract expansion item, md5, sha1 or sha256 operator, or a def
+ condition.
+
+ Note: Under versions of OpenSSL preceding 1.1.1, when a list of more than
+ one file is used for tls_certificate, this variable is not reliable.
$tls_in_peercert
This variable refers to the certificate presented by the peer of an inbound
connection when the message was received. It is only useful as the argument
- of a certextract expansion item, md5 or sha1 operator, or a def condition.
+ of a certextract expansion item, md5, sha1 or sha256 operator, or a def
+ condition. If certificate verification fails it may refer to a failing
+ chain element which is not the leaf.
$tls_out_ourcert
This variable refers to the certificate presented to the peer of an
outbound connection. It is only useful as the argument of a certextract
- expansion item, md5 or sha1 operator, or a def condition.
+ expansion item, md5, sha1 or sha256 operator, or a def condition.
$tls_out_peercert
This variable refers to the certificate presented by the peer of an
outbound connection. It is only useful as the argument of a certextract
- expansion item, md5 or sha1 operator, or a def condition.
+ expansion item, md5, sha1 or sha256 operator, or a def condition. If
+ certificate verification fails it may refer to a failing chain element
+ which is not the leaf.
$tls_in_certificate_verified
This variable is set to "1" if a TLS certificate was verified when the
message was received, and "0" otherwise.
- The deprecated $tls_certificate_verfied variable refers to the inbound side
- except when used in the context of an outbound SMTP delivery, when it
+ The deprecated $tls_certificate_verified variable refers to the inbound
+ side except when used in the context of an outbound SMTP delivery, when it
refers to the outbound.
$tls_out_certificate_verified
connection, this variable is set to the cipher suite that was negotiated,
for example DES-CBC3-SHA. In other circumstances, in particular, for
message received over unencrypted connections, the variable is empty.
- Testing $tls_cipher for emptiness is one way of distinguishing between
+ Testing $tls_in_cipher for emptiness is one way of distinguishing between
encrypted and non-encrypted connections during ACL processing.
The deprecated $tls_cipher variable is the same as $tls_in_cipher during
$tls_out_cipher
This variable is cleared before any outgoing SMTP connection is made, and
- then set to the outgoing cipher suite if one is negotiated. See chapter 41
+ then set to the outgoing cipher suite if one is negotiated. See chapter 42
for details of TLS support and chapter 30 for details of the smtp
transport.
+$tls_out_dane
+
+ DANE active status. See section 42.15.
+
$tls_in_ocsp
When a message is received from a remote client connection the result of
When a message is received from a remote host over an encrypted SMTP
connection, and Exim is configured to request a certificate from the
client, the value of the Distinguished Name of the certificate is made
- available in the $tls_in_peerdn during subsequent processing.
+ available in the $tls_in_peerdn during subsequent processing. If
+ certificate verification fails it may refer to a failing chain element
+ which is not the leaf.
The deprecated $tls_peerdn variable refers to the inbound side except when
used in the context of an outbound SMTP delivery, when it refers to the
When a message is being delivered to a remote host over an encrypted SMTP
connection, and Exim is configured to request a certificate from the
server, the value of the Distinguished Name of the certificate is made
- available in the $tls_out_peerdn during subsequent processing.
+ available in the $tls_out_peerdn during subsequent processing. If
+ certificate verification fails it may refer to a failing chain element
+ which is not the leaf.
$tls_in_sni
When a TLS session is being established, if the client sends the Server
Name Indication extension, the value will be placed in this variable. If
the variable appears in tls_certificate then this option and some others,
- described in 41.10, will be re-expanded early in the TLS session, to permit
+ described in 42.10, will be re-expanded early in the TLS session, to permit
a different certificate to be presented (and optionally a different key to
be used) to the client, based upon the value of the SNI extension.
During outbound SMTP deliveries, this variable reflects the value of the
tls_sni option on the transport.
+$tls_out_tlsa_usage
+
+ Bitfield of TLSA record types found. See section 42.15.
+
$tod_bsdinbox
The time of day and the date, in the format required for BSD-style mailbox
operation, or external command, as described above. It is also used during
a reduce expansion.
+$verify_mode
+
+ While a router or transport is being run in verify mode or for cutthrough
+ delivery, contains "S" for sender-verification or "R" for
+ recipient-verification. Otherwise, empty.
+
$version_number
The version number of Exim.
$warn_message_delay
This variable is set only during the creation of a message warning about a
- delivery delay. Details of its use are explained in section 48.2.
+ delivery delay. Details of its use are explained in section 49.2.
$warn_message_recipients
This variable is set only during the creation of a message warning about a
- delivery delay. Details of its use are explained in section 48.2.
+ delivery delay. Details of its use are explained in section 49.2.
There is also a command line option -pd (for delay) which suppresses the
initial startup, even if perl_at_start is set.
+ * To provide more security executing Perl code via the embedded Perl
+ interpreter, the perl_taintmode option can be set. This enables the taint
+ mode of the Perl interpreter. You are encouraged to set this option to a
+ true value. To avoid breaking existing installations, it defaults to false.
+
12.2 Calling Perl subroutines
-----------------------------
listen. Each item may optionally also specify a port.
The default list separator in both cases is a colon, but this can be changed as
-described in section 6.19. When IPv6 addresses are involved, it is usually best
+described in section 6.21. When IPv6 addresses are involved, it is usually best
to change the separator to avoid having to double all the colons. For example:
local_interfaces = <; 127.0.0.1 ; \
configuration by -D is allowed only when the caller is root or exim.
The value of -oX is a list of items. The default colon separator can be changed
-in the usual way if required. If there are any items that do not contain dots
-or colons (that is, are not IP addresses), the value of daemon_smtp_ports is
-replaced by the list of those items. If there are any items that do contain
+in the usual way (6.21) if required. If there are any items that do not contain
+dots or colons (that is, are not IP addresses), the value of daemon_smtp_ports
+is replaced by the list of those items. If there are any items that do contain
dots or colons, the value of local_interfaces is replaced by those items. Thus,
for example,
daemon_smtp_ports is no longer relevant in this example.)
-13.4 Support for the obsolete SSMTP (or SMTPS) protocol
--------------------------------------------------------
+13.4 Support for the submissions (aka SSMTP or SMTPS) protocol
+--------------------------------------------------------------
+
+Exim supports the use of TLS-on-connect, used by mail clients in the
+"submissions" protocol, historically also known as SMTPS or SSMTP. For some
+years, IETF Standards Track documents only blessed the STARTTLS-based
+Submission service (port 587) while common practice was to support the same
+feature set on port 465, but using TLS-on-connect. If your installation needs
+to provide service to mail clients (Mail User Agents, MUAs) then you should
+provide service on both the 587 and the 465 TCP ports.
+
+If the tls_on_connect_ports option is set to a list of port numbers or service
+names, connections to those ports must first establish TLS, before proceeding
+to the application layer use of the SMTP protocol.
-Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used
-before the STARTTLS command was standardized for SMTP. Some legacy clients
-still use this protocol. If the tls_on_connect_ports option is set to a list of
-port numbers or service names, connections to those ports must use SSMTP. The
-most common use of this option is expected to be
+The common use of this option is expected to be
tls_on_connect_ports = 465
-because 465 is the usual port number used by the legacy clients. There is also
-a command line option -tls-on-connect, which forces all ports to behave in this
-way when a daemon is started.
+per RFC 8314. There is also a command line option -tls-on-connect, which forces
+all ports to behave in this way when a daemon is started.
Warning: Setting tls_on_connect_ports does not of itself cause the daemon to
listen on those ports. You must still specify them in daemon_smtp_ports,
===============================================================================
14. MAIN CONFIGURATION
-The first part of the run time configuration file contains three types of item:
+The first part of the runtime configuration file contains three types of item:
* Macro definitions: These lines start with an upper case letter. See section
6.4 for details of macro processing.
* Main configuration settings: Each setting occupies one line of the file
(with possible continuations). If any setting is preceded by the word
"hide", the -bP command line option displays its value to admin users only.
- See section 6.10 for a description of the syntax of these option settings.
+ See section 6.11 for a description of the syntax of these option settings.
This chapter specifies all the main configuration options, along with their
types and default values. For ease of finding a particular option, they appear
------------------
bi_command to run for -bi command line option
+debug_store do extra internal checks
disable_ipv6 do no IPv6 processing
keep_malformed for broken files - should not happen
localhost_number for unique message ids in clusters
message_body_visible how much to show in $message_body
mua_wrapper run in "MUA wrapper" mode
print_topbitchars top-bit characters are printing
+spool_wireformat use wire-format spool data files when possible
timezone force time zone
14.3 Privilege controls
-----------------------
-admin_groups groups that are Exim admin users
-deliver_drop_privilege drop root for delivery processes
-local_from_check insert Sender: if necessary
-local_from_prefix for testing From: for local sender
-local_from_suffix for testing From: for local sender
-local_sender_retain keep Sender: from untrusted user
-never_users do not run deliveries as these
-prod_requires_admin forced delivery requires admin user
-queue_list_requires_admin queue listing requires admin user
-trusted_groups groups that are trusted
-trusted_users users that are trusted
+admin_groups groups that are Exim admin users
+commandline_checks_require_admin require admin for various checks
+deliver_drop_privilege drop root for delivery processes
+local_from_check insert Sender: if necessary
+local_from_prefix for testing From: for local sender
+local_from_suffix for testing From: for local sender
+local_sender_retain keep Sender: from untrusted user
+never_users do not run deliveries as these
+prod_requires_admin forced delivery requires admin user
+queue_list_requires_admin queue listing requires admin user
+trusted_groups groups that are trusted
+trusted_users users that are trusted
14.4 Logging
------------
+event_action custom logging
hosts_connection_nolog exemption from connect logging
log_file_path override compiled-in value
log_selector set/unset optional logging
message_logs create per-message logs
preserve_message_logs after message completion
process_log_path for SIGUSR1 and exiwhat
+slow_lookup_log control logging of slow DNS lookups
syslog_duplication controls duplicate log lines on syslog
syslog_facility set syslog "facility" field
+syslog_pid pid in syslog lines
syslog_processname set syslog "ident" field
syslog_timestamp timestamp syslog lines
write_rejectlog control use of message log
14.8 Embedded Perl Startup
--------------------------
-perl_at_start always start the interpreter
-perl_startup code to obey when starting Perl
+perl_at_start always start the interpreter
+perl_startup code to obey when starting Perl
+perl_taintmode enable taint mode in Perl
14.9 Daemon
acl_smtp_mail ACL for MAIL
acl_smtp_mailauth ACL for AUTH on MAIL command
acl_smtp_mime ACL for MIME parts
+acl_smtp_notquit ACL for non-QUIT terminations
acl_smtp_predata ACL for start of data
acl_smtp_quit ACL for QUIT
acl_smtp_rcpt ACL for RCPT
acl_smtp_vrfy ACL for VRFY
av_scanner specify virus scanner
check_rfc2047_length check length of RFC 2047 "encoded words"
+dns_cname_loops follow CNAMEs returned by resolver
dns_csa_search_limit control CSA parent search depth
dns_csa_use_reverse en/disable CSA IP reverse search
header_maxsize total size of message header
helo_verify_hosts HELO hard-checked for these hosts
host_lookup host name looked up for these hosts
host_lookup_order order of DNS and local name lookups
+hosts_proxy use proxy protocol for these hosts
host_reject_connection reject connection from these hosts
hosts_treat_as_local useful in some cluster configurations
local_scan_timeout timeout for local_scan()
tls_crl certificate revocation list
tls_dh_max_bits clamp D-H bit count suggestion
tls_dhparam DH parameters for server
+tls_eccurve EC curve selection for server
tls_ocsp_file location of server certificate status proof
tls_on_connect_ports specify SSMTP (SMTPS) ports
tls_privatekey location of server private key
See also the Policy controls section above.
+dkim_verify_signers DKIM domain for which DKIM ACL is run
host_lookup host name looked up for these hosts
host_lookup_order order of DNS and local name lookups
recipient_unqualified_hosts may send unqualified recipients
accept_8bitmime advertise 8BITMIME
auth_advertise_hosts advertise AUTH to these hosts
+chunking_advertise_hosts advertise CHUNKING to these hosts
+dsn_advertise_hosts advertise DSN extensions to these hosts
ignore_fromline_hosts allow "From " from these hosts
ignore_fromline_local allow "From " from local SMTP
pipelining_advertise_hosts advertise pipelining to these hosts
prdr_enable advertise PRDR to all hosts
+smtputf8_advertise_hosts advertise SMTPUTF8 to these hosts
tls_advertise_hosts advertise TLS to these hosts
dns_ipv4_lookup only v4 lookup for these domains
dns_retrans parameter for resolver
dns_retry parameter for resolver
+dns_trust_aa DNS zones trusted as authentic
dns_use_edns0 parameter for resolver
hold_domains hold delivery for these domains
local_interfaces for routing checks
bounce_message_file content of bounce
bounce_message_text content of bounce
bounce_return_body include body if returning message
+bounce_return_linesize_limit limit on returned message line length
bounce_return_message include original message in bounce
bounce_return_size_limit limit on returned message
bounce_sender_authentication send authenticated sender with bounce
Those options that undergo string expansion before use are marked with *.
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
|accept_8bitmime|Use: main|Type: boolean|Default: true|
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
This option causes Exim to send 8BITMIME in its response to an SMTP EHLO
command, and to accept the BODY= parameter on MAIL commands. However, though
defaults to true. A more detailed analysis of the issues is provided by Dan
Bernstein:
-http://cr.yp.to/smtp/8bitmime.html
+https://cr.yp.to/smtp/8bitmime.html
To log received 8BITMIME status use
log_selector = +8bitmime
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
|acl_not_smtp|Use: main|Type: string*|Default: unset|
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
This option defines the ACL that is run when a non-SMTP message has been read
-and is on the point of being accepted. See chapter 42 for further details.
+and is on the point of being accepted. See chapter 43 for further details.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|acl_not_smtp_mime|Use: main|Type: string*|Default: unset|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
This option defines the ACL that is run for individual MIME parts of non-SMTP
messages. It operates in exactly the same way as acl_smtp_mime operates for
SMTP messages.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|acl_not_smtp_start|Use: main|Type: string*|Default: unset|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
This option defines the ACL that is run before Exim starts reading a non-SMTP
-message. See chapter 42 for further details.
+message. See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_auth|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP AUTH command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|acl_smtp_connect|Use: main|Type: string*|Default: unset|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
This option defines the ACL that is run when an SMTP connection is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_data|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run after an SMTP DATA command has been
processed and the message itself has been received, but before the final
-acknowledgment is sent. See chapter 42 for further details.
+acknowledgment is sent. See chapter 43 for further details.
-+------------------+---------+-------------+--------------+
-|acl_smtp_data_prdr|Use: main|Type: string*|Default: unset|
-+------------------+---------+-------------+--------------+
++----------------------------------------------------------+
+|acl_smtp_data_prdr|Use: main|Type: string*|Default: accept|
++----------------------------------------------------------+
This option defines the ACL that, if the PRDR feature has been negotiated, is
run for each recipient after an SMTP DATA command has been processed and the
message itself has been received, but before the acknowledgment is sent. See
-chapter 42 for further details.
+chapter 43 for further details.
+
++----------------------------------------------------+
+|acl_smtp_dkim|Use: main|Type: string*|Default: unset|
++----------------------------------------------------+
+
+This option defines the ACL that is run for each DKIM signature (by default, or
+as specified in the dkim_verify_signers option) of a received message. See
+section 57.3 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_etrn|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP ETRN command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_expn|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP EXPN command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_helo|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP EHLO or HELO command is
-received. See chapter 42 for further details.
+received. See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_mail|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP MAIL command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|acl_smtp_mailauth|Use: main|Type: string*|Default: unset|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
This option defines the ACL that is run when there is an AUTH parameter on a
-MAIL command. See chapter 42 for details of ACLs, and chapter 33 for details of
+MAIL command. See chapter 43 for details of ACLs, and chapter 33 for details of
authentication.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_mime|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option is available when Exim is built with the content-scanning
extension. It defines the ACL that is run for each MIME part in a message. See
-section 43.4 for details.
+section 44.4 for details.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
+|acl_smtp_notquit|Use: main|Type: string*|Default: unset|
++-------------------------------------------------------+
+
+This option defines the ACL that is run when an SMTP session ends without a
+QUIT command being received. See chapter 43 for further details.
+
++-------------------------------------------------------+
|acl_smtp_predata|Use: main|Type: string*|Default: unset|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
This option defines the ACL that is run when an SMTP DATA command is received,
-before the message itself is received. See chapter 42 for further details.
+before the message itself is received. See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_quit|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP QUIT command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_rcpt|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP RCPT command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|acl_smtp_starttls|Use: main|Type: string*|Default: unset|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
This option defines the ACL that is run when an SMTP STARTTLS command is
-received. See chapter 42 for further details.
+received. See chapter 43 for further details.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|acl_smtp_vrfy|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option defines the ACL that is run when an SMTP VRFY command is received.
-See chapter 42 for further details.
+See chapter 43 for further details.
-+---------------+---------+-----------------+--------------+
++----------------------------------------------------------+
|add_environment|Use: main|Type: string list|Default: empty|
-+---------------+---------+-----------------+--------------+
++----------------------------------------------------------+
This option allows to set individual environment variables that the currently
-linked libraries and programs in child processes use. The default list is
-empty,
+linked libraries and programs in child processes use. See 29.4 for the
+environment of pipe transports.
-+------------+---------+------------------+--------------+
++--------------------------------------------------------+
|admin_groups|Use: main|Type: string list*|Default: unset|
-+------------+---------+------------------+--------------+
++--------------------------------------------------------+
This option is expanded just once, at the start of Exim's processing. If the
current group or any of the supplementary groups of an Exim caller is in this
permit them to read Exim's spool files (whose group owner is the Exim gid). To
permit this, you have to add individuals to the Exim group.
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
|allow_domain_literals|Use: main|Type: boolean|Default: false|
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
If this option is set, the RFC 2822 domain literal format is permitted in email
addresses. The option is not set by default, because the domain literal format
domain list local_domains in the default configuration). This "magic string"
matches the domain literal form of all the local host's IP addresses.
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
|allow_mx_to_ip|Use: main|Type: boolean|Default: false|
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
It appears that more and more DNS zone administrators are breaking the rules
and putting domain names that look like IP addresses on the right hand side of
MX records. Exim follows the rules and rejects this, giving an error message
-that explains the mis-configuration. However, some other MTAs support this
+that explains the misconfiguration. However, some other MTAs support this
practice, so to avoid "Why can't Exim do this?" complaints, allow_mx_to_ip
exists, in order to enable this heinous activity. It is not recommended, except
when you have no other choice.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|allow_utf8_domains|Use: main|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
Lots of discussion is going on about internationalized domain names. One camp
is strongly in favour of just using UTF-8 characters, and it seems that at
That is, set the option to an empty string so that no check is done.
-+--------------------+---------+----------------+----------+
++----------------------------------------------------------+
|auth_advertise_hosts|Use: main|Type: host list*|Default: *|
-+--------------------+---------+----------------+----------+
++----------------------------------------------------------+
If any server authentication mechanisms are configured, Exim advertises them in
response to an EHLO command only if the calling host matches this list.
expansion is empty, thus matching no hosts. Otherwise, the result of the
expansion is *, which matches all hosts.
-+---------+---------+----------+-----------+
++------------------------------------------+
|auto_thaw|Use: main|Type: time|Default: 0s|
-+---------+---------+----------+-----------+
++------------------------------------------+
If this option is set to a time greater than zero, a queue runner will try a
new delivery attempt on any frozen message, other than a bounce message, if
ignore_bounce_errors_after. It is retained for compatibility, but it is not
thought to be very useful any more, and its use should probably be avoided.
-+----------+---------+------------+------------------+
++----------------------------------------------------+
|av_scanner|Use: main|Type: string|Default: see below|
-+----------+---------+------------+------------------+
++----------------------------------------------------+
This option is available if Exim is built with the content-scanning extension.
It specifies which anti-virus scanner to use. The default value is:
sophie:/var/run/sophie
If the value of av_scanner starts with a dollar character, it is expanded
-before use. See section 43.1 for further details.
+before use. See section 44.1 for further details.
-+----------+---------+------------+--------------+
++------------------------------------------------+
|bi_command|Use: main|Type: string|Default: unset|
-+----------+---------+------------+--------------+
++------------------------------------------------+
This option supplies the name of a command that is run when Exim is called with
the -bi option (see chapter 5). The string value is just the command name, it
is not a complete command line. If an argument is required, it must come from
the -oA command line option.
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
|bounce_message_file|Use: main|Type: string|Default: unset|
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
This option defines a template file containing paragraphs of text to be used
for constructing bounce messages. Details of the file's contents are given in
-chapter 48. See also warn_message_file.
+chapter 49. See also warn_message_file.
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
|bounce_message_text|Use: main|Type: string|Default: unset|
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
When this option is set, its contents are included in the default bounce
message immediately after "This message was created automatically by mail
delivery software." It is not used if bounce_message_file is set.
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
|bounce_return_body|Use: main|Type: boolean|Default: true|
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
This option controls whether the body of an incoming message is included in a
bounce message when bounce_return_message is true. The default setting causes
detected during reception, only those header lines preceding the point at which
the error was detected are returned.
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------------+
+|bounce_return_linesize_limit|Use: main|Type: integer|Default: 998|
++-----------------------------------------------------------------+
+
+This option sets a limit in bytes on the line length of messages that are
+returned to senders due to delivery problems, when bounce_return_message is
+true. The default value corresponds to RFC limits. If the message being
+returned has lines longer than this value it is treated as if the
+bounce_return_size_limit (below) restriction was exceeded.
+
+The option also applies to bounces returned when an error is detected during
+reception of a message. In this case lines from the original are truncated.
+
+The option does not apply to messages generated by an autoreply transport.
+
++-----------------------------------------------------------+
|bounce_return_message|Use: main|Type: boolean|Default: true|
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------+
If this option is set false, none of the original message is included in bounce
messages generated by Exim. See also bounce_return_size_limit and
bounce_return_body.
-+------------------------+---------+-------------+-------------+
++--------------------------------------------------------------+
|bounce_return_size_limit|Use: main|Type: integer|Default: 100K|
-+------------------------+---------+-------------+-------------+
++--------------------------------------------------------------+
This option sets a limit in bytes on the size of messages that are returned to
senders as part of bounce messages when bounce_return_message is true. The
size). The idea is to save bandwidth on those undeliverable 15-megabyte
messages.
-+----------------------------+---------+------------+--------------+
++------------------------------------------------------------------+
|bounce_sender_authentication|Use: main|Type: string|Default: unset|
-+----------------------------+---------+------------+--------------+
++------------------------------------------------------------------+
This option provides an authenticated sender address that is sent with any
bounce messages generated by Exim that are sent over an authenticated SMTP
The value of bounce_sender_authentication must always be a complete email
address.
-+------------------------------+---------+----------+-----------+
++---------------------------------------------------------------+
|callout_domain_negative_expire|Use: main|Type: time|Default: 3h|
-+------------------------------+---------+----------+-----------+
++---------------------------------------------------------------+
This option specifies the expiry time for negative callout cache data for a
-domain. See section 42.45 for details of callout verification, and section
-42.47 for details of the caching.
+domain. See section 43.45 for details of callout verification, and section
+43.47 for details of the caching.
-+------------------------------+---------+----------+-----------+
++---------------------------------------------------------------+
|callout_domain_positive_expire|Use: main|Type: time|Default: 7d|
-+------------------------------+---------+----------+-----------+
++---------------------------------------------------------------+
This option specifies the expiry time for positive callout cache data for a
-domain. See section 42.45 for details of callout verification, and section
-42.47 for details of the caching.
+domain. See section 43.45 for details of callout verification, and section
+43.47 for details of the caching.
-+-----------------------+---------+----------+-----------+
++--------------------------------------------------------+
|callout_negative_expire|Use: main|Type: time|Default: 2h|
-+-----------------------+---------+----------+-----------+
++--------------------------------------------------------+
This option specifies the expiry time for negative callout cache data for an
-address. See section 42.45 for details of callout verification, and section
-42.47 for details of the caching.
+address. See section 43.45 for details of callout verification, and section
+43.47 for details of the caching.
-+-----------------------+---------+----------+------------+
++---------------------------------------------------------+
|callout_positive_expire|Use: main|Type: time|Default: 24h|
-+-----------------------+---------+----------+------------+
++---------------------------------------------------------+
This option specifies the expiry time for positive callout cache data for an
-address. See section 42.45 for details of callout verification, and section
-42.47 for details of the caching.
+address. See section 43.45 for details of callout verification, and section
+43.47 for details of the caching.
-+-------------------------+---------+-------------+------------------+
++--------------------------------------------------------------------+
|callout_random_local_part|Use: main|Type: string*|Default: see below|
-+-------------------------+---------+-------------+------------------+
++--------------------------------------------------------------------+
This option defines the "random" local part that can be used as part of callout
verification. The default value is
$primary_hostname-$tod_epoch-testing
-See section 42.46 for details of how this value is used.
+See section 43.46 for details of how this value is used.
-+----------------+---------+-------------+----------+
-|check_log_inodes|Use: main|Type: integer|Default: 0|
-+----------------+---------+-------------+----------+
++-----------------------------------------------------+
+|check_log_inodes|Use: main|Type: integer|Default: 100|
++-----------------------------------------------------+
See check_spool_space below.
-+---------------+---------+-------------+----------+
-|check_log_space|Use: main|Type: integer|Default: 0|
-+---------------+---------+-------------+----------+
++----------------------------------------------------+
+|check_log_space|Use: main|Type: integer|Default: 10M|
++----------------------------------------------------+
See check_spool_space below.
-+--------------------+---------+-------------+-------------+
++----------------------------------------------------------+
|check_rfc2047_length|Use: main|Type: boolean|Default: true|
-+--------------------+---------+-------------+-------------+
++----------------------------------------------------------+
RFC 2047 defines a way of encoding non-ASCII characters in headers using a
system of "encoded words". The RFC specifies a maximum length for an encoded
of the RFC, generates overlong encoded words. If check_rfc2047_length is set
false, Exim recognizes encoded words of any length.
-+------------------+---------+-------------+----------+
-|check_spool_inodes|Use: main|Type: integer|Default: 0|
-+------------------+---------+-------------+----------+
++-------------------------------------------------------+
+|check_spool_inodes|Use: main|Type: integer|Default: 100|
++-------------------------------------------------------+
See check_spool_space below.
-+-----------------+---------+-------------+----------+
-|check_spool_space|Use: main|Type: integer|Default: 0|
-+-----------------+---------+-------------+----------+
++------------------------------------------------------+
+|check_spool_space|Use: main|Type: integer|Default: 10M|
++------------------------------------------------------+
The four check_... options allow for checking of disk resources before a
message is accepted.
-When any of these options are set, they apply to all incoming messages. If you
-want to apply different checks to different kinds of message, you can do so by
-testing the variables $log_inodes, $log_space, $spool_inodes, and $spool_space
-in an ACL with appropriate additional conditions.
+When any of these options are nonzero, they apply to all incoming messages. If
+you want to apply different checks to different kinds of message, you can do so
+by testing the variables $log_inodes, $log_space, $spool_inodes, and
+$spool_space in an ACL with appropriate additional conditions.
check_spool_space and check_spool_inodes check the spool partition if either
value is greater than zero, for example:
-check_spool_space = 10M
+check_spool_space = 100M
check_spool_inodes = 100
The spool partition is the one that contains the directory defined by
no_smtp_check_spool_space is set.
The values for check_spool_space and check_log_space are held as a number of
-kilobytes. If a non-multiple of 1024 is specified, it is rounded up.
+kilobytes (though specified in bytes). If a non-multiple of 1024 is specified,
+it is rounded up.
For non-SMTP input and for batched SMTP input, the test is done at start-up; on
failure a message is written to stderr and Exim exits with a non-zero code, as
it obviously cannot send an error message of any kind.
-+-----------------+---------+------------+---------------+
+There is a slight performance penalty for these checks. Versions of Exim
+preceding 4.88 had these disabled by default; high-rate installations confident
+they will never run out of resources may wish to deliberately disable them.
+
++--------------------------------------------------------------+
+|chunking_advertise_hosts|Use: main|Type: host list*|Default: *|
++--------------------------------------------------------------+
+
+The CHUNKING extension (RFC3030) will be advertised in the EHLO message to
+these hosts. Hosts may use the BDAT command as an alternate to DATA.
+
++-------------------------------------------------------------------------+
+|commandline_checks_require_admin|Use: main|Type: boolean|Default: "false"|
++-------------------------------------------------------------------------+
+
+This option restricts various basic checking features to require an
+administrative user. This affects most of the -b* options, such as -be.
+
++----------------------------------------------------+
+|debug_store|Use: main|Type: boolean|Default: "false"|
++----------------------------------------------------+
+
+This option, when true, enables extra checking in Exim's internal memory
+management. For use when a memory corruption issue is being investigated, it
+should normally be left as default.
+
++--------------------------------------------------------+
|daemon_smtp_ports|Use: main|Type: string|Default: "smtp"|
-+-----------------+---------+------------+---------------+
++--------------------------------------------------------+
This option specifies one or more default SMTP ports on which the Exim daemon
listens. See chapter 13 for details of how it is used. For backward
compatibility, daemon_smtp_port (singular) is a synonym.
-+----------------------+---------+-------------+----------+
++---------------------------------------------------------+
|daemon_startup_retries|Use: main|Type: integer|Default: 9|
-+----------------------+---------+-------------+----------+
++---------------------------------------------------------+
This option, along with daemon_startup_sleep, controls the retrying done by the
daemon at startup when it cannot immediately bind a listening socket (typically
number of retries after the first failure, and daemon_startup_sleep defines the
length of time to wait between retries.
-+--------------------+---------+----------+------------+
++------------------------------------------------------+
|daemon_startup_sleep|Use: main|Type: time|Default: 30s|
-+--------------------+---------+----------+------------+
++------------------------------------------------------+
See daemon_startup_retries.
-+-------------+---------+---------------+------------+
++----------------------------------------------------+
|delay_warning|Use: main|Type: time list|Default: 24h|
-+-------------+---------+---------------+------------+
++----------------------------------------------------+
When a message is delayed, Exim sends a warning message to the sender at
intervals specified by this option. The data is a colon-separated list of times
after which to send warning messages. If the value of the option is an empty
string or a zero time, no warnings are sent. Up to 10 times may be given. If a
-message has been on the queue for longer than the last time, the last interval
+message has been in the queue for longer than the last time, the last interval
between the times is used to compute subsequent warning times. For example,
with
which depends on retry and queue-runner configuration. Typically retries will
be configured more frequently than warning messages.
-+-----------------------+---------+-------------+------------------+
++------------------------------------------------------------------+
|delay_warning_condition|Use: main|Type: string*|Default: see below|
-+-----------------------+---------+-------------+------------------+
++------------------------------------------------------------------+
The string is expanded at the time a warning message might be sent. If all the
deferred addresses have the same domain, it is set in $domain during the
Precedence: header, or have "auto-generated" or "auto-replied" in an
Auto-Submitted: header.
-+----------------------+---------+-------------+--------------+
++-------------------------------------------------------------+
|deliver_drop_privilege|Use: main|Type: boolean|Default: false|
-+----------------------+---------+-------------+--------------+
++-------------------------------------------------------------+
If this option is set true, Exim drops its root privilege at the start of a
delivery process, and runs as the Exim user throughout. This severely restricts
the kinds of local delivery that are possible, but is viable in certain types
of configuration. There is a discussion about the use of root privilege in
-chapter 54.
+chapter 55.
-+----------------------+---------+-----------------+--------------+
++-----------------------------------------------------------------+
|deliver_queue_load_max|Use: main|Type: fixed-point|Default: unset|
-+----------------------+---------+-----------------+--------------+
++-----------------------------------------------------------------+
When this option is set, a queue run is abandoned if the system load average
becomes greater than the value of the option. The option has no effect on
ancient operating systems on which Exim cannot determine the load average. See
also queue_only_load and smtp_load_reserve.
-+--------------------+---------+-------------+-------------+
++----------------------------------------------------------+
|delivery_date_remove|Use: main|Type: boolean|Default: true|
-+--------------------+---------+-------------+-------------+
++----------------------------------------------------------+
Exim's transports have an option for adding a Delivery-date: header to a
message when it is delivered, in exactly the same way as Return-path: is
removed at the time the message is received, to avoid any problems that might
occur when a delivered message is subsequently sent on to some other recipient.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|disable_fsync|Use: main|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option is available only if Exim was built with the compile-time option
ENABLE_DISABLE_FSYNC. When this is not set, a reference to disable_fsync in a
crashes and power outages may cause data to be lost or scrambled. Here be
Dragons. Beware.
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
|disable_ipv6|Use: main|Type: boolean|Default: false|
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
If this option is set true, even if the Exim binary has IPv6 support, no IPv6
activities take place. AAAA records are never looked up, and any IPv6 addresses
ignored. If IP literals are enabled, the ipliteral router declines to handle
IPv6 literal addresses.
-+------------------------+---------+------------------+--------------+
++-----------------------------------------------------------------------+
+|dkim_verify_signers|Use: main|Type: domain list*|Default: $dkim_signers|
++-----------------------------------------------------------------------+
+
+This option gives a list of DKIM domains for which the DKIM ACL is run. It is
+expanded after the message is received; by default it runs the ACL once for
+each signature in the message. See section 57.3.
+
++--------------------------------------------------------------------+
|dns_again_means_nonexist|Use: main|Type: domain list*|Default: unset|
-+------------------------+---------+------------------+--------------+
++--------------------------------------------------------------------+
DNS lookups give a "try again" response for the DNS errors "non-authoritative
host not found" and "SERVERFAIL". This can cause Exim to keep trying to deliver
SRV records give temporary errors. These more specific options are applied
after this global option.
-+-----------------------+---------+------------+------------------+
++-----------------------------------------------------------------+
|dns_check_names_pattern|Use: main|Type: string|Default: see below|
-+-----------------------+---------+------------+------------------+
++-----------------------------------------------------------------+
When this option is set to a non-empty string, it causes Exim to check domain
names for characters that are not allowed in host names before handing them to
accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you
must modify this pattern, or set the option to an empty string.
-+--------------------+---------+-------------+----------+
++-------------------------------------------------------+
|dns_csa_search_limit|Use: main|Type: integer|Default: 5|
-+--------------------+---------+-------------+----------+
++-------------------------------------------------------+
This option controls the depth of parental searching for CSA SRV records in the
-DNS, as described in more detail in section 42.50.
+DNS, as described in more detail in section 43.50.
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
|dns_csa_use_reverse|Use: main|Type: boolean|Default: true|
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
This option controls whether or not an IP address, given as a CSA domain, is
reversed and looked up in the reverse DNS, as described in more detail in
-section 42.50.
+section 43.50.
+
++--------------------------------------------------+
+|dns_cname_loops|Use: main|Type: integer|Default: 1|
++--------------------------------------------------+
+
+This option controls the following of CNAME chains, needed if the resolver does
+not do it internally. As of 2018 most should, and the default can be left. If
+you have an ancient one, a value of 10 is likely needed.
+
+The default value of one CNAME-follow is needed thanks to the observed return
+for an MX request, given no MX presence but a CNAME to an A, of the CNAME.
-+-------------+---------+-------------+-----------+
++-------------------------------------------------+
|dns_dnssec_ok|Use: main|Type: integer|Default: -1|
-+-------------+---------+-------------+-----------+
++-------------------------------------------------+
If this option is set to a non-negative number then Exim will initialise the
DNS resolver library to either use or not use DNSSEC, overriding the system
If the resolver library does not support DNSSEC then this option has no effect.
-+---------------+---------+------------------+--------------+
++-----------------------------------------------------------+
|dns_ipv4_lookup|Use: main|Type: domain list*|Default: unset|
-+---------------+---------+------------------+--------------+
++-----------------------------------------------------------+
When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks
for IPv6 address records (AAAA records) as well as IPv4 address records (A
not work for the AAAA record type. In due course, when the world's name servers
have all been upgraded, there should be no need for this option.
-+-----------+---------+----------+-----------+
++--------------------------------------------+
|dns_retrans|Use: main|Type: time|Default: 0s|
-+-----------+---------+----------+-----------+
++--------------------------------------------+
The options dns_retrans and dns_retry can be used to set the retransmission and
retry parameters for DNS lookups. Values of zero (the defaults) leave the
these settings affect the total time a DNS lookup may take. I haven't found any
documentation about timeouts on DNS lookups; these parameter values are
available in the external resolver interface structure, but nowhere does it
-seem to describe how they are used or what you might want to set in them.
+seem to describe how they are used or what you might want to set in them. See
+also the slow_lookup_log option.
-+---------+---------+-------------+----------+
++--------------------------------------------+
|dns_retry|Use: main|Type: integer|Default: 0|
-+---------+---------+-------------+----------+
++--------------------------------------------+
See dns_retrans above.
-+-------------+---------+-------------+-----------+
++--------------------------------------------------------+
+|dns_trust_aa|Use: main|Type: domain list*|Default: unset|
++--------------------------------------------------------+
+
+If this option is set then lookup results marked with the AA bit (Authoritative
+Answer) are trusted the same way as if they were DNSSEC-verified. The authority
+section's name of the answer must match with this expanded domain list.
+
+Use this option only if you talk directly to a resolver that is authoritative
+for some zones and does not set the AD (Authentic Data) bit in the answer. Some
+DNS servers may have an configuration option to mark the answers from their own
+zones as verified (they set the AD bit). Others do not have this option. It is
+considered as poor practice using a resolver that is an authoritative server
+for some zones.
+
+Use this option only if you really have to (e.g. if you want to use DANE for
+remote delivery to a server that is listed in the DNS zones that your resolver
+is authoritative for).
+
+If the DNS answer packet has the AA bit set and contains resource record in the
+answer section, the name of the first NS record appearing in the authority
+section is compared against the list. If the answer packet is authoritative but
+the answer section is empty, the name of the first SOA record in the
+authoritative section is used instead.
+
++-------------------------------------------------+
|dns_use_edns0|Use: main|Type: integer|Default: -1|
-+-------------+---------+-------------+-----------+
++-------------------------------------------------+
If this option is set to a non-negative number then Exim will initialise the
DNS resolver library to either use or not use EDNS0 extensions, overriding the
If the resolver library does not support EDNS0 then this option has no effect.
-+-------+---------+-------------+--------------+
+OpenBSD's asr resolver routines are known to ignore the EDNS0 option; this
+means that DNSSEC will not work with Exim on that platform either, unless Exim
+is linked against an alternative DNS client library.
+
++----------------------------------------------+
|drop_cr|Use: main|Type: boolean|Default: false|
-+-------+---------+-------------+--------------+
++----------------------------------------------+
This is an obsolete option that is now a no-op. It used to affect the way Exim
handled CR and LF characters in incoming messages. What happens now is
-described in section 46.2.
+described in section 47.2.
+
++-------------------------------------------------------------+
+|dsn_advertise_hosts|Use: main|Type: host list*|Default: unset|
++-------------------------------------------------------------+
+
+DSN extensions (RFC3461) will be advertised in the EHLO message to, and
+accepted from, these hosts. Hosts may use the NOTIFY and ENVID options on RCPT
+TO commands, and RET and ORCPT options on MAIL FROM commands. A NOTIFY=SUCCESS
+option requests success-DSN messages. A NOTIFY= option with no argument
+requests that no delay or failure DSNs are sent.
-+--------+---------+-------------+------------------+
++---------------------------------------------------+
|dsn_from|Use: main|Type: string*|Default: see below|
-+--------+---------+-------------+------------------+
++---------------------------------------------------+
This option can be used to vary the contents of From: header lines in bounces
and other automatically generated messages ("Delivery Status Notifications" -
The value is expanded every time it is needed. If the expansion fails, a panic
is logged, and the default value is used.
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
|envelope_to_remove|Use: main|Type: boolean|Default: true|
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
Exim's transports have an option for adding an Envelope-to: header to a message
when it is delivered, in exactly the same way as Return-path: is handled.
-Envelope-to: records the original recipient address from the messages's
-envelope that caused the delivery to happen. Such headers should not be present
-in incoming messages, and this option causes them to be removed at the time the
+Envelope-to: records the original recipient address from the message's envelope
+that caused the delivery to happen. Such headers should not be present in
+incoming messages, and this option causes them to be removed at the time the
message is received, to avoid any problems that might occur when a delivered
message is subsequently sent on to some other recipient.
-+-----------+---------+------------------+--------------+
++-------------------------------------------------------+
|errors_copy|Use: main|Type: string list*|Default: unset|
-+-----------+---------+------------------+--------------+
++-------------------------------------------------------+
Setting this option causes Exim to send bcc copies of bounce messages that it
generates to other addresses. Note: This does not apply to bounce messages
there was any wildcard matching in the pattern, the expansion variables $0, $1,
etc. are set in the normal way.
-+---------------+---------+------------+--------------+
++-----------------------------------------------------+
|errors_reply_to|Use: main|Type: string|Default: unset|
-+---------------+---------+------------+--------------+
++-----------------------------------------------------+
By default, Exim's bounce and delivery warning messages contain the header line
quota_warn_message option in an appendfile transport contain its own Reply-To:
header line, the value of the errors_reply_to option is not used.
-+----------+---------+------------+--------------------------------+
++---------------------------------------------------+
+|event_action|Use: main|Type: string*|Default: unset|
++---------------------------------------------------+
+
+This option declares a string to be expanded for Exim's events mechanism. For
+details see chapter 60.
+
++------------------------------------------------------------------+
|exim_group|Use: main|Type: string|Default: compile-time configured|
-+----------+---------+------------+--------------------------------+
++------------------------------------------------------------------+
This option changes the gid under which Exim runs when it gives up root
privilege. The default value is compiled into the binary. The value of this
option is used only when exim_user is also set. Unless it consists entirely of
digits, the string is looked up using getgrnam(), and failure causes a
-configuration error. See chapter 54 for a discussion of security issues.
+configuration error. See chapter 55 for a discussion of security issues.
-+---------+---------+------------+------------------+
++---------------------------------------------------+
|exim_path|Use: main|Type: string|Default: see below|
-+---------+---------+------------+------------------+
++---------------------------------------------------+
This option specifies the path name of the Exim binary, which is used when Exim
needs to re-exec itself. The default is set up to point to the file exim in the
where the binary is. (They then use the -bP option to extract option settings
such as the value of spool_directory.)
-+---------+---------+------------+--------------------------------+
++-----------------------------------------------------------------+
|exim_user|Use: main|Type: string|Default: compile-time configured|
-+---------+---------+------------+--------------------------------+
++-----------------------------------------------------------------+
This option changes the uid under which Exim runs when it gives up root
privilege. The default value is compiled into the binary. Ownership of the run
Unless it consists entirely of digits, the string is looked up using getpwnam()
, and failure causes a configuration error. If exim_group is not also supplied,
-the gid is taken from the result of getpwnam() if it is used. See chapter 54
+the gid is taken from the result of getpwnam() if it is used. See chapter 55
for a discussion of security issues.
-+----------------------+---------+-----------------+--------------+
++-----------------------------------------------------------------+
|extra_local_interfaces|Use: main|Type: string list|Default: unset|
-+----------------------+---------+-----------------+--------------+
++-----------------------------------------------------------------+
This option defines network interfaces that are to be considered local when
routing, but which are not used for listening by the daemon. See section 13.8
for details.
-+-------------------------------------+---------+-------------+-------------+
-|extract_addresses_remove_ arguments|Use: main|Type: boolean|Default: true|
-+-------------------------------------+---------+-------------+-------------+
++------------------------------------------------------------------------+
+|extract_addresses_remove_arguments|Use: main|Type: boolean|Default: true|
++------------------------------------------------------------------------+
According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses
are present on the command line when the -t option is used to build an envelope
argument headers. If it is set false, Exim adds rather than removes argument
addresses.
-+----------------+---------+-------------+----------+
++---------------------------------------------------+
|finduser_retries|Use: main|Type: integer|Default: 0|
-+----------------+---------+-------------+----------+
++---------------------------------------------------+
On systems running NIS or other schemes in which user and group information is
distributed from a remote system, there can be times when getpwnam() and
a traditional /etc/passwd file, because it will cause Exim needlessly to search
the file multiple times for non-existent users, and also cause delay.
-+-----------+---------+----------------------------------+--------------+
++-----------------------------------------------------------------------+
|freeze_tell|Use: main|Type: string list, comma separated|Default: unset|
-+-----------+---------+----------------------------------+--------------+
++-----------------------------------------------------------------------+
On encountering certain errors, or when configured to do so in a system filter,
ACL, or special router, Exim freezes a message. This means that no further
configure freezing in a filter or ACL, you must arrange for any logging that
you require.
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
|gecos_name|Use: main|Type: string*|Default: unset|
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
Some operating systems, notably HP-UX, use the "gecos" field in the system
password file to hold other information in addition to users' real names. Exim
gecos_pattern = ([^,]*)
gecos_name = $1
-+-------------+---------+------------+--------------+
++---------------------------------------------------+
|gecos_pattern|Use: main|Type: string|Default: unset|
-+-------------+---------+------------+--------------+
++---------------------------------------------------+
See gecos_name above.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|gnutls_compat_mode|Use: main|Type: boolean|Default: unset|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
This option controls whether GnuTLS is used in compatibility mode in an Exim
server. This reduces security slightly, but improves interworking with older
implementations of TLS.
-option gnutls_allow_auto_pkcs11 main boolean unset This option will let GnuTLS
-(2.12.0 or later) autoload PKCS11 modules with the p11-kit configuration files
-in /etc/pkcs11/modules/.
++---------------------------------------------------------------+
+|gnutls_allow_auto_pkcs11|Use: main|Type: boolean|Default: unset|
++---------------------------------------------------------------+
-See http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for
+This option will let GnuTLS (2.12.0 or later) autoload PKCS11 modules with the
+p11-kit configuration files in /etc/pkcs11/modules/.
+
+See https://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for
documentation.
-+---------------+---------+------------+------------------+
++---------------------------------------------------------+
|headers_charset|Use: main|Type: string|Default: see below|
-+---------------+---------+------------+------------------+
++---------------------------------------------------------+
This option sets a default character set for translating from encoded MIME
"words" in header lines, when referenced by an $h_xxx expansion item. The
is ISO-8859-1. For more details see the description of header insertions in
section 11.5.
-+--------------+---------+-------------+------------------+
++---------------------------------------------------------+
|header_maxsize|Use: main|Type: integer|Default: see below|
-+--------------+---------+-------------+------------------+
++---------------------------------------------------------+
This option controls the overall maximum size of a message's header section.
The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for
that is 1M. Messages with larger header sections are rejected.
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
|header_line_maxsize|Use: main|Type: integer|Default: 0|
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
This option limits the length of any individual header line in a message, after
all the continuations have been joined together. Messages with individual
header lines that are longer than the limit are rejected. The default value of
zero means "no limit".
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
|helo_accept_junk_hosts|Use: main|Type: host list*|Default: unset|
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and
gives an error response for invalid data. Unfortunately, there are some SMTP
want to do semantic checking. See also helo_allow_chars for a way of extending
the permitted character set.
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
|helo_allow_chars|Use: main|Type: string|Default: unset|
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
This option can be set to a string of rogue characters that are permitted in
all EHLO and HELO names in addition to the standard letters, digits, hyphens,
Note that the value is one string, not a list.
-+-------------------+---------+------------------+----------------+
++-----------------------------------------------------------------+
|helo_lookup_domains|Use: main|Type: domain list*|Default: "@:@[]"|
-+-------------------+---------+------------------+----------------+
++-----------------------------------------------------------------+
If the domain given by a client in a HELO or EHLO command matches this list, a
reverse lookup is done in order to establish the host's true name. The default
forces a lookup if the client host gives the server's name or any of its IP
addresses (in brackets), something that broken clients have been seen to do.
-+---------------------+---------+----------------+--------------+
++---------------------------------------------------------------+
|helo_try_verify_hosts|Use: main|Type: host list*|Default: unset|
-+---------------------+---------+----------------+--------------+
++---------------------------------------------------------------+
By default, Exim just checks the syntax of HELO and EHLO commands (see
helo_accept_junk_hosts and helo_allow_chars). However, some sites like to do
* matches the host name that Exim obtains by doing a reverse lookup of the
calling host address, or
- * when looked up using gethostbyname() (or getipnodebyname() when available)
- yields the calling host address.
+ * when looked up in DNS yields the calling host address.
However, the EHLO or HELO command is not rejected if any of the checks fail.
Processing continues, but the result of the check is remembered, and can be
detected later in an ACL by the "verify = helo" condition.
-+-----------------+---------+----------------+--------------+
+If DNS was used for successful verification, the variable $helo_verify_dnssec
+records the DNSSEC status of the lookups.
+
++-----------------------------------------------------------+
|helo_verify_hosts|Use: main|Type: host list*|Default: unset|
-+-----------------+---------+----------------+--------------+
++-----------------------------------------------------------+
Like helo_try_verify_hosts, this option is obsolete, and retained only for
backwards compatibility. For hosts that match this option, Exim checks the host
entries are written to the main and reject logs. If a MAIL command is received
before EHLO or HELO, it is rejected with a 503 error.
-+------------+---------+------------------+--------------+
++--------------------------------------------------------+
|hold_domains|Use: main|Type: domain list*|Default: unset|
-+------------+---------+------------------+--------------+
++--------------------------------------------------------+
-This option allows mail for particular domains to be held on the queue
+This option allows mail for particular domains to be held in the queue
manually. The option is overridden if a message delivery is forced with the -M,
-qf, -Rf or -Sf options, and also while testing or verifying addresses using
-bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing
any retry rule. If you want to hold messages for longer than the normal retry
times, insert a dummy retry rule with a long retry time.
-+-----------+---------+----------------+--------------+
++-----------------------------------------------------+
|host_lookup|Use: main|Type: host list*|Default: unset|
-+-----------+---------+----------------+--------------+
++-----------------------------------------------------+
Exim does not look up the name of a calling host from its IP address unless it
is required to compare against some host list, or the host matches
dns_again_means_nonexist, helo_lookup_domains, and "verify =
reverse_host_lookup" in ACLs.
-+-----------------+---------+-----------------+-----------------------+
++---------------------------------------------------------------------+
|host_lookup_order|Use: main|Type: string list|Default: "bydns:byaddr"|
-+-----------------+---------+-----------------+-----------------------+
++---------------------------------------------------------------------+
This option specifies the order of different lookup methods when Exim is trying
to find a host name from an IP address. The default is to do a DNS lookup
Different operating systems give different results in this case. That is why
the default tries a DNS lookup first.
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
|host_reject_connection|Use: main|Type: host list*|Default: unset|
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
If this option is set, incoming SMTP calls from the hosts listed are rejected
as soon as the connection is made. This option is obsolete, and retained only
The ability to give an immediate rejection (either by this option or using an
ACL) is provided for use in unusual cases. Many hosts will just try again,
sometimes without much delay. Normally, it is better to use an ACL to reject
-incoming messages at a later stage, such as after RCPT commands. See chapter 42
+incoming messages at a later stage, such as after RCPT commands. See chapter 43
.
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
|hosts_connection_nolog|Use: main|Type: host list*|Default: unset|
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
This option defines a list of hosts for which connection logging does not
happen, even though the smtp_connection log selector is set. For example, you
If the smtp_connection log selector is not set, this option has no effect.
-+--------------------+---------+------------------+--------------+
++-----------------------------------------------------+
+|hosts_proxy|Use: main|Type: host list*|Default: unset|
++-----------------------------------------------------+
+
+This option enables use of Proxy Protocol proxies for incoming connections. For
+details see section 58.1.
+
++----------------------------------------------------------------+
|hosts_treat_as_local|Use: main|Type: domain list*|Default: unset|
-+--------------------+---------+------------------+--------------+
++----------------------------------------------------------------+
If this option is set, any host names that match the domain list are treated as
if they were the local host when Exim is scanning host lists obtained from MX
extra_local_interfaces, and chapter 13, which contains a discussion about local
network interfaces and recognizing the local host.
-+-------------+---------+-----------------+--------------+
++--------------------------------------------------------+
|ibase_servers|Use: main|Type: string list|Default: unset|
-+-------------+---------+-----------------+--------------+
++--------------------------------------------------------+
This option provides a list of InterBase servers and associated connection
-data, to be used in conjunction with ibase lookups (see section 9.21). The
+data, to be used in conjunction with ibase lookups (see section 9.22). The
option is available only if Exim has been built with InterBase support.
-+--------------------------+---------+----------+------------+
++------------------------------------------------------------+
|ignore_bounce_errors_after|Use: main|Type: time|Default: 10w|
-+--------------------------+---------+----------+------------+
++------------------------------------------------------------+
This option affects the processing of bounce messages that cannot be delivered,
that is, those that suffer a permanent delivery failure. (Bounce messages that
After a permanent delivery failure, bounce messages are frozen, because there
is no sender to whom they can be returned. When a frozen bounce message has
-been on the queue for more than the given time, it is unfrozen at the next
+been in the queue for more than the given time, it is unfrozen at the next
queue run, and a further delivery is attempted. If delivery fails again, the
bounce message is discarded. This makes it possible to keep failed bounce
messages around for a shorter time than the normal maximum retry time for
dealing with other kinds of frozen message, see auto_thaw and
timeout_frozen_after.
-+---------------------+---------+----------------+--------------+
++---------------------------------------------------------------+
|ignore_fromline_hosts|Use: main|Type: host list*|Default: unset|
-+---------------------+---------+----------------+--------------+
++---------------------------------------------------------------+
Some broken SMTP clients insist on sending a UUCP-like "From " line before the
headers of a message. By default this is treated as the start of the message's
than a remote host, and is using -bs to inject the messages,
ignore_fromline_local must be set to achieve this effect.
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
|ignore_fromline_local|Use: main|Type: boolean|Default: false|
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
See ignore_fromline_hosts above.
-+----------------+---------+-----------------+--------------+
++-----------------------------------------------------------+
|keep_environment|Use: main|Type: string list|Default: unset|
-+----------------+---------+-----------------+--------------+
++-----------------------------------------------------------+
This option contains a string list of environment variables to keep. You have
to trust these variables or you have to be sure that these variables do not
You may work around this using a regular expression that does not match the
macro name: ^[F]OO_HOME$.
-Current versions of Exim issue a warning during startupif you do not mention
-keep_environment or add_environment in your runtime configuration file.
+Current versions of Exim issue a warning during startup if you do not mention
+keep_environment in your runtime configuration file and if your current
+environment is not empty. Future versions may not issue that warning anymore.
-+--------------+---------+----------+-----------+
+See the add_environment main config option for a way to set environment
+variables to a fixed value. The environment for pipe transports is handled
+separately, see section 29.4 for details.
+
++-----------------------------------------------+
|keep_malformed|Use: main|Type: time|Default: 4d|
-+--------------+---------+----------+-----------+
++-----------------------------------------------+
This option specifies the length of time to keep messages whose spool files
have been corrupted in some way. This should, of course, never happen. At the
next attempt to deliver such a message, it gets removed. The incident is
logged.
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
|ldap_ca_cert_dir|Use: main|Type: string|Default: unset|
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
This option indicates which directory contains CA certificates for verifying a
TLS certificate presented by an LDAP server. While Exim does not provide a
default value, your SSL library may. Analogous to tls_verify_certificates but
as a client-side option for LDAP and constrained to be a directory.
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
|ldap_ca_cert_file|Use: main|Type: string|Default: unset|
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
This option indicates which file contains CA certificates for verifying a TLS
certificate presented by an LDAP server. While Exim does not provide a default
value, your SSL library may. Analogous to tls_verify_certificates but as a
client-side option for LDAP and constrained to be a file.
-+--------------+---------+------------+--------------+
++----------------------------------------------------+
|ldap_cert_file|Use: main|Type: string|Default: unset|
-+--------------+---------+------------+--------------+
++----------------------------------------------------+
This option indicates which file contains an TLS client certificate which Exim
should present to the LDAP server during TLS negotiation. Should be used
together with ldap_cert_key.
-+-------------+---------+------------+--------------+
++---------------------------------------------------+
|ldap_cert_key|Use: main|Type: string|Default: unset|
-+-------------+---------+------------+--------------+
++---------------------------------------------------+
This option indicates which file contains the secret/private key to use to
prove identity to the LDAP server during TLS negotiation. Should be used
together with ldap_cert_file, which contains the identity to be proven.
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
|ldap_cipher_suite|Use: main|Type: string|Default: unset|
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
This controls the TLS cipher-suite negotiation during TLS negotiation with the
-LDAP server. See 41.4 for more details of the format of cipher-suite options
+LDAP server. See 42.4 for more details of the format of cipher-suite options
with OpenSSL (as used by LDAP client libraries).
-+--------------------+---------+-----------------+--------------+
++---------------------------------------------------------------+
|ldap_default_servers|Use: main|Type: string list|Default: unset|
-+--------------------+---------+-----------------+--------------+
++---------------------------------------------------------------+
This option provides a list of LDAP servers which are tried in turn when an
-LDAP query does not contain a server. See section 9.14 for details of LDAP
+LDAP query does not contain a server. See section 9.15 for details of LDAP
queries. This option is available only when Exim has been built with LDAP
support.
-+-----------------+---------+------------+---------------+
++--------------------------------------------------------+
|ldap_require_cert|Use: main|Type: string|Default: unset.|
-+-----------------+---------+------------+---------------+
++--------------------------------------------------------+
This should be one of the values "hard", "demand", "allow", "try" or "never". A
value other than one of these is interpreted as "never". See the entry
"TLS_REQCERT" in your system man page for ldap.conf(5). Although Exim does not
set a default, the LDAP library probably defaults to hard/demand.
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
|ldap_start_tls|Use: main|Type: boolean|Default: false|
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
If set, Exim will attempt to negotiate TLS with the LDAP server when connecting
on a regular LDAP port. This is the LDAP equivalent of SMTP's "STARTTLS". This
is distinct from using "ldaps", which is the LDAP form of SSL-on-connect. In
the event of failure to negotiate TLS, the action taken is controlled by
-ldap_require_cert.
+ldap_require_cert. This option is ignored for "ldapi" connections.
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
|ldap_version|Use: main|Type: integer|Default: unset|
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
This option can be used to force Exim to set a specific protocol version for
LDAP. If it option is unset, it is shown by the -bP command line option as -1.
headers; otherwise it is 2. This option is available only when Exim has been
built with LDAP support.
-+----------------+---------+-------------+-------------+
++------------------------------------------------------+
|local_from_check|Use: main|Type: boolean|Default: true|
-+----------------+---------+-------------+-------------+
++------------------------------------------------------+
When a message is submitted locally (that is, not over a TCP/IP connection) by
an untrusted user, Exim removes any existing Sender: header line, and checks
untrusted_set_sender permits the user to supply an envelope sender.
For messages received over TCP/IP, an ACL can specify "submission mode" to
-request similar header line checking. See section 46.16, which has more details
+request similar header line checking. See section 47.16, which has more details
about Sender: processing.
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
|local_from_prefix|Use: main|Type: string|Default: unset|
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
When Exim checks the From: header line of locally submitted messages for
matching the login id (see local_from_check above), it can be configured to
the actual sender address that is constructed from the login name and qualify
domain.
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
|local_from_suffix|Use: main|Type: string|Default: unset|
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
See local_from_prefix above.
-+----------------+---------+-----------------+------------------+
++---------------------------------------------------------------+
|local_interfaces|Use: main|Type: string list|Default: see below|
-+----------------+---------+-----------------+------------------+
++---------------------------------------------------------------+
This option controls which network interfaces are used by the daemon for
listening; they are also used to identify the local host when routing. Chapter
local_interfaces = <; ::0 ; 0.0.0.0
-+------------------+---------+----------+-----------+
++---------------------------------------------------+
|local_scan_timeout|Use: main|Type: time|Default: 5m|
-+------------------+---------+----------+-----------+
++---------------------------------------------------+
-This timeout applies to the local_scan() function (see chapter 44). Zero means
+This timeout applies to the local_scan() function (see chapter 45). Zero means
"no timeout". If the timeout is exceeded, the incoming message is rejected with
a temporary error if it is an SMTP message. For a non-SMTP message, the message
is dropped and Exim ends with a non-zero code. The incident is logged on the
main and reject logs.
-+-------------------+---------+-------------+--------------+
++----------------------------------------------------------+
|local_sender_retain|Use: main|Type: boolean|Default: false|
-+-------------------+---------+-------------+--------------+
++----------------------------------------------------------+
When a message is submitted locally (that is, not over a TCP/IP connection) by
an untrusted user, Exim removes any existing Sender: header line. If you do not
want this to happen, you must set local_sender_retain, and you must also set
local_from_check to be false (Exim will complain if you do not). See also the
-ACL modifier "control = suppress_local_fixups". Section 46.16 has more details
+ACL modifier "control = suppress_local_fixups". Section 47.16 has more details
about Sender: processing.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|localhost_number|Use: main|Type: string*|Default: unset|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
Exim's message ids are normally unique only within the local host. If
uniqueness among a set of hosts is required, each host must set a different
the message id, instead of just being a fractional part of the time, are
computed from the time and the local host number as described in section 3.4.
-+-------------+---------+------------------+----------------------------+
++-----------------------------------------------------------------------+
|log_file_path|Use: main|Type: string list*|Default: set at compile time|
-+-------------+---------+------------------+----------------------------+
++-----------------------------------------------------------------------+
This option sets the path which is used to determine the names of Exim's log
files, or indicates that logging is to be to syslog, or both. It is expanded
when Exim is entered, so it can, for example, contain a reference to the host
-name. If no specific path is set for the log files at compile or run time, they
-are written in a sub-directory called log in Exim's spool directory. Chapter 51
-contains further details about Exim's logging, and section 51.1 describes how
-the contents of log_file_path are used. If this string is fixed at your
-installation (contains no expansion variables) it is recommended that you do
-not set this option in the configuration file, but instead supply the path
-using LOG_FILE_PATH in Local/Makefile so that it is available to Exim for
-logging errors detected early on - in particular, failure to read the
-configuration file.
-
-+------------+---------+------------+--------------+
+name. If no specific path is set for the log files at compile or runtime, or if
+the option is unset at runtime (i.e. "log_file_path = ") they are written in a
+sub-directory called log in Exim's spool directory. Chapter 52 contains further
+details about Exim's logging, and section 52.1 describes how the contents of
+log_file_path are used. If this string is fixed at your installation (contains
+no expansion variables) it is recommended that you do not set this option in
+the configuration file, but instead supply the path using LOG_FILE_PATH in
+Local/Makefile so that it is available to Exim for logging errors detected
+early on - in particular, failure to read the configuration file.
+
++--------------------------------------------------+
|log_selector|Use: main|Type: string|Default: unset|
-+------------+---------+------------+--------------+
++--------------------------------------------------+
This option can be used to reduce or increase the number of things that Exim
writes to its log files. Its argument is made up of names preceded by plus or
log_selector = +arguments -retry_defer
A list of possible names and what they control is given in the chapter on
-logging, in section 51.15.
+logging, in section 52.15.
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
|log_timezone|Use: main|Type: boolean|Default: false|
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
By default, the timestamps on log lines are in local time without the timezone.
This means that if your timezone changes twice a year, the timestamps in log
$tod_log variable contains the log timestamp without the zone, but there is
another variable called $tod_zone that contains just the timezone offset.
-+---------------+---------+-------------+-----------+
++---------------------------------------------------+
|lookup_open_max|Use: main|Type: integer|Default: 25|
-+---------------+---------+-------------+-----------+
++---------------------------------------------------+
This option limits the number of simultaneously open files for single-key
lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally
of lookup_open_max. If you are getting "too many open files" errors with NDBM,
you need to reduce the value of lookup_open_max.
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
|max_username_length|Use: main|Type: integer|Default: 0|
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
Some operating systems are broken in that they truncate long arguments to
getpwnam() to eight characters, instead of returning "no such user". If this
option is set greater than zero, any attempt to call getpwnam() with an
argument that is longer behaves as if getpwnam() failed.
-+---------------------+---------+----------+--------------+
++---------------------------------------------------------+
|message_body_newlines|Use: main|Type: bool|Default: false|
-+---------------------+---------+----------+--------------+
++---------------------------------------------------------+
By default, newlines in the message body are replaced by spaces when setting
the $message_body and $message_body_end expansion variables. If this option is
set true, this no longer happens.
-+--------------------+---------+-------------+------------+
++---------------------------------------------------------+
|message_body_visible|Use: main|Type: integer|Default: 500|
-+--------------------+---------+-------------+------------+
++---------------------------------------------------------+
This option specifies how much of a message's body is to be included in the
$message_body and $message_body_end expansion variables.
-+------------------------+---------+-------------+--------------+
++---------------------------------------------------------------+
|message_id_header_domain|Use: main|Type: string*|Default: unset|
-+------------------------+---------+-------------+--------------+
++---------------------------------------------------------------+
If this option is set, the string is expanded and used as the right hand side
(domain) of the Message-ID: header that Exim creates if a locally-originated
the expansion is forced to fail, or if the result is an empty string, the
option is ignored.
-+----------------------+---------+-------------+--------------+
++-------------------------------------------------------------+
|message_id_header_text|Use: main|Type: string*|Default: unset|
-+----------------------+---------+-------------+--------------+
++-------------------------------------------------------------+
If this variable is set, the string is expanded and used to augment the text of
the Message-id: header that Exim creates if a locally-originated incoming
means that variables such as $tod_log can be used, because the spaces and
colons will become hyphens.
-+------------+---------+-------------+-------------+
++--------------------------------------------------+
|message_logs|Use: main|Type: boolean|Default: true|
-+------------+---------+-------------+-------------+
++--------------------------------------------------+
If this option is turned off, per-message log files are not created in the
msglog spool sub-directory. This reduces the amount of disk I/O required by
per-message log) to three. The other major I/O activity is Exim's main log,
which is not affected by this option.
-+------------------+---------+-------------+------------+
++-------------------------------------------------------+
|message_size_limit|Use: main|Type: string*|Default: 50M|
-+------------------+---------+-------------+------------+
++-------------------------------------------------------+
This option limits the maximum size of message that Exim will process. The
value is expanded for each incoming connection so, for example, it can be made
maximum size that your virus-scanner is configured to support, you may get
failures triggered by large mails. The right size to configure for the
virus-scanner depends upon what data is passed and the options in use but it's
-probably safest to just set it to a little larger than this value. Eg, with a
+probably safest to just set it to a little larger than this value. E.g., with a
default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
some problems may result.
SIZE extension in an EHLO response, but without a limit, so as to permit SMTP
clients to still indicate the message size along with the MAIL verb.
-+--------------------+---------+-------------+--------------+
++-----------------------------------------------------------+
|move_frozen_messages|Use: main|Type: boolean|Default: false|
-+--------------------+---------+-------------+--------------+
++-----------------------------------------------------------+
This option, which is available only if Exim has been built with the setting
for handling such moved messages, and they do not show up in lists generated by
-bp or by the Exim monitor.
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
|mua_wrapper|Use: main|Type: boolean|Default: false|
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
Setting this option true causes Exim to run in a very restrictive mode in which
-it passes messages synchronously to a smart host. Chapter 50 contains a full
+it passes messages synchronously to a smart host. Chapter 51 contains a full
description of this facility.
-+-------------+---------+-----------------+--------------+
++--------------------------------------------------------+
|mysql_servers|Use: main|Type: string list|Default: unset|
-+-------------+---------+-----------------+--------------+
++--------------------------------------------------------+
This option provides a list of MySQL servers and associated connection data, to
-be used in conjunction with mysql lookups (see section 9.21). The option is
+be used in conjunction with mysql lookups (see section 9.22). The option is
available only if Exim has been built with MySQL support.
-+-----------+---------+------------------+--------------+
++-------------------------------------------------------+
|never_users|Use: main|Type: string list*|Default: unset|
-+-----------+---------+------------------+--------------+
++-------------------------------------------------------+
This option is expanded just once, at the start of Exim's processing. Local
message deliveries are normally run in processes that are setuid to the
harm. This option overrides the pipe_as_creator option of the pipe transport
driver.
-+---------------+---------+-----------------+------------------+
-|openssl_options|Use: main|Type: string list|Default: +no_sslv2|
-+---------------+---------+-----------------+------------------+
++-----------------------------------------------------------------------------+
+|openssl_options| Use: | Type: string | Default: +no_sslv2 +single_dh_use|
+| | main | list | +no_ticket|
++-----------------------------------------------------------------------------+
This option allows an administrator to adjust the SSL options applied by
OpenSSL to connections. It is given as a space-separated list of items, each
lightly. An unrecognised item will be detected at startup, by invoking Exim
with the -bV flag.
+The option affects Exim operating both as a server and as a client.
+
Historical note: prior to release 4.80, Exim defaulted this value to
"+dont_insert_empty_fragments", which may still be needed for compatibility
with some clients, but which lowers security by increasing exposure to some now
infamous attacks.
-An example:
+Examples:
# Make both old MS and old Eudora happy:
openssl_options = -all +microsoft_big_sslv3_buffer \
+dont_insert_empty_fragments
+# Disable older protocol versions:
+openssl_options = +no_sslv2 +no_sslv3
+
Possible options may include:
* "all"
release is new enough to contain this work-around. This may be a situation
where you have to upgrade OpenSSL to get buggy clients working.
-+--------------+---------+-----------------+--------------+
++---------------------------------------------------------+
|oracle_servers|Use: main|Type: string list|Default: unset|
-+--------------+---------+-----------------+--------------+
++---------------------------------------------------------+
This option provides a list of Oracle servers and associated connection data,
-to be used in conjunction with oracle lookups (see section 9.21). The option is
+to be used in conjunction with oracle lookups (see section 9.22). The option is
available only if Exim has been built with Oracle support.
-+--------------------+---------+------------------+--------------+
++----------------------------------------------------------------+
|percent_hack_domains|Use: main|Type: domain list*|Default: unset|
-+--------------------+---------+------------------+--------------+
++----------------------------------------------------------------+
The "percent hack" is the convention whereby a local part containing a percent
sign is re-interpreted as a new email address, with the percent replaced by @.
to reject recipient addresses with percent characters in their local parts.
Exim's default configuration does this.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|perl_at_start|Use: main|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option is available only when Exim is built with an embedded Perl
interpreter. See chapter 12 for details of its use.
-+------------+---------+------------+--------------+
++--------------------------------------------------+
|perl_startup|Use: main|Type: string|Default: unset|
-+------------+---------+------------+--------------+
++--------------------------------------------------+
This option is available only when Exim is built with an embedded Perl
interpreter. See chapter 12 for details of its use.
-+-------------+---------+-----------------+--------------+
++---------------------------------------------------+
+|perl_startup|Use: main|Type: boolean|Default: false|
++---------------------------------------------------+
+
+This Option enables the taint mode of the embedded Perl interpreter.
+
++--------------------------------------------------------+
|pgsql_servers|Use: main|Type: string list|Default: unset|
-+-------------+---------+-----------------+--------------+
++--------------------------------------------------------+
This option provides a list of PostgreSQL servers and associated connection
-data, to be used in conjunction with pgsql lookups (see section 9.21). The
+data, to be used in conjunction with pgsql lookups (see section 9.22). The
option is available only if Exim has been built with PostgreSQL support.
-+-------------+---------+-------------+----------------------------+
++------------------------------------------------------------------+
|pid_file_path|Use: main|Type: string*|Default: set at compile time|
-+-------------+---------+-------------+----------------------------+
++------------------------------------------------------------------+
This option sets the name of the file to which the Exim daemon writes its
process id. The string is expanded, so it can contain, for example, references
command line option. A pid file is not written if a "non-standard" daemon is
run by means of the -oX option, unless a path is explicitly supplied by -oP.
-+--------------------------+---------+----------------+----------+
++----------------------------------------------------------------+
|pipelining_advertise_hosts|Use: main|Type: host list*|Default: *|
-+--------------------------+---------+----------------+----------+
++----------------------------------------------------------------+
This option can be used to suppress the advertisement of the SMTP PIPELINING
extension to specific hosts. See also the no_pipelining control in section
-42.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim
+43.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim
server enforces strict synchronization for each SMTP command and response. When
PIPELINING is advertised, Exim assumes that clients will use it; "out of order"
commands that are "expected" do not count as protocol errors (see
smtp_max_synprot_errors).
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
|prdr_enable|Use: main|Type: boolean|Default: false|
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
This option can be used to enable the Per-Recipient Data Response extension to
SMTP, defined by Eric Hall. If the option is set, PRDR is advertised by Exim
when operating as a server. If the client requests PRDR, and more than one
recipient, for a message an additional ACL is called for each recipient after
-the message content is recieved. See section 42.9.
+the message content is received. See section 43.9.
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
|preserve_message_logs|Use: main|Type: boolean|Default: false|
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
If this option is set, message log files are not deleted when messages are
completed. Instead, they are moved to a sub-directory of the spool directory
purposes. This is a dangerous option to set on systems with any appreciable
volume of mail. Use with care!
-+----------------+---------+------------+------------------+
++----------------------------------------------------------+
|primary_hostname|Use: main|Type: string|Default: see below|
-+----------------+---------+------------+------------------+
++----------------------------------------------------------+
This specifies the name of the current host. It is used in the default EHLO or
HELO command for outgoing SMTP messages (changeable via the helo_data option in
$primary_hostname contains the host name, whether set explicitly by this
option, or defaulted.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|print_topbitchars|Use: main|Type: boolean|Default: false|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
By default, Exim considers only those characters whose codes lie in the range
32-126 to be printing characters. In a number of circumstances (for example,
This option also affects the header syntax checks performed by the autoreply
transport, and whether Exim uses RFC 2047 encoding of the user's full name when
-constructing From: and Sender: addresses (as described in section 46.18).
+constructing From: and Sender: addresses (as described in section 47.18).
Setting this option can cause Exim to generate eight bit message headers that
do not conform to the standards.
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
|process_log_path|Use: main|Type: string|Default: unset|
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
This option sets the name of the file to which an Exim process writes its
"process log" when sent a USR1 signal. This is used by the exiwhat utility
useful in environments where two different Exims are running, using different
spool directories.
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
|prod_requires_admin|Use: main|Type: boolean|Default: true|
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
The -M, -R, and -q command-line options require the caller to be an admin user
-unless prod_requires_admin is set false. See also queue_list_requires_admin.
+unless prod_requires_admin is set false. See also queue_list_requires_admin and
+commandline_checks_require_admin.
-+--------------+---------+------------+------------------+
++--------------------------------------------------------+
|qualify_domain|Use: main|Type: string|Default: see below|
-+--------------+---------+------------+------------------+
++--------------------------------------------------------+
This option specifies the domain name that is added to any envelope sender
addresses that do not have a domain qualification. It also applies to recipient
Internally, Exim always works with fully qualified envelope addresses. If
qualify_domain is not set, it defaults to the primary_hostname value.
-+-----------------+---------+------------+------------------+
++-----------------------------------------------------------+
|qualify_recipient|Use: main|Type: string|Default: see below|
-+-----------------+---------+------------+------------------+
++-----------------------------------------------------------+
This option allows you to specify a different domain for qualifying recipient
addresses to the one that is used for senders. See qualify_domain above.
-+-------------+---------+------------------+--------------+
++---------------------------------------------------------+
|queue_domains|Use: main|Type: domain list*|Default: unset|
-+-------------+---------+------------------+--------------+
++---------------------------------------------------------+
This option lists domains for which immediate delivery is not required. A
delivery process is started whenever a message is received, but only those
domains that do not match are processed. All other deliveries wait until the
next queue run. See also hold_domains and queue_smtp_domains.
-+-------------------------+---------+-------------+-------------+
++---------------------------------------------------------------+
|queue_list_requires_admin|Use: main|Type: boolean|Default: true|
-+-------------------------+---------+-------------+-------------+
++---------------------------------------------------------------+
The -bp command-line option, which lists the messages that are on the queue,
requires the caller to be an admin user unless queue_list_requires_admin is set
-false. See also prod_requires_admin.
+false. See also prod_requires_admin and commandline_checks_require_admin.
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
|queue_only|Use: main|Type: boolean|Default: false|
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
If queue_only is set, a delivery process is not automatically started whenever
-a message is received. Instead, the message waits on the queue for the next
+a message is received. Instead, the message waits in the queue for the next
queue run. Even if queue_only is false, incoming messages may not get delivered
immediately when certain conditions (such as heavy load) occur.
command line options override queue_only unless queue_only_override is set
false. See also queue_only_file, queue_only_load, and smtp_accept_queue.
-+---------------+---------+------------+--------------+
++-----------------------------------------------------+
|queue_only_file|Use: main|Type: string|Default: unset|
-+---------------+---------+------------+--------------+
++-----------------------------------------------------+
This option can be set to a colon-separated list of absolute path names, each
one optionally preceded by "smtp". When Exim is receiving a message, it tests
causes Exim to behave as if queue_smtp_domains were set to "*" whenever /some/
file exists.
-+---------------+---------+-----------------+--------------+
++----------------------------------------------------------+
|queue_only_load|Use: main|Type: fixed-point|Default: unset|
-+---------------+---------+-----------------+--------------+
++----------------------------------------------------------+
If the system load average is higher than this value, incoming messages from
all sources are queued, and no automatic deliveries are started. If this
determine the load average. See also deliver_queue_load_max and
smtp_load_reserve.
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------+
|queue_only_load_latch|Use: main|Type: boolean|Default: true|
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------+
When this option is true (the default), once one message has been queued
because the load average is higher than the value set by queue_only_load, all
should be set false. This causes the value of the load average to be
re-evaluated for each message.
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
|queue_only_override|Use: main|Type: boolean|Default: true|
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
When this option is true, the -odx command line options override the setting of
queue_only or queue_only_file in the configuration file. If queue_only_override
is set false, the -odx options cannot be used to override; they are accepted,
but ignored.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|queue_run_in_order|Use: main|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
If this option is set, queue runs happen in order of message arrival instead of
in an arbitrary order. For this to happen, a complete list of the entire queue
queue is large, because of the extra work in setting up the single, large list.
In most situations, queue_run_in_order should not be set.
-+-------------+---------+-------------+----------+
-|queue_run_max|Use: main|Type: integer|Default: 5|
-+-------------+---------+-------------+----------+
++-------------------------------------------------+
+|queue_run_max|Use: main|Type: integer*|Default: 5|
++-------------------------------------------------+
This controls the maximum number of queue runner processes that an Exim daemon
can run simultaneously. This does not mean that it starts them all at once, but
run. If you do not want queue runs to occur, omit the -qxx setting on the
daemon's command line.
-+------------------+---------+------------------+--------------+
+To set limits for different named queues use an expansion depending on the
+$queue_name variable.
+
++--------------------------------------------------------------+
|queue_smtp_domains|Use: main|Type: domain list*|Default: unset|
-+------------------+---------+------------------+--------------+
++--------------------------------------------------------------+
When this option is set, a delivery process is started whenever a message is
received, routing is performed, and local deliveries take place. However, if
any SMTP deliveries are required for domains that match queue_smtp_domains,
-they are not immediately delivered, but instead the message waits on the queue
+they are not immediately delivered, but instead the message waits in the queue
for the next queue run. Since routing of the message has taken place, Exim
knows to which remote hosts it must be delivered, and so when the queue run
happens, multiple messages for the same host are delivered over a single SMTP
queued in this way, and is equivalent to setting queue_smtp_domains to "*". See
also hold_domains and queue_domains.
-+---------------+---------+----------+-----------+
++------------------------------------------------+
|receive_timeout|Use: main|Type: time|Default: 0s|
-+---------------+---------+----------+-----------+
++------------------------------------------------+
This option sets the timeout for accepting a non-SMTP message, that is, the
maximum time that Exim waits when reading a message on the standard input. If
-the value is zero, it will wait for ever. This setting is overridden by the -or
+the value is zero, it will wait forever. This setting is overridden by the -or
command line option. The timeout for incoming SMTP messages is controlled by
smtp_receive_timeout.
-+--------------------+---------+-------------+------------------+
++---------------------------------------------------------------+
|received_header_text|Use: main|Type: string*|Default: see below|
-+--------------------+---------+-------------+------------------+
++---------------------------------------------------------------+
This string defines the contents of the Received: message header that is added
to each message, except for the timestamp, which is automatically added on at
checks have taken place, the timestamp is updated to the time at which the
message was accepted.
-+--------------------+---------+-------------+-----------+
++--------------------------------------------------------+
|received_headers_max|Use: main|Type: integer|Default: 30|
-+--------------------+---------+-------------+-----------+
++--------------------------------------------------------+
When a message is to be delivered, the number of Received: headers is counted,
and if it is greater than this parameter, a mail loop is assumed to have
occurred, the delivery is abandoned, and an error message is generated. This
applies to both local and remote deliveries.
-+---------------------------+---------+----------------+--------------+
++---------------------------------------------------------------------+
|recipient_unqualified_hosts|Use: main|Type: host list*|Default: unset|
-+---------------------------+---------+----------------+--------------+
++---------------------------------------------------------------------+
This option lists those hosts from which Exim is prepared to accept unqualified
recipient addresses in message envelopes. The addresses are made fully
host that matches recipient_unqualified_hosts, or if the message was submitted
locally (not using TCP/IP), and the -bnq option was not set.
-+--------------+---------+-------------+----------+
++-------------------------------------------------+
|recipients_max|Use: main|Type: integer|Default: 0|
-+--------------+---------+-------------+----------+
++-------------------------------------------------+
If this option is set greater than zero, it specifies the maximum number of
original recipients for any message. Additional recipients that are generated
Note: The RFCs specify that an SMTP server should accept at least 100 RCPT
commands in a single message.
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
|recipients_max_reject|Use: main|Type: boolean|Default: false|
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
If this option is set true, Exim rejects SMTP messages containing too many
recipients by giving 552 errors to the surplus RCPT commands, and a 554 error
of recipients. The remote server should then re-send the message for the
remaining recipients at a later time.
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
|remote_max_parallel|Use: main|Type: integer|Default: 2|
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
This option controls parallel delivery of one message to a number of remote
hosts. If the value is less than 2, parallel delivery is disabled, and Exim
before queueing, so that several messages for the same host will eventually get
delivered down the same connection.
-+-------------------+---------+------------------+--------------+
++---------------------------------------------------------------+
|remote_sort_domains|Use: main|Type: domain list*|Default: unset|
-+-------------------+---------+------------------+--------------+
++---------------------------------------------------------------+
When there are a number of remote deliveries for a message, they are sorted by
domain into the order given by this list. For example,
would attempt to deliver to all addresses in the cam.ac.uk domain first, then
to those in the uk domain, then to any others.
-+-----------------+---------+----------+-----------+
++--------------------------------------------------+
|retry_data_expire|Use: main|Type: time|Default: 7d|
-+-----------------+---------+----------+-----------+
++--------------------------------------------------+
This option sets a "use before" time on retry information in Exim's hints
database. Any older retry data is ignored. This means that, for example, once a
host has not been tried for 7 days, Exim behaves as if it has no knowledge of
past failures.
-+------------------+---------+----------+------------+
++----------------------------------------------------+
|retry_interval_max|Use: main|Type: time|Default: 24h|
-+------------------+---------+----------+------------+
++----------------------------------------------------+
Chapter 32 describes Exim's mechanisms for controlling the intervals between
delivery attempts for messages that cannot be delivered straight away. This
option sets an overall limit to the length of time between retries. It cannot
be set greater than 24 hours; any attempt to do so forces the default value.
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
|return_path_remove|Use: main|Type: boolean|Default: true|
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
RFC 2821, section 4.4, states that an SMTP server must insert a Return-path:
header line into a message when it makes a "final delivery". The Return-path:
options for adding Return-path: headers at the time of delivery. They are
normally used only for final local deliveries.
-+-----------------+---------+-------------+-------------+
++-------------------------------------------------------+
|return_size_limit|Use: main|Type: integer|Default: 100K|
-+-----------------+---------+-------------+-------------+
++-------------------------------------------------------+
This option is an obsolete synonym for bounce_return_size_limit.
-+-------------+---------+----------------+----------+
-|rfc1413_hosts|Use: main|Type: host list*|Default: *|
-+-------------+---------+----------------+----------+
++-----------------------------------------------------+
+|rfc1413_hosts|Use: main|Type: host list*|Default: @[]|
++-----------------------------------------------------+
RFC 1413 identification calls are made to any client host which matches an item
-in the list.
+in the list. The default value specifies just this host, being any local
+interface for the system.
-+---------------------+---------+----------+-----------+
-|rfc1413_query_timeout|Use: main|Type: time|Default: 5s|
-+---------------------+---------+----------+-----------+
++------------------------------------------------------+
+|rfc1413_query_timeout|Use: main|Type: time|Default: 0s|
++------------------------------------------------------+
This sets the timeout on RFC 1413 identification calls. If it is set to zero,
no RFC 1413 calls are ever made.
-+------------------------+---------+----------------+--------------+
++------------------------------------------------------------------+
|sender_unqualified_hosts|Use: main|Type: host list*|Default: unset|
-+------------------------+---------+----------------+--------------+
++------------------------------------------------------------------+
This option lists those hosts from which Exim is prepared to accept unqualified
sender addresses. The addresses are made fully qualified by the addition of
sender_unqualified_hosts, or if the message was submitted locally (not using
TCP/IP), and the -bnq option was not set.
-+---------------+---------+-----------------+--------------+
++----------------------------------------------------------+
|set_environment|Use: main|Type: string list|Default: empty|
-+---------------+---------+-----------------+--------------+
++----------------------------------------------------------+
This option allows to set individual environment variables that the currently
linked libraries and programs in child processes use. The default list is
empty,
-+---------------------+---------+-------------+-------------+
++--------------------------------------------------+
+|slow_lookup_log|Use: main|Type: integer|Default: 0|
++--------------------------------------------------+
+
+This option controls logging of slow lookups. If the value is nonzero it is
+taken as a number of milliseconds and lookups taking longer than this are
+logged. Currently this applies only to DNS lookups.
+
++-----------------------------------------------------------+
|smtp_accept_keepalive|Use: main|Type: boolean|Default: true|
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------+
This option controls the setting of the SO_KEEPALIVE option on incoming TCP/IP
socket connections. When set, it causes the kernel to probe idle connections
call properly. The keepalive mechanism takes several hours to detect
unreachable hosts.
-+---------------+---------+-------------+-----------+
++---------------------------------------------------+
|smtp_accept_max|Use: main|Type: integer|Default: 20|
-+---------------+---------+-------------+-----------+
++---------------------------------------------------+
This option specifies the maximum number of simultaneous incoming SMTP calls
that Exim will accept. It applies only to the listening daemon; there is no
has not been reached for the client host, smtp_accept_reserve and
smtp_load_reserve are then checked before accepting the connection.
-+-----------------------+---------+-------------+-----------+
++-----------------------------------------------------------+
|smtp_accept_max_nonmail|Use: main|Type: integer|Default: 10|
-+-----------------------+---------+-------------+-----------+
++-----------------------------------------------------------+
Exim counts the number of "non-mail" commands in an SMTP session, and drops the
connection if there are too many. This option defines "too many". The check
counted. Otherwise, all commands other than MAIL, RCPT, DATA, and QUIT are
counted.
-+-----------------------------+---------+----------------+----------+
++-------------------------------------------------------------------+
|smtp_accept_max_nonmail_hosts|Use: main|Type: host list*|Default: *|
-+-----------------------------+---------+----------------+----------+
++-------------------------------------------------------------------+
You can control which hosts are subject to the smtp_accept_max_nonmail check by
setting this option. The default value makes it apply to all hosts. By changing
the value, you can exclude any badly-behaved hosts that you have to live with.
-+------------------------------+---------+-------------+-------------+
++--------------------------------------------------------------------+
|smtp_accept_max_per_connection|Use: main|Type: integer|Default: 1000|
-+------------------------------+---------+-------------+-------------+
++--------------------------------------------------------------------+
The value of this option limits the number of MAIL commands that Exim is
prepared to accept over a single SMTP connection, whether or not each command
precaution against a client that goes mad (incidents of this type have been
seen).
-+------------------------+---------+-------------+--------------+
++---------------------------------------------------------------+
|smtp_accept_max_per_host|Use: main|Type: string*|Default: unset|
-+------------------------+---------+-------------+--------------+
++---------------------------------------------------------------+
This option restricts the number of simultaneous IP connections from a single
host (strictly, from a single IP address) to the Exim daemon. The option is
could cause a vast number or processes to be created). While the daemon is
doing this processing, it cannot accept any other incoming connections.
-+-----------------+---------+-------------+----------+
++----------------------------------------------------+
|smtp_accept_queue|Use: main|Type: integer|Default: 0|
-+-----------------+---------+-------------+----------+
++----------------------------------------------------+
If the number of simultaneous incoming SMTP connections being handled via the
listening daemon exceeds this value, messages received by SMTP are just placed
-on the queue; no delivery processes are started automatically. The count is
+in the queue; no delivery processes are started automatically. The count is
fixed at the start of an SMTP connection. It cannot be updated in the
subprocess that receives messages, and so the queueing or not queueing applies
to all messages received in the same connection.
queue_only, queue_only_load, queue_smtp_domains, and the various -odx command
line options.
-+--------------------------------+---------+-------------+-----------+
++--------------------------------------------------------------------+
|smtp_accept_queue_per_connection|Use: main|Type: integer|Default: 10|
-+--------------------------------+---------+-------------+-----------+
++--------------------------------------------------------------------+
This option limits the number of delivery processes that Exim starts
automatically when receiving messages via SMTP, whether via the daemon or by
the use of -bs or -bS. If the value of the option is greater than zero, and the
number of messages received in a single SMTP session exceeds this number,
-subsequent messages are placed on the queue, but no delivery processes are
+subsequent messages are placed in the queue, but no delivery processes are
started. This helps to limit the number of Exim processes when a server
restarts after downtime and there is a lot of mail waiting for it on other
systems. On large systems, the default should probably be increased, and on
dial-in client systems it should probably be set to zero (that is, disabled).
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
|smtp_accept_reserve|Use: main|Type: integer|Default: 0|
-+-------------------+---------+-------------+----------+
++------------------------------------------------------+
When smtp_accept_max is set greater than zero, this option specifies a number
of SMTP connections that are reserved for connections from the hosts that are
accepted only from hosts listed in smtp_reserve_hosts, provided the other
criteria for acceptance are met.
-+--------------------+---------+-------------+--------------+
++-----------------------------------------------------------+
|smtp_active_hostname|Use: main|Type: string*|Default: unset|
-+--------------------+---------+-------------+--------------+
++-----------------------------------------------------------+
This option is provided for multi-homed servers that want to masquerade as
several different hosts. At the start of an incoming SMTP connection, its value
it is also used as the default for HELO commands in callout verification if
there is no remote transport from which to obtain a helo_data value.
-+-----------+---------+-------------+------------------+
++------------------------------------------------------+
|smtp_banner|Use: main|Type: string*|Default: see below|
-+-----------+---------+-------------+------------------+
++------------------------------------------------------+
This string, which is expanded every time it is used, is output as the initial
positive response to an SMTP connection. The default setting is:
in this string. Exim adds it automatically (several times in the case of a
multiline response).
-+----------------------+---------+-------------+-------------+
++------------------------------------------------------------+
|smtp_check_spool_space|Use: main|Type: boolean|Default: true|
-+----------------------+---------+-------------+-------------+
++------------------------------------------------------------+
When this option is set, if an incoming SMTP session encounters the SIZE option
on a MAIL command, it checks that there is enough space in the spool
free the amount specified by check_spool_space (even if that value is zero). If
there isn't enough space, a temporary error code is returned.
-+--------------------+---------+-------------+-----------+
++--------------------------------------------------------+
|smtp_connect_backlog|Use: main|Type: integer|Default: 20|
-+--------------------+---------+-------------+-----------+
++--------------------------------------------------------+
This option specifies a maximum number of waiting SMTP connections. Exim passes
this value to the TCP/IP system when it sets up its listener. Once this number
(to 50, say). It also gives some protection against denial-of-service attacks
by SYN flooding.
-+-----------------+---------+-------------+-------------+
++-------------------------------------------------------+
|smtp_enforce_sync|Use: main|Type: boolean|Default: true|
-+-----------------+---------+-------------+-------------+
++-------------------------------------------------------+
The SMTP protocol specification requires the client to wait for a response from
the server at certain points in the dialogue. Without PIPELINING these
The check can be globally disabled by setting smtp_enforce_sync false. If you
want to disable the check selectively (for example, only for certain hosts),
you can do so by an appropriate use of a control modifier in an ACL (see
-section 42.22). See also pipelining_advertise_hosts.
+section 43.22). See also pipelining_advertise_hosts.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|smtp_etrn_command|Use: main|Type: string*|Default: unset|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
If this option is set, the given command is run whenever an SMTP ETRN command
is received from a host that is permitted to issue such commands (see chapter
-42). The string is split up into separate arguments which are independently
+43). The string is split up into separate arguments which are independently
expanded. The expansion variable $domain is set to the argument of the ETRN
command, and no syntax checking is done on it. For example:
SMTP, so it is not possible for it to change the uid before running the
command.
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
|smtp_etrn_serialize|Use: main|Type: boolean|Default: true|
-+-------------------+---------+-------------+-------------+
++---------------------------------------------------------+
When this option is set, it prevents the simultaneous execution of more than
one identical command as a result of ETRN in an SMTP connection. See section
-47.8 for details.
+48.8 for details.
-+-----------------+---------+-----------------+--------------+
++------------------------------------------------------------+
|smtp_load_reserve|Use: main|Type: fixed-point|Default: unset|
-+-----------------+---------+-----------------+--------------+
++------------------------------------------------------------+
If the system load average ever gets higher than this, incoming SMTP calls are
accepted only from those hosts that match an entry in smtp_reserve_hosts. If
on which Exim cannot determine the load average. See also
deliver_queue_load_max and queue_only_load.
-+-----------------------+---------+-------------+----------+
++----------------------------------------------------------+
|smtp_max_synprot_errors|Use: main|Type: integer|Default: 3|
-+-----------------------+---------+-------------+----------+
++----------------------------------------------------------+
Exim rejects SMTP commands that contain syntax or protocol errors. In
particular, a syntactically invalid email address, as in this command:
pipelining_advertise_hosts), and in this situation, "expected" errors do not
count towards the limit.
-+-------------------------+---------+-------------+----------+
++------------------------------------------------------------+
|smtp_max_unknown_commands|Use: main|Type: integer|Default: 3|
-+-------------------------+---------+-------------+----------+
++------------------------------------------------------------+
If there are too many unrecognized commands in an incoming SMTP session, an
Exim server drops the connection. This is a defence against some kinds of abuse
that subvert web clients into making connections to SMTP ports; in these
circumstances, a number of non-SMTP command lines are sent first.
-+--------------------+---------+----------------+--------------+
++--------------------------------------------------------------+
|smtp_ratelimit_hosts|Use: main|Type: host list*|Default: unset|
-+--------------------+---------+----------------+--------------+
++--------------------------------------------------------------+
Some sites find it helpful to be able to limit the rate at which certain hosts
can send them messages, and the rate at which an individual message can specify
Exim has two rate-limiting facilities. This section describes the older
facility, which can limit rates within a single connection. The newer ratelimit
-ACL condition can limit rates across all connections. See section 42.38 for
+ACL condition can limit rates across all connections. See section 43.38 for
details of the newer facility.
When a host matches smtp_ratelimit_hosts, the values of smtp_ratelimit_mail and
increasing by a factor of 1.05 each time. The second setting applies delays to
RCPT commands when more than four occur in a single message.
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
|smtp_ratelimit_mail|Use: main|Type: string|Default: unset|
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
See smtp_ratelimit_hosts above.
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
|smtp_ratelimit_rcpt|Use: main|Type: string|Default: unset|
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
See smtp_ratelimit_hosts above.
-+--------------------+---------+----------+-----------+
-|smtp_receive_timeout|Use: main|Type: time|Default: 5m|
-+--------------------+---------+----------+-----------+
++------------------------------------------------------+
+|smtp_receive_timeout|Use: main|Type: time*|Default: 5m|
++------------------------------------------------------+
This sets a timeout value for SMTP reception. It applies to all forms of SMTP
input, including batch SMTP. If a line of input (either an SMTP command or a
The former means that Exim was expecting to read an SMTP command; the latter
means that it was in the DATA phase, reading the contents of a message.
+If the first character of the option is a "$" the option is expanded before use
+and may depend on $sender_host_name, $sender_host_address and $sender_host_port
+.
+
The value set by this option can be overridden by the -os command-line option.
A setting of zero time disables the timeout, but this should never be used for
SMTP over TCP/IP. (It can be useful in some cases of local input using -bs or
-bS.) For non-SMTP input, the reception timeout is controlled by
receive_timeout and -or.
-+------------------+---------+----------------+--------------+
++------------------------------------------------------------+
|smtp_reserve_hosts|Use: main|Type: host list*|Default: unset|
-+------------------+---------+----------------+--------------+
++------------------------------------------------------------+
This option defines hosts for which SMTP connections are reserved; see
smtp_accept_reserve and smtp_load_reserve above.
-+-------------------------+---------+-------------+--------------+
++----------------------------------------------------------------+
|smtp_return_error_details|Use: main|Type: boolean|Default: false|
-+-------------------------+---------+-------------+--------------+
++----------------------------------------------------------------+
In the default state, Exim uses bland messages such as "Administrative
prohibition" when it rejects SMTP commands for policy reasons. Many sysadmins
550-Rejected after DATA: '>' missing at end of address:
550 failing address in "From" header is: <user@dom.ain
-+-------------+---------+------------+------------------+
-|spamd_address|Use: main|Type: string|Default: see below|
-+-------------+---------+------------+------------------+
++--------------------------------------------------------------+
+|smtputf8_advertise_hosts|Use: main|Type: host list*|Default: *|
++--------------------------------------------------------------+
+
+When Exim is built with support for internationalised mail names, the
+availability thereof is advertised in response to EHLO only to those client
+hosts that match this option. See chapter 59 for details of Exim's support for
+internationalisation.
+
++-----------------------------------------------------------+
+|spamd_address|Use: main|Type: string|Default: 127.0.0.1 783|
++-----------------------------------------------------------+
This option is available when Exim is compiled with the content-scanning
-extension. It specifies how Exim connects to SpamAssassin's spamd daemon. The
-default value is
+extension. It specifies how Exim connects to SpamAssassin's spamd daemon. See
+section 44.2 for more details.
-127.0.0.1 783
++--------------------------------------------------------------------+
+|spf_guess|Use: main|Type: string|Default: v=spf1 a/24 mx/24 ptr ?all|
++--------------------------------------------------------------------+
-See section 43.2 for more details.
+This option is available when Exim is compiled with SPF support. See section
+57.4 for more details.
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
|split_spool_directory|Use: main|Type: boolean|Default: false|
-+---------------------+---------+-------------+--------------+
++------------------------------------------------------------+
If this option is set, it causes Exim to split its input directory into 62
subdirectories, each with a single alphanumeric character as its name. The
When split_spool_directory is set, the behaviour of queue runner processes
changes. Instead of creating a list of all messages in the queue, and then
-trying to deliver each one in turn, it constructs a list of those in one
+trying to deliver each one, in turn, it constructs a list of those in one
sub-directory and tries to deliver them, before moving on to the next
sub-directory. The sub-directories are processed in a random order. This
spreads out the scanning of the input directories, and uses less memory. It is
-particularly beneficial when there are lots of messages on the queue. However,
+particularly beneficial when there are lots of messages in the queue. However,
if queue_run_in_order is set, none of this new processing happens. The entire
queue has to be scanned and sorted before any deliveries can start.
-+---------------+---------+-------------+----------------------------+
++--------------------------------------------------------------------+
|spool_directory|Use: main|Type: string*|Default: set at compile time|
-+---------------+---------+-------------+----------------------------+
++--------------------------------------------------------------------+
This defines the directory in which Exim keeps its spool, that is, the messages
it is waiting to deliver. The default value is taken from the compile-time
By using this option to override the compiled-in path, it is possible to run
tests of Exim without using the standard spool.
-+-------------------+---------+----------+-----------+
++-------------------------------------------------------+
+|spool_wireformat|Use: main|Type: boolean|Default: false|
++-------------------------------------------------------+
+
+If this option is set, Exim may for some messages use an alternative format for
+data-files in the spool which matches the wire format. Doing this permits more
+efficient message reception and transmission. Currently it is only done for
+messages received using the ESMTP CHUNKING option.
+
+The following variables will not have useful values:
+
+$max_received_linelength
+$body_linecount
+$body_zerocount
+
+Users of the local_scan() API (see 45), and any external programs which are
+passed a reference to a message data file (except via the "regex", "malware" or
+"spam") ACL conditions) will need to be aware of the different formats
+potentially available.
+
+Using any of the ACL conditions noted will negate the reception benefit (as a
+Unix-mbox-format file is constructed for them). The transmission benefit is
+maintained.
+
++----------------------------------------------------+
|sqlite_lock_timeout|Use: main|Type: time|Default: 5s|
-+-------------------+---------+----------+-----------+
++----------------------------------------------------+
This option controls the timeout that the sqlite lookup uses when trying to
-access an SQLite database. See section 9.25 for more details.
+access an SQLite database. See section 9.26 for more details.
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
|strict_acl_vars|Use: main|Type: boolean|Default: false|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
This option controls what happens if a syntactically valid but undefined ACL
variable is referenced. If it is false (the default), an empty string is
-substituted; if it is true, an error is generated. See section 42.19 for
+substituted; if it is true, an error is generated. See section 43.19 for
details of ACL variables.
-+---------------------------+---------+-------------+--------------+
++------------------------------------------------------------------+
|strip_excess_angle_brackets|Use: main|Type: boolean|Default: false|
-+---------------------------+---------+-------------+--------------+
++------------------------------------------------------------------+
If this option is set, redundant pairs of angle brackets round "route-addr"
items in addresses are stripped. For example, <<xxx@a.b.c.d>> is treated as
another MTA, the excess angle brackets are not passed on. If this option is not
set, multiple pairs of angle brackets cause a syntax error.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|strip_trailing_dot|Use: main|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
If this option is set, a trailing dot at the end of a domain in an address is
ignored. If this is in the envelope and the message is passed on to another
domain causes a syntax error. However, addresses in header lines are checked
only when an ACL requests header syntax checking.
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
|syslog_duplication|Use: main|Type: boolean|Default: true|
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
When Exim is logging to syslog, it writes the log lines for its three separate
logs at different syslog priorities so that they can in principle be separated
is written, at LOG_NOTICE priority. Lines that normally go to both the main and
the panic log are written at the LOG_ALERT priority.
-+---------------+---------+------------+--------------+
++-----------------------------------------------------+
|syslog_facility|Use: main|Type: string|Default: unset|
-+---------------+---------+------------+--------------+
++-----------------------------------------------------+
This option sets the syslog "facility" name, used when Exim is logging to
syslog. The value must be one of the strings "mail", "user", "news", "uucp",
"daemon", or "localx" where x is a digit between 0 and 7. If this option is
-unset, "mail" is used. See chapter 51 for details of Exim's logging.
+unset, "mail" is used. See chapter 52 for details of Exim's logging.
+
++------------------------------------------------+
+|syslog_pid|Use: main|Type: boolean|Default: true|
++------------------------------------------------+
-+------------------+---------+------------+---------------+
+If syslog_pid is set false, the PID on Exim's log lines are omitted when these
+lines are sent to syslog. (Syslog normally prefixes the log lines with the PID
+of the logging process automatically.) You need to enable the "+pid" log
+selector item, if you want Exim to write it's PID into the logs.) See chapter
+52 for details of Exim's logging.
+
++---------------------------------------------------------+
|syslog_processname|Use: main|Type: string|Default: "exim"|
-+------------------+---------+------------+---------------+
++---------------------------------------------------------+
This option sets the syslog "ident" name, used when Exim is logging to syslog.
-The value must be no longer than 32 characters. See chapter 51 for details of
+The value must be no longer than 32 characters. See chapter 52 for details of
Exim's logging.
-+----------------+---------+-------------+-------------+
++------------------------------------------------------+
|syslog_timestamp|Use: main|Type: boolean|Default: true|
-+----------------+---------+-------------+-------------+
++------------------------------------------------------+
If syslog_timestamp is set false, the timestamps on Exim's log lines are
-omitted when these lines are sent to syslog. See chapter 51 for details of
+omitted when these lines are sent to syslog. See chapter 52 for details of
Exim's logging.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|system_filter|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option specifies an Exim filter file that is applied to all messages at
the start of each delivery attempt, before any routing is done. System filters
must be Exim filters; they cannot be Sieve filters. If the system filter
generates any deliveries to files or pipes, or any new mail messages, the
appropriate system_filter_..._transport option(s) must be set, to define which
-transports are to be used. Details of this facility are given in chapter 45.
+transports are to be used. Details of this facility are given in chapter 46. A
+forced expansion failure results in no filter operation.
-+---------------------------------+---------+-------------+--------------+
++------------------------------------------------------------------------+
|system_filter_directory_transport|Use: main|Type: string*|Default: unset|
-+---------------------------------+---------+-------------+--------------+
++------------------------------------------------------------------------+
This sets the name of the transport driver that is to be used when the save
command in a system message filter specifies a path ending in "/", implying
delivery of each message into a separate file in some directory. During the
delivery, the variable $address_file contains the path name.
-+----------------------------+---------+-------------+--------------+
++-------------------------------------------------------------------+
|system_filter_file_transport|Use: main|Type: string*|Default: unset|
-+----------------------------+---------+-------------+--------------+
++-------------------------------------------------------------------+
This sets the name of the transport driver that is to be used when the save
command in a system message filter specifies a path not ending in "/". During
the delivery, the variable $address_file contains the path name.
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
|system_filter_group|Use: main|Type: string|Default: unset|
-+-------------------+---------+------------+--------------+
++---------------------------------------------------------+
This option is used only when system_filter_user is also set. It sets the gid
under which the system filter is run, overriding any gid that is associated
with the user. The value may be numerical or symbolic.
-+----------------------------+---------+-------------+--------------+
++-------------------------------------------------------------------+
|system_filter_pipe_transport|Use: main|Type: string*|Default: unset|
-+----------------------------+---------+-------------+--------------+
++-------------------------------------------------------------------+
This specifies the transport driver that is to be used when a pipe command is
used in a system filter. During the delivery, the variable $address_pipe
contains the pipe command.
-+-----------------------------+---------+-------------+--------------+
++--------------------------------------------------------------------+
|system_filter_reply_transport|Use: main|Type: string*|Default: unset|
-+-----------------------------+---------+-------------+--------------+
++--------------------------------------------------------------------+
This specifies the transport driver that is to be used when a mail command is
used in a system filter.
-+------------------+---------+------------+--------------+
++--------------------------------------------------------+
|system_filter_user|Use: main|Type: string|Default: unset|
-+------------------+---------+------------+--------------+
++--------------------------------------------------------+
If this option is set to root, the system filter is run in the main Exim
delivery process, as root. Otherwise, the system filter runs in a separate
under which the filter is run is used when transporting them, unless a
transport option overrides.
-+-----------+---------+-------------+-------------+
++-------------------------------------------------+
|tcp_nodelay|Use: main|Type: boolean|Default: true|
-+-----------+---------+-------------+-------------+
++-------------------------------------------------+
If this option is set false, it stops the Exim daemon setting the TCP_NODELAY
option on its listening sockets. Setting TCP_NODELAY turns off the "Nagle
only those sockets that are set up for listening by the daemon. Sockets created
by the smtp transport for delivering mail always set TCP_NODELAY.
-+--------------------+---------+----------+-----------+
++-----------------------------------------------------+
|timeout_frozen_after|Use: main|Type: time|Default: 0s|
-+--------------------+---------+----------+-----------+
++-----------------------------------------------------+
If timeout_frozen_after is set to a time greater than zero, a frozen message of
-any kind that has been on the queue for longer than the given time is
+any kind that has been in the queue for longer than the given time is
automatically cancelled at the next queue run. If the frozen message is a
bounce message, it is just discarded; otherwise, a bounce is sent to the
sender, in a similar manner to cancellation by the -Mg command line option. If
message, see ignore_bounce_errors_after.
Note: the default value of zero means no timeouts; with this setting, frozen
-messages remain on the queue forever (except for any frozen bounce messages
+messages remain in the queue forever (except for any frozen bounce messages
that are released by ignore_bounce_errors_after).
-+--------+---------+------------+--------------+
++----------------------------------------------+
|timezone|Use: main|Type: string|Default: unset|
-+--------+---------+------------+--------------+
++----------------------------------------------+
The value of timezone is used to set the environment variable TZ while running
Exim (if it is different on entry). This ensures that all timestamps created by
appropriate behaviour for obtaining wall-clock time on some, but unfortunately
not all, operating systems.
-+-------------------+---------+----------------+--------------+
-|tls_advertise_hosts|Use: main|Type: host list*|Default: unset|
-+-------------------+---------+----------------+--------------+
++---------------------------------------------------------+
+|tls_advertise_hosts|Use: main|Type: host list*|Default: *|
++---------------------------------------------------------+
When Exim is built with support for TLS encrypted connections, the availability
of the STARTTLS command to set up an encrypted session is advertised in
response to EHLO only to those client hosts that match this option. See chapter
-41 for details of Exim's support for TLS.
+42 for details of Exim's support for TLS. Note that the default value requires
+that a certificate be supplied using the tls_certificate option. If TLS support
+for incoming connections is not required the tls_advertise_hosts option should
+be set empty.
-+---------------+---------+-------------+--------------+
-|tls_certificate|Use: main|Type: string*|Default: unset|
-+---------------+---------+-------------+--------------+
++-----------------------------------------------------+
+|tls_certificate|Use: main|Type: string|Default: list*|
++-----------------------------------------------------+
-The value of this option is expanded, and must then be the absolute path to a
-file which contains the server's certificates. The server's private key is also
-assumed to be in this file if tls_privatekey is unset. See chapter 41 for
-further details.
+The value of this option is expanded, and must then be a list of absolute paths
+to files which contains the server's certificates. Commonly only one file is
+needed. The server's private key is also assumed to be in this file if
+tls_privatekey is unset. See chapter 42 for further details.
Note: The certificates defined by this option are used only when Exim is
receiving incoming messages as a server. If you want to supply certificates for
use when sending messages as a client, you must set the tls_certificate option
in the relevant smtp transport.
+Note: If you use filenames based on IP addresses, change the list separator in
+the usual way (6.21) >to avoid confusion under IPv6.
+
+Note: Under versions of OpenSSL preceding 1.1.1, when a list of more than one
+file is used, the $tls_in_ourcert variable is unreliable.
+
+Note: OCSP stapling is not usable under OpenSSL when a list of more than one
+file is used.
+
If the option contains $tls_out_sni and Exim is built against OpenSSL, then if
the OpenSSL build supports TLS extensions and the TLS client sends the Server
-Name Indication extension, then this option and others documented in 41.10 will
+Name Indication extension, then this option and others documented in 42.10 will
be re-expanded.
-+-------+---------+-------------+--------------+
+If this option is unset or empty a fresh self-signed certificate will be
+generated for every connection.
+
++----------------------------------------------+
|tls_crl|Use: main|Type: string*|Default: unset|
-+-------+---------+-------------+--------------+
++----------------------------------------------+
This option specifies a certificate revocation list. The expanded value must be
-the name of a file that contains a CRL in PEM format.
+the name of a file that contains CRLs in PEM format.
-See 41.10 for discussion of when this option might be re-expanded.
+Under OpenSSL the option can specify a directory with CRL files.
-+---------------+---------+-------------+-------------+
+Note: Under OpenSSL the option must, if given, supply a CRL for each signing
+element of the certificate chain (i.e. all but the leaf). For the file variant
+this can be multiple PEM blocks in the one file.
+
+See 42.10 for discussion of when this option might be re-expanded.
+
++-----------------------------------------------------+
|tls_dh_max_bits|Use: main|Type: integer|Default: 2236|
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
The number of bits used for Diffie-Hellman key-exchange may be suggested by the
chosen TLS library. That value might prove to be too high for interoperability.
little less than this figure, because GnuTLS is inexact and may produce a
larger prime than requested.
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
|tls_dhparam|Use: main|Type: string*|Default: unset|
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
The value of this option is expanded and indicates the source of DH parameters
to be used by Exim.
-If it is a filename starting with a "/", then it names a file from which DH
-parameters should be loaded. If the file exists, it should hold a PEM-encoded
-PKCS#3 representation of the DH prime. If the file does not exist, for OpenSSL
-it is an error. For GnuTLS, Exim will attempt to create the file and fill it
-with a generated DH prime. For OpenSSL, if the DH bit-count from loading the
-file is greater than tls_dh_max_bits then it will be ignored, and treated as
-though the tls_dhparam were set to "none".
+Note: The Exim Maintainers strongly recommend using a filename with
+site-generated local DH parameters, which has been supported across all
+versions of Exim. The other specific constants available are a fallback so that
+even when "unconfigured", Exim can offer Perfect Forward Secrecy in older
+ciphersuites in TLS.
+
+If tls_dhparam is a filename starting with a "/", then it names a file from
+which DH parameters should be loaded. If the file exists, it should hold a
+PEM-encoded PKCS#3 representation of the DH prime. If the file does not exist,
+for OpenSSL it is an error. For GnuTLS, Exim will attempt to create the file
+and fill it with a generated DH prime. For OpenSSL, if the DH bit-count from
+loading the file is greater than tls_dh_max_bits then it will be ignored, and
+treated as though the tls_dhparam were set to "none".
If this option expands to the string "none", then no DH parameters will be
loaded by Exim.
If this option expands to the string "historic" and Exim is using GnuTLS, then
Exim will attempt to load a file from inside the spool directory. If the file
-does not exist, Exim will attempt to create it. See section 41.3 for further
+does not exist, Exim will attempt to create it. See section 42.3 for further
details.
If Exim is using OpenSSL and this option is empty or unset, then Exim will load
-a default DH prime; the default is the 2048 bit prime described in section 2.2
-of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which in
-IKE is assigned number 23.
+a default DH prime; the default is Exim-specific but lacks verifiable
+provenance.
+
+In older versions of Exim the default was the 2048 bit prime described in
+section 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order
+Subgroup", which in IKE is assigned number 23.
Otherwise, the option must expand to the name used by Exim for any of a number
-of DH primes specified in RFC 2409, RFC 3526 and RFC 5114. As names, Exim uses
-"ike" followed by the number used by IKE, of "default" which corresponds to
-"ike23".
+of DH primes specified in RFC 2409, RFC 3526, RFC 5114, RFC 7919, or from other
+sources. As names, Exim uses a standard specified name, else "ike" followed by
+the number used by IKE, or "default" which corresponds to
+"exim.dev.20160529.3".
-The available primes are: "ike1", "ike2", "ike5", "ike14", "ike15", "ike16",
-"ike17", "ike18", "ike22", "ike23" (aka "default") and "ike24".
+The available standard primes are: "ffdhe2048", "ffdhe3072", "ffdhe4096",
+"ffdhe6144", "ffdhe8192", "ike1", "ike2", "ike5", "ike14", "ike15", "ike16",
+"ike17", "ike18", "ike22", "ike23" and "ike24".
+
+The available additional primes are: "exim.dev.20160529.1",
+"exim.dev.20160529.2" and "exim.dev.20160529.3".
Some of these will be too small to be accepted by clients. Some may be too
-large to be accepted by clients.
+large to be accepted by clients. The open cryptographic community has
+suspicions about the integrity of some of the later IKE values, which led into
+RFC7919 providing new fixed constants (the "ffdhe" identifiers).
+
+At this point, all of the "ike" values should be considered obsolete; they're
+still in Exim to avoid breaking unusual configurations, but are candidates for
+removal the next time we have backwards-incompatible changes.
The TLS protocol does not negotiate an acceptable size for this; clients tend
to hard-drop connections if what is offered by the server is unacceptable,
to the 4.80 release, as Debian used to patch Exim to raise the minimum
acceptable bound from 1024 to 2048.
-+-------------+---------+-------------+--------------+
++---------------------------------------------------+
+|tls_eccurve|Use: main|Type: string*|Default: "auto"|
++---------------------------------------------------+
+
+This option selects a EC curve for use by Exim when used with OpenSSL. It has
+no effect when Exim is used with GnuTLS.
+
+After expansion it must contain a valid EC curve parameter, such as
+"prime256v1", "secp384r1", or "P-512". Consult your OpenSSL manual for valid
+selections.
+
+For OpenSSL versions before (and not including) 1.0.2, the string "auto"
+selects "prime256v1". For more recent OpenSSL versions "auto" tells the library
+to choose.
+
+If the option expands to an empty string, no EC curves will be enabled.
+
++----------------------------------------------------+
|tls_ocsp_file|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This option must if set expand to the absolute path to a file which contains a
current status proof for the server's certificate, as obtained from the
Certificate Authority.
-+--------------------+---------+-----------------+--------------+
+Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
+
+For GnuTLS 3.5.6 or later the expanded value of this option can be a list of
+files, to match a list given for the tls_certificate option. The ordering of
+the two lists must match.
+
++---------------------------------------------------------------+
|tls_on_connect_ports|Use: main|Type: string list|Default: unset|
-+--------------------+---------+-----------------+--------------+
++---------------------------------------------------------------+
This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
-operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately
-set up without waiting for the client to issue a STARTTLS command. For further
+operate the SSMTP (SMTPS) protocol, where a TLS session is immediately set up
+without waiting for the client to issue a STARTTLS command. For further
details, see section 13.4.
-+--------------+---------+-------------+--------------+
-|tls_privatekey|Use: main|Type: string*|Default: unset|
-+--------------+---------+-------------+--------------+
++----------------------------------------------------+
+|tls_privatekey|Use: main|Type: string|Default: list*|
++----------------------------------------------------+
-The value of this option is expanded, and must then be the absolute path to a
-file which contains the server's private key. If this option is unset, or if
-the expansion is forced to fail, or the result is an empty string, the private
-key is assumed to be in the same file as the server's certificates. See chapter
-41 for further details.
+The value of this option is expanded, and must then be a list of absolute paths
+to files which contains the server's private keys. If this option is unset, or
+if the expansion is forced to fail, or the result is an empty string, the
+private key is assumed to be in the same file as the server's certificates. See
+chapter 42 for further details.
-See 41.10 for discussion of when this option might be re-expanded.
+See 42.10 for discussion of when this option might be re-expanded.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|tls_remember_esmtp|Use: main|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
If this option is set true, Exim violates the RFCs by remembering that it is in
"esmtp" state after successfully negotiating a TLS session. This provides
support for broken clients that fail to send a new EHLO after starting a TLS
session.
-+-------------------+---------+-------------+--------------+
++----------------------------------------------------------+
|tls_require_ciphers|Use: main|Type: string*|Default: unset|
-+-------------------+---------+-------------+--------------+
++----------------------------------------------------------+
This option controls which ciphers can be used for incoming TLS connections.
The smtp transport has an option of the same name for controlling outgoing
different clients if required. The value of this option must be a list of
permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
in somewhat different ways. If GnuTLS is being used, the client controls the
-preference order of the available ciphers. Details are given in sections 41.4
-and 41.5.
+preference order of the available ciphers. Details are given in sections 42.4
+and 42.5.
-+--------------------+---------+----------------+--------------+
++--------------------------------------------------------------+
|tls_try_verify_hosts|Use: main|Type: host list*|Default: unset|
-+--------------------+---------+----------------+--------------+
++--------------------------------------------------------------+
See tls_verify_hosts below.
-+-----------------------+---------+-------------+--------------+
-|tls_verify_certificates|Use: main|Type: string*|Default: unset|
-+-----------------------+---------+-------------+--------------+
++---------------------------------------------------------------+
+|tls_verify_certificates|Use: main|Type: string*|Default: system|
++---------------------------------------------------------------+
+
+The value of this option is expanded, and must then be either the word "system"
+or the absolute path to a file or directory containing permitted certificates
+for clients that match tls_verify_hosts or tls_try_verify_hosts.
+
+The "system" value for the option will use a system default location compiled
+into the SSL library. This is not available for GnuTLS versions preceding
+3.0.20, and will be taken as empty; an explicit location must be specified.
-The value of this option is expanded, and must then be the absolute path to a
-file containing permitted certificates for clients that match tls_verify_hosts
-or tls_try_verify_hosts. Alternatively, if you are using OpenSSL, you can set
-tls_verify_certificates to the name of a directory containing certificate
-files. This does not work with GnuTLS; the option must be set to the name of a
-single file if you are using GnuTLS.
+The use of a directory for the option value is not available for GnuTLS
+versions preceding 3.3.6 and a single file must be used.
+
+With OpenSSL the certificates specified explicitly either by file or directory
+are added to those given by the system default location.
These certificates should be for the certificate authorities trusted, rather
than the public cert of individual clients. With both OpenSSL and GnuTLS, if
the value is a file then the certificates are sent by Exim as a server to
connecting clients, defining the list of accepted certificate authorities. Thus
-the values defined should be considered public data. To avoid this, use OpenSSL
-with a directory.
+the values defined should be considered public data. To avoid this, use the
+explicit directory version.
-See 41.10 for discussion of when this option might be re-expanded.
+See 42.10 for discussion of when this option might be re-expanded.
A forced expansion failure or setting to an empty string is equivalent to being
unset.
-+----------------+---------+----------------+--------------+
++----------------------------------------------------------+
|tls_verify_hosts|Use: main|Type: host list*|Default: unset|
-+----------------+---------+----------------+--------------+
++----------------------------------------------------------+
This option, along with tls_try_verify_hosts, controls the checking of
certificates from clients. The expected certificates are defined by
Client hosts that match neither of these lists are not asked to present
certificates.
-+--------------+---------+------------------+--------------+
++----------------------------------------------------------+
|trusted_groups|Use: main|Type: string list*|Default: unset|
-+--------------+---------+------------------+--------------+
++----------------------------------------------------------+
This option is expanded just once, at the start of Exim's processing. If this
option is set, any process that is running in one of the listed groups, or
callers are permitted to do. If neither trusted_groups nor trusted_users is
set, only root and the Exim user are trusted.
-+-------------+---------+------------------+--------------+
++---------------------------------------------------------+
|trusted_users|Use: main|Type: string list*|Default: unset|
-+-------------+---------+------------------+--------------+
++---------------------------------------------------------+
This option is expanded just once, at the start of Exim's processing. If this
option is set, any process that is running as one of the listed users is
details of what trusted callers are permitted to do. If neither trusted_groups
nor trusted_users is set, only root and the Exim user are trusted.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|unknown_login|Use: main|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
This is a specialized feature for use in unusual configurations. By default, if
the uid of the caller of Exim cannot be looked up using getpwuid(), Exim gives
unknown_login is used, the value of unknown_username is used for the user's
real name (gecos field), unless this has been set by the -F option.
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
|unknown_username|Use: main|Type: string|Default: unset|
-+----------------+---------+------------+--------------+
++------------------------------------------------------+
See unknown_login.
-+--------------------+---------+-------------------+--------------+
++-----------------------------------------------------------------+
|untrusted_set_sender|Use: main|Type: address list*|Default: unset|
-+--------------------+---------+-------------------+--------------+
++-----------------------------------------------------------------+
When an untrusted user submits a message to Exim using the standard input, Exim
normally creates an envelope sender address from the user's login and the
parameters. Furthermore, it does not stop Exim from removing an existing
Sender: header in the message, or from adding a Sender: header if necessary.
See local_sender_retain and local_from_check for ways of overriding these
-actions. The handling of the Sender: header is also described in section 46.16.
+actions. The handling of the Sender: header is also described in section 47.16.
The log line for a message's arrival shows the envelope sender following "<=".
For local messages, the user's login always follows, after "U=". In -bp
displays, and in the Exim monitor, if an untrusted user sets an envelope sender
address, the user's login is shown in parentheses after the sender address.
-+-----------------+---------+------------+------------------+
++-----------------------------------------------------------+
|uucp_from_pattern|Use: main|Type: string|Default: see below|
-+-----------------+---------+------------+------------------+
++-----------------------------------------------------------+
Some applications that pass messages to an MTA via a command line interface use
an initial line starting with "From " to pass the envelope sender. In
uucp_from_sender is "$1", which therefore just uses this first word ("ph10" in
the example above) as the message's sender. See also ignore_fromline_hosts.
-+----------------+---------+-------------+-------------+
++------------------------------------------------------+
|uucp_from_sender|Use: main|Type: string*|Default: "$1"|
-+----------------+---------+-------------+-------------+
++------------------------------------------------------+
See uucp_from_pattern above.
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
|warn_message_file|Use: main|Type: string|Default: unset|
-+-----------------+---------+------------+--------------+
++-------------------------------------------------------+
This option defines a template file containing paragraphs of text to be used
for constructing the warning message which is sent by Exim when a message has
-been on the queue for a specified amount of time, as specified by delay_warning
-. Details of the file's contents are given in chapter 48. See also
+been in the queue for a specified amount of time, as specified by delay_warning
+. Details of the file's contents are given in chapter 49. See also
bounce_message_file.
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
|write_rejectlog|Use: main|Type: boolean|Default: true|
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
If this option is set false, Exim no longer writes anything to the reject log.
-See chapter 51 for details of what Exim writes to its logs.
+See chapter 52 for details of what Exim writes to its logs.
of expansion of the options that provide data for a transport is: errors_to,
headers_add, headers_remove, transport.
-+------------+------------+-------------+--------------+
++------------------------------------------------------+
|address_data|Use: routers|Type: string*|Default: unset|
-+------------+------------+-------------+--------------+
++------------------------------------------------------+
The string is expanded just before the router is run, that is, after all the
precondition tests have succeeded. If the expansion is forced to fail, the
ACL, it remains available for use in the rest of the ACL statement. After
verifying a sender, the value is transferred to $sender_address_data.
-+------------+--------------+-------------+-------------+
++-------------------------------------------------------+
|address_test|Use: routers**|Type: boolean|Default: true|
-+------------+--------------+-------------+-------------+
++-------------------------------------------------------+
If this option is set false, the router is skipped when routing is being tested
by means of the -bt command line option. This can be a convenience when your
first router sends messages to an external scanner, because it saves you having
to set the "already scanned" indicator when testing real address routing.
-+--------------------+------------+-------------+--------------+
++--------------------------------------------------------------+
|cannot_route_message|Use: routers|Type: string*|Default: unset|
-+--------------------+------------+-------------+--------------+
++--------------------------------------------------------------+
This option specifies a text message that is used when an address cannot be
routed because Exim has run out of routers. The default message is "Unrouteable
explicitly forced, a message about the failure is written to the main and panic
logs, in addition to the normal message about the routing failure.
-+------------------+------------+-------------+--------------+
++------------------------------------------------------------+
|caseful_local_part|Use: routers|Type: boolean|Default: false|
-+------------------+------------+-------------+--------------+
++------------------------------------------------------------+
By default, routers handle the local parts of addresses in a case-insensitive
manner, though the actual case is preserved for transmission with the message.
This option applies to the processing of an address by a router. When a
recipient address is being processed in an ACL, there is a separate control
modifier that can be used to specify case-sensitive processing within the ACL
-(see section 42.22).
+(see section 43.22).
-+----------------+--------------+-------------+--------------+
++------------------------------------------------------------+
|check_local_user|Use: routers**|Type: boolean|Default: false|
-+----------------+--------------+-------------+--------------+
++------------------------------------------------------------+
When this option is true, Exim checks that the local part of the recipient
address (with affixes removed if relevant) is the name of an account on the
home directory) do not occur when a passwd lookup is used in a local_parts (or
any other) precondition.
-+---------+--------------+-------------+--------------+
++-----------------------------------------------------+
|condition|Use: routers**|Type: string*|Default: unset|
-+---------+--------------+-------------+--------------+
++-----------------------------------------------------+
This option specifies a general precondition test that has to succeed for the
router to be called. The condition option is the last precondition to be
of the other precondition options are common special cases that could in fact
be specified using condition.
-+-----------+------------+-------------+--------------+
+Historical note: We have condition on ACLs and on Routers. Routers are far
+older, and use one set of semantics. ACLs are newer and when they were created,
+the ACL condition process was given far stricter parse semantics. The bool{}
+expansion condition uses the same rules as ACLs. The bool_lax{} expansion
+condition uses the same rules as Routers. More pointedly, the bool_lax{} was
+written to match the existing Router rules processing behavior.
+
+This is best illustrated in an example:
+
+# If used in an ACL condition will fail with a syntax error, but
+# in a router condition any extra characters are treated as a string
+
+$ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
+true {yes} {no}}
+
+$ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}'
+ {yes} {no}}
+
+In each example above, the if statement actually ends after "{google.com}}".
+Since no true or false braces were defined, the default if behavior is to
+return a boolean true or a null answer (which evaluates to false). The rest of
+the line is then treated as a string. So the first example resulted in the
+boolean answer "true" with the string " {yes} {no}}" appended to it. The second
+example resulted in the null output (indicating false) with the string " {yes}
+{no}}" appended to it.
+
+In fact you can put excess forward braces in too. In the router condition,
+Exim's parser only looks for "{" symbols when they mean something, like after a
+"$" or when required as part of a conditional. But otherwise "{" and "}" are
+treated as ordinary string characters.
+
+Thus, in a Router, the above expansion strings will both always evaluate true,
+as the result of expansion is a non-empty string which doesn't match an
+explicit false value. This can be tricky to debug. By contrast, in an ACL
+either of those strings will always result in an expansion error because the
+result doesn't look sufficiently boolean.
+
++-----------------------------------------------------+
|debug_print|Use: routers|Type: string*|Default: unset|
-+-----------+------------+-------------+--------------+
++-----------------------------------------------------+
If this option is set and debugging is enabled (see the -d command line option)
or in address-testing mode (see the -bt command line option), the string is
tested. A newline is added to the text if it does not end with one. The
variable $router_name contains the name of the router.
-+---------------+------------+-------------+--------------+
++---------------------------------------------------------+
|disable_logging|Use: routers|Type: boolean|Default: false|
-+---------------+------------+-------------+--------------+
++---------------------------------------------------------+
If this option is set true, nothing is logged for any routing errors or for any
deliveries caused by this router. You should not set this option unless you
really, really know what you are doing. See also the generic transport option
of the same name.
-+-------+--------------+------------------+--------------+
++---------------------------------------------------------------------+
+|dnssec_request_domains|Use: routers|Type: domain list*|Default: unset|
++---------------------------------------------------------------------+
+
+DNS lookups for domains matching dnssec_request_domains will be done with the
+dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup
+sequence.
+
++---------------------------------------------------------------------+
+|dnssec_require_domains|Use: routers|Type: domain list*|Default: unset|
++---------------------------------------------------------------------+
+
+DNS lookups for domains matching dnssec_require_domains will be done with the
+dnssec request bit set. Any returns not having the Authenticated Data bit (AD
+bit) set will be ignored and logged as a host-lookup failure. This applies to
+all of the SRV, MX, AAAA, A lookup sequence.
+
++--------------------------------------------------------+
|domains|Use: routers**|Type: domain list*|Default: unset|
-+-------+--------------+------------------+--------------+
++--------------------------------------------------------+
If this option is set, the router is skipped unless the current domain matches
the list. If the match is achieved by means of a file lookup, the data that the
expansions of the driver's private options. See section 3.12 for a list of the
order in which preconditions are evaluated.
-+------+------------+------------+--------------+
++-----------------------------------------------+
|driver|Use: routers|Type: string|Default: unset|
-+------+------------+------------+--------------+
++-----------------------------------------------+
This option must always be set. It specifies which of the available routers is
to be used.
-+---------+------------+-------------+--------------+
++-----------------------------------------------------+
+|dsn_lasthop|Use: routers|Type: boolean|Default: false|
++-----------------------------------------------------+
+
+If this option is set true, and extended DSN (RFC3461) processing is in effect,
+Exim will not pass on DSN requests to downstream DSN-aware hosts but will
+instead send a success DSN as if the next hop does not support DSN. Not
+effective on redirect routers.
+
++---------------------------------------------------+
|errors_to|Use: routers|Type: string*|Default: unset|
-+---------+------------+-------------+--------------+
++---------------------------------------------------+
If a router successfully handles an address, it may assign the address to a
transport for delivery or it may generate child addresses. In both cases, if
return_path.
The most common use of errors_to is to direct mailing list bounces to the
-manager of the list, as described in section 49.2, or to implement VERP
-(Variable Envelope Return Paths) (see section 49.6).
+manager of the list, as described in section 50.2, or to implement VERP
+(Variable Envelope Return Paths) (see section 50.6).
-+----+--------------+-------------+-------------+
++-----------------------------------------------+
|expn|Use: routers**|Type: boolean|Default: true|
-+----+--------------+-------------+-------------+
++-----------------------------------------------+
If this option is turned off, the router is skipped when testing an address as
a result of processing an SMTP EXPN command. You might, for example, want to
system alias file. See section 3.12 for a list of the order in which
preconditions are evaluated.
-The use of the SMTP EXPN command is controlled by an ACL (see chapter 42). When
+The use of the SMTP EXPN command is controlled by an ACL (see chapter 43). When
Exim is running an EXPN command, it is similar to testing an address with -bt.
Compare VRFY, whose counterpart is -bv.
-+-----------+------------+-------------+--------------+
++-----------------------------------------------------+
|fail_verify|Use: routers|Type: boolean|Default: false|
-+-----------+------------+-------------+--------------+
++-----------------------------------------------------+
Setting this option has the effect of setting both fail_verify_sender and
fail_verify_recipient to the same value.
-+---------------------+------------+-------------+--------------+
++---------------------------------------------------------------+
|fail_verify_recipient|Use: routers|Type: boolean|Default: false|
-+---------------------+------------+-------------+--------------+
++---------------------------------------------------------------+
If this option is true and an address is accepted by this router when verifying
a recipient, verification fails.
-+------------------+------------+-------------+--------------+
++------------------------------------------------------------+
|fail_verify_sender|Use: routers|Type: boolean|Default: false|
-+------------------+------------+-------------+--------------+
++------------------------------------------------------------+
If this option is true and an address is accepted by this router when verifying
a sender, verification fails.
-+--------------+------------+-----------------+--------------+
++------------------------------------------------------------+
|fallback_hosts|Use: routers|Type: string list|Default: unset|
-+--------------+------------+-----------------+--------------+
++------------------------------------------------------------+
String expansion is not applied to this option. The argument must be a
colon-separated list of host names or IP addresses. The list separator can be
-changed (see section 6.19), and a port can be specified with each name or
+changed (see section 6.21), and a port can be specified with each name or
address. In fact, the format of each item is exactly the same as defined for
the list of hosts in a manualroute router (see section 20.5).
randomized for each use. See the fallback_hosts option of the smtp transport
for further details.
-+-----+------------+-------------+------------------+
++---------------------------------------------------+
|group|Use: routers|Type: string*|Default: see below|
-+-----+------------+-------------+------------------+
++---------------------------------------------------+
When a router queues an address for a transport, and the transport does not
specify a group, the group given here is used when running the delivery
check_local_user is set, when the default is taken from the password
information. See also initgroups and user and the discussion in chapter 23.
-+-----------+------------+-----------+--------------+
++---------------------------------------------------+
|headers_add|Use: routers|Type: list*|Default: unset|
-+-----------+------------+-----------+--------------+
-
-This option specifies a list of text headers, newline-separated, that is
-associated with any addresses that are accepted by the router. Each item is
-separately expanded, at routing time. However, this option has no effect when
-an address is just being verified. The way in which the text is used to add
-header lines at transport time is described in section 46.17. New header lines
-are not actually added until the message is in the process of being
-transported. This means that references to header lines in string expansions in
-the transport's configuration do not "see" the added header lines.
++---------------------------------------------------+
+
+This option specifies a list of text headers, newline-separated (by default,
+changeable in the usual way 6.21), that is associated with any addresses that
+are accepted by the router. Each item is separately expanded, at routing time.
+However, this option has no effect when an address is just being verified. The
+way in which the text is used to add header lines at transport time is
+described in section 47.17. New header lines are not actually added until the
+message is in the process of being transported. This means that references to
+header lines in string expansions in the transport's configuration do not "see"
+the added header lines.
The headers_add option is expanded after errors_to, but before headers_remove
and transport. If an item is empty, or if an item expansion is forced to fail,
this ambiguous situation should be avoided. The repeat_use option of the
redirect router may be of help.
-+--------------+------------+-----------+--------------+
++------------------------------------------------------+
|headers_remove|Use: routers|Type: list*|Default: unset|
-+--------------+------------+-----------+--------------+
-
-This option specifies a list of text headers, colon-separated, that is
-associated with any addresses that are accepted by the router. Each item is
-separately expanded, at routing time. However, this option has no effect when
-an address is just being verified. The way in which the text is used to remove
-header lines at transport time is described in section 46.17. Header lines are
-not actually removed until the message is in the process of being transported.
-This means that references to header lines in string expansions in the
-transport's configuration still "see" the original header lines.
++------------------------------------------------------+
+
+This option specifies a list of text headers, colon-separated (by default,
+changeable in the usual way 6.21), that is associated with any addresses that
+are accepted by the router. Each item is separately expanded, at routing time.
+However, this option has no effect when an address is just being verified. The
+way in which the text is used to remove header lines at transport time is
+described in section 47.17. Header lines are not actually removed until the
+message is in the process of being transported. This means that references to
+header lines in string expansions in the transport's configuration still "see"
+the original header lines.
The headers_remove option is expanded after errors_to and headers_add, but
before transport. If an item expansion is forced to fail, the item has no
this can lead to problems with duplicates -- see the similar warning for
headers_add above.
-+-------------------+------------+----------------+--------------+
+Warning 3: Because of the separate expansion of the list items, items that
+contain a list separator must have it doubled. To avoid this, change the list
+separator (6.21).
+
++----------------------------------------------------------------+
|ignore_target_hosts|Use: routers|Type: host list*|Default: unset|
-+-------------------+------------+----------------+--------------+
++----------------------------------------------------------------+
Although this option is a host list, it should normally contain IP address
entries rather than names. If any host that is looked up by the router has an
During its expansion, $host_address is set to the IP address that is being
checked.
-+----------+------------+-------------+--------------+
++----------------------------------------------------+
|initgroups|Use: routers|Type: boolean|Default: false|
-+----------+------------+-------------+--------------+
++----------------------------------------------------+
If the router queues an address for a transport, and this option is true, and
the uid supplied by the router is not overridden by the transport, the
additional groups associated with the uid are set up. See also group and user
and the discussion in chapter 23.
-+-----------------+--------------+-----------------+--------------+
++-----------------------------------------------------------------+
|local_part_prefix|Use: routers**|Type: string list|Default: unset|
-+-----------------+--------------+-----------------+--------------+
++-----------------------------------------------------------------+
If this option is set, the router is skipped unless the local part starts with
one of the given strings, or local_part_prefix_optional is true. See section
asterisk, it matches the longest possible sequence of arbitrary characters at
the start of the local part. An asterisk should therefore always be followed by
some character that does not occur in normal local parts. Wildcarding can be
-used to set up multiple user mailboxes, as described in section 49.8.
+used to set up multiple user mailboxes, as described in section 50.8.
During the testing of the local_parts option, and while the router is running,
the prefix is removed from the local part, and is available in the expansion
used in both a prefix and a suffix on the same router. Different separator
characters must be used to avoid ambiguity.
-+--------------------------+------------+-------------+--------------+
++--------------------------------------------------------------------+
|local_part_prefix_optional|Use: routers|Type: boolean|Default: false|
-+--------------------------+------------+-------------+--------------+
++--------------------------------------------------------------------+
See local_part_prefix above.
-+-----------------+--------------+-----------------+--------------+
++-----------------------------------------------------------------+
|local_part_suffix|Use: routers**|Type: string list|Default: unset|
-+-----------------+--------------+-----------------+--------------+
++-----------------------------------------------------------------+
This option operates in the same way as local_part_prefix, except that the
local part must end (rather than start) with the given string, the
suffix. This option facility is commonly used to handle local parts of the form
something-request and multiple user mailboxes of the form username-foo.
-+--------------------------+------------+-------------+--------------+
++--------------------------------------------------------------------+
|local_part_suffix_optional|Use: routers|Type: boolean|Default: false|
-+--------------------------+------------+-------------+--------------+
++--------------------------------------------------------------------+
See local_part_suffix above.
-+-----------+--------------+----------------------+--------------+
++----------------------------------------------------------------+
|local_parts|Use: routers**|Type: local part list*|Default: unset|
-+-----------+--------------+----------------------+--------------+
++----------------------------------------------------------------+
The router is run only if the local part of the address matches the list. See
section 3.12 for a list of the order in which preconditions are evaluated, and
local_parts = postmaster
data = postmaster@real.domain.example
-+------------+------------+-------------+------------------+
++----------------------------------------------------------+
|log_as_local|Use: routers|Type: boolean|Default: see below|
-+------------+------------+-------------+------------------+
++----------------------------------------------------------+
Exim has two logging styles for delivery, the idea being to make local
deliveries stand out more visibly from remote ones. In the "local" style, the
assigns an address to a transport. It has no effect on routers that redirect
addresses.
-+----+------------+--------------+-------------+
++----------------------------------------------+
|more|Use: routers|Type: boolean*|Default: true|
-+----+------------+--------------+-------------+
++----------------------------------------------+
The result of string expansion for this option must be a valid boolean value,
that is, one of the strings "yes", "no", "true", or "false". Any other result
is forced to fail, the router declines, and the value of more controls what
happens next.
-+---------------+------------+-------------+--------------+
++---------------------------------------------------------+
|pass_on_timeout|Use: routers|Type: boolean|Default: false|
-+---------------+------------+-------------+--------------+
++---------------------------------------------------------+
If a router times out during a host lookup, it normally causes deferral of the
address. If pass_on_timeout is set, the address is passed on to the next
lookups. They are treated in the same way as a timeout, and this option applies
to all of them.
-+-----------+------------+------------+--------------+
++----------------------------------------------------+
|pass_router|Use: routers|Type: string|Default: unset|
-+-----------+------------+------------+--------------+
++----------------------------------------------------+
Routers that recognize the generic self option (dnslookup, ipliteral, and
manualroute) are able to return "pass", forcing routing to continue, and
does not apply when a router returns "decline" because it cannot handle an
address.
-+---------------+------------+------------+--------------+
++--------------------------------------------------------+
|redirect_router|Use: routers|Type: string|Default: unset|
-+---------------+------------+------------+--------------+
++--------------------------------------------------------+
Sometimes an administrator knows that it is pointless to reprocess addresses
generated from alias or forward files with the same router again. For example,
instead of at the first router. This option has no effect if the router in
which it is set does not generate new addresses.
-+-------------+--------------+------------------+--------------+
++--------------------------------------------------------------+
|require_files|Use: routers**|Type: string list*|Default: unset|
-+-------------+--------------+------------------+--------------+
++--------------------------------------------------------------+
This option provides a general mechanism for predicating the running of a
router on the existence or non-existence of certain files or directories.
through the require_files list, expanding each item separately.
Because the list is split before expansion, any colons in expansion items must
-be doubled, or the facility for using a different list separator must be used.
-If any expansion is forced to fail, the item is ignored. Other expansion
+be doubled, or the facility for using a different list separator must be used (
+6.21). If any expansion is forced to fail, the item is ignored. Other expansion
failures cause routing of the address to be deferred.
If any expanded string is empty, it is ignored. Otherwise, except as described
in which preconditions are evaluated.) However, as these options are all
expanded, you can use the exists expansion condition to make such tests. The
require_files option is intended for checking files that the router may be
-going to use internally, or which are needed by a transport (for example
-.procmailrc).
+going to use internally, or which are needed by a transport (e.g., .procmailrc
+).
During delivery, the stat() function is run as root, but there is a facility
for some checking of the accessibility of a file by another user. This is not a
caused by a configuration error, and routing is deferred because the existence
or non-existence of the file cannot be determined. However, in some
circumstances it may be desirable to treat this condition as if the file did
-not exist. If the file name (or the exclamation mark that precedes the file
-name for non-existence) is preceded by a plus sign, the EACCES error is treated
-as if the file did not exist. For example:
+not exist. If the filename (or the exclamation mark that precedes the filename
+for non-existence) is preceded by a plus sign, the EACCES error is treated as
+if the file did not exist. For example:
require_files = +/some/file
users' .forward files), another solution is to set the verify option false so
that the router is skipped when verifying.
-+--------------------+------------+-------------+------------------+
++------------------------------------------------------------------+
|retry_use_local_part|Use: routers|Type: boolean|Default: see below|
-+--------------------+------------+-------------+------------------+
++------------------------------------------------------------------+
When a delivery suffers a temporary routing failure, a retry record is created
in Exim's hints database. For addresses whose routing depends only on the
appears. If the router generates child addresses, they are routed
independently; this setting does not become attached to them.
-+---------------------+------------+-------------+--------------+
++---------------------------------------------------------------+
|router_home_directory|Use: routers|Type: string*|Default: unset|
-+---------------------+------------+-------------+--------------+
++---------------------------------------------------------------+
This option sets a home directory for use while the router is running. (Compare
transport_home_directory, which sets a home directory for later transporting.)
In other words, router_home_directory overrides the password data for the
router, but not for the transport.
-+----+------------+------------+---------------+
++----------------------------------------------+
|self|Use: routers|Type: string|Default: freeze|
-+----+------------+------------+---------------+
++----------------------------------------------+
This option applies to those routers that use a recipient address to find a
list of remote hosts. Currently, these are the dnslookup, ipliteral, and
Exim with a different configuration file that handles the domain in another
way.
-+-------+--------------+-------------------+--------------+
++---------------------------------------------------------+
|senders|Use: routers**|Type: address list*|Default: unset|
-+-------+--------------+-------------------+--------------+
++---------------------------------------------------------+
If this option is set, the router is skipped unless the message's sender
address matches something on the list. See section 3.12 for a list of the order
sender, but is available when verifying any recipients. If the SMTP VRFY
command is enabled, it must be used after MAIL if the sender address matters.
-+--------------------+------------+-------------+--------------+
++--------------------------------------------------------------+
|translate_ip_address|Use: routers|Type: string*|Default: unset|
-+--------------------+------------+-------------+--------------+
++--------------------------------------------------------------+
There exist some rare networking situations (for example, packet radio) where
it is helpful to be able to translate IP addresses generated by normal routing
You should not make use of this facility unless you really understand what you
are doing.
-+---------+------------+-------------+--------------+
++---------------------------------------------------+
|transport|Use: routers|Type: string*|Default: unset|
-+---------+------------+-------------+--------------+
++---------------------------------------------------+
This option specifies the transport to be used when a router accepts an address
and sets it up for delivery. A transport is never needed if a router is used
private options that set up transports for pipe and file deliveries (see
chapter 22).
-+---------------------------+------------+-------------+--------------+
++---------------------------------------------------------------------+
|transport_current_directory|Use: routers|Type: string*|Default: unset|
-+---------------------------+------------+-------------+--------------+
++---------------------------------------------------------------------+
This option associates a current directory with any address that is routed to a
local transport. This can happen either because a transport is explicitly
forced failure, an error is logged, and delivery is deferred. See chapter 23
for details of the local delivery environment.
-+------------------------+------------+-------------+------------------+
++----------------------------------------------------------------------+
|transport_home_directory|Use: routers|Type: string*|Default: see below|
-+------------------------+------------+-------------+------------------+
++----------------------------------------------------------------------+
This option associates a home directory with any address that is routed to a
local transport. This can happen either because a transport is explicitly
See chapter 23 for further details of the local delivery environment.
-+------+------------+--------------+--------------+
++-------------------------------------------------+
|unseen|Use: routers|Type: boolean*|Default: false|
-+------+------------+--------------+--------------+
++-------------------------------------------------+
The result of string expansion for this option must be a valid boolean value,
that is, one of the strings "yes", "no", "true", or "false". Any other result
address_data option in the current or previous routers is passed on to
subsequent routers.
-+----+------------+-------------+------------------+
++--------------------------------------------------+
|user|Use: routers|Type: string*|Default: see below|
-+----+------------+-------------+------------------+
++--------------------------------------------------+
When a router queues an address for a transport, and the transport does not
specify a user, the user given here is used when running the delivery process.
group associated with the user is used. See also initgroups and group and the
discussion in chapter 23.
-+------+--------------+-------------+-------------+
++-------------------------------------------------+
|verify|Use: routers**|Type: boolean|Default: true|
-+------+--------------+-------------+-------------+
++-------------------------------------------------+
Setting this option has the effect of setting verify_sender and
verify_recipient to the same value.
-+-----------+--------------+-------------+--------------+
++-------------------------------------------------------+
|verify_only|Use: routers**|Type: boolean|Default: false|
-+-----------+--------------+-------------+--------------+
++-------------------------------------------------------+
If this option is set, the router is used only when verifying an address,
delivering in cutthrough mode or testing with the -bv option, not when actually
accesses any files, you need to make sure that they are accessible to the Exim
user or group.
-+----------------+--------------+-------------+-------------+
++-----------------------------------------------------------+
|verify_recipient|Use: routers**|Type: boolean|Default: true|
-+----------------+--------------+-------------+-------------+
++-----------------------------------------------------------+
If this option is false, the router is skipped when verifying recipient
addresses, delivering in cutthrough mode or testing recipient verification
using -bv. See section 3.12 for a list of the order in which preconditions are
-evaluated.
+evaluated. See also the $verify_mode variable.
-+-------------+--------------+-------------+-------------+
++--------------------------------------------------------+
|verify_sender|Use: routers**|Type: boolean|Default: true|
-+-------------+--------------+-------------+-------------+
++--------------------------------------------------------+
If this option is false, the router is skipped when verifying sender addresses
or testing sender verification using -bvs. See section 3.12 for a list of the
-order in which preconditions are evaluated.
+order in which preconditions are evaluated. See also the $verify_mode variable.
MX records of equal priority are sorted by Exim into a random order. Exim then
looks for address records for the host names obtained from MX or SRV records.
When a host has more than one IP address, they are sorted into a random order,
-except that IPv6 addresses are always sorted before IPv4 addresses. If all the
-IP addresses found are discarded by a setting of the ignore_target_hosts
-generic option, the router declines.
+except that IPv6 addresses are sorted before IPv4 addresses. If all the IP
+addresses found are discarded by a setting of the ignore_target_hosts generic
+option, the router declines.
Unless they have the highest priority (lowest MX value), MX records that point
to the local host, or to any host name that matches hosts_treat_as_local, are
------------------------------
There have been problems with DNS servers when SRV records are looked up. Some
-mis-behaving servers return a DNS error or timeout when a non-existent SRV
+misbehaving servers return a DNS error or timeout when a non-existent SRV
record is sought. Similar problems have in the past been reported for MX
records. The global dns_again_means_nonexist option can help with this problem,
but it is heavy-handed because it is a global option.
address; if such a router is expected to handle "all remaining non-local
domains", then it is important to set no_more.
+The router will defer rather than decline if the domain is found in the
+fail_defer_domains router option.
+
Reasons for a dnslookup router to decline currently include:
* The domain does not exist in DNS
The private options for the dnslookup router are as follows:
-+------------------+--------------+-------------+--------------+
++--------------------------------------------------------------+
|check_secondary_mx|Use: dnslookup|Type: boolean|Default: false|
-+------------------+--------------+-------------+--------------+
++--------------------------------------------------------------+
If this option is set, the router declines unless the local host is found in
(and removed from) the list of hosts obtained by MX lookup. This can be used to
differently to other domains. The way in which Exim decides whether a host is
the local host is described in section 13.8.
-+---------+--------------+-------------+--------------+
++-----------------------------------------------------+
|check_srv|Use: dnslookup|Type: string*|Default: unset|
-+---------+--------------+-------------+--------------+
++-----------------------------------------------------+
The dnslookup router supports the use of SRV records (see RFC 2782) in addition
to MX and address records. The support is disabled by default. To enable SRV
See section 17.1 above for a discussion of Exim's behaviour when there is a DNS
lookup error.
-+----------------------+--------------+------------------+--------------+
-|dnssec_request_domains|Use: dnslookup|Type: domain list*|Default: unset|
-+----------------------+--------------+------------------+--------------+
++-------------------------------------------------------------------+
+|fail_defer_domains|Use: dnslookup|Type: domain list*|Default: unset|
++-------------------------------------------------------------------+
-DNS lookups for domains matching dnssec_request_domains will be done with the
-dnssec request bit set. This applies to all of the SRV, MX A6, AAAA, A lookup
-sequence.
+DNS lookups for domains matching fail_defer_domains which find no matching
+record will cause the router to defer rather than the default behaviour of
+decline. This maybe be useful for queueing messages for a newly created domain
+while the DNS configuration is not ready. However, it will result in any
+message with mistyped domains also being queued.
-+----------------------+--------------+------------------+--------------+
-|dnssec_require_domains|Use: dnslookup|Type: domain list*|Default: unset|
-+----------------------+--------------+------------------+--------------+
++-------------------------------------------+
+|ipv4_only|Use: string*|Type: unset|Default:|
++-------------------------------------------+
-DNS lookups for domains matching dnssec_request_domains will be done with the
-dnssec request bit set. Any returns not having the Authenticated Data bit (AD
-bit) set wil be ignored and logged as a host-lookup failure. This applies to
-all of the SRV, MX A6, AAAA, A lookup sequence.
+The string is expanded, and if the result is anything but a forced failure, or
+an empty string, or one of the strings ?0? or ?no? or ?false? (checked without
+regard to the case of the letters), only A records are used.
+
++---------------------------------------------+
+|ipv4_prefer|Use: string*|Type: unset|Default:|
++---------------------------------------------+
-+----------+--------------+------------------+--------------+
+The string is expanded, and if the result is anything but a forced failure, or
+an empty string, or one of the strings ?0? or ?no? or ?false? (checked without
+regard to the case of the letters), A records are sorted before AAAA records
+(inverting the default).
+
++-----------------------------------------------------------+
|mx_domains|Use: dnslookup|Type: domain list*|Default: unset|
-+----------+--------------+------------------+--------------+
++-----------------------------------------------------------+
A domain that matches mx_domains is required to have either an MX or an SRV
record in order to be recognized. (The name of this option could be improved.)
has no MX record should be bounced immediately instead of being routed using
the address record.
-+---------------+--------------+------------------+--------------+
++----------------------------------------------------------------+
|mx_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
-+---------------+--------------+------------------+--------------+
++----------------------------------------------------------------+
If the DNS lookup for MX records for one of the domains in this list causes a
DNS lookup error, Exim behaves as if no MX records were found. See section 17.1
for more discussion.
-+--------------+--------------+-------------+-------------+
++---------------------------------------------------------+
|qualify_single|Use: dnslookup|Type: boolean|Default: true|
-+--------------+--------------+-------------+-------------+
++---------------------------------------------------------+
When this option is true, the resolver option RES_DEFNAMES is set for DNS
lookups. Typically, but not standardly, this causes the resolver to qualify
thesaurus.ref.example inside the resolver. For details of what your resolver
actually does, consult your man pages for resolver and resolv.conf.
-+---------------+--------------+-------------+-------------+
++----------------------------------------------------------+
|rewrite_headers|Use: dnslookup|Type: boolean|Default: true|
-+---------------+--------------+-------------+-------------+
++----------------------------------------------------------+
If the domain name in the address that is being processed is not fully
qualified, it may be expanded to its full form by a DNS lookup. For example, if
name returned by a DNS lookup begins with an asterisk, it is not used for
header rewriting.
-+------------------------+--------------+-------------+--------------+
++--------------------------------------------------------------------+
|same_domain_copy_routing|Use: dnslookup|Type: boolean|Default: false|
-+------------------------+--------------+-------------+--------------+
++--------------------------------------------------------------------+
Addresses with the same domain are normally routed by the dnslookup router to
the same list of hosts. However, this cannot be presumed, because the router
* The router did not change the address in any way, for example, by
"widening" the domain.
-+--------------+--------------+-------------+--------------+
++----------------------------------------------------------+
|search_parents|Use: dnslookup|Type: boolean|Default: false|
-+--------------+--------------+-------------+--------------+
++----------------------------------------------------------+
When this option is true, the resolver option RES_DNSRCH is set for DNS
lookups. This is different from the qualify_single option in that it applies to
record, because any domain that does not have its own MX record matches the
local wildcard.
-+----------------+--------------+------------------+--------------+
++-----------------------------------------------------------------+
|srv_fail_domains|Use: dnslookup|Type: domain list*|Default: unset|
-+----------------+--------------+------------------+--------------+
++-----------------------------------------------------------------+
If the DNS lookup for SRV records for one of the domains in this list causes a
DNS lookup error, Exim behaves as if no SRV records were found. See section
17.1 for more discussion.
-+-------------+--------------+-----------------+--------------+
++-------------------------------------------------------------+
|widen_domains|Use: dnslookup|Type: string list|Default: unset|
-+-------------+--------------+-----------------+--------------+
++-------------------------------------------------------------+
If a DNS lookup fails and this option is set, each of its strings in turn is
added onto the end of the domain, and the lookup is tried again. For example,
can be deferred. Since iplookup is just a rewriting router, a transport must
not be specified for it.
-+-----+-------------+------------+--------------+
++-----------------------------------------------+
|hosts|Use: iplookup|Type: string|Default: unset|
-+-----+-------------+------------+--------------+
++-----------------------------------------------+
This option must be supplied. Its value is a colon-separated list of host
names. The hosts are looked up using gethostbyname() (or getipnodebyname() when
available) and are tried in order until one responds to the query. If none
respond, what happens is controlled by optional.
-+--------+-------------+-------------+--------------+
++---------------------------------------------------+
|optional|Use: iplookup|Type: boolean|Default: false|
-+--------+-------------+-------------+--------------+
++---------------------------------------------------+
If optional is true, if no response is obtained from any host, the address is
passed to the next router, overriding no_more. If optional is false, delivery
to the address is deferred.
-+----+-------------+-------------+----------+
++-------------------------------------------+
|port|Use: iplookup|Type: integer|Default: 0|
-+----+-------------+-------------+----------+
++-------------------------------------------+
This option must be supplied. It specifies the port number for the TCP or UDP
call.
-+--------+-------------+------------+------------+
++------------------------------------------------+
|protocol|Use: iplookup|Type: string|Default: udp|
-+--------+-------------+------------+------------+
++------------------------------------------------+
This option can be set to "udp" or "tcp" to specify which of the two protocols
is to be used.
-+-----+-------------+-------------+------------------+
++----------------------------------------------------+
|query|Use: iplookup|Type: string*|Default: see below|
-+-----+-------------+-------------+------------------+
++----------------------------------------------------+
This defines the content of the query that is sent to the remote hosts. The
default value is:
The repetition serves as a way of checking that a response is to the correct
query in the default case (see response_pattern below).
-+-------+-------------+-------------+--------------+
++--------------------------------------------------+
|reroute|Use: iplookup|Type: string*|Default: unset|
-+-------+-------------+-------------+--------------+
++--------------------------------------------------+
If this option is not set, the rerouted address is precisely the byte string
returned by the remote host, up to the first white space, if any. If set, the
pattern is in use. In all cases, the rerouted address must end up in the form
local_part@domain.
-+----------------+-------------+------------+--------------+
++----------------------------------------------------------+
|response_pattern|Use: iplookup|Type: string|Default: unset|
-+----------------+-------------+------------+--------------+
++----------------------------------------------------------+
This option can be set to a regular expression that is applied to the string
returned from the remote host. If the pattern does not match the response, the
response_pattern = ^([^@]+)$
reroute = $local_part@$1
-+-------+-------------+----------+-----------+
++--------------------------------------------+
|timeout|Use: iplookup|Type: time|Default: 5s|
-+-------+-------------+----------+-----------+
++--------------------------------------------+
This specifies the amount of time to wait for a response from the remote
machine. The same timeout is used for the connect() function for a TCP call. It
The private options for the manualroute router are as follows:
-+----------------+----------------+------------+--------------+
++-------------------------------------------------------------+
|host_all_ignored|Use: manualroute|Type: string|Default: defer|
-+----------------+----------------+------------+--------------+
++-------------------------------------------------------------+
See host_find_failed.
-+----------------+----------------+------------+---------------+
++--------------------------------------------------------------+
|host_find_failed|Use: manualroute|Type: string|Default: freeze|
-+----------------+----------------+------------+---------------+
++--------------------------------------------------------------+
This option controls what happens when manualroute tries to find an IP address
for a host, and the host does not exist. The option can be set to one of the
if a host lookup gets a temporary error, delivery is deferred unless the
generic pass_on_timeout option is set.
-+---------------+----------------+-------------+--------------+
++-------------------------------------------------------------+
|hosts_randomize|Use: manualroute|Type: boolean|Default: false|
-+---------------+----------------+-------------+--------------+
++-------------------------------------------------------------+
If this option is set, the order of the items in a host list in a routing rule
is randomized each time the list is used, unless an option in the routing rule
randomized host list is passed to an smtp transport that also has
hosts_randomize set, the list is not re-randomized.
-+----------+----------------+-------------+--------------+
++--------------------------------------------------------+
|route_data|Use: manualroute|Type: string*|Default: unset|
-+----------+----------------+-------------+--------------+
++--------------------------------------------------------+
If this option is set, it must expand to yield the data part of a routing rule.
Typically, the expansion string includes a lookup based on the domain. For
router declines. Other kinds of expansion failure cause delivery to be
deferred.
-+----------+----------------+-----------------+--------------+
++------------------------------------------------------------+
|route_list|Use: manualroute|Type: string list|Default: unset|
-+----------+----------------+-----------------+--------------+
++------------------------------------------------------------+
This string is a list of routing rules, in the form defined below. Note that,
unlike most string lists, the items are separated by semicolons. This is so
that they may contain colon-separated host lists.
-+------------------------+----------------+-------------+--------------+
++----------------------------------------------------------------------+
|same_domain_copy_routing|Use: manualroute|Type: boolean|Default: false|
-+------------------------+----------------+-------------+--------------+
++----------------------------------------------------------------------+
Addresses with the same domain are normally routed by the manualroute router to
the same list of hosts. However, this cannot be presumed, because the router
The value of route_list is a string consisting of a sequence of routing rules,
separated by semicolons. If a semicolon is needed in a rule, it can be entered
as two semicolons. Alternatively, the list separator can be changed as
-described (for colon-separated lists) in section 6.19. Empty rules are ignored.
+described (for colon-separated lists) in section 6.20. Empty rules are ignored.
The format of each rule is
<domain pattern> <list of hosts> <options>
A list of hosts, whether obtained via route_data or route_list, is always
separately expanded before use. If the expansion fails, the router declines.
The result of the expansion must be a colon-separated list of names and/or IP
-addresses, optionally also including ports. The format of each item in the list
-is described in the next section. The list separator can be changed as
-described in section 6.19.
+addresses, optionally also including ports. If the list is written with spaces,
+it must be protected with quotes. The format of each item in the list is
+described in the next section. The list separator can be changed as described
+in section 6.21.
If the list of hosts was obtained from a route_list item, the following
variables are set during its expansion:
20.7 How the options are used
-----------------------------
-The options are a sequence of words; in practice no more than three are ever
-present. One of the words can be the name of a transport; this overrides the
-transport option on the router for this particular routing rule only. The other
-words (if present) control randomization of the list of hosts on a per-rule
-basis, and how the IP addresses of the hosts are to be found when routing to a
-remote transport. These options are as follows:
+The options are a sequence of words, space-separated. One of the words can be
+the name of a transport; this overrides the transport option on the router for
+this particular routing rule only. The other words (if present) control
+randomization of the list of hosts on a per-rule basis, and how the IP
+addresses of the hosts are to be found when routing to a remote transport.
+These options are as follows:
* randomize: randomize the order of the hosts in this list, overriding the
setting of hosts_randomize for this routing rule only.
no address records are found. If there is a temporary DNS error (such as a
timeout), delivery is deferred.
+ * ipv4_only: in direct DNS lookups, look up only A records.
+
+ * ipv4_prefer: in direct DNS lookups, sort A records before AAAA records.
+
For example:
route_list = domain1 host1:host2:host3 randomize bydns;\
TRY_AGAIN. That is why the default action is to try a DNS lookup first. Only if
that gives a definite "no such host" is the local function called.
+Compatibility: From Exim 4.85 until fixed for 4.90, there was an inadvertent
+constraint that a transport name as an option had to be the last option
+specified.
+
If no IP address for a host can be found, what happens is controlled by the
host_find_failed option.
skip this router for most addresses, it could sensibly be used in special
cases, even on a busy host. There are the following private options:
-+-------+-----------------+-------------+--------------+
++------------------------------------------------------+
|command|Use: queryprogram|Type: string*|Default: unset|
-+-------+-----------------+-------------+--------------+
++------------------------------------------------------+
This option must be set. It specifies the command that is to be run. The
command is split up into a command name and arguments, and then each is
expanded separately (exactly as for a pipe transport, described in chapter 29).
-+-------------+-----------------+------------+--------------+
++-----------------------------------------------------------+
|command_group|Use: queryprogram|Type: string|Default: unset|
-+-------------+-----------------+------------+--------------+
++-----------------------------------------------------------+
This option specifies a gid to be set when running the command while routing an
address for deliver. It must be set if command_user specifies a numerical uid.
If it begins with a digit, it is interpreted as the numerical value of the gid.
Otherwise it is looked up using getgrnam().
-+------------+-----------------+------------+--------------+
++----------------------------------------------------------+
|command_user|Use: queryprogram|Type: string|Default: unset|
-+------------+-----------------+------------+--------------+
++----------------------------------------------------------+
This option must be set. It specifies the uid which is set when running the
command while routing an address for delivery. If the value begins with a
the command. In this circumstance the command runs under the current uid and
gid.
-+-----------------+-----------------+------------+----------+
++-----------------------------------------------------------+
|current_directory|Use: queryprogram|Type: string|Default: /|
-+-----------------+-----------------+------------+----------+
++-----------------------------------------------------------+
This option specifies an absolute path which is made the current directory
before running the command.
-+-------+-----------------+----------+-----------+
++------------------------------------------------+
|timeout|Use: queryprogram|Type: time|Default: 1h|
-+-------+-----------------+----------+-----------+
++------------------------------------------------+
If the command does not complete within the timeout period, its process group
is killed and the message is frozen. A value of zero time specifies no timeout.
and pipes, and for generating autoreplies. See the file_transport,
pipe_transport and reply_transport descriptions below.
+If success DSNs have been requested redirection triggers one and the DSN
+options are not passed any further.
+
22.1 Redirection data
---------------------
* Otherwise, the data must be a comma-separated list of redirection items, as
described in the next section.
-When a message is redirected to a file (a "mail folder"), the file name given
-in a non-filter redirection list must always be an absolute path. A filter may
+When a message is redirected to a file (a "mail folder"), the filename given in
+a non-filter redirection list must always be an absolute path. A filter may
generate a relative path - how this is handled depends on the transport's
configuration. See section 26.1 for a discussion of this issue for the
appendfile transport.
When the redirection data is not an Exim or Sieve filter, for example, if it
comes from a conventional alias or forward file, it consists of a list of
-addresses, file names, pipe commands, or certain special items (see section
-22.6 below). The special items can be individually enabled or disabled by means
-of options whose names begin with allow_ or forbid_, depending on their default
+addresses, filenames, pipe commands, or certain special items (see section 22.6
+below). The special items can be individually enabled or disabled by means of
+options whose names begin with allow_ or forbid_, depending on their default
values. The items in the list are separated by commas or newlines. If a comma
is required in an item, the entire item must be enclosed in double quotes.
/home/world/minbari
- is treated as a file name, but
+ is treated as a filename, but
/s=molari/o=babylon/@x400gate.way
- is treated as an address. For a file name, a transport must be specified
+ is treated as an address. For a filename, a transport must be specified
using the file_transport option. However, if the generated path name ends
with a forward slash character, it is interpreted as a directory name
- rather than a file name, and directory_transport is used instead.
+ rather than a filename, and directory_transport is used instead.
Normally, either the router or the transport specifies a user and a group
under which to run the delivery. The default is to use the Exim user and
* Sometimes you want to throw away mail to a particular local part. Making
the data option expand to an empty string does not work, because that
- causes the router to decline. Instead, the alias item :blackhole: can be
- used. It does what its name implies. No delivery is done, and no error
- message is generated. This has the same effect as specifing /dev/null as a
- destination, but it can be independently disabled.
+ causes the router to decline. Instead, the alias item
+
+ :blackhole:
+
+ can be used. It does what its name implies. No delivery is done, and no
+ error message is generated. This has the same effect as specifying /dev/
+ null as a destination, but it can be independently disabled.
Warning: If :blackhole: appears anywhere in a redirection list, no delivery
is done for the original local part, even if other redirection items are
During routing for message delivery (as opposed to verification), a
redirection containing :fail: causes an immediate failure of the incoming
- address, whereas :defer: causes the message to remain on the queue so that
+ address, whereas :defer: causes the message to remain in the queue so that
a subsequent delivery attempt can happen at a later time. If an address is
deferred for too long, it will ultimately fail, because the normal retry
rules still apply.
The private options for the redirect router are as follows:
-+-----------+-------------+-------------+--------------+
++------------------------------------------------------+
|allow_defer|Use: redirect|Type: boolean|Default: false|
-+-----------+-------------+-------------+--------------+
++------------------------------------------------------+
Setting this option allows the use of :defer: in non-filter redirection data,
or the defer command in an Exim filter file.
-+----------+-------------+-------------+--------------+
++-----------------------------------------------------+
|allow_fail|Use: redirect|Type: boolean|Default: false|
-+----------+-------------+-------------+--------------+
++-----------------------------------------------------+
If this option is true, the :fail: item can be used in a redirection list, and
the fail command may be used in an Exim filter file.
-+------------+-------------+-------------+--------------+
++-------------------------------------------------------+
|allow_filter|Use: redirect|Type: boolean|Default: false|
-+------------+-------------+-------------+--------------+
++-------------------------------------------------------+
Setting this option allows Exim to interpret redirection data that starts with
"#Exim filter" or "#Sieve filter" as a set of filtering instructions. There are
run as the relevant user. When allow_filter is set true, Exim insists that
either check_local_user or user is set.
-+------------+-------------+-------------+--------------+
++-------------------------------------------------------+
|allow_freeze|Use: redirect|Type: boolean|Default: false|
-+------------+-------------+-------------+--------------+
++-------------------------------------------------------+
Setting this option allows the use of the freeze command in an Exim filter.
This command is more normally encountered in system filters, and is disabled by
default for redirection filters because it isn't something you usually want to
let ordinary users do.
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
|check_ancestor|Use: redirect|Type: boolean|Default: false|
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
This option is concerned with handling generated addresses that are the same as
some address in the list of redirection ancestors of the current address.
the .forward file prevents it from turning "jb" back into "joe.bloggs" when
that was the original address. See also the repeat_use option below.
-+-----------+-------------+-------------+------------------+
++----------------------------------------------------------+
|check_group|Use: redirect|Type: boolean|Default: see below|
-+-----------+-------------+-------------+------------------+
++----------------------------------------------------------+
When the file option is used, the group owner of the file is checked only when
this option is set. The permitted groups are those listed in the owngroups
group write bit, or if the owngroups option is set. Otherwise it is false, and
no group check occurs.
-+-----------+-------------+-------------+------------------+
++----------------------------------------------------------+
|check_owner|Use: redirect|Type: boolean|Default: see below|
-+-----------+-------------+-------------+------------------+
++----------------------------------------------------------+
When the file option is used, the owner of the file is checked only when this
option is set. If check_local_user is set, the local user is permitted;
default value for this option is true if check_local_user or owners is set.
Otherwise the default is false, and no owner check occurs.
-+----+-------------+-------------+--------------+
++-----------------------------------------------+
|data|Use: redirect|Type: string*|Default: unset|
-+----+-------------+-------------+--------------+
++-----------------------------------------------+
This option is mutually exclusive with file. One or other of them must be set,
but not both. The contents of data are expanded, and then used as the list of
you can use the ${sg} expansion item to turn the escape string of your choice
into a newline.
-+-------------------+-------------+-------------+--------------+
++--------------------------------------------------------------+
|directory_transport|Use: redirect|Type: string*|Default: unset|
-+-------------------+-------------+-------------+--------------+
++--------------------------------------------------------------+
A redirect router sets up a direct delivery to a directory when a path name
ending with a slash is specified as a new "address". The transport used is
specified by this option, which, after expansion, must be the name of a
configured transport. This should normally be an appendfile transport.
-+----+-------------+-------------+--------------+
++-----------------------------------------------+
|file|Use: redirect|Type: string*|Default: unset|
-+----+-------------+-------------+--------------+
++-----------------------------------------------+
This option specifies the name of a file that contains the redirection data. It
is mutually exclusive with the data option. The string is expanded before use;
a mount problem. If the containing directory does exist, but the file does not,
the router declines.
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
|file_transport|Use: redirect|Type: string*|Default: unset|
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
A redirect router sets up a direct delivery to a file when a path name not
ending in a slash is specified as a new "address". The transport used is
specified by this option, which, after expansion, must be the name of a
configured transport. This should normally be an appendfile transport. When it
-is running, the file name is in $address_file.
+is running, the filename is in $address_file.
-+-------------------+-------------+-------------+-------------+
++-------------------------------------------------------------+
|filter_prepend_home|Use: redirect|Type: boolean|Default: true|
-+-------------------+-------------+-------------+-------------+
++-------------------------------------------------------------+
When this option is true, if a save command in an Exim filter specifies a
relative path, and $home is defined, it is automatically prepended to the
relative path. If this option is set false, this action does not happen. The
relative path is then passed to the transport unmodified.
-+----------------+-------------+-------------+--------------+
++-----------------------------------------------------------+
|forbid_blackhole|Use: redirect|Type: boolean|Default: false|
-+----------------+-------------+-------------+--------------+
++-----------------------------------------------------------+
If this option is true, the :blackhole: item may not appear in a redirection
list.
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
|forbid_exim_filter|Use: redirect|Type: boolean|Default: false|
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
If this option is set true, only Sieve filters are permitted when allow_filter
is true.
-+-----------+-------------+-------------+--------------+
++------------------------------------------------------+
|forbid_file|Use: redirect|Type: boolean|Default: false|
-+-----------+-------------+-------------+--------------+
++------------------------------------------------------+
If this option is true, this router may not generate a new address that
specifies delivery to a local file or directory, either from a filter or from a
It applies to Sieve filters as well as to Exim filters, but if true, it locks
out the Sieve's "keep" facility.
-+--------------------+-------------+-------------+--------------+
++---------------------------------------------------------------+
|forbid_filter_dlfunc|Use: redirect|Type: boolean|Default: false|
-+--------------------+-------------+-------------+--------------+
++---------------------------------------------------------------+
If this option is true, string expansions in Exim filters are not allowed to
make use of the dlfunc expansion facility to run dynamically loaded functions.
-+------------------------+-------------+-------------+--------------+
++-------------------------------------------------------------------+
|forbid_filter_existstest|Use: redirect|Type: boolean|Default: false|
-+------------------------+-------------+-------------+--------------+
++-------------------------------------------------------------------+
If this option is true, string expansions in Exim filters are not allowed to
make use of the exists condition or the stat expansion item.
-+----------------------+-------------+-------------+--------------+
++-----------------------------------------------------------------+
|forbid_filter_logwrite|Use: redirect|Type: boolean|Default: false|
-+----------------------+-------------+-------------+--------------+
++-----------------------------------------------------------------+
If this option is true, use of the logging facility in Exim filters is not
permitted. Logging is in any case available only if the filter is being run
under some unprivileged uid (which is normally the case for ordinary users'
.forward files).
-+--------------------+-------------+-------------+--------------+
++---------------------------------------------------------------+
|forbid_filter_lookup|Use: redirect|Type: boolean|Default: false|
-+--------------------+-------------+-------------+--------------+
++---------------------------------------------------------------+
If this option is true, string expansions in Exim filter files are not allowed
to make use of lookup items.
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
|forbid_filter_perl|Use: redirect|Type: boolean|Default: false|
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
This option has an effect only if Exim is built with embedded Perl support. If
it is true, string expansions in Exim filter files are not allowed to make use
of the embedded Perl support.
-+----------------------+-------------+-------------+--------------+
++-----------------------------------------------------------------+
|forbid_filter_readfile|Use: redirect|Type: boolean|Default: false|
-+----------------------+-------------+-------------+--------------+
++-----------------------------------------------------------------+
If this option is true, string expansions in Exim filter files are not allowed
to make use of readfile items.
-+------------------------+-------------+-------------+--------------+
++-------------------------------------------------------------------+
|forbid_filter_readsocket|Use: redirect|Type: boolean|Default: false|
-+------------------------+-------------+-------------+--------------+
++-------------------------------------------------------------------+
If this option is true, string expansions in Exim filter files are not allowed
to make use of readsocket items.
-+-------------------+-------------+-------------+--------------+
++--------------------------------------------------------------+
|forbid_filter_reply|Use: redirect|Type: boolean|Default: false|
-+-------------------+-------------+-------------+--------------+
++--------------------------------------------------------------+
If this option is true, this router may not generate an automatic reply
message. Automatic replies can be generated only from Exim or Sieve filter
files, not from traditional forward files. This option is forced to be true if
one_time is set.
-+-----------------+-------------+-------------+--------------+
++------------------------------------------------------------+
|forbid_filter_run|Use: redirect|Type: boolean|Default: false|
-+-----------------+-------------+-------------+--------------+
++------------------------------------------------------------+
If this option is true, string expansions in Exim filter files are not allowed
to make use of run items.
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
|forbid_include|Use: redirect|Type: boolean|Default: false|
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
If this option is true, items of the form
are not permitted in non-filter redirection lists.
-+-----------+-------------+-------------+--------------+
++------------------------------------------------------+
|forbid_pipe|Use: redirect|Type: boolean|Default: false|
-+-----------+-------------+-------------+--------------+
++------------------------------------------------------+
If this option is true, this router may not generate a new address which
specifies delivery to a pipe, either from an Exim filter or from a conventional
forward file. This option is forced to be true if one_time is set.
-+-------------------+-------------+-------------+--------------+
++--------------------------------------------------------------+
|forbid_sieve_filter|Use: redirect|Type: boolean|Default: false|
-+-------------------+-------------+-------------+--------------+
++--------------------------------------------------------------+
If this option is set true, only Exim filters are permitted when allow_filter
is true.
-+----------------+-------------+-------------+--------------+
++-----------------------------------------------------------+
|forbid_smtp_code|Use: redirect|Type: boolean|Default: false|
-+----------------+-------------+-------------+--------------+
++-----------------------------------------------------------+
If this option is set true, any SMTP error codes that are present at the start
of messages specified for ":defer:" or ":fail:" are quietly ignored, and the
default codes (451 and 550, respectively) are always used.
-+--------------------+-------------+-------------+--------------+
++---------------------------------------------------------------+
|hide_child_in_errmsg|Use: redirect|Type: boolean|Default: false|
-+--------------------+-------------+-------------+--------------+
++---------------------------------------------------------------+
If this option is true, it prevents Exim from quoting a child address if it
generates a bounce or delay message for it. Instead it says "an address
bounces generated locally. If a message is forwarded to another host, its
bounce may well quote the generated address.
-+-------------+-------------+-------------+--------------+
++--------------------------------------------------------+
|ignore_eacces|Use: redirect|Type: boolean|Default: false|
-+-------------+-------------+-------------+--------------+
++--------------------------------------------------------+
If this option is set and an attempt to open a redirection file yields the
EACCES error (permission denied), the redirect router behaves as if the file
did not exist.
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
|ignore_enotdir|Use: redirect|Type: boolean|Default: false|
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
If this option is set and an attempt to open a redirection file yields the
ENOTDIR error (something on the path is not a directory), the redirect router
(the ENOTDIR error). This is a confusing area, because it seems that some
operating systems give ENOENT where others give ENOTDIR.
-+-----------------+-------------+------------+--------------+
++-----------------------------------------------------------+
|include_directory|Use: redirect|Type: string|Default: unset|
-+-----------------+-------------+------------+--------------+
++-----------------------------------------------------------+
If this option is set, the path names of any :include: items in a redirection
list must start with this directory.
-+--------+-------------+-------------------+------------+
++-------------------------------------------------------+
|modemask|Use: redirect|Type: octal integer|Default: 022|
-+--------+-------------+-------------------+------------+
++-------------------------------------------------------+
This specifies mode bits which must not be set for a file specified by the file
option. If any of the forbidden bits are set, delivery is deferred.
-+--------+-------------+-------------+--------------+
++---------------------------------------------------+
|one_time|Use: redirect|Type: boolean|Default: false|
-+--------+-------------+-------------+--------------+
++---------------------------------------------------+
Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
files each time it tries to deliver a message causes a problem when one or more
all_parents log selector is set. It is expected that one_time will typically be
used for mailing lists, where there is normally just one level of expansion.
-+------+-------------+-----------------+--------------+
++-----------------------------------------------------+
|owners|Use: redirect|Type: string list|Default: unset|
-+------+-------------+-----------------+--------------+
++-----------------------------------------------------+
This specifies a list of permitted owners for the file specified by file. This
list is in addition to the local user when check_local_user is set. See
check_owner above.
-+---------+-------------+-----------------+--------------+
++--------------------------------------------------------+
|owngroups|Use: redirect|Type: string list|Default: unset|
-+---------+-------------+-----------------+--------------+
++--------------------------------------------------------+
This specifies a list of permitted groups for the file specified by file. The
list is in addition to the local user's primary group when check_local_user is
set. See check_group above.
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
|pipe_transport|Use: redirect|Type: string*|Default: unset|
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
A redirect router sets up a direct delivery to a pipe when a string starting
with a vertical bar character is specified as a new "address". The transport
configured transport. This should normally be a pipe transport. When the
transport is run, the pipe command is in $address_pipe.
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
|qualify_domain|Use: redirect|Type: string*|Default: unset|
-+--------------+-------------+-------------+--------------+
++---------------------------------------------------------+
If this option is set, and an unqualified address (one without a domain) is
generated, and that address would normally be qualified by the global setting
for traditional .forward files, it applies only to addresses that are not
preceded by a backslash. Sieve filters cannot generate unqualified addresses.
-+-----------------------+-------------+-------------+--------------+
++------------------------------------------------------------------+
|qualify_preserve_domain|Use: redirect|Type: boolean|Default: false|
-+-----------------------+-------------+-------------+--------------+
++------------------------------------------------------------------+
If this option is set, the router's local qualify_domain option must not be set
(a configuration error occurs if it is). If an unqualified address (one without
value. In the case of a traditional .forward file, this applies whether or not
the address is preceded by a backslash.
-+----------+-------------+-------------+-------------+
++----------------------------------------------------+
|repeat_use|Use: redirect|Type: boolean|Default: true|
-+----------+-------------+-------------+-------------+
++----------------------------------------------------+
If this option is set false, the router is skipped for a child address that has
any ancestor that was routed by this router. This test happens before any of
when the ancestor is the same as the current address. See also check_ancestor
above and the generic redirect_router option.
-+---------------+-------------+-------------+--------------+
++----------------------------------------------------------+
|reply_transport|Use: redirect|Type: string*|Default: unset|
-+---------------+-------------+-------------+--------------+
++----------------------------------------------------------+
A redirect router sets up an automatic reply when a mail or vacation command is
used in a filter file. The transport used is specified by this option, which,
normally be an autoreply transport. Other transports are unlikely to do
anything sensible or useful.
-+-------+-------------+-------------+-------------+
++-------------------------------------------------+
|rewrite|Use: redirect|Type: boolean|Default: true|
-+-------+-------------+-------------+-------------+
++-------------------------------------------------+
If this option is set false, addresses generated by the router are not subject
to address rewriting. Otherwise, they are treated like new addresses and are
rewritten according to the global rewriting rules.
-+----------------+-------------+-------------+--------------+
++-----------------------------------------------------------+
|sieve_subaddress|Use: redirect|Type: string*|Default: unset|
-+----------------+-------------+-------------+--------------+
++-----------------------------------------------------------+
The value of this option is passed to a Sieve filter to specify the :subaddress
part of an address.
-+-----------------+-------------+-------------+--------------+
++------------------------------------------------------------+
|sieve_useraddress|Use: redirect|Type: string*|Default: unset|
-+-----------------+-------------+-------------+--------------+
++------------------------------------------------------------+
The value of this option is passed to a Sieve filter to specify the :user part
of an address. However, if it is unset, the entire original local part
(including any prefix or suffix) is used for :user.
-+------------------------+-------------+-------------+--------------+
++-------------------------------------------------------------------+
|sieve_vacation_directory|Use: redirect|Type: string*|Default: unset|
-+------------------------+-------------+-------------+--------------+
++-------------------------------------------------------------------+
To enable the "vacation" extension for Sieve filters, you must set
sieve_vacation_directory to the directory where vacation databases are held (do
option refers to an autoreply transport. Each user needs their own directory;
Exim will create it if necessary.
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
|skip_syntax_errors|Use: redirect|Type: boolean|Default: false|
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
If skip_syntax_errors is set, syntactically malformed addresses in non-filter
redirection data are skipped, and each failing address is logged. If
condition = ${if match {$sender_host_address}\
{\N^(|127\.0\.0\.1)$\N}}
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
|syntax_errors_text|Use: redirect|Type: string*|Default: unset|
-+------------------+-------------+-------------+--------------+
++-------------------------------------------------------------+
See skip_syntax_errors above.
-+----------------+-------------+------------+--------------+
++----------------------------------------------------------+
|syntax_errors_to|Use: redirect|Type: string|Default: unset|
-+----------------+-------------+------------+--------------+
++----------------------------------------------------------+
See skip_syntax_errors above.
This is supposed to write the message at the end of the file. However, if two
messages arrive at the same time, the file will be scrambled. You can use the
-exim_lock utility program (see section 52.15) to lock a file using the same
+exim_lock utility program (see section 53.15) to lock a file using the same
algorithm that Exim itself uses.
The following generic options apply to all transports:
-+---------+---------------+-------------+--------------+
++------------------------------------------------------+
|body_only|Use: transports|Type: boolean|Default: false|
-+---------+---------------+-------------+--------------+
++------------------------------------------------------+
If this option is set, the message's headers are not transported. It is
mutually exclusive with headers_only. If it is used with the appendfile or pipe
transports, the settings of message_prefix and message_suffix should be
checked, because this option does not automatically suppress them.
-+-----------------+---------------+-------------+--------------+
++--------------------------------------------------------------+
|current_directory|Use: transports|Type: string*|Default: unset|
-+-----------------+---------------+-------------+--------------+
++--------------------------------------------------------------+
This specifies the current directory that is to be set while running the
transport, overriding any value that may have been set by the router. If the
expansion fails for any reason, including forced failure, an error is logged,
and delivery is deferred.
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
|disable_logging|Use: transports|Type: boolean|Default: false|
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
If this option is set true, nothing is logged for any deliveries by the
transport or for any transport errors. You should not set this option unless
you really, really know what you are doing.
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
|debug_print|Use: transports|Type: string*|Default: unset|
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
If this option is set and debugging is enabled (see the -d command line
option), the string is expanded and included in the debugging output when the
variables $transport_name and $router_name contain the name of the transport
and the router that called it.
-+-----------------+---------------+-------------+--------------+
++--------------------------------------------------------------+
|delivery_date_add|Use: transports|Type: boolean|Default: false|
-+-----------------+---------------+-------------+--------------+
++--------------------------------------------------------------+
If this option is true, a Delivery-date: header is added to the message. This
gives the actual time the delivery was made. As this is not a standard header,
removal from incoming messages, so that delivered messages can safely be resent
to other recipients.
-+------+---------------+------------+--------------+
++--------------------------------------------------+
|driver|Use: transports|Type: string|Default: unset|
-+------+---------------+------------+--------------+
++--------------------------------------------------+
This specifies which of the available transport drivers is to be used. There is
no default, and this option must be set for every transport.
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
|envelope_to_add|Use: transports|Type: boolean|Default: false|
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
If this option is true, an Envelope-to: header is added to the message. This
gives the original address(es) in the incoming envelope that caused this
removal from incoming messages, so that delivered messages can safely be resent
to other recipients.
-+-----+---------------+-------------+-------------------+
++---------------------------------------------------------+
+|event_action|Use: transports|Type: string*|Default: unset|
++---------------------------------------------------------+
+
+This option declares a string to be expanded for Exim's events mechanism. For
+details see chapter 60.
+
++-------------------------------------------------------+
|group|Use: transports|Type: string*|Default: Exim group|
-+-----+---------------+-------------+-------------------+
++-------------------------------------------------------+
This option specifies a gid for running the transport process, overriding any
value that the router supplies, and also overriding any value associated with
user (see below).
-+-----------+---------------+-----------+--------------+
++------------------------------------------------------+
|headers_add|Use: transports|Type: list*|Default: unset|
-+-----------+---------------+-----------+--------------+
++------------------------------------------------------+
-This option specifies a list of text headers, newline-separated, which are
-(separately) expanded and added to the header portion of a message as it is
-transported, as described in section 46.17. Additional header lines can also be
-specified by routers. If the result of the expansion is an empty string, or if
-the expansion is forced to fail, no action is taken. Other expansion failures
-are treated as errors and cause the delivery to be deferred.
+This option specifies a list of text headers, newline-separated (by default,
+changeable in the usual way 6.21), which are (separately) expanded and added to
+the header portion of a message as it is transported, as described in section
+47.17. Additional header lines can also be specified by routers. If the result
+of the expansion is an empty string, or if the expansion is forced to fail, no
+action is taken. Other expansion failures are treated as errors and cause the
+delivery to be deferred.
Unlike most options, headers_add can be specified multiple times for a
transport; all listed headers are added.
-+------------+---------------+-------------+--------------+
++---------------------------------------------------------+
|headers_only|Use: transports|Type: boolean|Default: false|
-+------------+---------------+-------------+--------------+
++---------------------------------------------------------+
If this option is set, the message's body is not transported. It is mutually
exclusive with body_only. If it is used with the appendfile or pipe transports,
the settings of message_prefix and message_suffix should be checked, since this
option does not automatically suppress them.
-+--------------+---------------+-----------+--------------+
++---------------------------------------------------------+
|headers_remove|Use: transports|Type: list*|Default: unset|
-+--------------+---------------+-----------+--------------+
++---------------------------------------------------------+
-This option specifies a list of header names, colon-separated; these headers
-are omitted from the message as it is transported, as described in section
-46.17. Header removal can also be specified by routers. Each list item is
-separately expanded. If the result of the expansion is an empty string, or if
-the expansion is forced to fail, no action is taken. Other expansion failures
-are treated as errors and cause the delivery to be deferred.
+This option specifies a list of header names, colon-separated (by default,
+changeable in the usual way 6.21); these headers are omitted from the message
+as it is transported, as described in section 47.17. Header removal can also be
+specified by routers. Each list item is separately expanded. If the result of
+the expansion is an empty string, or if the expansion is forced to fail, no
+action is taken. Other expansion failures are treated as errors and cause the
+delivery to be deferred.
Unlike most options, headers_remove can be specified multiple times for a
-router; all listed headers are removed.
+transport; all listed headers are removed.
-+---------------+---------------+------------+--------------+
+Warning: Because of the separate expansion of the list items, items that
+contain a list separator must have it doubled. To avoid this, change the list
+separator (6.21).
+
++-----------------------------------------------------------+
|headers_rewrite|Use: transports|Type: string|Default: unset|
-+---------------+---------------+------------+--------------+
++-----------------------------------------------------------+
This option allows addresses in header lines to be rewritten at transport time,
that is, as the message is being copied to its destination. The contents of the
change the return path using return_path, but you cannot change envelope
recipients at this time.
-+--------------+---------------+-------------+--------------+
++-----------------------------------------------------------+
|home_directory|Use: transports|Type: string*|Default: unset|
-+--------------+---------------+-------------+--------------+
++-----------------------------------------------------------+
This option specifies a home directory setting for a local transport,
overriding any value that may be set by the router. The home directory is
option on the router. If the expansion fails for any reason, including forced
failure, an error is logged, and delivery is deferred.
-+----------+---------------+-------------+--------------+
++-------------------------------------------------------+
|initgroups|Use: transports|Type: boolean|Default: false|
-+----------+---------------+-------------+--------------+
++-------------------------------------------------------+
If this option is true and the uid for the delivery process is provided by the
transport, the initgroups() function is called when running the transport to
ensure that any additional groups associated with the uid are set up.
-+------------------+---------------+-------------+----------+
++----------------------------------------------------------+
+|max_parallel|Use: transports|Type: integer*|Default: unset|
++----------------------------------------------------------+
+
+If this option is set and expands to an integer greater than zero it limits the
+number of concurrent runs of the transport. The control does not apply to
+shadow transports.
+
+Exim implements this control by means of a hints database in which a record is
+incremented whenever a transport process is being created. The record is
+decremented and possibly removed when the process terminates. Obviously there
+is scope for records to get left lying around if there is a system or program
+crash. To guard against this, Exim ignores any records that are more than six
+hours old.
+
+If you use this option, you should also arrange to delete the relevant hints
+database whenever your system reboots. The names of the files start with misc
+and they are kept in the spool/db directory. There may be one or two files,
+depending on the type of DBM in use. The same files are used for ETRN and smtp
+transport serialization.
+
++-----------------------------------------------------------+
|message_size_limit|Use: transports|Type: string*|Default: 0|
-+------------------+---------------+-------------+----------+
++-----------------------------------------------------------+
This option controls the size of messages passed through the transport. It is
expanded before use; the result of the expansion must be a sequence of decimal
ensure that return_size_limit is less than the transport's message_size_limit,
as otherwise the bounce message will fail to get delivered.
-+--------------------+---------------+-------------+--------------+
++-----------------------------------------------------------------+
|rcpt_include_affixes|Use: transports|Type: boolean|Default: false|
-+--------------------+---------------+-------------+--------------+
++-----------------------------------------------------------------+
When this option is false (the default), and an address that has had any
affixes (prefixes or suffixes) removed from the local part is delivered by any
deliveries by the appendfile and pipe transports as well as to the lmtp and
smtp transports.
-+--------------------+---------------+-------------+------------------+
++---------------------------------------------------------------------+
|retry_use_local_part|Use: transports|Type: boolean|Default: see below|
-+--------------------+---------------+-------------+------------------+
++---------------------------------------------------------------------+
When a delivery suffers a temporary failure, a retry record is created in
Exim's hints database. For remote deliveries, the key for the retry record is
the default value is false for tidiness, but changing the value has no effect
on a remote transport in the current implementation.
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
|return_path|Use: transports|Type: string*|Default: unset|
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
If this option is set, the string is expanded at transport time and replaces
the existing return path (envelope sender) value in the copy of the message
the message's envelope sender, or an address set by the errors_to option on a
router. If the expansion is forced to fail, no replacement occurs; if it fails
for another reason, delivery is deferred. This option can be used to support
-VERP (Variable Envelope Return Paths) - see section 49.6.
+VERP (Variable Envelope Return Paths) - see section 50.6.
Note: If a delivery error is detected locally, including the case when a remote
server rejects a message at SMTP time, the bounce message is not sent to the
defaults to the incoming sender address, but can be changed by setting
errors_to in a router.
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
|return_path_add|Use: transports|Type: boolean|Default: false|
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
If this option is true, a Return-path: header is added to the message. Although
the return path is normally available in the prefix line of BSD mailboxes, this
return_path_remove, which requests removal of this header from incoming
messages, so that delivered messages can safely be resent to other recipients.
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
|shadow_condition|Use: transports|Type: string*|Default: unset|
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
See shadow_transport below.
-+----------------+---------------+------------+--------------+
++------------------------------------------------------------+
|shadow_transport|Use: transports|Type: string|Default: unset|
-+----------------+---------------+------------+--------------+
++------------------------------------------------------------+
A local transport may set the shadow_transport option to the name of another
local transport. Shadow remote transports are not supported.
provides, and implementing automatic acknowledgment policies based on message
headers that some sites insist on.
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
|transport_filter|Use: transports|Type: string*|Default: unset|
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
This option sets up a filtering (in the Unix shell sense) process for messages
at transport time. It should not be confused with mail filtering as set up by
-individual users or via a system filter.
+individual users or via a system filter. If unset, or expanding to an empty
+string, no filtering is done.
When the message is about to be written out, the command specified by
transport_filter is started up in a separate, parallel process, and the entire
passed through the filter as it is being copied into the newly generated
message, which happens if the return_message option is set.
-+------------------------+---------------+----------+-----------+
++---------------------------------------------------------------+
|transport_filter_timeout|Use: transports|Type: time|Default: 5m|
-+------------------------+---------------+----------+-----------+
++---------------------------------------------------------------+
When Exim is reading the output of a transport filter, it applies a timeout
that can be set by this option. Exceeding the timeout is normally treated as a
if the pipe transport's timeout_defer option is set true, it becomes a
temporary error.
-+----+---------------+-------------+------------------+
++-----------------------------------------------------+
|user|Use: transports|Type: string*|Default: Exim user|
-+----+---------------+-------------+------------------+
++-----------------------------------------------------+
This option specifies the user under whose uid the delivery process is to be
run, overriding any uid that may have been set by the router. If the user is
escape_string = ".."
when batched SMTP is in use. A full description of the batch SMTP mechanism is
-given in section 47.10. The lmtp transport does not have a use_bsmtp option,
+given in section 48.10. The lmtp transport does not have a use_bsmtp option,
because it always delivers using the SMTP protocol.
If the generic envelope_to_add option is set for a batching transport, the
fileinto "folder23";
In this situation, the expansion of file or directory in the transport must
-transform the relative path into an appropriate absolute file name. In the case
+transform the relative path into an appropriate absolute filename. In the case
of Sieve filters, the name inbox must be handled. It is the name that is used
as a result of a "keep" action in the filter. This example shows one way of
handling this requirement:
26.2 Private options for appendfile
-----------------------------------
-+----------+---------------+-------------+--------------+
++-------------------------------------------------------+
|allow_fifo|Use: appendfile|Type: boolean|Default: false|
-+----------+---------------+-------------+--------------+
++-------------------------------------------------------+
Setting this option permits delivery to named pipes (FIFOs) as well as to
regular files. If no process is reading the named pipe at delivery time, the
delivery is deferred.
-+-------------+---------------+-------------+--------------+
++----------------------------------------------------------+
|allow_symlink|Use: appendfile|Type: boolean|Default: false|
-+-------------+---------------+-------------+--------------+
++----------------------------------------------------------+
By default, appendfile will not deliver if the path name for the file is that
of a symbolic link. Setting this option relaxes that constraint, but there are
you are doing if you set this. Details of exactly what this option affects are
included in the discussion which follows this list of options.
-+--------+---------------+-------------+--------------+
++-----------------------------------------------------+
|batch_id|Use: appendfile|Type: string*|Default: unset|
-+--------+---------------+-------------+--------------+
++-----------------------------------------------------+
See the description of local delivery batching in chapter 25. However, batching
is automatically disabled for appendfile deliveries that happen as a result of
forwarding or aliasing or other redirection directly to a file.
-+---------+---------------+-------------+----------+
++--------------------------------------------------+
|batch_max|Use: appendfile|Type: integer|Default: 1|
-+---------+---------------+-------------+----------+
++--------------------------------------------------+
See the description of local delivery batching in chapter 25.
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
|check_group|Use: appendfile|Type: boolean|Default: false|
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
When this option is set, the group owner of the file defined by the file option
is checked to see that it is the same as the group under which the delivery
process is running. The default setting is false because the default file mode
is 0600, which means that the group is irrelevant.
-+-----------+---------------+-------------+-------------+
++-------------------------------------------------------+
|check_owner|Use: appendfile|Type: boolean|Default: true|
-+-----------+---------------+-------------+-------------+
++-------------------------------------------------------+
When this option is set, the owner of the file defined by the file option is
checked to ensure that it is the same as the user under which the delivery
process is running.
-+------------+---------------+------------+------------------+
++------------------------------------------------------------+
|check_string|Use: appendfile|Type: string|Default: see below|
-+------------+---------------+------------+------------------+
++------------------------------------------------------------+
As appendfile writes the message, the start of each line is tested for matching
check_string, and if it does, the initial matching characters are replaced by
message_prefix = "\1\1\1\1\n"
message_suffix = "\1\1\1\1\n"
-+----------------+---------------+-------------+-------------+
++------------------------------------------------------------+
|create_directory|Use: appendfile|Type: boolean|Default: true|
-+----------------+---------------+-------------+-------------+
++------------------------------------------------------------+
When this option is true, Exim attempts to create any missing superior
directories for the file that it is about to write. A created directory's mode
is propagated to the child; if not, the currently set group is used. However,
in FreeBSD, the parent's group is always used.
-+-----------+---------------+------------+-----------------+
++----------------------------------------------------------+
|create_file|Use: appendfile|Type: string|Default: anywhere|
-+-----------+---------------+------------+-----------------+
++----------------------------------------------------------+
This option constrains the location of files and directories that are created
by this transport. It applies to files defined by the file option and
The option must be set to one of the words "anywhere", "inhome", or
"belowhome". In the second and third cases, a home directory must have been set
-for the transport. This option is not useful when an explicit file name is
-given for normal mailbox deliveries. It is intended for the case when file
-names are generated from users' .forward files. These are usually handled by an
+for the transport. This option is not useful when an explicit filename is given
+for normal mailbox deliveries. It is intended for the case when filenames are
+generated from users' .forward files. These are usually handled by an
appendfile transport called address_file. See also file_must_exist.
-+---------+---------------+-------------+--------------+
++------------------------------------------------------+
|directory|Use: appendfile|Type: string*|Default: unset|
-+---------+---------------+-------------+--------------+
++------------------------------------------------------+
This option is mutually exclusive with the file option, but one of file or
directory must be set, unless the delivery is the direct result of a
(see maildir_format and mailstore_format), and see section 26.4 for further
details of this form of delivery.
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
|directory_file|Use: appendfile|Type: string*|Default: see below|
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
When directory is set, but neither maildir_format nor mailstore_format is set,
appendfile delivers each message into a file whose name is obtained by
inode of the file. The variable $inode is available only when expanding this
option.
-+--------------+---------------+-------------------+-------------+
++----------------------------------------------------------------+
|directory_mode|Use: appendfile|Type: octal integer|Default: 0700|
-+--------------+---------------+-------------------+-------------+
++----------------------------------------------------------------+
If appendfile creates any directories as a result of the create_directory
option, their mode is specified by this option.
-+-------------+---------------+------------+------------------------+
++-------------------------------------------------------------------+
|escape_string|Use: appendfile|Type: string|Default: see description|
-+-------------+---------------+------------+------------------------+
++-------------------------------------------------------------------+
See check_string above.
-+----+---------------+-------------+--------------+
++-------------------------------------------------+
|file|Use: appendfile|Type: string*|Default: unset|
-+----+---------------+-------------+--------------+
++-------------------------------------------------+
This option is mutually exclusive with the directory option, but one of file or
directory must be set, unless the delivery is the direct result of a
deliveries to be possible, or alternatively the group option can be used to run
the delivery under a group id which has write access to the directory.
-+-----------+---------------+------------+--------------+
++-------------------------------------------------------+
|file_format|Use: appendfile|Type: string|Default: unset|
-+-----------+---------------+------------+--------------+
++-------------------------------------------------------+
This option requests the transport to check the format of an existing file
before adding to it. The check consists of matching a specific string at the
any string, or if the transport named for a given string is not defined,
delivery is deferred.
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
|file_must_exist|Use: appendfile|Type: boolean|Default: false|
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
If this option is true, the file specified by the file option must exist. A
temporary error occurs if it does not, causing delivery to be deferred. If this
option is false, the file is created if it does not exist.
-+------------------+---------------+----------+-----------+
++---------------------------------------------------------+
|lock_fcntl_timeout|Use: appendfile|Type: time|Default: 0s|
-+------------------+---------------+----------+-----------+
++---------------------------------------------------------+
By default, the appendfile transport uses non-blocking calls to fcntl() when
locking an open mailbox file. If the call fails, the delivery process sleeps
failed to lock mailbox /some/file (fcntl)
-+------------------+---------------+----------+-----------+
++---------------------------------------------------------+
|lock_flock_timeout|Use: appendfile|Type: time|Default: 0s|
-+------------------+---------------+----------+-----------+
++---------------------------------------------------------+
This timeout applies to file locking when using flock() (see use_flock); the
timeout operates in a similar manner to lock_fcntl_timeout.
-+-------------+---------------+----------+-----------+
++----------------------------------------------------+
|lock_interval|Use: appendfile|Type: time|Default: 3s|
-+-------------+---------------+----------+-----------+
++----------------------------------------------------+
This specifies the time to wait between attempts to lock the file. See below
for details of locking.
-+------------+---------------+-------------+-----------+
++------------------------------------------------------+
|lock_retries|Use: appendfile|Type: integer|Default: 10|
-+------------+---------------+-------------+-----------+
++------------------------------------------------------+
This specifies the maximum number of attempts to lock the file. A value of zero
is treated as 1. See below for details of locking.
-+-------------+---------------+-------------------+-------------+
++---------------------------------------------------------------+
|lockfile_mode|Use: appendfile|Type: octal integer|Default: 0600|
-+-------------+---------------+-------------------+-------------+
++---------------------------------------------------------------+
This specifies the mode of the created lock file, when a lock file is being
used (see use_lockfile and use_mbx_lock).
-+----------------+---------------+----------+------------+
++--------------------------------------------------------+
|lockfile_timeout|Use: appendfile|Type: time|Default: 30m|
-+----------------+---------------+----------+------------+
++--------------------------------------------------------+
When a lock file is being used (see use_lockfile), if a lock file already
exists and is older than this value, it is assumed to have been left behind by
accident, and Exim attempts to remove it.
-+-----------------+---------------+-------------+--------------+
++--------------------------------------------------------------+
|mailbox_filecount|Use: appendfile|Type: string*|Default: unset|
-+-----------------+---------------+-------------+--------------+
++--------------------------------------------------------------+
If this option is set, it is expanded, and the result is taken as the current
number of files in the mailbox. It must be a decimal number, optionally
followed by K or M. This provides a way of obtaining this information from an
external source that maintains the data.
-+------------+---------------+-------------+--------------+
++---------------------------------------------------------+
|mailbox_size|Use: appendfile|Type: string*|Default: unset|
-+------------+---------------+-------------+--------------+
++---------------------------------------------------------+
If this option is set, it is expanded, and the result is taken as the current
size the mailbox. It must be a decimal number, optionally followed by K or M.
maintains the data. This is likely to be helpful for maildir deliveries where
it is computationally expensive to compute the size of a mailbox.
-+--------------+---------------+-------------+--------------+
++-----------------------------------------------------------+
|maildir_format|Use: appendfile|Type: boolean|Default: false|
-+--------------+---------------+-------------+--------------+
++-----------------------------------------------------------+
If this option is set with the directory option, the delivery is into a new
file, in the "maildir" format that is used by other mail software. When the
or not it ends with "/". This option is available only if SUPPORT_MAILDIR is
present in Local/Makefile. See section 26.5 below for further details.
-+-----------------------------+---------------+------------+------------------+
++-----------------------------------------------------------------------------+
|maildir_quota_directory_regex|Use: appendfile|Type: string|Default: See below|
-+-----------------------------+---------------+------------+------------------+
++-----------------------------------------------------------------------------+
This option is relevant only when maildir_use_size_file is set. It defines a
regular expression for specifying directories, relative to the quota directory
calculations, quota processing is bypassed for any messages that are delivered
directly into that directory.
-+---------------+---------------+-------------+-----------+
++---------------------------------------------------------+
|maildir_retries|Use: appendfile|Type: integer|Default: 10|
-+---------------+---------------+-------------+-----------+
++---------------------------------------------------------+
This option specifies the number of times to retry when writing a file in
"maildir" format. See section 26.5 below.
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
|maildir_tag|Use: appendfile|Type: string*|Default: unset|
-+-----------+---------------+-------------+--------------+
++--------------------------------------------------------+
This option applies only to deliveries in maildir format, and is described in
section 26.5 below.
-+---------------------+----------------+-------------+--------------+
++-------------------------------------------------------------------+
|maildir_use_size_file|Use: appendfile*|Type: boolean|Default: false|
-+---------------------+----------------+-------------+--------------+
++-------------------------------------------------------------------+
The result of string expansion for this option must be a valid boolean value.
If it is true, it enables support for maildirsize files. Exim creates a
quota option of the transport. If quota is unset, the value is zero. See
maildir_quota_directory_regex above and section 26.5 below for further details.
-+--------------------------+---------------+------------+--------------+
++----------------------------------------------------------------------+
|maildirfolder_create_regex|Use: appendfile|Type: string|Default: unset|
-+--------------------------+---------------+------------+--------------+
++----------------------------------------------------------------------+
The value of this option is a regular expression. If it is unset, it has no
effect. Otherwise, before a maildir delivery takes place, the pattern is
maildirfolder in the directory, and creates it if it does not exist. See
section 26.5 for more details.
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
|mailstore_format|Use: appendfile|Type: boolean|Default: false|
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
If this option is set with the directory option, the delivery is into two new
files in "mailstore" format. The option is available only if SUPPORT_MAILSTORE
is present in Local/Makefile. See section 26.4 below for further details.
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
|mailstore_prefix|Use: appendfile|Type: string*|Default: unset|
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
This option applies only to deliveries in mailstore format, and is described in
section 26.4 below.
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
|mailstore_suffix|Use: appendfile|Type: string*|Default: unset|
-+----------------+---------------+-------------+--------------+
++-------------------------------------------------------------+
This option applies only to deliveries in mailstore format, and is described in
section 26.4 below.
-+----------+---------------+-------------+--------------+
++-------------------------------------------------------+
|mbx_format|Use: appendfile|Type: boolean|Default: false|
-+----------+---------------+-------------+--------------+
++-------------------------------------------------------+
This option is available only if Exim has been compiled with SUPPORT_MBX set in
Local/Makefile. If mbx_format is set with the file option, the message is
means for the whole of a Pine or IMAP session), Exim will not be able to append
messages to it.
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
|message_prefix|Use: appendfile|Type: string*|Default: see below|
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
The string specified here is expanded and output at the start of every message.
The default is unset unless file is specified and use_bsmtp is not set, in
Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
n" in message_prefix.
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
|message_suffix|Use: appendfile|Type: string*|Default: see below|
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
The string specified here is expanded and output at the end of every message.
The default is unset unless file is specified and use_bsmtp is not set, in
Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
n" in message_suffix.
-+----+---------------+-------------------+-------------+
++------------------------------------------------------+
|mode|Use: appendfile|Type: octal integer|Default: 0600|
-+----+---------------+-------------------+-------------+
++------------------------------------------------------+
If the output file is created, it is given this mode. If it already exists and
has wider permissions, they are reduced to this mode. If it has narrower
particular mode, the mode of the output file is always forced to take that
value, and this option is ignored.
-+------------------+---------------+-------------+-------------+
++--------------------------------------------------------------+
|mode_fail_narrower|Use: appendfile|Type: boolean|Default: true|
-+------------------+---------------+-------------+-------------+
++--------------------------------------------------------------+
This option applies in the case when an existing mailbox file has a narrower
mode than that specified by the mode option. If mode_fail_narrower is true, the
delivery is deferred ("mailbox has the wrong mode"); otherwise Exim continues
with the delivery attempt, using the existing mode of the file.
-+-------------+---------------+-------------+--------------+
++----------------------------------------------------------+
|notify_comsat|Use: appendfile|Type: boolean|Default: false|
-+-------------+---------------+-------------+--------------+
++----------------------------------------------------------+
If this option is true, the comsat daemon is notified after every successful
delivery to a user mailbox. This is the daemon that notifies logged on users
about incoming mail.
-+-----+---------------+-------------+--------------+
++--------------------------------------------------+
|quota|Use: appendfile|Type: string*|Default: unset|
-+-----+---------------+-------------+--------------+
++--------------------------------------------------+
This option imposes a limit on the size of the file to which Exim is appending,
or to the total space used in the directory tree when the directory option is
The value of the option is expanded, and must then be a numerical value
(decimal point allowed), optionally followed by one of the letters K, M, or G,
-for kilobytes, megabytes, or gigabytes. If Exim is running on a system with
-large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
-be handled.
+for kilobytes, megabytes, or gigabytes, optionally followed by a slash and
+further option modifiers. If Exim is running on a system with large file
+support (Linux and FreeBSD have this), mailboxes larger than 2G can be handled.
+
+The option modifier no_check can be used to force delivery even if the over
+quota condition is met. The quota gets updated as usual.
Note: A value of zero is interpreted as "no quota".
continue until the quota has been exceeded; thereafter, no further messages are
delivered. See also quota_warn_threshold.
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
|quota_directory|Use: appendfile|Type: string*|Default: unset|
-+---------------+---------------+-------------+--------------+
++------------------------------------------------------------+
This option defines the directory to check for quota purposes when delivering
into individual files. The default is the delivery directory, or, if a file
called maildirfolder exists in a maildir directory, the parent of the delivery
directory.
-+---------------+---------------+-------------+----------+
++--------------------------------------------------------+
|quota_filecount|Use: appendfile|Type: string*|Default: 0|
-+---------------+---------------+-------------+----------+
++--------------------------------------------------------+
This option applies when the directory option is set. It limits the total
number of files in the directory (compare the inode limit in system quotas). It
failure causes delivery to be deferred. A value of zero is interpreted as "no
quota".
-+------------------+---------------+-------------+-------------+
+The option modifier no_check can be used to force delivery even if the over
+quota condition is met. The quota gets updated as usual.
+
++--------------------------------------------------------------+
|quota_is_inclusive|Use: appendfile|Type: boolean|Default: true|
-+------------------+---------------+-------------+-------------+
++--------------------------------------------------------------+
See quota above.
-+----------------+---------------+------------+--------------+
++------------------------------------------------------------+
|quota_size_regex|Use: appendfile|Type: string|Default: unset|
-+----------------+---------------+------------+--------------+
++------------------------------------------------------------+
This option applies when one of the delivery modes that writes a separate file
for each message is being used. When Exim wants to find the size of one of
these files in order to test the quota, it first checks quota_size_regex. If
-this is set to a regular expression that matches the file name, and it captures
+this is set to a regular expression that matches the filename, and it captures
one string, that string is interpreted as a representation of the file's size.
The value of quota_size_regex is not expanded.
This feature is useful only when users have no shell access to their mailboxes
- otherwise they could defeat the quota simply by renaming the files. This
facility can be used with maildir deliveries, by setting maildir_tag to add the
-file length to the file name. For example:
+file length to the filename. For example:
maildir_tag = ,S=$message_size
quota_size_regex = ,S=(\d+)
number of lines in the message.
The regular expression should not assume that the length is at the end of the
-file name (even though maildir_tag puts it there) because maildir MUAs
-sometimes add other information onto the ends of message file names.
+filename (even though maildir_tag puts it there) because maildir MUAs sometimes
+add other information onto the ends of message filenames.
Section 26.7 contains further information.
-+------------------+---------------+-------------+------------------+
++-------------------------------------------------------------------+
|quota_warn_message|Use: appendfile|Type: string*|Default: see below|
-+------------------+---------------+-------------+------------------+
++-------------------------------------------------------------------+
See below for the use of this option. If it is not set when
quota_warn_threshold is set, it defaults to
a warning threshold that is\n\
set by the system administrator.\n"
-+--------------------+---------------+-------------+----------+
++-------------------------------------------------------------+
|quota_warn_threshold|Use: appendfile|Type: string*|Default: 0|
-+--------------------+---------------+-------------+----------+
++-------------------------------------------------------------+
This option is expanded in the same way as quota (see above). If the resulting
value is greater than zero, and delivery of the message causes the size of the
independent of one another except when the threshold is specified as a
percentage.
-+---------+---------------+-------------+--------------+
++------------------------------------------------------+
|use_bsmtp|Use: appendfile|Type: boolean|Default: false|
-+---------+---------------+-------------+--------------+
++------------------------------------------------------+
If this option is set true, appendfile writes messages in "batch SMTP" format,
with the envelope sender and recipient(s) included as SMTP commands. If you
want to include a leading HELO command with such messages, you can do so by
-setting the message_prefix option. See section 47.10 for details of batch SMTP.
+setting the message_prefix option. See section 48.10 for details of batch SMTP.
-+--------+---------------+-------------+--------------+
++-----------------------------------------------------+
|use_crlf|Use: appendfile|Type: boolean|Default: false|
-+--------+---------------+-------------+--------------+
++-----------------------------------------------------+
This option causes lines to be terminated with the two-character CRLF sequence
(carriage return, linefeed) instead of just a linefeed character. In the case
have non-empty defaults, the values end with a single linefeed, so they must be
changed to end with "\r\n" if use_crlf is set.
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
|use_fcntl_lock|Use: appendfile|Type: boolean|Default: see below|
-+--------------+---------------+-------------+------------------+
++---------------------------------------------------------------+
This option controls the use of the fcntl() function to lock a file for
exclusive use when a message is being appended. It is set by default unless
all your MUAs use lock file locking. When both use_fcntl_lock and
use_flock_lock are unset, use_lockfile must be set.
-+--------------+---------------+-------------+--------------+
++-----------------------------------------------------------+
|use_flock_lock|Use: appendfile|Type: boolean|Default: false|
-+--------------+---------------+-------------+--------------+
++-----------------------------------------------------------+
This option is provided to support the use of flock() for file locking, for the
few situations where it is needed. Most modern operating systems support fcntl
Warning: flock() locks do not work on NFS files (unless flock() is just being
mapped onto fcntl() by the OS).
-+------------+---------------+-------------+------------------+
++-------------------------------------------------------------+
|use_lockfile|Use: appendfile|Type: boolean|Default: see below|
-+------------+---------------+-------------+------------------+
++-------------------------------------------------------------+
If this option is turned off, Exim does not attempt to create a lock file when
appending to a mailbox file. In this situation, the only locking is by fcntl().
possible to turn both use_lockfile and use_fcntl_lock off, except when
mbx_format is set.
-+------------+---------------+-------------+------------------+
++-------------------------------------------------------------+
|use_mbx_lock|Use: appendfile|Type: boolean|Default: see below|
-+------------+---------------+-------------+------------------+
++-------------------------------------------------------------+
This option is available only if Exim has been compiled with SUPPORT_MBX set in
Local/Makefile. Setting the option specifies that special MBX locking rules be
for writing as a new file. If this fails with an access error, delivery
is deferred.
- 2. Close the hitching post file, and hard link it to the lock file name.
+ 2. Close the hitching post file, and hard link it to the lock filename.
3. If the call to link() succeeds, creation of the lock file has
succeeded. Unlink the hitching post name.
is defined by the directory option (the "delivery directory"). If the delivery
is successful, the file is renamed into the new subdirectory.
-In the file name, <stime> is the current time of day in seconds, and <mtime> is
+In the filename, <stime> is the current time of day in seconds, and <mtime> is
the microsecond fraction of the time. After a maildir delivery, Exim checks
that the time-of-day clock has moved on by at least one microsecond before
-terminating the delivery process. This guarantees uniqueness for the file name.
+terminating the delivery process. This guarantees uniqueness for the filename.
However, as a precaution, Exim calls stat() for the file before opening it. If
any response other than ENOENT (does not exist) is given, Exim waits 2 seconds
and tries again, up to maildir_retries times.
If neither maildir_format nor mailstore_format is set, a single new file is
created directly in the named directory. For example, when delivering messages
into files in batched SMTP format for later delivery to some host (see section
-47.10), a setting such as
+48.10), a setting such as
directory = /var/bsmtp/$host
27.1 Private options for autoreply
----------------------------------
-+---+--------------+-------------+--------------+
++-----------------------------------------------+
|bcc|Use: autoreply|Type: string*|Default: unset|
-+---+--------------+-------------+--------------+
++-----------------------------------------------+
This specifies the addresses that are to receive "blind carbon copies" of the
message when the message is specified by the transport.
-+--+--------------+-------------+--------------+
++----------------------------------------------+
|cc|Use: autoreply|Type: string*|Default: unset|
-+--+--------------+-------------+--------------+
++----------------------------------------------+
This specifies recipients of the message and the contents of the Cc: header
when the message is specified by the transport.
-+----+--------------+-------------+--------------+
++------------------------------------------------+
|file|Use: autoreply|Type: string*|Default: unset|
-+----+--------------+-------------+--------------+
++------------------------------------------------+
The contents of the file are sent as the body of the message when the message
is specified by the transport. If both file and text are set, the text string
comes first.
-+-----------+--------------+-------------+--------------+
++-------------------------------------------------------+
|file_expand|Use: autoreply|Type: boolean|Default: false|
-+-----------+--------------+-------------+--------------+
++-------------------------------------------------------+
If this is set, the contents of the file named by the file option are subjected
to string expansion as they are added to the message.
-+-------------+--------------+-------------+--------------+
++---------------------------------------------------------+
|file_optional|Use: autoreply|Type: boolean|Default: false|
-+-------------+--------------+-------------+--------------+
++---------------------------------------------------------+
If this option is true, no error is generated if the file named by the file
option or passed with the address does not exist or cannot be read.
-+----+--------------+-------------+--------------+
++------------------------------------------------+
|from|Use: autoreply|Type: string*|Default: unset|
-+----+--------------+-------------+--------------+
++------------------------------------------------+
This specifies the contents of the From: header when the message is specified
by the transport.
-+-------+--------------+-------------+--------------+
++---------------------------------------------------+
|headers|Use: autoreply|Type: string*|Default: unset|
-+-------+--------------+-------------+--------------+
++---------------------------------------------------+
This specifies additional RFC 2822 headers that are to be added to the message
when the message is specified by the transport. Several can be given by using "
\n" to separate them. There is no check on the format.
-+---+--------------+-------------+--------------+
++-----------------------------------------------+
|log|Use: autoreply|Type: string*|Default: unset|
-+---+--------------+-------------+--------------+
++-----------------------------------------------+
This option names a file in which a record of every message sent is logged when
the message is specified by the transport.
-+----+--------------+-------------------+-------------+
++-----------------------------------------------------+
|mode|Use: autoreply|Type: octal integer|Default: 0600|
-+----+--------------+-------------------+-------------+
++-----------------------------------------------------+
If either the log file or the "once" file has to be created, this mode is used.
-+----------+--------------+-------------------+--------------+
++------------------------------------------------------------+
|never_mail|Use: autoreply|Type: address list*|Default: unset|
-+----------+--------------+-------------------+--------------+
++------------------------------------------------------------+
If any run of the transport creates a message with a recipient that matches any
item in the list, that recipient is quietly discarded. If all recipients are
discarded, no message is created. This applies both when the recipients are
generated by a filter and when they are specified in the transport.
-+----+--------------+-------------+--------------+
++------------------------------------------------+
|once|Use: autoreply|Type: string*|Default: unset|
-+----+--------------+-------------+--------------+
++------------------------------------------------+
This option names a file or DBM database in which a record of each To:
recipient is kept when the message is specified by the transport. Note: This
does not apply to Cc: or Bcc: recipients.
If once is unset, or is set to an empty string, the message is always sent. By
-default, if once is set to a non-empty file name, the message is not sent if a
+default, if once is set to a non-empty filename, the message is not sent if a
potential recipient is already listed in the database. However, if the
once_repeat option specifies a time greater than zero, the message is sent if
that much time has elapsed since a message was last sent to this recipient. A
intervals that depend on the rate of turnover of addresses in the file. If
once_repeat is set, it specifies a maximum time between repeats.
-+--------------+--------------+-------------+----------+
++------------------------------------------------------+
|once_file_size|Use: autoreply|Type: integer|Default: 0|
-+--------------+--------------+-------------+----------+
++------------------------------------------------------+
See once above.
-+-----------+--------------+-----------+-----------+
++--------------------------------------------------+
|once_repeat|Use: autoreply|Type: time*|Default: 0s|
-+-----------+--------------+-----------+-----------+
++--------------------------------------------------+
See once above. After expansion, the value of this option must be a valid time
value.
-+--------+--------------+-------------+--------------+
++----------------------------------------------------+
|reply_to|Use: autoreply|Type: string*|Default: unset|
-+--------+--------------+-------------+--------------+
++----------------------------------------------------+
This specifies the contents of the Reply-To: header when the message is
specified by the transport.
-+--------------+--------------+-------------+--------------+
++----------------------------------------------------------+
|return_message|Use: autoreply|Type: boolean|Default: false|
-+--------------+--------------+-------------+--------------+
++----------------------------------------------------------+
If this is set, a copy of the original message is returned with the new
message, subject to the maximum size set in the return_size_limit global
configuration option.
-+-------+--------------+-------------+--------------+
++---------------------------------------------------+
|subject|Use: autoreply|Type: string*|Default: unset|
-+-------+--------------+-------------+--------------+
++---------------------------------------------------+
This specifies the contents of the Subject: header when the message is
specified by the transport. It is tempting to quote the original subject in
non-bounce message to confirm a subscription, so the danger is relatively
small.
-+----+--------------+-------------+--------------+
++------------------------------------------------+
|text|Use: autoreply|Type: string*|Default: unset|
-+----+--------------+-------------+--------------+
++------------------------------------------------+
This specifies a single string to be used as the body of the message when the
message is specified by the transport. If both text and file are set, the text
comes first.
-+--+--------------+-------------+--------------+
++----------------------------------------------+
|to|Use: autoreply|Type: string*|Default: unset|
-+--+--------------+-------------+--------------+
++----------------------------------------------+
This specifies recipients of the message and the contents of the To: header
when the message is specified by the transport.
is present in your Local/Makefile in order to have the lmtp transport included
in the Exim binary. The private options of the lmtp transport are as follows:
-+--------+---------+-------------+--------------+
++-----------------------------------------------+
|batch_id|Use: lmtp|Type: string*|Default: unset|
-+--------+---------+-------------+--------------+
++-----------------------------------------------+
See the description of local delivery batching in chapter 25.
-+---------+---------+-------------+----------+
++--------------------------------------------+
|batch_max|Use: lmtp|Type: integer|Default: 1|
-+---------+---------+-------------+----------+
++--------------------------------------------+
This limits the number of addresses that can be handled in a single delivery.
Most LMTP servers can handle several addresses at once, so it is normally a
good idea to increase this value. See the description of local delivery
batching in chapter 25.
-+-------+---------+-------------+--------------+
++----------------------------------------------+
|command|Use: lmtp|Type: string*|Default: unset|
-+-------+---------+-------------+--------------+
++----------------------------------------------+
This option must be set if socket is not set. The string is a command which is
run in a separate process. It is split up into a command name and list of
is passed to the new process using the standard input and output to operate the
LMTP protocol.
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
|ignore_quota|Use: lmtp|Type: boolean|Default: false|
-+------------+---------+-------------+--------------+
++---------------------------------------------------+
If this option is set true, the string "IGNOREQUOTA" is added to RCPT commands,
provided that the LMTP server has advertised support for IGNOREQUOTA in its
response to the LHLO command.
-+------+---------+-------------+--------------+
++---------------------------------------------+
|socket|Use: lmtp|Type: string*|Default: unset|
-+------+---------+-------------+--------------+
++---------------------------------------------+
This option must be set if command is not set. The result of expansion must be
the name of a Unix domain socket. The transport connects to the socket and
delivers the message to it using the LMTP protocol.
-+-------+---------+----------+-----------+
++----------------------------------------+
|timeout|Use: lmtp|Type: time|Default: 5m|
-+-------+---------+----------+-----------+
++----------------------------------------+
The transport is aborted if the created process or Unix domain socket does not
respond to LMTP commands or message input within this timeout. Delivery is
If two messages arrive at almost the same time, and both are routed to a pipe
delivery, the two pipe transports may be run concurrently. You must ensure that
any pipe commands you set up are robust against this happening. If the commands
-write to a file, the exim_lock utility might be of use.
+write to a file, the exim_lock utility might be of use. Alternatively the
+max_parallel option could be used with a value of "1" to enforce serialization.
29.2 Returned status and data
command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}}
Special handling takes place when an argument consists of precisely the text
-"$pipe_addresses". This is not a general expansion variable; the only place
-this string is recognized is when it appears as an argument for a pipe or
-transport filter command. It causes each address that is being handled to be
-inserted in the argument list at that point as a separate argument. This avoids
-any problems with spaces or shell metacharacters, and is of use when a pipe
-transport is handling groups of addresses in a batch.
+"$pipe_addresses" (no quotes). This is not a general expansion variable; the
+only place this string is recognized is when it appears as an argument for a
+pipe or transport filter command. It causes each address that is being handled
+to be inserted in the argument list at that point as a separate argument. This
+avoids any problems with spaces or shell metacharacters, and is of use when a
+pipe transport is handling groups of addresses in a batch.
If force_command is enabled on the transport, Special handling takes place for
an argument that consists of precisely the text "$address_pipe". It is handled
The environment variables listed below are set up when the command is invoked.
This list is a compromise for maximum compatibility with other MTAs. Note that
the environment option can be used to add additional variables to this
-environment.
+environment. The environment for the pipe transport is not subject to the
+add_environment and keep_environment main config options.
DOMAIN the domain of the address
HOME the home directory, if set
29.5 Private options for pipe
-----------------------------
-+--------------+---------+------------------+--------------+
++----------------------------------------------------------+
|allow_commands|Use: pipe|Type: string list*|Default: unset|
-+--------------+---------+------------------+--------------+
++----------------------------------------------------------+
The string is expanded, and is then interpreted as a colon-separated list of
permitted commands. If restrict_to_path is not set, the only commands permitted
and restrict_to_path is not set, the only permitted command is /usr/bin/
vacation. The allow_commands option may not be set if use_shell is set.
-+--------+---------+-------------+--------------+
++-----------------------------------------------+
|batch_id|Use: pipe|Type: string*|Default: unset|
-+--------+---------+-------------+--------------+
++-----------------------------------------------+
See the description of local delivery batching in chapter 25.
-+---------+---------+-------------+----------+
++--------------------------------------------+
|batch_max|Use: pipe|Type: integer|Default: 1|
-+---------+---------+-------------+----------+
++--------------------------------------------+
This limits the number of addresses that can be handled in a single delivery.
See the description of local delivery batching in chapter 25.
-+------------+---------+------------+--------------+
++--------------------------------------------------+
|check_string|Use: pipe|Type: string|Default: unset|
-+------------+---------+------------+--------------+
++--------------------------------------------------+
As pipe writes the message, the start of each line is tested for matching
check_string, and if it does, the initial matching characters are replaced by
and escape_string are forced to values that implement the SMTP escaping
protocol. Any settings made in the configuration file are ignored.
-+-------+---------+-------------+--------------+
++----------------------------------------------+
|command|Use: pipe|Type: string*|Default: unset|
-+-------+---------+-------------+--------------+
++----------------------------------------------+
This option need not be set when pipe is being used to deliver to pipes
obtained directly from address redirections. In other cases, the option must be
Exim, and each argument is separately expanded, as described in section 29.3
above.
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
|environment|Use: pipe|Type: string*|Default: unset|
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
This option is used to add additional variables to the environment in which the
command runs (see section 29.4 for the default list). Its value is a string
which is expanded, and then interpreted as a colon-separated list of
environment settings of the form <name>=<value>.
-+-------------+---------+------------+--------------+
++---------------------------------------------------+
|escape_string|Use: pipe|Type: string|Default: unset|
-+-------------+---------+------------+--------------+
++---------------------------------------------------+
See check_string above.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|freeze_exec_fail|Use: pipe|Type: boolean|Default: false|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
Failure to exec the command in a pipe transport is by default treated like any
other failure while running the command. However, if freeze_exec_fail is set,
failure to exec is treated specially, and causes the message to be frozen,
whatever the setting of ignore_status.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|freeze_signal|Use: pipe|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
Normally if the process run by a command in a pipe transport exits on a signal,
a bounce message is sent. If freeze_signal is set, the message will be frozen
in Exim's queue instead.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|force_command|Use: pipe|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
Normally when a router redirects an address directly to a pipe command the
command option on the transport is ignored. If force_command is set, the
set, expanding out to the original argument vector as separate items, similarly
to a Unix shell ""$@"" construct.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|ignore_status|Use: pipe|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
If this option is true, the status returned by the subprocess that is set up to
run the command is ignored, and Exim behaves as if zero had been returned.
Note: This option does not apply to timeouts, which do not return a status. See
the timeout_defer option for how timeouts are handled.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|log_defer_output|Use: pipe|Type: boolean|Default: false|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
If this option is set, and the status returned by the command is one of the
codes listed in temp_errors (that is, delivery was deferred), and any output
-was produced, the first line of it is written to the main log.
+was produced on stdout or stderr, the first line of it is written to the main
+log.
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
|log_fail_output|Use: pipe|Type: boolean|Default: false|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
-If this option is set, and the command returns any output, and also ends with a
-return code that is neither zero nor one of the return codes listed in
-temp_errors (that is, the delivery failed), the first line of output is written
-to the main log. This option and log_output are mutually exclusive. Only one of
-them may be set.
+If this option is set, and the command returns any output on stdout or stderr,
+and also ends with a return code that is neither zero nor one of the return
+codes listed in temp_errors (that is, the delivery failed), the first line of
+output is written to the main log. This option and log_output are mutually
+exclusive. Only one of them may be set.
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
|log_output|Use: pipe|Type: boolean|Default: false|
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
-If this option is set and the command returns any output, the first line of
-output is written to the main log, whatever the return code. This option and
-log_fail_output are mutually exclusive. Only one of them may be set.
+If this option is set and the command returns any output on stdout or stderr,
+the first line of output is written to the main log, whatever the return code.
+This option and log_fail_output are mutually exclusive. Only one of them may be
+set.
-+----------+---------+-------------+------------+
++-----------------------------------------------+
|max_output|Use: pipe|Type: integer|Default: 20K|
-+----------+---------+-------------+------------+
++-----------------------------------------------+
This specifies the maximum amount of output that the command may produce on its
standard output and standard error file combined. If the limit is exceeded, the
return_output). Because of buffering effects, the amount of output may exceed
the limit by a small amount before Exim notices.
-+--------------+---------+-------------+------------------+
++---------------------------------------------------------+
|message_prefix|Use: pipe|Type: string*|Default: see below|
-+--------------+---------+-------------+------------------+
++---------------------------------------------------------+
The string specified here is expanded and output at the start of every message.
The default is unset if use_bsmtp is set. Otherwise it is
Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
n" in message_prefix.
-+--------------+---------+-------------+------------------+
++---------------------------------------------------------+
|message_suffix|Use: pipe|Type: string*|Default: see below|
-+--------------+---------+-------------+------------------+
++---------------------------------------------------------+
The string specified here is expanded and output at the end of every message.
The default is unset if use_bsmtp is set. Otherwise it is a single newline. The
Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\
n" in message_suffix.
-+----+---------+------------+------------------+
-|path|Use: pipe|Type: string|Default: see below|
-+----+---------+------------+------------------+
-
-This option specifies the string that is set up in the PATH environment
-variable of the subprocess. The default is:
-
-/bin:/usr/bin
++---------------------------------------------------+
+|path|Use: pipe|Type: string*|Default: /bin:/usr/bin|
++---------------------------------------------------+
-If the command option does not yield an absolute path name, the command is
-sought in the PATH directories, in the usual way. Warning: This does not apply
-to a command specified as a transport filter.
+This option is expanded and specifies the string that is set up in the PATH
+environment variable of the subprocess. If the command option does not yield an
+absolute path name, the command is sought in the PATH directories, in the usual
+way. Warning: This does not apply to a command specified as a transport filter.
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
|permit_coredump|Use: pipe|Type: boolean|Default: false|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
Normally Exim inhibits core-dumps during delivery. If you have a need to get a
core-dump of a pipe command, enable this command. This enables core-dumps
setuid binary and most operating systems will inhibit coredumps of these by
default, so further OS-specific action may be required.
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
|pipe_as_creator|Use: pipe|Type: boolean|Default: false|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
If the generic user option is not set and this option is true, the delivery
process is run under the uid that was in force when Exim was originally called
group option), the gid that was in force when Exim was originally called to
accept the message is used.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|restrict_to_path|Use: pipe|Type: boolean|Default: false|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
When this option is set, any command name not listed in allow_commands must
contain no slashes. The command is searched for only in the directories listed
command has been generated from a user's .forward file. This is usually handled
by a pipe transport called address_pipe.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|return_fail_output|Use: pipe|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
If this option is true, and the command produced any output and ended with a
return code other than zero or one of the codes listed in temp_errors (that is,
from the command is discarded. This option and return_output are mutually
exclusive. Only one of them may be set.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|return_output|Use: pipe|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
If this option is true, and the command produced any output, the delivery is
deemed to have failed whatever the return code from the command, and the output
option. This option and return_fail_output are mutually exclusive. Only one of
them may be set.
-+-----------+---------+-----------------+------------------+
++----------------------------------------------------------+
|temp_errors|Use: pipe|Type: string list|Default: see below|
-+-----------+---------+-----------------+------------------+
++----------------------------------------------------------+
This option contains either a colon-separated list of numbers, or a single
asterisk. If ignore_status is false and return_output is not set, and the
that does not define these macros, it assumes values of 75 and 73,
respectively.
-+-------+---------+----------+-----------+
++----------------------------------------+
|timeout|Use: pipe|Type: time|Default: 1h|
-+-------+---------+----------+-----------+
++----------------------------------------+
If the command fails to complete within this time, it is killed. This normally
causes the delivery to fail (but see timeout_defer). A zero time interval
and kills the whole process group on a timeout. However, this can be defeated
if one of the processes starts a new process group.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|timeout_defer|Use: pipe|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
A timeout in a pipe transport, either in the command that the transport runs,
or in a transport filter that is associated with it, is by default treated as a
hard error, and the delivery fails. However, if timeout_defer is set true, both
kinds of timeout become temporary errors, causing the delivery to be deferred.
-+-----+---------+-------------------+------------+
++------------------------------------------------+
|umask|Use: pipe|Type: octal integer|Default: 022|
-+-----+---------+-------------------+------------+
++------------------------------------------------+
This specifies the umask setting for the subprocess that runs the command.
-+---------+---------+-------------+--------------+
++------------------------------------------------+
|use_bsmtp|Use: pipe|Type: boolean|Default: false|
-+---------+---------+-------------+--------------+
++------------------------------------------------+
If this option is set true, the pipe transport writes messages in "batch SMTP"
format, with the envelope sender and recipient(s) included as SMTP commands. If
you want to include a leading HELO command with such messages, you can do so by
-setting the message_prefix option. See section 47.10 for details of batch SMTP.
+setting the message_prefix option. See section 48.10 for details of batch SMTP.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|use_classresources|Use: pipe|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/
OS. If it is set true, the setclassresources() function is used to set resource
limits when a pipe transport is run to perform a delivery. The limits for the
uid under which the pipe is to run are obtained from the login class database.
-+--------+---------+-------------+--------------+
++-----------------------------------------------+
|use_crlf|Use: pipe|Type: boolean|Default: false|
-+--------+---------+-------------+--------------+
++-----------------------------------------------+
This option causes lines to be terminated with the two-character CRLF sequence
(carriage return, linefeed) instead of just a linefeed character. In the case
and message_suffix end with a single linefeed, so their values must be changed
to end with "\r\n" if use_crlf is set.
-+---------+---------+-------------+--------------+
++------------------------------------------------+
|use_shell|Use: pipe|Type: boolean|Default: false|
-+---------+---------+-------------+--------------+
++------------------------------------------------+
If this option is set, it causes the command to be passed to /bin/sh instead of
being run directly from the transport, as described in section 29.3. This is
run of the smtp transport over a single TCP/IP connection. (What Exim
actually does when it has too many addresses to send in one message also
depends on the value of the global remote_max_parallel option. Details are
- given in section 47.1.)
+ given in section 48.1.)
* When a message has been successfully delivered over a TCP/IP connection,
Exim looks in its hints database to see if there are any other messages
The private options of the smtp transport are as follows:
-+----------------------------+---------+-------------+-------------+
++------------------------------------------------------------------+
|address_retry_include_sender|Use: smtp|Type: boolean|Default: true|
-+----------------------------+---------+-------------+-------------+
++------------------------------------------------------------------+
When an address is delayed because of a 4xx response to a RCPT command, it is
the combination of sender and recipient that is delayed in subsequent queue
setting address_retry_include_sender false. However, this can lead to problems
with servers that regularly issue 4xx responses to RCPT commands.
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
|allow_localhost|Use: smtp|Type: boolean|Default: false|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
When a host specified in hosts or fallback_hosts (see below) turns out to be
the local host, or is listed in hosts_treat_as_local, delivery is deferred by
ensures that no looping will result (for example, a differently configured Exim
is listening on the port to which the message is sent).
-+--------------------+---------+-------------+--------------+
++-----------------------------------------------------------+
|authenticated_sender|Use: smtp|Type: string*|Default: unset|
-+--------------------+---------+-------------+--------------+
++-----------------------------------------------------------+
When Exim has authenticated as a client, or if authenticated_sender_force is
true, this option sets a value for the AUTH= item on outgoing MAIL commands,
Because of expected uses such as that just described for Cyrus (when no domain
is involved), there is no checking on the syntax of the provided value.
-+--------------------------+---------+-------------+--------------+
++-----------------------------------------------------------------+
|authenticated_sender_force|Use: smtp|Type: boolean|Default: false|
-+--------------------------+---------+-------------+--------------+
++-----------------------------------------------------------------+
If this option is set true, the authenticated_sender option's value is used for
the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as
a client.
-+---------------+---------+----------+-----------+
++------------------------------------------------+
|command_timeout|Use: smtp|Type: time|Default: 5m|
-+---------------+---------+----------+-----------+
++------------------------------------------------+
This sets a timeout for receiving a response to an SMTP command that has been
sent out. It is also used when waiting for the initial banner line from the
remote host. Its value must not be zero.
-+---------------+---------+----------+-----------+
++------------------------------------------------+
|connect_timeout|Use: smtp|Type: time|Default: 5m|
-+---------------+---------+----------+-----------+
++------------------------------------------------+
This sets a timeout for the connect() function, which sets up a TCP/IP call to
a remote host. A setting of zero allows the system timeout (typically several
no system timeout, which is why the default value for this option is 5 minutes,
a value recommended by RFC 1123.
-+-----------------------+---------+-------------+------------+
++------------------------------------------------------------+
|connection_max_messages|Use: smtp|Type: integer|Default: 500|
-+-----------------------+---------+-------------+------------+
++------------------------------------------------------------+
This controls the maximum number of separate message deliveries that are sent
over a single TCP/IP connection. If the value is zero, there is no limit. For
testing purposes, this value can be overridden by the -oB command line option.
-+------------+---------+----------+-----------+
++---------------------------------------------------------------+
+|dane_require_tls_ciphers|Use: smtp|Type: string*|Default: unset|
++---------------------------------------------------------------+
+
+This option may be used to override tls_require_ciphers for connections where
+DANE has been determined to be in effect. If not set, then tls_require_ciphers
+will be used. Normal SMTP delivery is not able to make strong demands of TLS
+cipher configuration, because delivery will fall back to plaintext. Once DANE
+has been determined to be in effect, there is no plaintext fallback and making
+the TLS cipherlist configuration stronger will increase security, rather than
+counter-intuitively decreasing it. If the option expands to be empty or is
+forced to fail, then it will be treated as unset and tls_require_ciphers will
+be used instead.
+
++---------------------------------------------+
|data_timeout|Use: smtp|Type: time|Default: 5m|
-+------------+---------+----------+-----------+
++---------------------------------------------+
This sets a timeout for the transmission of each block in the data portion of
the message. As a result, the overall timeout for a message depends on the size
of the message. Its value must not be zero. See also final_timeout.
-+------------------+---------+-------------+-------------+
++-------------------------------------------------+
+|dkim_canon|Use: smtp|Type: string*|Default: unset|
++-------------------------------------------------+
+
++-------------------------------------------------+
+|dkim_domain|Use: smtp|Type: string|Default: list*|
++-------------------------------------------------+
+
++-------------------------------------------------+
+|dkim_hash|Use: smtp|Type: string*|Default: sha256|
++-------------------------------------------------+
+
++----------------------------------------------------+
+|dkim_identity|Use: smtp|Type: string*|Default: unset|
++----------------------------------------------------+
+
++-------------------------------------------------------+
+|dkim_private_key|Use: smtp|Type: string*|Default: unset|
++-------------------------------------------------------+
+
++----------------------------------------------------+
+|dkim_selector|Use: smtp|Type: string*|Default: unset|
++----------------------------------------------------+
+
++--------------------------------------------------+
+|dkim_strict|Use: smtp|Type: string*|Default: unset|
++--------------------------------------------------+
+
++----------------------------------------------------------+
+|dkim_sign_headers|Use: smtp|Type: string*|Default: per RFC|
++----------------------------------------------------------+
+
++------------------------------------------------------+
+|dkim_timestamps|Use: smtp|Type: string*|Default: unset|
++------------------------------------------------------+
+
+DKIM signing options. For details see section 57.2.
+
++--------------------------------------------------------+
|delay_after_cutoff|Use: smtp|Type: boolean|Default: true|
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
This option controls what happens when all remote IP addresses for a given
domain have been inaccessible for so long that they have passed their retry
continuous stream of messages for the dead hosts, unsetting delay_after_cutoff
means that there will be many more attempts to deliver to them.
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
|dns_qualify_single|Use: smtp|Type: boolean|Default: true|
-+------------------+---------+-------------+-------------+
++--------------------------------------------------------+
If the hosts or fallback_hosts option is being used, and the gethostbyname
option is false, the RES_DEFNAMES resolver option is set. See the
qualify_single option in chapter 17 for more details.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|dns_search_parents|Use: smtp|Type: boolean|Default: false|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
If the hosts or fallback_hosts option is being used, and the gethostbyname
option is false, the RES_DNSRCH resolver option is set. See the search_parents
option in chapter 17 for more details.
-+----------------------+---------+------------------+--------------+
++------------------------------------------------------------------+
|dnssec_request_domains|Use: smtp|Type: domain list*|Default: unset|
-+----------------------+---------+------------------+--------------+
++------------------------------------------------------------------+
DNS lookups for domains matching dnssec_request_domains will be done with the
-dnssec request bit set. This applies to all of the SRV, MX A6, AAAA, A lookup
+dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup
sequence.
-+----------------------+---------+------------------+--------------+
++------------------------------------------------------------------+
|dnssec_require_domains|Use: smtp|Type: domain list*|Default: unset|
-+----------------------+---------+------------------+--------------+
++------------------------------------------------------------------+
-DNS lookups for domains matching dnssec_request_domains will be done with the
+DNS lookups for domains matching dnssec_require_domains will be done with the
dnssec request bit set. Any returns not having the Authenticated Data bit (AD
-bit) set wil be ignored and logged as a host-lookup failure. This applies to
-all of the SRV, MX A6, AAAA, A lookup sequence.
+bit) set will be ignored and logged as a host-lookup failure. This applies to
+all of the SRV, MX, AAAA, A lookup sequence.
-+----+---------+-------------+--------------+
++-------------------------------------------+
|dscp|Use: smtp|Type: string*|Default: unset|
-+----+---------+-------------+--------------+
++-------------------------------------------+
This option causes the DSCP value associated with a socket to be set to one of
a number of fixed strings or to numeric value. The -bI:dscp option may be used
equipment, or do much of anything without cooperation with your Network
Engineer and those of all network operators between the source and destination.
-+--------------+---------+-----------------+--------------+
++---------------------------------------------------------+
|fallback_hosts|Use: smtp|Type: string list|Default: unset|
-+--------------+---------+-----------------+--------------+
++---------------------------------------------------------+
String expansion is not applied to this option. The argument must be a
colon-separated list of host names or IP addresses, optionally also including
-port numbers, though the separator can be changed, as described in section 6.19
+port numbers, though the separator can be changed, as described in section 6.20
. Each individual item in the list is the same as an item in a route_list
setting for the manualroute router, as described in section 20.5.
cases when the host list comes with the address and when it is taken from hosts
. This option provides a "use a smart host only if delivery fails" facility.
-+-------------+---------+----------+------------+
++-----------------------------------------------+
|final_timeout|Use: smtp|Type: time|Default: 10m|
-+-------------+---------+----------+------------+
++-----------------------------------------------+
This is the timeout that applies while waiting for the response to the final
line containing just "." that terminates a message. Its value must not be zero.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|gethostbyname|Use: smtp|Type: boolean|Default: false|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
If this option is true when the hosts and/or fallback_hosts options are being
used, names are looked up using gethostbyname() (or getipnodebyname() when
the DNS, but it may also consult other sources of information such as /etc/
hosts.
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
|gnutls_compat_mode|Use: smtp|Type: boolean|Default: unset|
-+------------------+---------+-------------+--------------+
++---------------------------------------------------------+
This option controls whether GnuTLS is used in compatibility mode in an Exim
server. This reduces security slightly, but improves interworking with older
implementations of TLS.
-+---------+---------+-------------+------------------+
++----------------------------------------------------+
|helo_data|Use: smtp|Type: string*|Default: see below|
-+---------+---------+-------------+------------------+
++----------------------------------------------------+
The value of this option is expanded after a connection to a another host has
been set up. The result is used as the argument for the EHLO, HELO, or LHLO
The use of helo_data applies both to sending messages and when doing callouts.
-+-----+---------+------------------+--------------+
++-------------------------------------------------+
|hosts|Use: smtp|Type: string list*|Default: unset|
-+-----+---------+------------------+--------------+
++-------------------------------------------------+
Hosts are associated with an address by a router such as dnslookup, which finds
the hosts by looking up the address domain in the DNS, or by manualroute, which
The string is first expanded, before being interpreted as a colon-separated
list of host names or IP addresses, possibly including port numbers. The
separator may be changed to something other than colon, as described in section
-6.19. Each individual item in the list is the same as an item in a route_list
+6.20. Each individual item in the list is the same as an item in a route_list
setting for the manualroute router, as described in section 20.5. However, note
that the "/MX" facility of the manualroute router is not available here.
During delivery, the hosts are tried in order, subject to their retry status,
unless hosts_randomize is set.
-+-----------------+---------+----------------+--------------+
++-----------------------------------------------------------+
|hosts_avoid_esmtp|Use: smtp|Type: host list*|Default: unset|
-+-----------------+---------+----------------+--------------+
++-----------------------------------------------------------+
This option is for use with broken hosts that announce ESMTP facilities (for
example, PIPELINING) and then fail to implement them properly. When a host
SMTP session. This means that it cannot use any of the ESMTP facilities such as
AUTH, PIPELINING, SIZE, and STARTTLS.
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
|hosts_avoid_pipelining|Use: smtp|Type: host list*|Default: unset|
-+----------------------+---------+----------------+--------------+
++----------------------------------------------------------------+
Exim will not use the SMTP PIPELINING extension when delivering to any host
that matches this list, even if the server host advertises PIPELINING support.
-+---------------+---------+----------------+--------------+
++---------------------------------------------------------+
|hosts_avoid_tls|Use: smtp|Type: host list*|Default: unset|
-+---------------+---------+----------------+--------------+
++---------------------------------------------------------+
Exim will not try to start a TLS session when delivering to any host that
-matches this list. See chapter 41 for details of TLS.
+matches this list. See chapter 42 for details of TLS.
-+----------------------+---------+----------------+----------+
-|hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: *|
-+----------------------+---------+----------------+----------+
++----------------------------------------------------------------+
+|hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: unset|
++----------------------------------------------------------------+
Exim will not try to start a TLS session for a verify callout, or when
-delivering in cutthrough mode, to any host that matches this list. Note that
-the default is to not use TLS.
+delivering in cutthrough mode, to any host that matches this list.
-+-------------+---------+-------------+----------+
++------------------------------------------------+
|hosts_max_try|Use: smtp|Type: integer|Default: 5|
-+-------------+---------+-------------+----------+
++------------------------------------------------+
This option limits the number of IP addresses that are tried for any one
delivery in cases where there are temporary delivery errors. Section 30.5
describes in detail how the value of this option is used.
-+-----------------------+---------+-------------+-----------+
++-----------------------------------------------------------+
|hosts_max_try_hardlimit|Use: smtp|Type: integer|Default: 50|
-+-----------------------+---------+-------------+-----------+
++-----------------------------------------------------------+
This is an additional check on the maximum number of IP addresses that Exim
tries for any one delivery. Section 30.5 describes its use and why it exists.
-+----------------+---------+----------------+--------------+
++----------------------------------------------------------+
|hosts_nopass_tls|Use: smtp|Type: host list*|Default: unset|
-+----------------+---------+----------------+--------------+
++----------------------------------------------------------+
For any host that matches this list, a connection on which a TLS session has
been started will not be passed to a new delivery process for sending another
-message on the same connection. See section 41.11 for an explanation of when
+message on the same connection. See section 42.11 for an explanation of when
this might be needed.
-+--------------+---------+-------------+--------------+
++-------------------------------------------------------+
+|hosts_noproxy_tls|Use: smtp|Type: host list*|Default: *|
++-------------------------------------------------------+
+
+For any host that matches this list, a TLS session which has been started will
+not be passed to a new delivery process for sending another message on the same
+session.
+
+The traditional implementation closes down TLS and re-starts it in the new
+process, on the same open TCP connection, for each successive message sent. If
+permitted by this option a pipe to to the new process is set up instead, and
+the original process maintains the TLS connection and proxies the SMTP
+connection from and to the new process and any subsequents. The new process has
+no access to TLS information, so cannot include it in logging.
+
++-----------------------------------------------------+
|hosts_override|Use: smtp|Type: boolean|Default: false|
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
If this option is set and the hosts option is also set, any hosts that are
attached to the address are ignored, and instead the hosts specified by the
hosts option are always used. This option does not apply to fallback_hosts.
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
|hosts_randomize|Use: smtp|Type: boolean|Default: false|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
If this option is set, and either the list of hosts is taken from the hosts or
the fallback_hosts option, or the hosts supplied by the router were not
randomized for each use, but the first three always end up before the last two.
If hosts_randomize is not set, a "+" item in the list is ignored.
-+------------------+---------+----------------+--------------+
++------------------------------------------------------------+
|hosts_require_auth|Use: smtp|Type: host list*|Default: unset|
-+------------------+---------+----------------+--------------+
++------------------------------------------------------------+
This option provides a list of servers for which authentication must succeed
before Exim will try to transfer a message. If authentication fails for servers
hard failure if required. See also hosts_try_auth, and chapter 33 for details
of authentication.
-+------------------+---------+----------------+----------+
++--------------------------------------------------------+
|hosts_request_ocsp|Use: smtp|Type: host list*|Default: *|
-+------------------+---------+----------------+----------+
++--------------------------------------------------------+
Exim will request a Certificate Status on a TLS session for any host that
matches this list. tls_verify_certificates should also be set for the
transport.
-+------------------+---------+----------------+--------------+
++------------------------------------------------------------+
+|hosts_require_dane|Use: smtp|Type: host list*|Default: unset|
++------------------------------------------------------------+
+
+If built with DANE support, Exim will require that a DNSSEC-validated TLSA
+record is present for any host matching the list, and that a DANE-verified TLS
+connection is made. There will be no fallback to in-clear communication. See
+section 42.15.
+
++------------------------------------------------------------+
|hosts_require_ocsp|Use: smtp|Type: host list*|Default: unset|
-+------------------+---------+----------------+--------------+
++------------------------------------------------------------+
Exim will request, and check for a valid Certificate Status being given, on a
TLS session for any host that matches this list. tls_verify_certificates should
also be set for the transport.
-+-----------------+---------+----------------+--------------+
++-----------------------------------------------------------+
|hosts_require_tls|Use: smtp|Type: host list*|Default: unset|
-+-----------------+---------+----------------+--------------+
++-----------------------------------------------------------+
Exim will insist on using a TLS session when delivering to any host that
-matches this list. See chapter 41 for details of TLS. Note: This option affects
+matches this list. See chapter 42 for details of TLS. Note: This option affects
outgoing mail only. To insist on TLS for incoming messages, use an appropriate
ACL.
-+--------------+---------+----------------+--------------+
++--------------------------------------------------------+
|hosts_try_auth|Use: smtp|Type: host list*|Default: unset|
-+--------------+---------+----------------+--------------+
++--------------------------------------------------------+
This option provides a list of servers to which, provided they announce
authentication support, Exim will attempt to authenticate as a client when it
unauthenticated. See also hosts_require_auth, and chapter 33 for details of
authentication.
-+--------------+---------+----------------+--------------+
-|hosts_try_prdr|Use: smtp|Type: host list*|Default: unset|
-+--------------+---------+----------------+--------------+
++--------------------------------------------------------+
+|hosts_try_chunking|Use: smtp|Type: host list*|Default: *|
++--------------------------------------------------------+
+
+This option provides a list of servers to which, provided they announce
+CHUNKING support, Exim will attempt to use BDAT commands rather than DATA. BDAT
+will not be used in conjunction with a transport filter.
+
++--------------------------------------------------------+
+|hosts_try_dane|Use: smtp|Type: host list*|Default: unset|
++--------------------------------------------------------+
+
+If built with DANE support, Exim will lookup a TLSA record for any host
+matching the list. If found and verified by DNSSEC, a DANE-verified TLS
+connection is made to that host; there will be no fallback to in-clear
+communication. See section 42.15.
+
++------------------------------------------------------------+
+|hosts_try_fastopen|Use: smtp|Type: host list*|Default: unset|
++------------------------------------------------------------+
+
+This option provides a list of servers to which, provided the facility is
+supported by this system, Exim will attempt to perform a TCP Fast Open. No data
+is sent on the SYN segment but, if the remote server also supports the
+facility, it can send its SMTP banner immediately after the SYN,ACK segment.
+This can save up to one round-trip time.
+
+The facility is only active for previously-contacted servers, as the initiator
+must present a cookie in the SYN segment.
+
+On (at least some) current Linux distributions the facility must be enabled in
+the kernel by the sysadmin before the support is usable. There is no option for
+control of the server side; if the system supports it it is always enabled.
+Note that lengthy operations in the connect ACL, such as DNSBL lookups, will
+still delay the emission of the SMTP banner.
+
++----------------------------------------------------+
+|hosts_try_prdr|Use: smtp|Type: host list*|Default: *|
++----------------------------------------------------+
This option provides a list of servers to which, provided they announce PRDR
-support, Exim will attempt to negotiate PRDR for multi-recipient messages.
+support, Exim will attempt to negotiate PRDR for multi-recipient messages. The
+option can usually be left as default.
-+---------+---------+------------------+--------------+
++-----------------------------------------------------+
|interface|Use: smtp|Type: string list*|Default: unset|
-+---------+---------+------------------+--------------+
++-----------------------------------------------------+
This option specifies which interface to bind to when making an outgoing SMTP
call. The value is an IP address, not an interface name such as "eth0". Do not
during the expansion of the string. Forced expansion failure, or an empty
string result causes the option to be ignored. Otherwise, after expansion, the
string must be a list of IP addresses, colon-separated by default, but the
-separator can be changed in the usual way. For example:
+separator can be changed in the usual way (6.21). For example:
interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
interface is not set, or is ignored, the system's IP functions choose which
interface to use if the host has more than one.
-+---------+---------+-------------+-------------+
++-----------------------------------------------+
|keepalive|Use: smtp|Type: boolean|Default: true|
-+---------+---------+-------------+-------------+
++-----------------------------------------------+
This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket
connections. When set, it causes the kernel to probe idle connections
call properly. The keepalive mechanism takes several hours to detect
unreachable hosts.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|lmtp_ignore_quota|Use: smtp|Type: boolean|Default: false|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
If this option is set true when the protocol option is set to "lmtp", the
string "IGNOREQUOTA" is added to RCPT commands, provided that the LMTP server
has advertised support for IGNOREQUOTA in its response to the LHLO command.
-+--------+---------+-------------+------------+
++---------------------------------------------+
|max_rcpt|Use: smtp|Type: integer|Default: 100|
-+--------+---------+-------------+------------+
++---------------------------------------------+
This option limits the number of RCPT commands that are sent in a single SMTP
message transaction. Each set of addresses is treated independently, and so can
cause parallel connections to the same host if remote_max_parallel permits
this.
-+------------+---------+-------------+-------------+
-|multi_domain|Use: smtp|Type: boolean|Default: true|
-+------------+---------+-------------+-------------+
++---------------------------------------------------+
+|multi_domain|Use: smtp|Type: boolean*|Default: true|
++---------------------------------------------------+
When this option is set, the smtp transport can handle a number of addresses
containing a mixture of different domains provided they all resolve to the same
for the transport, because it is set only when there is a single domain
involved in a remote delivery.
-+----+---------+-------------+------------------+
+It is expanded per-address and can depend on any of $address_data, $domain_data
+, $local_part_data, $host, $host_address and $host_port.
+
++-----------------------------------------------+
|port|Use: smtp|Type: string*|Default: see below|
-+----+---------+-------------+------------------+
++-----------------------------------------------+
This option specifies the TCP/IP port on the server to which Exim connects.
Note: Do not confuse this with the port that was used when a message was
If the value of this option begins with a digit it is taken as a port number;
otherwise it is looked up using getservbyname(). The default value is normally
-"smtp", but if protocol is set to "lmtp", the default is "lmtp". If the
-expansion fails, or if a port number cannot be found, delivery is deferred.
+"smtp", but if protocol is set to "lmtp" the default is "lmtp" and if protocol
+is set to "smtps" the default is "smtps". If the expansion fails, or if a port
+number cannot be found, delivery is deferred.
+
+Note that at least one Linux distribution has been seen failing to put "smtps"
+in its "/etc/services" file, resulting is such deferrals.
-+--------+---------+------------+-------------+
++---------------------------------------------+
|protocol|Use: smtp|Type: string|Default: smtp|
-+--------+---------+------------+-------------+
++---------------------------------------------+
If this option is set to "lmtp" instead of "smtp", the default value for the
port option changes to "lmtp", and the transport operates the LMTP protocol
deliveries into closed message stores. Exim also has support for running LMTP
over a pipe to a local process - see chapter 28.
-If this option is set to "smtps", the default vaule for the port option changes
+If this option is set to "smtps", the default value for the port option changes
to "smtps", and the transport initiates TLS immediately after connecting, as an
-outbound SSL-on-connect, instead of using STARTTLS to upgrade. The Internet
-standards bodies strongly discourage use of this mode.
+outbound SSL-on-connect, instead of using STARTTLS to upgrade.
-+------------------------+---------+-------------+-------------+
-|retry_include_ip_address|Use: smtp|Type: boolean|Default: true|
-+------------------------+---------+-------------+-------------+
+The Internet standards bodies used to strongly discourage use of this mode, but
+as of RFC 8314 it is perferred over STARTTLS for message submission (as
+distinct from MTA-MTA communication).
+
++---------------------------------------------------------------+
+|retry_include_ip_address|Use: smtp|Type: boolean*|Default: true|
++---------------------------------------------------------------+
Exim normally includes both the host name and the IP address in the key it
constructs for indexing retry data after a temporary delivery failure. This
However, in some dialup environments hosts are assigned a different IP address
each time they connect. In this situation the use of the IP address as part of
the retry key leads to undesirable behaviour. Setting this option false causes
-Exim to use only the host name. This should normally be done on a separate
-instance of the smtp transport, set up specially to handle the dialup hosts.
+Exim to use only the host name. Since it is expanded it can be made to depend
+on the host or domain.
-+---------------+---------+----------------+--------------+
++---------------------------------------------------------+
|serialize_hosts|Use: smtp|Type: host list*|Default: unset|
-+---------------+---------+----------------+--------------+
++---------------------------------------------------------+
Because Exim operates in a distributed manner, if several messages for the same
host arrive at around the same time, more than one simultaneous connection to
or two files, depending on the type of DBM in use. The same files are used for
ETRN serialization.
-+-------------+---------+-------------+-------------+
+See also the max_parallel generic transport option.
+
++---------------------------------------------------+
|size_addition|Use: smtp|Type: integer|Default: 1024|
-+-------------+---------+-------------+-------------+
++---------------------------------------------------+
If a remote SMTP server indicates that it supports the SIZE option of the MAIL
command, Exim uses this to pass over the message size at the start of an SMTP
Alternatively, if the value of size_addition is set negative, it disables the
use of the SIZE option altogether.
-+---------------+---------+-------------+--------------+
++--------------------------------------------------+
+|socks_proxy|Use: smtp|Type: string*|Default: unset|
++--------------------------------------------------+
+
+This option enables use of SOCKS proxies for connections made by the transport.
+For details see section 58.2.
+
++------------------------------------------------------+
|tls_certificate|Use: smtp|Type: string*|Default: unset|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
The value of this option must be the absolute path to a file which contains the
client's certificate, for possible use when sending a message over an encrypted
connection. The values of $host and $host_address are set to the name and
-address of the server during the expansion. See chapter 41 for details of TLS.
+address of the server during the expansion. See chapter 42 for details of TLS.
Note: This option must be set if you want Exim to be able to use a TLS
certificate when sending messages as a client. The global option of the same
assumed that the same certificate should be used when Exim is operating as a
client.
-+-------+---------+-------------+--------------+
++----------------------------------------------+
|tls_crl|Use: smtp|Type: string*|Default: unset|
-+-------+---------+-------------+--------------+
++----------------------------------------------+
This option specifies a certificate revocation list. The expanded value must be
the name of a file that contains a CRL in PEM format.
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
|tls_dh_min_bits|Use: smtp|Type: integer|Default: 1024|
-+---------------+---------+-------------+-------------+
++-----------------------------------------------------+
When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman key
agreement is negotiated, the server will provide a large prime number for use.
Only supported when using GnuTLS.
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
|tls_privatekey|Use: smtp|Type: string*|Default: unset|
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
The value of this option must be the absolute path to a file which contains the
client's private key. This is used when sending a message over an encrypted
are set to the name and address of the server during the expansion. If this
option is unset, or the expansion is forced to fail, or the result is an empty
string, the private key is assumed to be in the same file as the certificate.
-See chapter 41 for details of TLS.
+See chapter 42 for details of TLS.
-+-------------------+---------+-------------+--------------+
++----------------------------------------------------------+
|tls_require_ciphers|Use: smtp|Type: string*|Default: unset|
-+-------------------+---------+-------------+--------------+
++----------------------------------------------------------+
The value of this option must be a list of permitted cipher suites, for use
when setting up an outgoing encrypted connection. (There is a global option of
the same name for controlling incoming connections.) The values of $host and
$host_address are set to the name and address of the server during the
-expansion. See chapter 41 for details of TLS; note that this option is used in
-different ways by OpenSSL and GnuTLS (see sections 41.4 and 41.5). For GnuTLS,
+expansion. See chapter 42 for details of TLS; note that this option is used in
+different ways by OpenSSL and GnuTLS (see sections 42.4 and 42.5). For GnuTLS,
the order of the ciphers is a preference order.
-+-------+---------+-------------+--------------+
++----------------------------------------------+
|tls_sni|Use: smtp|Type: string*|Default: unset|
-+-------+---------+-------------+--------------+
++----------------------------------------------+
If this option is set then it sets the $tls_out_sni variable and causes any TLS
session to pass this value as the Server Name Indication extension to the
remote side, which can be used by the remote side to select an appropriate
certificate and private key for the session.
-See 41.10 for more information.
+See 42.10 for more information.
Note that for OpenSSL, this feature requires a build of OpenSSL that supports
TLS extensions.
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------+
|tls_tempfail_tryclear|Use: smtp|Type: boolean|Default: true|
-+---------------------+---------+-------------+-------------+
++-----------------------------------------------------------+
When the server host is not in hosts_require_tls, and there is a problem in
setting up a TLS session, this option determines whether or not Exim should try
fails, Exim closes the current connection (because it is in an unknown state),
opens a new one to the same host, and then tries the delivery in clear.
-+--------------------+---------+----------------------+--------+
-|tls_try_verify_hosts|Use: smtp|Type: host list* unset|Default:|
-+--------------------+---------+----------------------+--------+
++----------------------------------------------------------+
+|tls_try_verify_hosts|Use: smtp|Type: host list*|Default: *|
++----------------------------------------------------------+
This option gives a list of hosts for which, on encrypted connections,
certificate verification will be tried but need not succeed. The
tls_verify_certificates option must also be set. Note that unless the host is
in this list TLS connections will be denied to hosts using self-signed
-certificates when tls_verify_certificates is set. The
+certificates when tls_verify_certificates is matched. The
$tls_out_certificate_verified variable is set when certificate verification
succeeds.
-+-----------------------+---------+-------------+--------------+
-|tls_verify_certificates|Use: smtp|Type: string*|Default: unset|
-+-----------------------+---------+-------------+--------------+
++---------------------------------------------------------------+
+|tls_verify_cert_hostnames|Use: smtp|Type: host list*|Default: *|
++---------------------------------------------------------------+
-The value of this option must be the absolute path to a file containing
-permitted server certificates, for use when setting up an encrypted connection.
-Alternatively, if you are using OpenSSL, you can set tls_verify_certificates to
-the name of a directory containing certificate files. This does not work with
-GnuTLS; the option must be set to the name of a single file if you are using
-GnuTLS. The values of $host and $host_address are set to the name and address
-of the server during the expansion of this option. See chapter 41 for details
-of TLS.
+This option give a list of hosts for which, while verifying the server
+certificate, checks will be included on the host name (note that this will
+generally be the result of a DNS MX lookup) versus Subject and
+Subject-Alternate-Name fields. Wildcard names are permitted limited to being
+the initial component of a 3-or-more component FQDN.
-For back-compatability, if neither tls_verify_hosts nor tls_try_verify_hosts
-are set and certificate verification fails the TLS connection is closed.
+There is no equivalent checking on client certificates.
-+----------------+---------+----------------------+--------+
-|tls_verify_hosts|Use: smtp|Type: host list* unset|Default:|
-+----------------+---------+----------------------+--------+
++---------------------------------------------------------------+
+|tls_verify_certificates|Use: smtp|Type: string*|Default: system|
++---------------------------------------------------------------+
-This option gives a list of hosts for which. on encrypted connections,
+The value of this option must be either the word "system" or the absolute path
+to a file or directory containing permitted certificates for servers, for use
+when setting up an encrypted connection.
+
+The "system" value for the option will use a location compiled into the SSL
+library. This is not available for GnuTLS versions preceding 3.0.20; a value of
+"system" is taken as empty and an explicit location must be specified.
+
+The use of a directory for the option value is not available for GnuTLS
+versions preceding 3.3.6 and a single file must be used.
+
+With OpenSSL the certificates specified explicitly either by file or directory
+are added to those given by the system default location.
+
+The values of $host and $host_address are set to the name and address of the
+server during the expansion of this option. See chapter 42 for details of TLS.
+
+For back-compatibility, if neither tls_verify_hosts nor tls_try_verify_hosts
+are set (a single-colon empty list counts as being set) and certificate
+verification fails the TLS connection is closed.
+
++----------------------------------------------------------+
+|tls_verify_hosts|Use: smtp|Type: host list*|Default: unset|
++----------------------------------------------------------+
+
+This option gives a list of hosts for which, on encrypted connections,
certificate verification must succeed. The tls_verify_certificates option must
also be set. If both this option and tls_try_verify_hosts are unset operation
is as if this option selected all hosts.
++---------------------------------------------------------+
+|utf8_downconvert|Use: smtp|Type: integer!!|Default: unset|
++---------------------------------------------------------+
+
+If built with internationalization support, this option controls conversion of
+UTF-8 in message addresses to a-label form. For details see section 59.1.
+
30.5 How the limits for the number of hosts to try are used
-----------------------------------------------------------
31.3 Testing the rewriting rules that apply on input
----------------------------------------------------
-Exim's input rewriting configuration appears in a part of the run time
+Exim's input rewriting configuration appears in a part of the runtime
configuration file headed by "begin rewrite". It can be tested by the -brw
command line option. This takes an address (which can be a full RFC 2822
address) as its argument. The output is a list of how the address would be
RFC 2822 address, including the angle brackets if necessary. If text
outside angle brackets contains a character whose value is greater than 126
or less than 32 (except for tab), the text is encoded according to RFC
- 2047. The character set is taken from headers_charset, which defaults to
- ISO-8859-1.
+ 2047. The character set is taken from headers_charset, which gets its
+ default at build time.
When the "w" flag is set on a rule that causes an envelope address to be
rewritten, all but the working part of the replacement address is
delivered at the first attempt. If there are no retry rules (the section is
empty or not present), there are no retries. In this situation, temporary
errors are treated as permanent. The default configuration contains a single,
-general-purpose retry rule (see section 7.5). The -brt command line option can
+general-purpose retry rule (see section 7.6). The -brt command line option can
be used to test which retry rule will be used for a given address, domain and
error.
been delayed, delivery of a new message to the same host is not immediately
tried, but waits for the host's retry time to arrive. If the retry_defer log
selector is set, the message "retry time not reached" is written to the main
-log whenever a delivery is skipped for this reason. Section 47.2 contains more
+log whenever a delivery is skipped for this reason. Section 48.2 contains more
details of the handling of errors during remote deliveries.
Retry processing applies to routing as well as to delivering, except as covered
legitimate reasons for this (host died, network died), but if it repeats a
lot for the same host, it indicates something odd.
+lookup
+
+ A DNS lookup for a host failed. Note that a dnslookup router will need to
+ have matched its fail_defer_domains option for this retry type to be
+ usable. Also note that a manualroute router will probably need its
+ host_find_failed option set to defer.
+
refused_MX
A connection to a host obtained from an MX record was refused.
sending everything to a smart host, for example).
The data in the retry hints database can be inspected by using the exim_dumpdb
-or exim_fixdb utility programs (see chapter 52). The latter utility can also be
+or exim_fixdb utility programs (see chapter 53). The latter utility can also be
used to change the data. The exinext utility script can be used to find out
what the next retry times are for the hosts associated with a particular mail
domain, and also for local deliveries that have been deferred.
If the delivery is remote, there are two possibilities, controlled by the
delay_after_cutoff option of the smtp transport. The option is true by default.
-Until the post-cutoff retry time for one of the IP addresses is reached, the
-failing email address is bounced immediately, without a delivery attempt taking
-place. After that time, one new delivery attempt is made to those IP addresses
-that are past their retry times, and if that still fails, the address is
-bounced and new retry times are computed.
+Until the post-cutoff retry time for one of the IP addresses, as set by the
+retry_data_expire option, is reached, the failing email address is bounced
+immediately, without a delivery attempt taking place. After that time, one new
+delivery attempt is made to those IP addresses that are past their retry times,
+and if that still fails, the address is bounced and new retry times are
+computed.
In other words, when all the hosts for a given email address have been failing
for a long time, Exim bounces rather then defers until one of the hosts' retry
its delivery when others to the same address get through. In this situation,
because some messages are successfully delivered, the "retry clock" for the
host or address keeps getting reset by the successful deliveries, and so
-failing messages remain on the queue for ever because the cutoff time is never
+failing messages remain in the queue for ever because the cutoff time is never
reached.
Two exceptional actions are applied to prevent this happening. The first
applies to errors that are related to a message rather than a remote host.
-Section 47.2 has a discussion of the different kinds of error; examples of
+Section 48.2 has a discussion of the different kinds of error; examples of
message-related errors are 4xx responses to MAIL or DATA commands, and quota
failures. For this type of error, if a message's arrival time is earlier than
the "first failed" time for the error, the earlier time is used when scanning
===============================================================================
33. SMTP AUTHENTICATION
-The "authenticators" section of Exim's run time configuration is concerned with
+The "authenticators" section of Exim's runtime configuration is concerned with
SMTP authentication. This facility is an extension to the SMTP protocol,
described in RFC 2554, which allows a client SMTP host to authenticate itself
to a server. This is a common way for a server to recognize clients that are
AUTH_HEIMDAL_GSSAPI=yes
AUTH_PLAINTEXT=yes
AUTH_SPA=yes
+AUTH_TLS=yes
in Local/Makefile, respectively. The first of these supports the CRAM-MD5
authentication mechanism (RFC 2195), and the second provides an interface to
The sixth can be configured to support the PLAIN authentication mechanism (RFC
2595) or the LOGIN mechanism, which is not formally documented, but used by
several MUAs. The seventh authenticator supports Microsoft's Secure Password
-Authentication mechanism.
+Authentication mechanism. The eighth is an Exim authenticator but not an SMTP
+one; instead it can use information from a TLS negotiation.
The authenticators are configured using the same syntax as other drivers (see
-section 6.22). If no authenticators are required, no authentication section
+section 6.23). If no authenticators are required, no authentication section
need be present in the configuration file. Each authenticator can in principle
have both server and client functions. When Exim is receiving SMTP mail, it is
acting as a server; when it is sending out messages over SMTP, it is acting as
33.1 Generic options for authenticators
---------------------------------------
-+----------------+-------------------+-------------+--------------+
++-----------------------------------------------------------------+
|client_condition|Use: authenticators|Type: string*|Default: unset|
-+----------------+-------------------+-------------+--------------+
++-----------------------------------------------------------------+
When Exim is authenticating as a client, it skips any authenticator whose
client_condition expansion yields "0", "no", or "false". This can be used, for
client_condition = ${if !eq{$tls_out_cipher}{}}
-+-------------+-------------------+-------------+--------------+
++--------------------------------------------------------------+
|client_set_id|Use: authenticators|Type: string*|Default: unset|
-+-------------+-------------------+-------------+--------------+
++--------------------------------------------------------------+
When client authentication succeeds, this condition is expanded; the result is
-used in the log lines for outbound messasges. Typically it will be the user
-name used for authentication.
+used in the log lines for outbound messages. Typically it will be the user name
+used for authentication.
-+------+-------------------+------------+--------------+
++------------------------------------------------------+
|driver|Use: authenticators|Type: string|Default: unset|
-+------+-------------------+------------+--------------+
++------------------------------------------------------+
This option must always be set. It specifies which of the available
authenticators is to be used.
-+-----------+-------------------+------------+--------------+
++-----------------------------------------------------------+
|public_name|Use: authenticators|Type: string|Default: unset|
-+-----------+-------------------+------------+--------------+
++-----------------------------------------------------------+
This option specifies the name of the authentication mechanism that the driver
implements, and by which it is known to the outside world. These names should
but Exim in fact matches them caselessly. If public_name is not set, it
defaults to the driver's instance name.
-+--------------------------+-------------------+-------------+--------------+
++---------------------------------------------------------------------------+
|server_advertise_condition|Use: authenticators|Type: string*|Default: unset|
-+--------------------------+-------------------+-------------+--------------+
++---------------------------------------------------------------------------+
When a server is about to advertise an authentication mechanism, the condition
is expanded. If it yields the empty string, "0", "no", or "false", the
advertised. If the failure was not forced, and was not caused by a lookup
defer, the incident is logged. See section 33.3 below for further discussion.
-+----------------+-------------------+-------------+--------------+
++-----------------------------------------------------------------+
|server_condition|Use: authenticators|Type: string*|Default: unset|
-+----------------+-------------------+-------------+--------------+
++-----------------------------------------------------------------+
This option must be set for a plaintext server authenticator, where it is used
directly to control authentication. See section 34.2 for details.
result, a temporary error code is returned, with the expanded string as the
error text.
-+------------------+-------------------+-------------+--------------+
++-------------------------------------------------------------------+
|server_debug_print|Use: authenticators|Type: string*|Default: unset|
-+------------------+-------------------+-------------+--------------+
++-------------------------------------------------------------------+
If this option is set and authentication debugging is enabled (see the -d
command line option), the string is expanded and included in the debugging
out the values of variables. If expansion of the string fails, the error
message is written to the debugging output, and Exim carries on processing.
-+-------------+-------------------+-------------+--------------+
++--------------------------------------------------------------+
|server_set_id|Use: authenticators|Type: string*|Default: unset|
-+-------------+-------------------+-------------+--------------+
++--------------------------------------------------------------+
When an Exim server successfully authenticates a client, this string is
expanded using data from the authentication, and preserved for any incoming
messages in the variable $authenticated_id. It is also included in the log
lines for incoming messages. For example, a user/password authenticator
configuration might preserve the user name that was used to authenticate, and
-refer to it subsequently during delivery of the message. If expansion fails,
-the option is ignored.
+refer to it subsequently during delivery of the message. On a failing
+authentication the expansion result is instead saved in the
+$authenticated_fail_id variable. If expansion fails, the option is ignored.
-+--------------------------+-------------------+-------------+--------------+
++---------------------------------------------------------------------------+
|server_mail_auth_condition|Use: authenticators|Type: string*|Default: unset|
-+--------------------------+-------------------+-------------+--------------+
++---------------------------------------------------------------------------+
This option allows a server to discard authenticated sender addresses supplied
as part of MAIL commands in SMTP connections that are authenticated by the
from which the message was received. This variable is empty if there was no
successful authentication.
+Successful authentication sets up information used by the $authresults
+expansion item.
+
33.4 Testing server authentication
----------------------------------
retry rules, and thereby turned into a permanent error if you wish. In the
second case, Exim tries to deliver the message unauthenticated.
+Note that the hostlist test for whether to do authentication can be confused if
+name-IP lookups change between the time the peer is decided upon and the time
+that the transport runs. For example, with a manualroute router given a host
+name, and with DNS "round-robin" used by that name: if the local resolver cache
+times out between the router and the transport running, the transport may get
+an IP for the name for its authentication check which does not match the
+connection peer IP. No authentication will then be done, despite the names
+being identical.
+
+For such cases use a separate transport which always authenticates.
+
When Exim has authenticated itself to a remote server, it adds the AUTH
parameter to the MAIL commands it sends, if it has an authenticated sender for
the message. If the message came from a remote host, the authenticated sender
authentication mechanisms, both of which transfer authentication data as plain
(unencrypted) text (though base64 encoded). The use of plain text is a security
risk; you are strongly advised to insist on the use of SMTP encryption (see
-chapter 41) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted
+chapter 42) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted
plain text, you should not use the same passwords for SMTP connections as you
do for login accounts.
When configured as a server, plaintext uses the following options:
-+----------------+-------------------+-------------+--------------+
++-----------------------------------------------------------------+
|server_condition|Use: authenticators|Type: string*|Default: unset|
-+----------------+-------------------+-------------+--------------+
++-----------------------------------------------------------------+
This is actually a global authentication option, but it must be set in order to
configure the plaintext driver as a server. Its use is described below.
-+--------------+--------------+-------------+--------------+
++----------------------------------------------------------+
|server_prompts|Use: plaintext|Type: string*|Default: unset|
-+--------------+--------------+-------------+--------------+
++----------------------------------------------------------+
The contents of this option, after expansion, must be a colon-separated list of
prompt strings. If expansion fails, a temporary authentication rejection is
authentication fails. If the result of the expansion is "1", "yes", or "true",
authentication succeeds and the generic server_set_id option is expanded and
saved in $authenticated_id. For any other result, a temporary error code is
-returned, with the expanded string as the error text
+returned, with the expanded string as the error text.
Warning: If you use a lookup in the expansion to find the user's password, be
sure to make the authentication fail if the user is unknown. There are good and
The plaintext authenticator has two client options:
-+----------------------------+--------------+-------------+--------------+
++------------------------------------------------------------------------+
|client_ignore_invalid_base64|Use: plaintext|Type: boolean|Default: false|
-+----------------------------+--------------+-------------+--------------+
++------------------------------------------------------------------------+
If the client receives a server prompt that is not a valid base64 string,
authentication is abandoned by default. However, if this option is set true,
the error in the challenge is ignored and the client sends the response as
usual.
-+-----------+--------------+-------------+--------------+
++-------------------------------------------------------+
|client_send|Use: plaintext|Type: string*|Default: unset|
-+-----------+--------------+-------------+--------------+
++-------------------------------------------------------+
The string is a colon-separated list of authentication data strings. Each
string is independently expanded before being sent to the server. The first
This authenticator has one server option, which must be set to configure the
authenticator as a server:
-+-------------+-------------+-------------+--------------+
++--------------------------------------------------------+
|server_secret|Use: cram_md5|Type: string*|Default: unset|
-+-------------+-------------+-------------+--------------+
++--------------------------------------------------------+
When the server receives the client's response, the user name is placed in the
expansion variable $auth1, and server_secret is expanded to obtain the password
driver = cram_md5
public_name = CRAM-MD5
server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
- dbmjz{/etc/sasldb2}}
+ dbmjz{/etc/sasldb2}{$value}fail}
server_set_id = $auth1
When used as a client, the cram_md5 authenticator has two options:
-+-----------+-------------+-------------+------------------------------+
++----------------------------------------------------------------------+
|client_name|Use: cram_md5|Type: string*|Default: the primary host name|
-+-----------+-------------+-------------+------------------------------+
++----------------------------------------------------------------------+
This string is expanded, and the result used as the user name data when
computing the response to the server's challenge.
-+-------------+-------------+-------------+--------------+
++--------------------------------------------------------+
|client_secret|Use: cram_md5|Type: string*|Default: unset|
-+-------------+-------------+-------------+--------------+
++--------------------------------------------------------+
This option must be set for the authenticator to work as a client. Its value is
expanded and the result used as the secret string when computing the response.
===============================================================================
36. THE CYRUS_SASL AUTHENTICATOR
-The code for this authenticator was provided by Matthew Byng-Maddick of A L
-Digital Ltd (http://www.aldigital.co.uk).
+The code for this authenticator was provided by Matthew Byng-Maddick while at A
+L Digital Ltd.
The cyrus_sasl authenticator provides server support for the Cyrus SASL library
implementation of the RFC 2222 ("Simple Authentication and Security Layer").
so can the cyrus_sasl authenticator. By default it uses the public name of the
driver to determine which mechanism to support.
-Where access to some kind of secret file is required, for example in GSSAPI or
+Where access to some kind of secret file is required, for example, in GSSAPI or
CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and
that the Cyrus SASL library has no way of escalating privileges by default. You
may also find you need to set environment variables, depending on the driver
variable for this purpose is now deprecated, as it can lead to confusion in
string expansions that also use numeric variables for other things.
-+---------------+---------------+-------------+------------------+
++----------------------------------------------------------------+
|server_hostname|Use: cyrus_sasl|Type: string*|Default: see below|
-+---------------+---------------+-------------+------------------+
++----------------------------------------------------------------+
This option selects the hostname that is used when communicating with the
library. The default value is "$primary_hostname". It is up to the underlying
SASL plug-in what it does with this data.
-+-----------+---------------+------------+------------------+
++-----------------------------------------------------------+
|server_mech|Use: cyrus_sasl|Type: string|Default: see below|
-+-----------+---------------+------------+------------------+
++-----------------------------------------------------------+
This option selects the authentication mechanism this driver should use. The
default is the value of the generic public_name option. This option allows you
server_mech = CRAM-MD5
server_set_id = $auth1
-+------------+---------------+-------------+--------------+
++---------------------------------------------------------+
|server_realm|Use: cyrus_sasl|Type: string*|Default: unset|
-+------------+---------------+-------------+--------------+
++---------------------------------------------------------+
This specifies the SASL realm that the server claims to be in.
-+--------------+---------------+------------+---------------+
++-----------------------------------------------------------+
|server_service|Use: cyrus_sasl|Type: string|Default: "smtp"|
-+--------------+---------------+------------+---------------+
++-----------------------------------------------------------+
This is the SASL service that the server claims to implement.
This authenticator is an interface to the authentication facility of the
Dovecot POP/IMAP server, which can support a number of authentication methods.
+Note that Dovecot must be configured to use auth-client not auth-userdb. If you
+are using Dovecot to authenticate POP/IMAP clients, it might be helpful to use
+the same mechanisms for SMTP authentication. This is a server authenticator
+only. There is only one option:
-Note that Dovecot must be configured to use auth-client not auth-userdb.
-
-If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
-to use the same mechanisms for SMTP authentication. This is a server
-authenticator only. There is only one option:
-
-+-------------+------------+------------+--------------+
++------------------------------------------------------+
|server_socket|Use: dovecot|Type: string|Default: unset|
-+-------------+------------+------------+--------------+
++------------------------------------------------------+
-This option must specify the socket that is the interface to Dovecot
+This option must specify the UNIX socket that is the interface to Dovecot
authentication. The public_name option must specify an authentication mechanism
that Dovecot is configured to support. You can have several authenticators for
different mechanisms. For example:
particular new authentication mechanism will be supported without code changes
in Exim.
-+---------------------+----------+-------------+--------------+
+Exim's gsasl authenticator does not have client-side support at this time; only
+the server-side support is implemented. Patches welcome.
+
++-------------------------------------------------------------+
|server_channelbinding|Use: gsasl|Type: boolean|Default: false|
-+---------------------+----------+-------------+--------------+
++-------------------------------------------------------------+
+
+Do not set this true without consulting a cryptographic engineer.
Some authentication mechanisms are able to use external context at both ends of
the session to bind the authentication to that context, and fail the
ciphersuites can provide identifying information about the cryptographic
context.
-This means that certificate identity and verification becomes a non-issue, as a
-man-in-the-middle attack will cause the correct client and server to see
-different identifiers and authentication will fail.
+This should have meant that certificate identity and verification becomes a
+non-issue, as a man-in-the-middle attack will cause the correct client and
+server to see different identifiers and authentication will fail.
This is currently only supported when using the GnuTLS library. This is only
usable by mechanisms which support "channel binding"; at time of writing,
that's the SCRAM family.
This defaults off to ensure smooth upgrade across Exim releases, in case this
-option causes some clients to start failing. Some future release of Exim may
-switch the default to be true.
+option causes some clients to start failing. Some future release of Exim might
+have switched the default to be true.
+
+However, Channel Binding in TLS has proven to be broken in current versions. Do
+not plan to rely upon this feature for security, ever, without consulting with
+a subject matter expert (a cryptographic engineer).
-+---------------+----------+-------------+------------------+
++-----------------------------------------------------------+
|server_hostname|Use: gsasl|Type: string*|Default: see below|
-+---------------+----------+-------------+------------------+
++-----------------------------------------------------------+
This option selects the hostname that is used when communicating with the
library. The default value is "$primary_hostname". Some mechanisms will use
this data.
-+-----------+----------+------------+------------------+
++------------------------------------------------------+
|server_mech|Use: gsasl|Type: string|Default: see below|
-+-----------+----------+------------+------------------+
++------------------------------------------------------+
This option selects the authentication mechanism this driver should use. The
default is the value of the generic public_name option. This option allows you
server_mech = CRAM-MD5
server_set_id = $auth1
-+---------------+----------+-------------+--------------+
++-------------------------------------------------------+
|server_password|Use: gsasl|Type: string*|Default: unset|
-+---------------+----------+-------------+--------------+
++-------------------------------------------------------+
Various mechanisms need access to the cleartext password on the server, so that
proof-of-possession can be demonstrated on the wire, without sending the
If using this option, it may make sense to set the server_condition option to
be simply "true".
-+------------+----------+-------------+--------------+
++----------------------------------------------------+
|server_realm|Use: gsasl|Type: string*|Default: unset|
-+------------+----------+-------------+--------------+
++----------------------------------------------------+
This specifies the SASL realm that the server claims to be in. Some mechanisms
will use this data.
-+-----------------+----------+-------------+--------------+
++---------------------------------------------------------+
|server_scram_iter|Use: gsasl|Type: string*|Default: unset|
-+-----------------+----------+-------------+--------------+
++---------------------------------------------------------+
This option provides data for the SCRAM family of mechanisms. $auth1 is not
available at evaluation time. (This may change, as we receive feedback on use)
-+-----------------+----------+-------------+--------------+
++---------------------------------------------------------+
|server_scram_salt|Use: gsasl|Type: string*|Default: unset|
-+-----------------+----------+-------------+--------------+
++---------------------------------------------------------+
This option provides data for the SCRAM family of mechanisms. $auth1 is not
available at evaluation time. (This may change, as we receive feedback on use)
-+--------------+----------+------------+---------------+
++------------------------------------------------------+
|server_service|Use: gsasl|Type: string|Default: "smtp"|
-+--------------+----------+------------+---------------+
++------------------------------------------------------+
This is the SASL service that the server claims to implement. Some mechanisms
will use this data.
The heimdal_gssapi authenticator provides server integration for the Heimdal
GSSAPI/Kerberos library, permitting Exim to set a keytab pathname reliably.
-+---------------+-------------------+-------------+------------------+
++--------------------------------------------------------------------+
|server_hostname|Use: heimdal_gssapi|Type: string*|Default: see below|
-+---------------+-------------------+-------------+------------------+
++--------------------------------------------------------------------+
This option selects the hostname that is used, with server_service, for
constructing the GSS server name, as a GSS_C_NT_HOSTBASED_SERVICE identifier.
The default value is "$primary_hostname".
-+-------------+-------------------+-------------+--------------+
++--------------------------------------------------------------+
|server_keytab|Use: heimdal_gssapi|Type: string*|Default: unset|
-+-------------+-------------------+-------------+--------------+
++--------------------------------------------------------------+
If set, then Heimdal will not use the system default keytab (typically /etc/
krb5.keytab) but instead the pathname given in this option. The value should be
a pathname, with no "file:" prefix.
-+--------------+-------------------+-------------+-------------+
++--------------------------------------------------------------+
|server_service|Use: heimdal_gssapi|Type: string*|Default: smtp|
-+--------------+-------------------+-------------+-------------+
++--------------------------------------------------------------+
This option specifies the service identifier used, in conjunction with
-server_hostname, for building the identifer for finding credentials from the
+server_hostname, for building the identifier for finding credentials from the
keytab.
The spa authenticator provides client support for Microsoft's Secure Password
Authentication mechanism, which is also sometimes known as NTLM (NT LanMan).
The code for client side of this authenticator was contributed by Marc
-Prud'hommeaux, and much of it is taken from the Samba project (http://
-www.samba.org). The code for the server side was subsequently contributed by
+Prud'hommeaux, and much of it is taken from the Samba project (https://
+www.samba.org/). The code for the server side was subsequently contributed by
Tom Kistner. The mechanism works as follows:
* After the AUTH command has been accepted, the client sends an SPA
The spa authenticator has just one server option:
-+---------------+--------+-------------+--------------+
++-----------------------------------------------------+
|server_password|Use: spa|Type: string*|Default: unset|
-+---------------+--------+-------------+--------------+
++-----------------------------------------------------+
This option is expanded, and the result must be the cleartext password for the
authenticating user, whose name is at this point in $auth1. For compatibility
The spa authenticator has the following client options:
-+-------------+--------+-------------+--------------+
++---------------------------------------------------+
|client_domain|Use: spa|Type: string*|Default: unset|
-+-------------+--------+-------------+--------------+
++---------------------------------------------------+
This option specifies an optional domain for the authentication.
-+---------------+--------+-------------+--------------+
++-----------------------------------------------------+
|client_password|Use: spa|Type: string*|Default: unset|
-+---------------+--------+-------------+--------------+
++-----------------------------------------------------+
This option specifies the user's password, and must be set.
-+---------------+--------+-------------+--------------+
++-----------------------------------------------------+
|client_username|Use: spa|Type: string*|Default: unset|
-+---------------+--------+-------------+--------------+
++-----------------------------------------------------+
This option specifies the user name, and must be set. Here is an example of a
configuration of this authenticator for use with the mail servers at msn.com:
===============================================================================
-41. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL
+41. THE TLS AUTHENTICATOR
+
+The tls authenticator provides server support for authentication based on
+client certificates.
+
+It is not an SMTP authentication mechanism and is not advertised by the server
+as part of the SMTP EHLO response. It is an Exim authenticator in the sense
+that it affects the protocol element of the log line, can be tested for by the
+authenticated ACL condition, and can set the $authenticated_id variable.
+
+The client must present a verifiable certificate, for which it must have been
+requested via the tls_verify_hosts or tls_try_verify_hosts main options (see 42
+).
+
+If an authenticator of this type is configured it is run before any SMTP-level
+communication is done, and can authenticate the connection. If it does, SMTP
+authentication is not offered.
+
+A maximum of one authenticator of this type may be present.
+
+The tls authenticator has three server options:
+
++---------------------------------------------------+
+|server_param1|Use: tls|Type: string*|Default: unset|
++---------------------------------------------------+
+
+This option is expanded after the TLS negotiation and the result is placed in
+$auth1. If the expansion is forced to fail, authentication fails. Any other
+expansion failure causes a temporary error code to be returned.
+
++---------------------------------------------------+
+|server_param2|Use: tls|Type: string*|Default: unset|
++---------------------------------------------------+
+
++---------------------------------------------------+
+|server_param3|Use: tls|Type: string*|Default: unset|
++---------------------------------------------------+
+
+As above, for $auth2 and $auth3.
+
+server_param1 may also be spelled server_param.
+
+Example:
+
+tls:
+ driver = tls
+ server_param1 = ${certextract {subj_altname,mail,>:} \
+ {$tls_in_peercert}}
+ server_condition = ${if and { {eq{$tls_in_certificate_verified}{1}} \
+ {forany {$auth1} \
+ {!= {0} \
+ {${lookup ldap{ldap:///\
+ mailname=${quote_ldap_dn:${lc:$item}},\
+ ou=users,LDAP_DC?mailid} {$value}{0} \
+ } } } }}}
+ server_set_id = ${if = {1}{${listcount:$auth1}} {$auth1}{}}
+
+This accepts a client certificate that is verifiable against any of your
+configured trust-anchors (which usually means the full set of public CAs) and
+which has a SAN with a good account name.
+
+Note that, up to TLS1.2, the client cert is on the wire in-clear, including the
+SAN, The account name is therefore guessable by an opponent. TLS 1.3 protects
+both server and client certificates, and is not vulnerable in this way.
+Likewise, a traditional plaintext SMTP AUTH done inside TLS is not.
+
+Note that because authentication is traditionally an SMTP operation, the
+authenticated ACL condition cannot be used in a connect- or helo-ACL.
+
+
+
+===============================================================================
+42. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL
Support for TLS (Transport Layer Security), formerly known as SSL (Secure
Sockets Layer), is implemented by making use of the OpenSSL library or the
to get TLS to work.
-41.1 Support for the legacy "ssmtp" (aka "smtps") protocol
-----------------------------------------------------------
+42.1 Support for the "submissions" (aka "ssmtp" and "smtps") protocol
+---------------------------------------------------------------------
-Early implementations of encrypted SMTP used a different TCP port from normal
-SMTP, and expected an encryption negotiation to start immediately, instead of
-waiting for a STARTTLS command from the client using the standard SMTP port.
-The protocol was called "ssmtp" or "smtps", and port 465 was allocated for this
-purpose.
+The history of port numbers for TLS in SMTP is a little messy and has been
+contentious. As of RFC 8314, the common practice of using the historically
+allocated port 465 for "email submission but with TLS immediately upon connect
+instead of using STARTTLS" is officially blessed by the IETF, and recommended
+by them in preference to STARTTLS.
-This approach was abandoned when encrypted SMTP was standardized, but there are
-still some legacy clients that use it. Exim supports these clients by means of
-the tls_on_connect_ports global option. Its value must be a list of port
-numbers; the most common use is expected to be:
+The name originally assigned to the port was "ssmtp" or "smtps", but as clarity
+emerged over the dual roles of SMTP, for MX delivery and Email Submission,
+nomenclature has shifted. The modern name is now "submissions".
+
+This approach was, for a while, officially abandoned when encrypted SMTP was
+standardized, but many clients kept using it, even as the TCP port number was
+reassigned for other use. Thus you may encounter guidance claiming that you
+shouldn't enable use of this port. In practice, a number of mail-clients have
+only ever supported submissions, not submission with STARTTLS upgrade. Ideally,
+offer both submission (587) and submissions (465) service.
+
+Exim supports TLS-on-connect by means of the tls_on_connect_ports global
+option. Its value must be a list of port numbers; the most common use is
+expected to be:
tls_on_connect_ports = 465
rather, it specifies different behaviour on a port that is defined elsewhere.
There is also a -tls-on-connect command line option. This overrides
-tls_on_connect_ports; it forces the legacy behaviour for all ports.
+tls_on_connect_ports; it forces the TLS-only behaviour for all ports.
-41.2 OpenSSL vs GnuTLS
+42.2 OpenSSL vs GnuTLS
----------------------
The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS
There are some differences in usage when using GnuTLS instead of OpenSSL:
- * The tls_verify_certificates option must contain the name of a file, not the
- name of a directory (for OpenSSL it can be either).
+ * The tls_verify_certificates option cannot be the path of a directory for
+ GnuTLS versions before 3.3.6 (for later versions, or OpenSSL, it can be
+ either).
* The default value for tls_dhparam differs for historical reasons.
transport option).
* The tls_require_ciphers options operate differently, as described in the
- sections 41.4 and 41.5.
+ sections 42.4 and 42.5.
* The tls_dh_min_bits SMTP transport option is only honoured by GnuTLS. When
using OpenSSL, this option is ignored. (If an API is found to let OpenSSL
be configured in this way, let the Exim Maintainers know and we'll likely
use it).
+ * With GnuTLS, if an explicit list is used for the tls_privatekey main option
+ main option, it must be ordered to match the tls_certificate list.
+
* Some other recently added features may only be available in one or the
other. This should be documented with the feature. If the documentation
does not explicitly state that the feature is infeasible in the other TLS
implementation, then patches are welcome.
-41.3 GnuTLS parameter computation
+42.3 GnuTLS parameter computation
---------------------------------
This section only applies if tls_dhparam is set to "historic" or to an explicit
the generated prime, so it might still be too large.
-41.4 Requiring specific ciphers in OpenSSL
+42.4 Requiring specific ciphers in OpenSSL
------------------------------------------
There is a function in the OpenSSL library that can be passed a list of cipher
suites before the cipher negotiation takes place. This specifies which ciphers
-are acceptable. The list is colon separated and may contain names like
-DES-CBC3-SHA. Exim passes the expanded value of tls_require_ciphers directly to
-this function call. Many systems will install the OpenSSL manual-pages, so you
-may have ciphers(1) available to you. The following quotation from the OpenSSL
+
+are acceptable for TLS versions prior to 1.3.
+
+The list is colon separated and may contain names like DES-CBC3-SHA. Exim
+passes the expanded value of tls_require_ciphers directly to this function
+call. Many systems will install the OpenSSL manual-pages, so you may have
+ciphers(1) available to you. The following quotation from the OpenSSL
documentation specifies what forms of item are allowed in the cipher string:
* It can consist of a single cipher suite such as RC4-SHA.
{DEFAULT}\
{HIGH:!MD5:!SHA1}}
+This example will prefer ECDSA-authenticated ciphers over RSA ones:
+
+tls_require_ciphers = ECDSA:RSA:!COMPLEMENTOFDEFAULT
-41.5 Requiring specific ciphers or other parameters in GnuTLS
+For TLS version 1.3 the control available is less fine-grained and Exim does
+not provide access to it at present. The value of the tls_require_ciphers
+option is ignored when TLS version 1.3 is negotiated.
+
+As of writing the library default cipher suite list for TLSv1.3 is
+
+TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
+
+
+42.5 Requiring specific ciphers or other parameters in GnuTLS
-------------------------------------------------------------
The GnuTLS library allows the caller to provide a "priority string", documented
as part of the gnutls_priority_init function. This is very similar to the
ciphersuite specification in OpenSSL.
-The tls_require_ciphers option is treated as the GnuTLS priority string.
+The tls_require_ciphers option is treated as the GnuTLS priority string and
+controls both protocols and ciphers.
The tls_require_ciphers option is available both as an global option,
controlling how Exim behaves as a server, and also as an option of the smtp
feature enhancements of GnuTLS.
Documentation of the strings accepted may be found in the GnuTLS manual, under
-"Priority strings". This is online as http://www.gnutls.org/manual/html_node/
+"Priority strings". This is online as https://www.gnutls.org/manual/html_node/
Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be
-newer than the version installed on your system. If you are using GnuTLS 3,
-then the example code on that site can be used to test a given string.
+newer than the version installed on your system. If you are using GnuTLS 3,
+then the example code https://www.gnutls.org/manual/gnutls.html#
+Listing-the-ciphersuites-in-a-priority-string on that site can be used to test
+a given string.
+
+For example:
+
+# Disable older versions of protocols
+tls_require_ciphers = NORMAL:%LATEST_RECORD_VERSION:-VERS-SSL3.0
Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
additional options, "gnutls_require_kx", "gnutls_require_mac" and "
{SECURE128}}
-41.6 Configuring an Exim server to use TLS
+42.6 Configuring an Exim server to use TLS
------------------------------------------
When Exim has been built with TLS support, it advertises the availability of
the STARTTLS command to client hosts that match tls_advertise_hosts, but not to
-any others. The default value of this option is unset, which means that
-STARTTLS is not advertised at all. This default is chosen because you need to
-set some other options in order to make TLS available, and also it is sensible
-for systems that want to use TLS only as a client.
+any others. The default value of this option is *, which means that STARTTLS is
+always advertised. Set it to blank to never advertise; this is reasonable for
+systems that want to use TLS only as a client.
+
+If STARTTLS is to be used you need to set some other options in order to make
+TLS available.
If a client issues a STARTTLS command and there is some configuration problem
in the server, the command is rejected with a 454 error. If the client persists
If a STARTTLS command is issued within an existing TLS session, it is rejected
with a 554 error code.
-To enable TLS operations on a server, you must set tls_advertise_hosts to match
-some hosts. You can, of course, set it to * to match all hosts. However, this
-is not all you need to do. TLS sessions to a server won't work without some
-further configuration at the server end.
+To enable TLS operations on a server, the tls_advertise_hosts option must be
+set to match some hosts. The default is * which matches all hosts.
+
+If this is all you do, TLS encryption will be enabled but not authentication -
+meaning that the peer has no assurance it is actually you he is talking to. You
+gain protection from a passive sniffer listening on the wire but not from
+someone able to intercept the communication.
-It is rumoured that all existing clients that support TLS/SSL use RSA
-encryption. To make this work you need to set, in the server,
+Further protection requires some further configuration at the server end.
+
+To make TLS work you need to set, in the server,
tls_certificate = /some/file/name
tls_privatekey = /some/file/name
These options are, in fact, expanded strings, so you can make them depend on
the identity of the client that is connected if you wish. The first file
contains the server's X509 certificate, and the second contains the private key
-that goes with it. These files need to be readable by the Exim user, and must
-always be given as full path names. They can be the same file if both the
-certificate and the key are contained within it. If tls_privatekey is not set,
-or if its expansion is forced to fail or results in an empty string, this is
-assumed to be the case. The certificate file may also contain intermediate
-certificates that need to be sent to the client to enable it to authenticate
-the server's certificate.
+that goes with it. These files need to be PEM format and readable by the Exim
+user, and must always be given as full path names. The key must not be
+password-protected. They can be the same file if both the certificate and the
+key are contained within it. If tls_privatekey is not set, or if its expansion
+is forced to fail or results in an empty string, this is assumed to be the
+case. The certificate file may also contain intermediate certificates that need
+to be sent to the client to enable it to authenticate the server's certificate.
+
+For dual-stack (eg. RSA and ECDSA) configurations, these options can be
+colon-separated lists of file paths. Ciphers using given authentication
+algorithms require the presence of a suitable certificate to supply the
+public-key. The server selects among the certificates to present to the client
+depending on the selected cipher, hence the priority ordering for ciphers will
+affect which certificate is used.
If you do not understand about certificates and keys, please try to find a
source of this background information, which is not Exim-specific. (There are a
-few comments below in section 41.12.)
+few comments below in section 42.12.)
Note: These options do not apply when Exim is operating as a client - they
apply only in the case of a server. If you need to use a certificate in an Exim
depending on the tls_cipher log selector).
-41.7 Requesting and verifying client certificates
+42.7 Requesting and verifying client certificates
-------------------------------------------------
If you want an Exim server to request a certificate when negotiating a TLS
all TLS connections. For any host that matches one of these options, Exim
requests a certificate as part of the setup of the TLS session. The contents of
the certificate are verified by comparing it with a list of expected
-certificates. These must be available in a file or, for OpenSSL only (not
-GnuTLS), a directory, identified by tls_verify_certificates.
+trust-anchors or certificates. These may be the system default set (depending
+on library version), an explicit file or, depending on library version, a
+directory, identified by tls_verify_certificates.
A file can contain multiple certificates, concatenated end to end. If a
directory is used (OpenSSL only), each certificate must be in a separate file,
where /cert/file contains a single certificate.
+There is no checking of names of the client against the certificate Subject
+Name or Subject Alternate Names.
+
The difference between tls_verify_hosts and tls_try_verify_hosts is what
happens if the client does not supply a certificate, or if the certificate does
not match any of the certificates in the collection named by
is empty.
-41.8 Revoked certificates
+42.8 Revoked certificates
-------------------------
Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
identically named option for the smtp transport. In each case, the value of the
option is expanded and must then be the name of a file that contains a CRL in
PEM format. The downside is that clients have to periodically re-download a
-potentially huge file from every certificate authority the know of.
+potentially huge file from every certificate authority they know of.
The way with most moving parts at query time is Online Certificate Status
Protocol (OCSP), where the client verifies the certificate against an OCSP
current proof expires. The downside is that it requires server support.
Unless Exim is built with the support disabled, or with GnuTLS earlier than
-version 3.1.3, support for OCSP stapling is included.
+version 3.3.16 / 3.4.8 support for OCSP stapling is included.
There is a global option called tls_ocsp_file. The file specified therein is
expected to be in DER format, and contain an OCSP proof. Exim will serve it as
noted this as invalid overall, but the re-fetch script did not.
-41.9 Configuring an Exim client to use TLS
+42.9 Configuring an Exim client to use TLS
------------------------------------------
The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries
If the server is Exim, it will request a certificate only if tls_verify_hosts
or tls_try_verify_hosts matches the client.
-If the tls_verify_certificates option is set on the smtp transport, it must
-name a file or, for OpenSSL only (not GnuTLS), a directory, that contains a
-collection of expected server certificates. The client verifies the server's
-certificate against this collection, taking into account any revoked
-certificates that are in the list defined by tls_crl. Failure to verify fails
-the TLS connection unless either of the tls_verify_hosts or
-tls_try_verify_hosts options are set.
+If the tls_verify_certificates option is set on the smtp transport, it
+specifies a collection of expected server certificates. These may be the system
+default set (depending on library version), a file, or (depending on library
+version) a directory. The client verifies the server's certificate against this
+collection, taking into account any revoked certificates that are in the list
+defined by tls_crl. Failure to verify fails the TLS connection unless either of
+the tls_verify_hosts or tls_try_verify_hosts options are set.
The tls_verify_hosts and tls_try_verify_hosts options restrict certificate
verification to the listed servers. Verification either must or need not
succeed respectively.
+The tls_verify_cert_hostnames option lists hosts for which additional checks
+are made: that the host name (the one in the DNS A record) is valid for the
+certificate. The option defaults to always checking.
+
The smtp transport has two OCSP-related options: hosts_require_ocsp; a
host-list for which a Certificate Status is requested and required for the
connection to proceed. The default value is empty. hosts_request_ocsp; a
set to the relevant values for the outgoing connection.
-41.10 Use of TLS Server Name Indication
+42.10 Use of TLS Server Name Indication
---------------------------------------
With TLS1.0 or above, there is an extension mechanism by which extra
possibly choose to use different certificates and keys (and more) for this
session.
-This is analagous to HTTP's "Host:" header, and is the main mechanism by which
+This is analogous to HTTP's "Host:" header, and is the main mechanism by which
HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address.
With SMTP to MX, there are the same problems here as in choosing the identity
* tls_verify_certificates
- * tls_verify_certificates
+ * tls_ocsp_file
Great care should be taken to deal with matters of case, various injection
attacks in the string ("../" or SQL), and ensuring that a valid filename can
-always be referenced; it is important to remember that $tls_sni is arbitrary
-unverified data provided prior to authentication.
+always be referenced; it is important to remember that $tls_in_sni is arbitrary
+unverified data provided prior to authentication. Further, the initial
+certificate is loaded before SNI is arrived, so an expansion for
+tls_certificate must have a default which is used when $tls_in_sni is empty.
The Exim developers are proceeding cautiously and so far no other TLS options
are re-expanded.
-When Exim is built againt OpenSSL, OpenSSL must have been built with support
+When Exim is built against OpenSSL, OpenSSL must have been built with support
for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with
enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see
"-servername" in the output, then OpenSSL has support.
built, then you have SNI support).
-41.11 Multiple messages on the same encrypted TCP/IP connection
+42.11 Multiple messages on the same encrypted TCP/IP connection
---------------------------------------------------------------
Exim sends multiple messages down the same TCP/IP connection by starting up an
process to the next. This implementation does not fit well with the use of TLS,
because there is quite a lot of state information associated with a TLS
connection, not just a socket identification. Passing all the state information
-to a new process is not feasible. Consequently, Exim shuts down an existing TLS
-session before passing the socket to a new process. The new process may then
-try to start a new TLS session, and if successful, may try to re-authenticate
-if AUTH is in use, before sending the next message.
+to a new process is not feasible. Consequently, for sending using TLS Exim
+starts an additional proxy process for handling the encryption, piping the
+unencrypted data stream from and to the delivery processes.
+
+An older mode of operation can be enabled on a per-host basis by the
+hosts_noproxy_tls option on the smtp transport. If the host matches this list
+the proxy process described above is not used; instead Exim shuts down an
+existing TLS session being run by the delivery process before passing the
+socket to a new process. The new process may then try to start a new TLS
+session, and if successful, may try to re-authenticate if AUTH is in use,
+before sending the next message.
The RFC is not clear as to whether or not an SMTP session continues in clear
after TLS has been shut down, or whether TLS may be restarted again later, as
new processes if TLS has been used.
-41.12 Certificates and all that
+42.12 Certificates and all that
-------------------------------
In order to understand fully how TLS works, you need to know about
-certificates, certificate signing, and certificate authorities. This is not the
-place to give a tutorial, especially as I do not know very much about it
-myself. Some helpful introduction can be found in the FAQ for the SSL addition
-to Apache, currently at
+certificates, certificate signing, and certificate authorities. This is a large
+topic and an introductory guide is unsuitable for the Exim reference manual, so
+instead we provide pointers to existing documentation.
+
+The Apache web-server was for a long time the canonical guide, so their
+documentation is a good place to start; their SSL module's Introduction
+document is currently at
+
+https://httpd.apache.org/docs/current/ssl/ssl_intro.html
-http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24
+and their FAQ is at
-Other parts of the modssl documentation are also helpful, and have links to
-further files. Eric Rescorla's book, SSL and TLS, published by Addison-Wesley
-(ISBN 0-201-61598-3), contains both introductory and more in-depth
-descriptions. Some sample programs taken from the book are available from
+https://httpd.apache.org/docs/current/ssl/ssl_faq.html
-http://www.rtfm.com/openssl-examples/
+Eric Rescorla's book, SSL and TLS, published by Addison-Wesley (ISBN
+0-201-61598-3) in 2001, contains both introductory and more in-depth
+descriptions. More recently Ivan Risti?'s book Bulletproof SSL and TLS,
+published by Feisty Duck (ISBN 978-1907117046) in 2013 is good. Ivan is the
+author of the popular TLS testing tools at https://www.ssllabs.com/.
-41.13 Certificate chains
+42.13 Certificate chains
------------------------
The file named by tls_certificate may contain more than one certificate. This
in such a case can be frustratingly vague.
-41.14 Self-signed certificates
+42.14 Self-signed certificates
------------------------------
You can create a self-signed certificate using the req command provided with
For information on creating self-signed CA certificates and using them to sign
user certificates, see the General implementation overview chapter of the
-Open-source PKI book, available online at http://ospkibook.sourceforge.net/.
+Open-source PKI book, available online at https://sourceforge.net/projects/
+ospkibook/.
+
+
+42.15 DANE
+----------
+
+DNS-based Authentication of Named Entities, as applied to SMTP over TLS,
+provides assurance to a client that it is actually talking to the server it
+wants to rather than some attacker operating a Man In The Middle (MITM)
+operation. The latter can terminate the TLS connection you make, and make
+another one to the server (so both you and the server still think you have an
+encrypted connection) and, if one of the "well known" set of Certificate
+Authorities has been suborned - something which *has* been seen already (2014),
+a verifiable certificate (if you're using normal root CAs, eg. the Mozilla set,
+as your trust anchors).
+
+What DANE does is replace the CAs with the DNS as the trust anchor. The
+assurance is limited to a) the possibility that the DNS has been suborned, b)
+mistakes made by the admins of the target server. The attack surface presented
+by (a) is thought to be smaller than that of the set of root CAs.
+
+It also allows the server to declare (implicitly) that connections to it should
+use TLS. An MITM could simply fail to pass on a server's STARTTLS.
+
+DANE scales better than having to maintain (and side-channel communicate)
+copies of server certificates for every possible target server. It also scales
+(slightly) better than having to maintain on an SMTP client a copy of the
+standard CAs bundle. It also means not having to pay a CA for certificates.
+
+DANE requires a server operator to do three things: 1) run DNSSEC. This
+provides assurance to clients that DNS lookups they do for the server have not
+been tampered with. The domain MX record applying to this server, its A record,
+its TLSA record and any associated CNAME records must all be covered by DNSSEC.
+2) add TLSA DNS records. These say what the server certificate for a TLS
+connection should be. 3) offer a server certificate, or certificate chain, in
+TLS connections which is is anchored by one of the TLSA records.
+
+There are no changes to Exim specific to server-side operation of DANE. Support
+for client-side operation of DANE can be included at compile time by defining
+SUPPORT_DANE=yes in Local/Makefile. If it has been included, the macro
+"_HAVE_DANE" will be defined.
+
+The TLSA record for the server may have "certificate usage" of DANE-TA(2) or
+DANE-EE(3). These are the "Trust Anchor" and "End Entity" variants. The latter
+specifies the End Entity directly, i.e. the certificate involved is that of the
+server (and if only DANE-EE is used then it should be the sole one transmitted
+during the TLS handshake); this is appropriate for a single system, using a
+self-signed certificate. DANE-TA usage is effectively declaring a specific CA
+to be used; this might be a private CA or a public, well-known one. A private
+CA at simplest is just a self-signed certificate (with certain attributes)
+which is used to sign server certificates, but running one securely does
+require careful arrangement. With DANE-TA, as implemented in Exim and commonly
+in other MTAs, the server TLS handshake must transmit the entire certificate
+chain from CA to server-certificate. DANE-TA is commonly used for several
+services and/or servers, each having a TLSA query-domain CNAME record, all of
+which point to a single TLSA record. DANE-TA and DANE-EE can both be used
+together.
+
+Our recommendation is to use DANE with a certificate from a public CA, because
+this enables a variety of strategies for remote clients to verify your
+certificate. You can then publish information both via DANE and another
+technology, "MTA-STS", described below.
+
+When you use DANE-TA to publish trust anchor information, you ask entities
+outside your administrative control to trust the Certificate Authority for
+connections to you. If using a private CA then you should expect others to
+still apply the technical criteria they'd use for a public CA to your
+certificates. In particular, you should probably try to follow current best
+practices for CA operation around hash algorithms and key sizes. Do not expect
+other organizations to lower their security expectations just because a
+particular profile might be reasonable for your own internal use.
+
+When this text was last updated, this in practice means to avoid use of SHA-1
+and MD5; if using RSA to use key sizes of at least 2048 bits (and no larger
+than 4096, for interoperability); to use keyUsage fields correctly; to use
+random serial numbers. The list of requirements is subject to change as best
+practices evolve. If you're not already using a private CA, or it doesn't meet
+these requirements, then we encourage you to avoid all these issues and use a
+public CA such as Let's Encrypt instead.
+
+The TLSA record should have a Selector field of SPKI(1) and a Matching Type
+field of SHA2-512(2).
+
+At the time of writing, https://www.huque.com/bin/gen_tlsa is useful for
+quickly generating TLSA records; and commands like
+
+ openssl x509 -in -pubkey -noout <certificate.pem \
+ | openssl rsa -outform der -pubin 2>/dev/null \
+ | openssl sha512 \
+ | awk '{print $2}'
+
+are workable for 4th-field hashes.
+
+For use with the DANE-TA model, server certificates must have a correct name
+(SubjectName or SubjectAltName).
+
+The Certificate issued by the CA published in the DANE-TA model should be
+issued using a strong hash algorithm. Exim, and importantly various other MTAs
+sending to you, will not re-enable hash algorithms which have been disabled by
+default in TLS libraries. This means no MD5 and no SHA-1. SHA2-256 is the
+minimum for reliable interoperability (and probably the maximum too, in 2018).
+
+The use of OCSP-stapling should be considered, allowing for fast revocation of
+certificates (which would otherwise be limited by the DNS TTL on the TLSA
+records). However, this is likely to only be usable with DANE-TA. NOTE: the
+default of requesting OCSP for all hosts is modified iff DANE is in use, to:
+
+ hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \
+ {= {4}{$tls_out_tlsa_usage}} } \
+ {*}{}}
+
+The (new) variable $tls_out_tlsa_usage is a bitfield with numbered bits set for
+TLSA record usage codes. The zero above means DANE was not in use, the four
+means that only DANE-TA usage TLSA records were found. If the definition of
+hosts_request_ocsp includes the string "tls_out_tlsa_usage", they are
+re-expanded in time to control the OCSP request.
+
+This modification of hosts_request_ocsp is only done if it has the default
+value of "*". Admins who change it, and those who use hosts_require_ocsp,
+should consider the interaction with DANE in their OCSP settings.
+
+For client-side DANE there are three new smtp transport options, hosts_try_dane
+, hosts_require_dane and dane_require_tls_ciphers. The require variant will
+result in failure if the target host is not DNSSEC-secured.
+
+DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA
+records.
+
+A TLSA lookup will be done if either of the above options match and the
+host-lookup succeeded using dnssec. If a TLSA lookup is done and succeeds, a
+DANE-verified TLS connection will be required for the host. If it does not, the
+host will not be used; there is no fallback to non-DANE or non-TLS.
+
+If DANE is requested and usable, then the TLS cipher list configuration prefers
+to use the option dane_require_tls_ciphers and falls back to
+tls_require_ciphers only if that is unset. This lets you configure "decent
+crypto" for DANE and "better than nothing crypto" as the default. Note though
+that while GnuTLS lets the string control which versions of TLS/SSL will be
+negotiated, OpenSSL does not and you're limited to ciphersuite constraints.
+
+If DANE is requested and useable (see above) the following transport options
+are ignored:
+
+ hosts_require_tls
+ tls_verify_hosts
+ tls_try_verify_hosts
+ tls_verify_certificates
+ tls_crl
+ tls_verify_cert_hostnames
+
+If DANE is not usable, whether requested or not, and CA-anchored verification
+evaluation is wanted, the above variables should be set appropriately.
+
+Currently the dnssec_request_domains must be active and dnssec_require_domains
+is ignored.
+
+If verification was successful using DANE then the "CV" item in the delivery
+log line will show as "CV=dane".
+
+There is a new variable $tls_out_dane which will have "yes" if verification
+succeeded using DANE and "no" otherwise (only useful in combination with
+events; see 60), and a new variable $tls_out_tlsa_usage (detailed above).
+
+An event (see 60) of type "dane:fail" will be raised on failures to achieve
+DANE-verified connection, if one was either requested and offered, or required.
+This is intended to support TLS-reporting as defined in https://tools.ietf.org/
+html/draft-ietf-uta-smtp-tlsrpt-17. The $event_data will be one of the Result
+Types defined in Section 4.3 of that document.
+
+Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
+
+DANE is specified in published RFCs and decouples certificate authority trust
+selection from a "race to the bottom" of "you must trust everything for mail to
+get through". There is an alternative technology called MTA-STS, which instead
+publishes MX trust anchor information on an HTTPS website. At the time this
+text was last updated, MTA-STS was still a draft, not yet an RFC. Exim has no
+support for MTA-STS as a client, but Exim mail server operators can choose to
+publish information describing their TLS configuration using MTA-STS to let
+those clients who do use that protocol derive trust information.
+
+The MTA-STS design requires a certificate from a public Certificate Authority
+which is recognized by clients sending to you. That selection of which CAs are
+trusted by others is outside your control.
+
+The most interoperable course of action is probably to use Let's Encrypt, with
+automated certificate renewal; to publish the anchor information in
+DNSSEC-secured DNS via TLSA records for DANE clients (such as Exim and Postfix)
+and to publish anchor information for MTA-STS as well. This is what is done for
+the exim.org domain itself (with caveats around occasionally broken MTA-STS
+because of incompatible specification changes prior to reaching RFC status).
===============================================================================
-42. ACCESS CONTROL LISTS
+43. ACCESS CONTROL LISTS
-Access Control Lists (ACLs) are defined in a separate section of the run time
+Access Control Lists (ACLs) are defined in a separate section of the runtime
configuration file, headed by "begin acl". Each ACL definition starts with a
name, terminated by a colon. Here is a complete ACL section that contains just
one very small ACL:
a realistic ACL for checking RCPT commands. This is discussed in chapter 7.
-42.1 Testing ACLs
+43.1 Testing ACLs
-----------------
The -bh command line option provides a way of testing your ACL configuration
-locally by running a fake SMTP session with which you interact. The host
-relay-test.mail-abuse.org provides a service for checking your relaying
-configuration (see section 42.53 for more details).
+locally by running a fake SMTP session with which you interact.
-42.2 Specifying when ACLs are used
+43.2 Specifying when ACLs are used
----------------------------------
In order to cause an ACL to be used, you have to name it in one of the relevant
acl_smtp_connect ACL for start of SMTP connection
acl_smtp_data ACL after DATA is complete
acl_smtp_data_prdr ACL for each recipient, after DATA is complete
+ acl_smtp_dkim ACL for each DKIM signer
acl_smtp_etrn ACL for ETRN
acl_smtp_expn ACL for EXPN
acl_smtp_helo ACL for HELO or EHLO
possible at RCPT time.
-42.3 The non-SMTP ACLs
+43.3 The non-SMTP ACLs
----------------------
The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
run, it is too late.
The acl_not_smtp_mime ACL is available only when Exim is compiled with the
-content-scanning extension. For details, see chapter 43.
+content-scanning extension. For details, see chapter 44.
The acl_not_smtp ACL is run just before the local_scan() function. Any kind of
rejection is treated as permanent, because there is no way of sending a
temporary error for these kinds of message.
-42.4 The SMTP connect ACL
+43.4 The SMTP connect ACL
-------------------------
The ACL test specified by acl_smtp_connect happens at the start of an SMTP
smtp_banner option.
-42.5 The EHLO/HELO ACL
+43.5 The EHLO/HELO ACL
----------------------
The ACL test specified by acl_smtp_helo happens when the client issues an EHLO
indeed is required to issue a new EHLO or HELO after successfully setting up
encryption following a STARTTLS command.
+Note also that a deny neither forces the client to go away nor means that mail
+will be refused on the connection. Consider checking for $sender_helo_name
+being defined in a MAIL or RCPT ACL to do that.
+
If the command is accepted by an accept verb that has a message modifier, the
message may not contain more than one line (it will be truncated at the first
newline and a panic logged if it does). Such a message cannot affect the EHLO
options that are listed on the second and subsequent lines of an EHLO response.
-42.6 The DATA ACLs
+43.6 The DATA ACLs
------------------
Two ACLs are associated with the DATA command, because it is two-stage command,
ACL specified by acl_smtp_data, which is the second ACL that is associated with
the DATA command.
+If CHUNKING was advertised and a BDAT command sequence is received, the
+acl_smtp_predata ACL is not run. The acl_smtp_data is run after the last BDAT
+command and all of the data specified is received.
+
For both of these ACLs, it is not possible to reject individual recipients. An
error response rejects the entire message. Unfortunately, it is known that some
MTAs do not treat hard (5xx) responses to the DATA command (either before or
and the acl_smtp_mime ACLs.
-42.7 The SMTP DKIM ACL
+43.7 The SMTP DKIM ACL
----------------------
The acl_smtp_dkim ACL is available only when Exim is compiled with DKIM support
This ACL is evaluated before acl_smtp_mime and acl_smtp_data.
-For details on the operation of DKIM, see chapter 56.
+For details on the operation of DKIM, see section 57.1.
-42.8 The SMTP MIME ACL
+43.8 The SMTP MIME ACL
----------------------
The acl_smtp_mime option is available only when Exim is compiled with the
-content-scanning extension. For details, see chapter 43.
+content-scanning extension. For details, see chapter 44.
This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data.
-42.9 The SMTP PRDR ACL
+43.9 The SMTP PRDR ACL
----------------------
The acl_smtp_data_prdr ACL is available only when Exim is compiled with PRDR
feature is negotiated between client and server for a message, and more than
one recipient has been accepted.
-The ACL test specfied by acl_smtp_data_prdr happens after a message has been
-recieved, and is executed for each recipient of the message. The test may
-accept or deny for inividual recipients. The acl_smtp_data will still be called
-after this ACL and can reject the message overall, even if this ACL has
-accepted it for some or all recipients.
+The ACL test specified by acl_smtp_data_prdr happens after a message has been
+received, and is executed once for each recipient of the message with
+$local_part and $domain valid. The test may accept, defer or deny for
+individual recipients. The acl_smtp_data will still be called after this ACL
+and can reject the message overall, even if this ACL has accepted it for some
+or all recipients.
PRDR may be used to support per-user content filtering. Without it one must
defer any recipient after the first that has a different content-filter
configuration. With PRDR, the RCPT-time check for this can be disabled when the
-MAIL-time $smtp_command included "PRDR". Any required difference in behaviour
-of the main DATA-time ACL should however depend on the PRDR-time ACL having
-run, as Exim will avoid doing so in some situations (eg. single-recipient
-mails).
+variable $prdr_requested is "yes". Any required difference in behaviour of the
+main DATA-time ACL should however depend on the PRDR-time ACL having run, as
+Exim will avoid doing so in some situations (e.g. single-recipient mails).
See also the prdr_enable global option and the hosts_try_prdr smtp transport
option.
client.
-42.10 The QUIT ACL
+43.10 The QUIT ACL
------------------
The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL
does not affect the response code to QUIT, which is always 221. Thus, the ACL
-does not in fact control any access. For this reason, the only verbs that are
-permitted are accept and warn.
+does not in fact control any access. For this reason, it may only accept or
+warn as its final result.
This ACL can be used for tasks such as custom logging at the end of an SMTP
session. For example, you can use ACL variables in other ACLs to count
connection is closed. In these special cases, the QUIT ACL does not run.
-42.11 The not-QUIT ACL
+43.11 The not-QUIT ACL
----------------------
The not-QUIT ACL, specified by acl_smtp_notquit, is run in most cases when an
verb in another ACL, it is the message from the other ACL that is used.
-42.12 Finding an ACL to use
+43.12 Finding an ACL to use
---------------------------
The value of an acl_smtp_xxx option is expanded before use, so you can use
{acl_check_rcpt} {acl_check_rcpt_submit} }
In the default configuration file there are some example settings for providing
-an RFC 4409 message submission service on port 587 and a non-standard "smtps"
-service on port 465. You can use a string expansion like this to choose an ACL
-for MUAs on these ports which is more appropriate for this purpose than the
-default ACL on port 25.
+an RFC 4409 message "submission" service on port 587 and an RFC 8314
+"submissions" service on port 465. You can use a string expansion like this to
+choose an ACL for MUAs on these ports which is more appropriate for this
+purpose than the default ACL on port 25.
The expanded string does not have to be the name of an ACL in the configuration
file; there are other possibilities. Having expanded the string, Exim searches
for an ACL as follows:
- * If the string begins with a slash, Exim uses it as a file name, and reads
+ * If the string begins with a slash, Exim uses it as a filename, and reads
its contents as an ACL. The lines are processed in the same way as lines in
the Exim configuration file. In particular, continuation lines are
supported, blank lines are ignored, as are lines whose first non-whitespace
file.
-42.13 ACL return codes
+43.13 ACL return codes
----------------------
Except for the QUIT ACL, which does not affect the SMTP return code (see
-section 42.10 above), the result of running an ACL is either "accept" or
+section 43.10 above), the result of running an ACL is either "accept" or
"deny", or, if some test cannot be completed (for example, if a database is
down), "defer". These results cause 2xx, 5xx, and 4xx return codes,
respectively, to be used in the SMTP dialogue. A fourth return, "error", occurs
from the DATA or the non-SMTP ACL discards all the remaining recipients. The
"discard" return is not permitted for the acl_smtp_predata ACL.
+If the ACL for VRFY returns "accept", a recipient verify (without callout) is
+done on the address and the result determines the SMTP response.
+
The local_scan() function is always run, even if there are no remaining
recipients; it may create new recipients.
-42.14 Unset ACL options
+43.14 Unset ACL options
-----------------------
The default actions when any of the acl_xxx options are unset are not all the
connection. For an example, see the ACL in the default configuration file.
-42.15 Data for message ACLs
+43.15 Data for message ACLs
---------------------------
When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables
contains the total number of accepted recipients.
-42.16 Data for non-message ACLs
+43.16 Data for non-message ACLs
-------------------------------
When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY,
option to do this.)
-42.17 Format of an ACL
+43.17 Format of an ACL
----------------------
An individual ACL consists of a number of statements. Each statement starts
example:
deny dnslists = list1.example
-dnslists = list2.example
+ dnslists = list2.example
If there are no conditions, the verb is always obeyed. Exim stops evaluating
the conditions and modifiers when it reaches a condition that fails. What
test a sender address in the ACL that is run for a VRFY command.
-42.18 ACL verbs
+43.18 ACL verbs
---------------
The ACL verbs are as follows:
RCPT command:
accept domains = +local_domains
- endpass
- verify = recipient
+ endpass
+ verify = recipient
If the recipient domain does not match the domains condition, control
passes to the next statement. If it does match, the recipient is verified,
passes control to subsequent statements only if the message's sender can be
verified. Otherwise, it rejects the command. Note the positioning of the
message modifier, before the verify condition. The reason for this is
- discussed in section 42.20.
+ discussed in section 43.20.
* warn: If all the conditions are true, a line specified by the log_message
modifier is written to Exim's main log. Control always passes to the next
If log_message is not present, a warn verb just checks its conditions and
obeys any "immediate" modifiers (such as control, set, logwrite, add_header
, and remove_header) that appear before the first failing condition. There
- is more about adding header lines in section 42.24.
+ is more about adding header lines in section 43.24.
If any condition on a warn statement cannot be completed (that is, there is
some sort of defer), the log line specified by log_message is not written.
mechanism. It is conventional to align the conditions vertically.
-42.19 ACL variables
+43.19 ACL variables
-------------------
There are some special variables that can be set during ACL processing. They
their names are compatible, so there is no problem with upgrading.
-42.20 Condition and modifier processing
+43.20 Condition and modifier processing
---------------------------------------
An exclamation mark preceding a condition negates its result. For example:
which time Exim has set up the message.
-42.21 ACL modifiers
+43.21 ACL modifiers
-------------------
The ACL modifiers are as follows:
This modifier specifies one or more header lines that are to be added to an
incoming message, assuming, of course, that the message is ultimately
- accepted. For details, see section 42.24.
+ accepted. For details, see section 43.24.
continue = <text>
individual recipients, even if the control modifier appears in a RCPT ACL.
As there are now quite a few controls that can be applied, they are
- described separately in section 42.22. The control modifier can be used in
+ described separately in section 43.22. The control modifier can be used in
several different ways. For example:
- * It can be at the end of an accept statement:
+ + It can be at the end of an accept statement:
accept ...some conditions
control = queue_only
In this case, the control is applied when this statement yields
"accept", in other words, when the conditions are all true.
- * It can be in the middle of an accept statement:
+ + It can be in the middle of an accept statement:
accept ...some conditions...
control = queue_only
conditions is false. In this case, some subsequent statement must yield
"accept" for the control to be relevant.
- * It can be used with warn to apply the control, leaving the decision
+ + It can be used with warn to apply the control, leaving the decision
about accepting or denying to a subsequent verb. For example:
warn ...some conditions...
, so it does not add anything to the message and does not write a log
entry.
- * If you want to apply a control unconditionally, you can use it with a
+ + If you want to apply a control unconditionally, you can use it with a
require verb. For example:
require control = no_multiline_responses
processed anyway. If the message contains newlines, this gives rise to a
multi-line SMTP response.
+ For ACLs that are called by an acl = ACL condition, the message is stored
+ in $acl_verify_message, from which the calling ACL may use it.
+
If message is used on a statement that verifies an address, the message
specified overrides any message that is generated by the verification
process. However, the original message is available in the variable
add_header acts as soon as it is encountered. If message is used with warn
in an ACL that is not concerned with receiving a message, it has no effect.
+queue = <text>
+
+ This modifier specifies the use of a named queue for spool files for the
+ message. It can only be used before the message is received (i.e. not in
+ the DATA ACL). This could be used, for example, for known high-volume burst
+ sources of traffic, or for quarantine of messages. Separate queue-runner
+ processes will be needed for named queues. If the text after expansion is
+ empty, the default queue is used.
+
remove_header = <text>
This modifier specifies one or more header names in a colon-separated list
that are to be removed from an incoming message, assuming, of course, that
- the message is ultimately accepted. For details, see section 42.25.
+ the message is ultimately accepted. For details, see section 43.25.
set <acl_name> = <value>
- This modifier puts a value into one of the ACL variables (see section 42.19
+ This modifier puts a value into one of the ACL variables (see section 43.19
).
udpsend = <parameters>
$tod_zulu $sender_host_address
-42.22 Use of the control modifier
+43.22 Use of the control modifier
---------------------------------
The control modifier supports the following settings:
Notice that we put back the lower cased version afterwards, assuming that
is what is wanted for subsequent tests.
-control = cutthrough_delivery
+control = cutthrough_delivery/<options>
This option requests delivery be attempted while the item is being
- received. It is usable in the RCPT ACL and valid only for single-recipient
- mails forwarded from one SMTP connection to another. If a recipient-verify
- callout connection is requested in the same ACL it is held open and used
- for the data, otherwise one is made after the ACL completes.
+ received.
+
+ The option is usable in the RCPT ACL. If enabled for a message received via
+ smtp and routed to an smtp transport, and only one transport, interface,
+ destination host and port combination is used for all recipients of the
+ message, then the delivery connection is made while the receiving
+ connection is open and data is copied from one to the other.
+
+ An attempt to set this option for any recipient but the first for a mail
+ will be quietly ignored. If a recipient-verify callout (with use_sender)
+ connection is subsequently requested in the same ACL it is held open and
+ used for any subsequent recipients and the data, otherwise one is made
+ after the initial RCPT ACL completes.
Note that routers are used in verify mode, and cannot depend on content of
received headers. Note also that headers cannot be modified by any of the
post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers
- (subject to the above) and transports.
+ (subject to the above) and transports. The Received-By: header is generated
+ as soon as the body reception starts, rather than the traditional time
+ after the full message is received; this will affect the timestamp.
+
+ All the usual ACLs are called; if one results in the message being
+ rejected, all effort spent in delivery (including the costs on the ultimate
+ destination) will be wasted. Note that in the case of data-time ACLs this
+ includes the entire message body.
Cutthrough delivery is not supported via transport-filters or when DKIM
signing of outgoing messages is done, because it sends data to the ultimate
- destination before the entire message has been received from the source.
+ destination before the entire message has been received from the source. It
+ is not supported for messages received with the SMTP PRDR or CHUNKING
+ options in use.
Should the ultimate destination system positively accept or reject the
mail, a corresponding indication is given to the source system and nothing
- is queued. If there is a temporary error the item is queued for later
- delivery in the usual fashion. If the item is successfully delivered in
- cutthrough mode the log line is tagged with ">>" rather than "=>" and
- appears before the acceptance "<=" line.
+ is queued. If the item is successfully delivered in cutthrough mode the
+ delivery log lines are tagged with ">>" rather than "=>" and appear before
+ the acceptance "<=" line.
+
+ If there is a temporary error the item is queued for later delivery in the
+ usual fashion. This behaviour can be adjusted by appending the option defer
+ =<value> to the control; the default value is "spool" and the alternate
+ value "pass" copies an SMTP defer response from the target back to the
+ initiator and does not queue the message. Note that this is independent of
+ any recipient verify conditions in the ACL.
Delivery in this mode avoids the generation of a bounce mail to a (possibly
faked) sender when the destination system is doing content-scan based
control = debug/<options>
This control turns on debug logging, almost as though Exim had been invoked
- with "-d", with the output going to a new logfile, by default called
- debuglog. The filename can be adjusted with the tag option, which may
- access any variables already defined. The logging may be adjusted with the
- opts option, which takes the same values as the "-d" command-line option.
- Some examples (which depend on variables that don't exist in all contexts):
+ with "-d", with the output going to a new logfile in the usual logs
+ directory, by default called debuglog. The filename can be adjusted with
+ the tag option, which may access any variables already defined. The logging
+ may be adjusted with the opts option, which takes the same values as the
+ "-d" command-line option. Logging started this way may be stopped, and the
+ file removed, with the kill option. Some examples (which depend on
+ variables that don't exist in all contexts):
control = debug
control = debug/tag=.$sender_host_address
control = debug/opts=+expand+acl
control = debug/tag=.$message_exim_id/opts=+expand
+ control = debug/kill
control = dkim_disable_verify
This control turns off DKIM verification processing entirely. For details
- on the operation and configuration of DKIM, see chapter 56.
+ on the operation and configuration of DKIM, see section 57.1.
control = dscp/<value>
after all only a sop to broken clients, is implemented by doing two very
easy things:
- * Extra information that is normally output as part of a rejection caused
+ + Extra information that is normally output as part of a rejection caused
by sender verification failure is omitted. Only the final line
(typically "sender verification failed") is sent.
- * If a message modifier supplies a multiline response, only the first
+ + If a message modifier supplies a multiline response, only the first
line is output.
The setting of the switch can, of course, be made conditional on the
not present. This control is not permitted in the acl_smtp_data ACL,
because that is too late (the message has already been created).
- Chapter 46 describes the processing that Exim applies to messages. Section
- 46.1 covers the processing that happens in submission mode; the available
+ Chapter 47 describes the processing that Exim applies to messages. Section
+ 47.1 covers the processing that happens in submission mode; the available
options for this control are described there. The control applies only to
the current message, not to any subsequent ones that may be received in the
same SMTP connection.
complement of "control = submission". It disables the fixups that are
normally applied to locally-submitted messages. Specifically:
- * Any Sender: header line is left alone (in this respect, it is a dynamic
+ + Any Sender: header line is left alone (in this respect, it is a dynamic
version of local_sender_retain).
- * No Message-ID:, From:, or Date: header lines are added.
+ + No Message-ID:, From:, or Date: header lines are added.
- * There is no check that From: corresponds to the actual sender.
+ + There is no check that From: corresponds to the actual sender.
This control may be useful when a remotely-originated message is accepted,
passed to some scanning program, and then re-submitted for delivery. It can
Note: This control applies only to the current message, not to any others
that are being submitted at the same time using -bs or -bS.
+control = utf8_downconvert
+
+ This control enables conversion of UTF-8 in message addresses to a-label
+ form. For details see section 59.1.
+
-42.23 Summary of message fixup control
+43.23 Summary of message fixup control
--------------------------------------
All four possibilities for message fixups can be specified:
* Remotely submitted, fixups applied: use "control = submission".
-42.24 Adding header lines in ACLs
+43.24 Adding header lines in ACLs
---------------------------------
The add_header modifier can be used to add one or more extra header lines to an
including deny (though this is potentially useful only in a RCPT ACL).
Headers will not be added to the message if the modifier is used in DATA, MIME
-or DKIM ACLs for messages delivered by cutthrough routing.
+or DKIM ACLs for a message delivered by cutthrough routing.
Leading and trailing newlines are removed from the data for the add_header
modifier; if it then contains one or more newlines that are not followed by a
run. Similarly, header lines that are added by the DATA or MIME ACLs are not
visible in those ACLs. Because of this restriction, you cannot use header lines
as a way of passing data between (for example) the MAIL and RCPT ACLs. If you
-want to do this, you can use ACL variables, as described in section 42.19.
+want to do this, you can use ACL variables, as described in section 43.19.
The list of headers yet to be added is given by the $headers_added variable.
in a router or transport.
-42.25 Removing header lines in ACLs
+43.25 Removing header lines in ACLs
-----------------------------------
The remove_header modifier can be used to remove one or more header lines from
including deny, though this is really not useful for any verb that doesn't
result in a delivered message.
-Headers will not be removed to the message if the modifier is used in DATA,
-MIME or DKIM ACLs for messages delivered by cutthrough routing.
+Headers will not be removed from the message if the modifier is used in DATA,
+MIME or DKIM ACLs for a message delivered by cutthrough routing.
More than one header can be removed at the same time by using a colon separated
list of header names. The header matching is case insensitive. Wildcards are
warn message = Remove internal headers
remove_header = $acl_c_ihdrs
-Removed header lines are accumulated during the MAIL, RCPT, and predata ACLs.
-They are removed from the message before processing the DATA and MIME ACLs.
-There is no harm in attempting to remove the same header twice nor is removing
-a non-existent header. Further header lines to be removed may be accumulated
+Header names for removal are accumulated during the MAIL, RCPT, and predata
+ACLs. Matching header lines are removed from the message before processing the
+DATA and MIME ACLs. If multiple header lines match, all are removed. There is
+no harm in attempting to remove the same header twice nor in removing a
+non-existent header. Further header lines to be removed may be accumulated
during the DATA and MIME ACLs, after which they are removed from the message,
if present. In the case of non-SMTP messages, headers to be removed are
accumulated during the non-SMTP ACLs, and are removed from the message after
removed by the DATA or MIME ACLs are still visible in those ACLs. Because of
this restriction, you cannot use header lines as a way of controlling data
passed between (for example) the MAIL and RCPT ACLs. If you want to do this,
-you should instead use ACL variables, as described in section 42.19.
+you should instead use ACL variables, as described in section 43.19.
The remove_header modifier acts immediately as it is encountered during the
processing of an ACL. Notice the difference between these two cases:
system filter or in a router or transport.
-42.26 ACL conditions
+43.26 ACL conditions
--------------------
Some of the conditions listed in this section are available only when Exim is
compiled with the content-scanning extension. They are included here briefly
for completeness. More detailed descriptions can be found in the discussion on
-content scanning in chapter 43.
+content scanning in chapter 44.
Not all conditions are relevant in all circumstances. For example, testing
senders and recipients does not make sense in an ACL that is being run as the
can be appended; they appear within the called ACL in $acl_arg1 to
$acl_arg9, and $acl_narg is set to the count of values. Previous values of
these variables are restored after the call returns. The name and values
- are expanded separately.
+ are expanded separately. Note that spaces in complex expansions which are
+ used as arguments will act as argument separators.
If the nested acl returns "drop" and the outer condition denies access, the
connection is dropped. If it returns "discard", the verb must be accept or
acl_smtp_mime. It causes the current MIME part to be decoded into a file.
If all goes well, the condition is true. It is false only if there are
problems such as a syntax error or a memory shortage. For more details, see
- chapter 43.
-
-demime = <extension list>
-
- This condition is available only when Exim is compiled with the
- content-scanning extension. Its use is described in section 43.6.
+ chapter 44.
dnslists = <list of domain names and other data>
as "RBL lists", after the original Realtime Blackhole List, but note that
the use of the lists at mail-abuse.org now carries a charge. There are too
many different variants of this condition to describe briefly here. See
- sections 42.27-42.37 for details.
+ sections 43.27-43.37 for details.
domains = <domain list>
This condition is available only when Exim is compiled with the
content-scanning extension. It causes the incoming message to be scanned
- for viruses. For details, see chapter 43.
+ for viruses. For details, see chapter 44.
mime_regex = <list of regular expressions>
This condition is available only when Exim is compiled with the
content-scanning extension, and it is allowed only in the ACL defined by
acl_smtp_mime. It causes the current MIME part to be scanned for a match
- with any of the regular expressions. For details, see chapter 43.
+ with any of the regular expressions. For details, see chapter 44.
ratelimit = <parameters>
This condition can be used to limit the rate at which a user or host
- submits messages. Details are given in section 42.38.
+ submits messages. Details are given in section 43.38.
recipients = <address list>
This condition is available only when Exim is compiled with the
content-scanning extension, and is available only in the DATA, MIME, and
non-SMTP ACLs. It causes the incoming message to be scanned for a match
- with any of the regular expressions. For details, see chapter 43.
+ with any of the regular expressions. For details, see chapter 44.
sender_domains = <domain list>
This condition is available only when Exim is compiled with the
content-scanning extension. It causes the incoming message to be scanned by
- SpamAssassin. For details, see chapter 43.
+ SpamAssassin. For details, see chapter 44.
verify = certificate
This condition is true in an SMTP session if the session is encrypted, and
a certificate was received from the client, and the certificate was
verified. The server requests a certificate only if the client matches
- tls_verify_hosts or tls_try_verify_hosts (see chapter 41).
+ tls_verify_hosts or tls_try_verify_hosts (see chapter 42).
verify = csa
This condition checks whether the sending host (the client) is authorized
- to send email. Details of how this works are given in section 42.50.
+ to send email. Details of how this works are given in section 43.50.
verify = header_names_ascii
command.
Details of address verification and the options are given later, starting
- at section 42.44 (callouts are described in section 42.45). You can combine
+ at section 43.44 (callouts are described in section 43.45). You can combine
this condition with the senders condition to restrict it to bounce messages
only:
This condition is relevant only in an ACL that is run after a message has
been received, that is, in an ACL specified by acl_smtp_data or
acl_not_smtp. It checks the syntax of all header lines that can contain
- lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:).
- Unqualified addresses (local parts without domains) are permitted only in
- locally generated messages and from hosts that match
- sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.
+ lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:),
+ returning true if there are no problems. Unqualified addresses (local parts
+ without domains) are permitted only in locally generated messages and from
+ hosts that match sender_unqualified_hosts or recipient_unqualified_hosts,
+ as appropriate.
Note that this condition is a syntax check only. However, a common spamming
ploy used to be to send syntactically invalid headers such as
This condition is relevant only after a RCPT command. It verifies the
current recipient. Details of address verification are given later,
- starting at section 42.44. After a recipient has been verified, the value
+ starting at section 43.44. After a recipient has been verified, the value
of $address_data is the last value that was set while routing the address.
This applies even if the verification fails. When an address that is being
verified is redirected to a single address, verification continues with the
new address, and in that case, the subsequent value of $address_data is the
value for the child address.
-verify = reverse_host_lookup
+verify = reverse_host_lookup/<options>
This condition ensures that a verified host name has been looked up from
the IP address of the client host. (This may have happened already if the
reverse DNS lookup, or one of its aliases, does, when it is itself looked
up in the DNS, yield the original IP address.
+ There is one possible option, "defer_ok". If this is present and a DNS
+ operation returns a temporary error, the verify condition succeeds.
+
If this condition is used for a locally generated message (that is, when
there is no client host involved), it always succeeds.
you want to preserve the value for longer, you can save it in an ACL
variable.
- Details of verification are given later, starting at section 42.44. Exim
+ Details of verification are given later, starting at section 43.44. Exim
caches the result of sender verification, to avoid doing it more than once
per message.
This is a variation of the previous option, in which a modified address is
verified as a sender.
+ Note that '/' is legal in local-parts; if the address may have such (eg. is
+ generated from the received message) they must be protected from the
+ options parsing by doubling:
+
+ verify = sender=${sg{${address:$h_sender:}}{/}{//}}
+
-42.27 Using DNS lists
+43.27 Using DNS lists
---------------------
In its simplest form, the dnslists condition tests whether the calling host is
warn message = X-Warn: sending host is on dialups list
dnslists = dialups.mail-abuse.org
-DNS list lookups are cached by Exim for the duration of the SMTP session, so a
-lookup based on the IP address is done at most once for any incoming
-connection. Exim does not share information between multiple incoming
-connections (but your local name server cache should be active).
+DNS list lookups are cached by Exim for the duration of the SMTP session (but
+limited by the DNS return TTL value), so a lookup based on the IP address is
+done at most once for any incoming connection (assuming long-enough TTL). Exim
+does not share information between multiple incoming connections (but your
+local name server cache should be active).
+There are a number of DNS lists to choose from, some commercial, some free, or
+free for small deployments. An overview can be found at https://
+en.wikipedia.org/wiki/Comparison_of_DNS_blacklists.
-42.28 Specifying the IP address for a DNS list lookup
+
+43.28 Specifying the IP address for a DNS list lookup
-----------------------------------------------------
By default, the IP address that is used in a DNS list lookup is the IP address
This feature is not very helpful with explicit IP addresses; it is intended for
use with IP addresses that are looked up, for example, the IP addresses of the
MX hosts or nameservers of an email sender address. For an example, see section
-42.30 below.
+43.30 below.
-42.29 DNS lists keyed on domain names
+43.29 DNS lists keyed on domain names
-------------------------------------
There are some lists that are keyed on domain names rather than inverted IP
-addresses (see for example the domain based zones link at http://
+addresses (see, e.g., the domain based zones link at http://
www.rfc-ignorant.org/). No reversing of components is used with these lists.
You can change the name that is looked up in a DNS list by listing it after the
domain name, introduced by a slash. For example,
name. The whole condition is true if either of the DNS lookups succeeds.
-42.30 Multiple explicit keys for a DNS list
+43.30 Multiple explicit keys for a DNS list
-------------------------------------------
The syntax described above for looking up explicitly-defined values (either
a.domain.black.list.tld
Once a DNS record has been found (that matches a specific IP return address, if
-specified - see section 42.33), no further lookups are done. If there is a
+specified - see section 43.33), no further lookups are done. If there is a
temporary DNS error, the rest of the sublist of domains or IP addresses is
tried. A temporary error for the whole dnslists item occurs only if no other
DNS lookup in this sublist succeeds. In other words, a successful lookup for
dnsdb lookup finds the IP addresses for these hosts. The result of expanding
the condition might be something like this:
-dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|...
+dnslists = sbl.spamhaus.org/<|192.168.2.3|192.168.5.6|...
Thus, this example checks whether or not the IP addresses of the sender
domain's mail servers are on the Spamhaus black list.
The key that was used for a successful DNS list lookup is put into the variable
-$dnslist_matched (see section 42.32).
+$dnslist_matched (see section 43.32).
-42.31 Data returned by DNS lists
+43.31 Data returned by DNS lists
--------------------------------
DNS lists are constructed using address records in the DNS. The original RBL
127.1.0.6 RSS and DUL
127.1.0.7 RSS and DUL and RBL
-Section 42.33 below describes how you can distinguish between different values.
-Some DNS lists may return more than one address record; see section 42.35 for
+Section 43.33 below describes how you can distinguish between different values.
+Some DNS lists may return more than one address record; see section 43.35 for
details of how they are checked.
-42.32 Variables set from DNS lists
+43.32 Variables set from DNS lists
----------------------------------
When an entry is found in a DNS list, the variable $dnslist_domain contains the
the key is also available in another variable (in this case,
$sender_host_address). In more complicated cases, however, this is not true.
-For example, using a data lookup (as described in section 42.30) might generate
+For example, using a data lookup (as described in section 43.30) might generate
a dnslists lookup like this:
deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
addresses are included in $dnslist_value, separated by commas and spaces. The
variable $dnslist_text contains the contents of any associated TXT record. For
lists such as RBL+ the TXT record for a merged entry is often not very
-meaningful. See section 42.36 for a way of obtaining more information.
+meaningful. See section 43.36 for a way of obtaining more information.
You can use the DNS list variables in message or log_message modifiers -
although these appear before the condition in the ACL, they are not expanded
dnslists = rbl-plus.mail-abuse.example
-42.33 Additional matching conditions for DNS lists
+43.33 Additional matching conditions for DNS lists
--------------------------------------------------
You can add an equals sign and an IP address after a dnslists domain name in
rejects only those hosts that yield 127.0.0.2. Without this additional data,
any address record is considered to be a match. For the moment, we assume that
-the DNS lookup returns just one record. Section 42.35 describes how multiple
+the DNS lookup returns just one record. Section 43.35 describes how multiple
records are handled.
More than one IP address may be given for checking, using a comma as a
odd number.
-42.34 Negated DNS matching conditions
+43.34 Negated DNS matching conditions
-------------------------------------
You can supply a negative list of IP addresses as part of a dnslists condition.
which is less clear, and harder to maintain.
-42.35 Handling multiple DNS records from a DNS list
+43.35 Handling multiple DNS records from a DNS list
---------------------------------------------------
A DNS lookup for a dnslists condition may return more than one DNS record,
between "=" and "==" and between "&" and "=&".
-42.36 Detailed information from merged DNS lists
+43.36 Detailed information from merged DNS lists
------------------------------------------------
When the facility for restricting the matching IP values in a DNS list is used,
tested is indeed on the first list. The first domain is the one that is put in
$dnslist_domain. For example:
-reject message = \
+deny message = \
rejected because $sender_host_address is blacklisted \
at $dnslist_domain\n$dnslist_text
dnslists = \
several times, but because the results of the DNS lookups are cached, the DNS
calls themselves are not repeated. For example:
-reject dnslists = \
+deny dnslists = \
http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
done. Only if there is a match is one of the more specific lists consulted.
-42.37 DNS lists and IPv6
+43.37 DNS lists and IPv6
------------------------
If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
dnslists = <; dnsbl.example.com/<|$acl_m_addrslist
-42.38 Rate limiting incoming messages
+43.38 Rate limiting incoming messages
-------------------------------------
The ratelimit ACL condition can be used to measure and control the rate at
"$local_part@$domain" with the per_rcpt option (see below) in a RCPT ACL.
Each ratelimit condition can have up to four options. A per_* option specifies
-what Exim measures the rate of, for example messages or recipients or bytes.
+what Exim measures the rate of, for example, messages or recipients or bytes.
You can adjust the measurement using the unique= and/or count= options. You can
also control when Exim updates the recorded rate using a strict, leaky, or
readonly option. The options are separated by a slash, like the other
lookup key is not affected by changes to the update mode and the count= option.
-42.39 Ratelimit options for what is being measured
+43.39 Ratelimit options for what is being measured
--------------------------------------------------
The per_conn option limits the client's connection rate. It is not normally
accepted. It can be used in the acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime,
acl_smtp_data, or acl_smtp_rcpt ACLs. In acl_smtp_rcpt the rate is updated one
recipient at a time; in the other ACLs the rate is updated with the total
-recipient count in one go. Note that in either case the rate limiting engine
-will see a message with many recipients as a large high-speed burst.
+(accepted) recipient count in one go. Note that in either case the rate
+limiting engine will see a message with many recipients as a large high-speed
+burst.
The per_addr option is like the per_rcpt option, except it counts the number of
different recipients that the client has sent messages to in the last time
rate by one (except for the per_rcpt option in ACLs other than acl_smtp_rcpt).
The count does not have to be an integer.
-The unique= option is described in section 42.42 below.
+The unique= option is described in section 43.42 below.
-42.40 Ratelimit update modes
+43.40 Ratelimit update modes
----------------------------
You can specify one of three options with the ratelimit condition to control
specify the readonly option explicitly.
-42.41 Ratelimit options for handling fast clients
+43.41 Ratelimit options for handling fast clients
-------------------------------------------------
If a client's average rate is greater than the maximum, the rate limiting
The leaky (default) option means that the client's recorded rate is not updated
if it is above the limit. The effect of this is that Exim measures the client's
-average rate of successfully sent email, which cannot be greater than the
-maximum allowed. If the client is over the limit it may suffer some
-counter-measures (as specified in the ACL), but it will still be able to send
-email at the configured maximum rate, whatever the rate of its attempts. This
-is generally the better choice if you have clients that retry automatically.
-For example, it does not prevent a sender with an over-aggressive retry rate
-from getting any email through.
+average rate of successfully sent email,
+
+up to the given limit. This is appropriate if the countermeasure when the
+condition is true consists of refusing the message, and is generally the better
+choice if you have clients that retry automatically. If the action when true is
+anything more complex then this option is likely not what is wanted.
The strict option means that the client's recorded rate is always updated. The
effect of this is that Exim measures the client's average rate of attempts to
ln(peakrate/maxrate)
-42.42 Limiting the rate of different events
+43.42 Limiting the rate of different events
-------------------------------------------
The ratelimit unique= option controls a mechanism for counting the rate of
intended.
-42.43 Using rate limiting
+43.43 Using rate limiting
-------------------------
Exim's other ACL facilities are used to define what counter-measures are taken
ratelimit data).
-42.44 Address verification
+43.44 Address verification
--------------------------
-Several of the verify conditions described in section 42.26 cause addresses to
-be verified. Section 42.48 discusses the reporting of sender verification
+Several of the verify conditions described in section 43.26 cause addresses to
+be verified. Section 43.48 discusses the reporting of sender verification
failures. The verification conditions can be followed by options that modify
the verification process. The options are separated from the keyword and from
each other by slashes, and some of them contain parameters. For example:
the condition is forced to be true instead. Note that this is a main
verification option as well as a suboption for callouts.
- * The no_details option is covered in section 42.48, which discusses the
+ * The no_details option is covered in section 43.48, which discusses the
reporting of sender address verification failures.
* The success_on_redirect option causes verification always to succeed
immediately after a successful redirection. By default, if a redirection
generates just one address, that address is also verified. See further
- discussion in section 42.49.
+ discussion in section 43.49.
After an address verification failure, $acl_verify_message contains the error
message that is associated with the failure. It can be preserved by coding like
The main use of these variables is expected to be to distinguish between
rejections of MAIL and rejections of RCPT in callouts.
+The above variables may also be set after a successful address verification to:
+
+ * random: A random local-part callout succeeded
-42.45 Callout verification
+
+43.45 Callout verification
--------------------------
For non-local addresses, routing verifies the domain, but is unable to do any
described below. This facility should be used with care, because it can add a
lot of resource usage to the cost of verifying an address. However, Exim does
cache the results of callouts, which helps to reduce the cost. Details of
-caching are in section 42.47.
+caching are in section 43.47.
Recipient callouts are usually used only between hosts that are controlled by
the same administration. For example, a corporate gateway host could use
disabled by using a control modifier to set no_callout_flush.
-42.46 Additional parameters for callouts
+43.46 Additional parameters for callouts
----------------------------------------
The callout option can be followed by an equals sign and a number of optional
of the sender when checking recipients. If used indiscriminately, it
reduces the usefulness of callout caching.
+hold
+
+ This option applies to recipient callouts only. For example:
+
+ require verify = recipient/callout=use_sender,hold
+
+ It causes the connection to be held open and used for any further
+ recipients and for eventual delivery (should that be done quickly). Doing
+ this saves on TCP and SMTP startup costs, and TLS costs also when that is
+ used for the connections. The advantage is only gained if there are no
+ callout cache hits (which could be enforced by the no_cache option), if the
+ use_sender option is used, if neither the random nor the use_postmaster
+ option is used, and if no other callouts intervene.
+
If you use any of the parameters that set a non-empty sender for the MAIL
command (mailfrom, postmaster_mailfrom, use_postmaster, or use_sender), you
should think about possible loops. Recipient checking is usually done between
callouts are performed than when an empty sender or postmaster is used.
-42.47 Callout caching
+43.47 Callout caching
---------------------
Exim caches the results of callouts in order to reduce the amount of resources
behaviour will be the same.
-42.48 Sender address verification reporting
+43.48 Sender address verification reporting
-------------------------------------------
-See section 42.44 for a general discussion of verification. When sender
+See section 43.44 for a general discussion of verification. When sender
verification fails in an ACL, the details of the failure are given as
additional output lines before the 550 response to the relevant SMTP command
(RCPT or DATA). For example, if sender callout is in use, you might see:
verify = sender/no_details
-42.49 Redirection while verifying
+43.49 Redirection while verifying
---------------------------------
A dilemma arises when a local address is redirected by aliasing or forwarding
address and a report is output for each of them.
-42.50 Client SMTP authorization (CSA)
+43.50 Client SMTP authorization (CSA)
-------------------------------------
Client SMTP Authorization is a system that allows a site to advertise which
authorization required but absent, or "?" for unknown.
-42.51 Bounce address tag validation
+43.51 Bounce address tag validation
-----------------------------------
Bounce address tag validation (BATV) is a scheme whereby the envelope senders
the original envelope sender address by using a simple key to add a hash of the
address and some time-based randomizing information. The prvs expansion item
creates a signed address, and the prvscheck expansion item checks one. The
-syntax of these expansion items is described in section 11.5.
+syntax of these expansion items is described in section 11.5. The validity
+period on signed addresses is seven days.
As an example, suppose the secret per-address keys are stored in an MySQL
database. A query to look up the key for an address could be defined as a macro
If no key can be found for the existing return path, no signing takes place.
-42.52 Using an ACL to control relaying
+43.52 Using an ACL to control relaying
--------------------------------------
An MTA is said to relay a message if it receives it from some host and delivers
in chapter 7.
-42.53 Checking a relay configuration
+43.53 Checking a relay configuration
------------------------------------
You can check the relay characteristics of your configuration in the same way
that you can test any ACL behaviour for an incoming SMTP connection, by using
the -bh option to run a fake SMTP session with which you interact.
-For specifically testing for unwanted relaying, the host
-relay-test.mail-abuse.org provides a useful service. If you telnet to this host
-from the host on which Exim is running, using the normal telnet port, you will
-see a normal telnet connection message and then quite a long delay. Be patient.
-The remote host is making an SMTP connection back to your host, and trying a
-number of common probes to test for open relay vulnerability. The results of
-the tests will eventually appear on your terminal.
-
===============================================================================
-43. CONTENT SCANNING AT ACL TIME
+44. CONTENT SCANNING AT ACL TIME
The extension of Exim to include content scanning at ACL time, formerly known
as "exiscan", was originally implemented as a patch by Tom Kistner. The code
specification.
It is also possible to scan the content of messages at other times. The
-local_scan() function (see chapter 44) allows for content scanning after all
+local_scan() function (see chapter 45) allows for content scanning after all
the ACLs have run. A transport filter can be used to scan messages at delivery
time (see the transport_filter option, described in chapter 24).
* Two new main configuration options: av_scanner and spamd_address.
-There is another content-scanning configuration option for Local/Makefile,
-called WITH_OLD_DEMIME. If this is set, the old, deprecated demime ACL
-condition is compiled, in addition to all the other content-scanning features.
-
Content-scanning is continually evolving, and new features are still being
added. While such features are still unstable and liable to incompatible
changes, they are made available in Exim by setting options whose names begin
same directory by default.
-43.1 Scanning for viruses
+44.1 Scanning for viruses
-------------------------
The malware ACL condition lets you connect virus scanner software to Exim. It
specialized interfaces for "daemon" type virus scanners, which are resident in
memory and thus are much faster.
-You can set the av_scanner option in first part of the Exim configuration file
-to specify which scanner to use, together with any additional options that are
+A timeout of 2 minutes is applied to a scanner call (by default); if it expires
+then a defer action is taken.
+
+You can set the av_scanner option in the main part of the configuration to
+specify which scanner to use, together with any additional options that are
needed. The basic syntax is as follows:
av_scanner = <scanner-type>:<option1>:<option2>:[...]
av_scanner = sophie:/var/run/sophie
If the value of av_scanner starts with a dollar character, it is expanded
-before use. The usual list-parsing of the content (see 6.19) applies. The
-following scanner types are supported in this release:
+before use. The usual list-parsing of the content (see 6.20) applies. The
+following scanner types are supported in this release, though individual ones
+can be included or not at build time:
+
+avast
+
+ This is the scanner daemon of Avast. It has been tested with Avast Core
+ Security (currently at version 2.2.0). You can get a trial version at
+ https://www.avast.com or for Linux at https://www.avast.com/
+ linux-server-antivirus. This scanner type takes one option, which can be
+ either a full path to a UNIX socket, or host and port specifiers separated
+ by white space. The host may be a name or an IP address; the port is either
+ a single number or a pair of numbers with a dash between. A list of options
+ may follow. These options are interpreted on the Exim's side of the malware
+ scanner, or are given on separate lines to the daemon as options before the
+ main scan command.
+
+ If "pass_unscanned" is set, any files the Avast scanner can't scan (e.g.
+ decompression bombs, or invalid archives) are considered clean. Use with
+ care.
+
+ For example:
+
+ av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup
+ av_scanner = avast:/var/run/avast/scan.sock:pass_unscanned:FLAGS -fullfiles:SENSITIVITY -pup
+ av_scanner = avast:192.168.2.22 5036
+
+ If you omit the argument, the default path /var/run/avast/scan.sock is
+ used. If you use a remote host, you need to make Exim's spool directory
+ available to it, as the scanner is passed a file path, not file contents.
+ For information about available commands and their options you may use
+
+ $ socat UNIX:/var/run/avast/scan.sock STDIO:
+ FLAGS
+ SENSITIVITY
+ PACK
+
+ If the scanner returns a temporary failure (e.g. license issues, or
+ permission problems), the message is deferred and a paniclog entry is
+ written. The usual "defer_ok" option is available.
aveserver
This is the scanner daemon of Kaspersky Version 5. You can get a trial
- version at http://www.kaspersky.com. This scanner type takes one option,
+ version at https://www.kaspersky.com/. This scanner type takes one option,
which is the path to the daemon's UNIX socket. The default is shown in this
example:
clamd
- This daemon-type scanner is GPL and free. You can get it at http://
+ This daemon-type scanner is GPL and free. You can get it at https://
www.clamav.net/. Some older versions of clamd do not seem to unpack MIME
containers, so it used to be recommended to unpack MIME attachments in the
- MIME ACL. This no longer believed to be necessary. One option is required:
- either the path and name of a UNIX socket file, or a hostname or IP number,
- and a port, separated by space, as in the second of these examples:
+ MIME ACL. This is no longer believed to be necessary.
+
+ The options are a list of server specifiers, which may be a UNIX socket
+ specification, a TCP socket specification, or a (global) option.
+
+ A socket specification consists of a space-separated list. For a Unix
+ socket the first element is a full path for the socket, for a TCP socket
+ the first element is the IP address and the second a port number, Any
+ further elements are per-server (non-global) options. These per-server
+ options are supported:
+
+ retry=<timespec> Retry on connect fail
+
+ The "retry" option specifies a time after which a single retry for a failed
+ connect is made. The default is to not retry.
+
+ If a Unix socket file is specified, only one server is supported.
+
+ Examples:
av_scanner = clamd:/opt/clamd/socket
av_scanner = clamd:192.0.2.3 1234
av_scanner = clamd:192.0.2.3 1234:local
+ av_scanner = clamd:192.0.2.3 1234 retry=10s
av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234
If the value of av_scanner points to a UNIX socket file or contains the
- local keyword, then the ClamAV interface will pass a filename containing
- the data to be scanned, which will should normally result in less I/O
- happening and be more efficient. Normally in the TCP case, the data is
- streamed to ClamAV as Exim does not assume that there is a common
- filesystem with the remote host. There is an option WITH_OLD_CLAMAV_STREAM
- in src/EDITME available, should you be running a version of ClamAV prior to
- 0.95.
+ "local" option, then the ClamAV interface will pass a filename containing
+ the data to be scanned, which should normally result in less I/O happening
+ and be more efficient. Normally in the TCP case, the data is streamed to
+ ClamAV as Exim does not assume that there is a common filesystem with the
+ remote host.
The final example shows that multiple TCP targets can be specified. Exim
will randomly use one for each incoming email (i.e. it load balances them).
drweb
- The DrWeb daemon scanner (http://www.sald.com/) interface takes one
- argument, either a full path to a UNIX socket, or an IP address and port
- separated by white space, as in these examples:
+ The DrWeb daemon scanner (https://www.sald.ru/) interface takes one option,
+ either a full path to a UNIX socket, or host and port specifiers separated
+ by white space. The host may be a name or an IP address; the port is either
+ a single number or a pair of numbers with a dash between. For example:
av_scanner = drweb:/var/run/drwebd.sock
av_scanner = drweb:192.168.2.20 31337
If you omit the argument, the default path /usr/local/drweb/run/drwebd.sock
is used. Thanks to Alex Miller for contributing the code for this scanner.
+f-protd
+
+ The f-protd scanner is accessed via HTTP over TCP. One argument is taken,
+ being a space-separated hostname and port number (or port-range). For
+ example:
+
+ av_scanner = f-protd:localhost 10200-10204
+
+ If you omit the argument, the default values shown above are used.
+
+f-prot6d
+
+ The f-prot6d scanner is accessed using the FPSCAND protocol over TCP. One
+ argument is taken, being a space-separated hostname and port number. For
+ example:
+
+ av_scanner = f-prot6d:localhost 10200
+
+ If you omit the argument, the default values show above are used.
+
fsecure
- The F-Secure daemon scanner (http://www.f-secure.com) takes one argument
+ The F-Secure daemon scanner (https://www.f-secure.com/) takes one argument
which is the path to a UNIX socket. For example:
av_scanner = fsecure:/path/to/.fsav
mksd
- This is a daemon type scanner that is aimed mainly at Polish users, though
- some parts of documentation are now available in English. You can get it at
- http://linux.mks.com.pl/. The only option for this scanner type is the
- maximum number of processes used simultaneously to scan the attachments,
- provided that the demime facility is employed and also provided that mksd
- has been run with at least the same number of child processes. For example:
+ This was a daemon type scanner that is aimed mainly at Polish users, though
+ some documentation was available in English. The history can be shown at
+ https://en.wikipedia.org/wiki/Mks_vir and this appears to be a candidate
+ for removal from Exim, unless we are informed of other virus scanners which
+ use the same protocol to integrate. The only option for this scanner type
+ is the maximum number of processes used simultaneously to scan the
+ attachments, provided that mksd has been run with at least the same number
+ of child processes. For example:
av_scanner = mksd:2
This is a general-purpose way of talking to simple scanner daemons running
on the local machine. There are four options: an address (which may be an
- IP addres and port, or the path of a Unix socket), a commandline to send
+ IP address and port, or the path of a Unix socket), a commandline to send
(may include a single %s which will be replaced with the path to the mail
- file to be scanned), an RE to trigger on from the returned data, an RE to
- extract malware_name from the returned data. For example:
+ file to be scanned), an RE to trigger on from the returned data, and an RE
+ to extract malware_name from the returned data. For example:
- av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$
+ av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)$
- Default for the socket specifier is /tmp/malware.sock. Default for the
- commandline is %s\n. Both regular-expressions are required.
+ Note that surrounding whitespace is stripped from each option, meaning
+ there is no way to specify a trailing newline. The socket specifier and
+ both regular-expressions are required. Default for the commandline is %s\n
+ (note this does have a trailing newline); specify an empty element to get
+ this.
sophie
Sophie is a daemon that uses Sophos' libsavi library to scan for viruses.
- You can get Sophie at http://www.clanfield.info/sophie/. The only option
- for this scanner type is the path to the UNIX socket that Sophie uses for
+ You can get Sophie at http://sophie.sourceforge.net/. The only option for
+ this scanner type is the path to the UNIX socket that Sophie uses for
client communication. For example:
av_scanner = sophie:/tmp/sophie
using expandable items in av_scanner disables this caching, in which case each
use of the malware condition causes a new scan of the message.
-The malware condition takes a right-hand argument that is expanded before use.
-It can then be one of
+The malware condition takes a right-hand argument that is expanded before use
+and taken as a list, slash-separated by default. The first element can then be
+one of
* "true", "*", or "1", in which case the message is scanned for viruses. The
condition succeeds if a virus was found, and fail otherwise. This is the
* A regular expression, in which case the message is scanned for viruses. The
condition succeeds if a virus is found and its name matches the regular
expression. This allows you to take special actions on certain types of
- virus.
+ virus. Note that "/" characters in the RE must be doubled due to the
+ list-processing, unless the separator is changed (in the usual way 6.21).
+
+You can append a "defer_ok" element to the malware argument list to accept
+messages even if there is a problem with the virus scanner. Otherwise, such a
+problem causes the ACL to defer.
-You can append "/defer_ok" to the malware condition to accept messages even if
-there is a problem with the virus scanner. Otherwise, such a problem causes the
-ACL to defer.
+You can append a "tmo=<val>" element to the malware argument list to specify a
+non-default timeout. The default is two minutes. For example:
+
+malware = * / defer_ok / tmo=10s
+
+A timeout causes the ACL to defer.
+
+When a connection is made to the scanner the expansion variable
+$callout_address is set to record the actual address used.
When a virus is found, the condition sets up an expansion variable called
$malware_name that contains the name of the virus. You can use it in a message
modifier that specifies the error returned to the sender, and/or in logging
data.
-If your virus scanner cannot unpack MIME and TNEF containers itself, you should
-use the demime condition (see section 43.6) before the malware condition.
-
Beware the interaction of Exim's message_size_limit with any size limits
imposed by your anti-virus scanner.
Here is a very simple scanning example:
deny message = This message contains malware ($malware_name)
- demime = *
malware = *
The next example accepts messages when there is a problem with the scanner:
deny message = This message contains malware ($malware_name)
- demime = *
malware = */defer_ok
The next example shows how to use an ACL variable to scan with both sophie and
malware = *
-43.2 Scanning with SpamAssassin
--------------------------------
+44.2 Scanning with SpamAssassin and Rspamd
+------------------------------------------
The spam ACL condition calls SpamAssassin's spamd daemon to get a spam score
-and a report for the message. You can get SpamAssassin at http://
-www.spamassassin.org, or, if you have a working Perl installation, you can use
-CPAN by running:
+and a report for the message. Support is also provided for Rspamd.
+
+For more information about installation and configuration of SpamAssassin or
+Rspamd refer to their respective websites at https://spamassassin.apache.org/
+and https://www.rspamd.com/
+
+SpamAssassin can be installed with CPAN by running:
perl -MCPAN -e 'install Mail::SpamAssassin'
documentation to see how you can tweak it. The default installation should work
nicely, however.
-After having installed and configured SpamAssassin, start the spamd daemon. By
-default, it listens on 127.0.0.1, TCP port 783. If you use another host or port
-for spamd, you must set the spamd_address option in the global part of the Exim
-configuration as follows (example):
+By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you intend
+to use an instance running on the local host you do not need to set
+spamd_address. If you intend to use another host or port for SpamAssassin, you
+must set the spamd_address option in the global part of the Exim configuration
+as follows (example):
+
+spamd_address = 192.168.99.45 783
-spamd_address = 192.168.99.45 387
+The SpamAssassin protocol relies on a TCP half-close from the client. If your
+SpamAssassin client side is running a Linux system with an iptables firewall,
+consider setting net.netfilter.nf_conntrack_tcp_timeout_close_wait to at least
+the timeout, Exim uses when waiting for a response from the SpamAssassin server
+(currently defaulting to 120s). With a lower value the Linux connection
+tracking may consider your half-closed connection as dead too soon.
-You do not need to set this option if you use the default. As of version 2.60,
-spamd also supports communication over UNIX sockets. If you want to use these,
-supply spamd_address with an absolute file name instead of a address/port pair:
+To use Rspamd (which by default listens on all local addresses on TCP port
+11333) you should add variant=rspamd after the address/port pair, for example:
+
+spamd_address = 127.0.0.1 11333 variant=rspamd
+
+As of version 2.60, SpamAssassin also supports communication over UNIX sockets.
+If you want to us these, supply spamd_address with an absolute filename instead
+of an address/port pair:
spamd_address = /var/run/spamd_socket
You can have multiple spamd servers to improve scalability. These can reside on
other hardware reachable over the network. To specify multiple spamd servers,
put multiple address/port pairs in the spamd_address option, separated with
-colons:
+colons (the separator can be changed in the usual way 6.21):
spamd_address = 192.168.2.10 783 : \
192.168.2.11 783 : \
192.168.2.12 783
-Up to 32 spamd servers are supported. The servers are queried in a random
-fashion. When a server fails to respond to the connection attempt, all other
-servers are tried until one succeeds. If no server responds, the spam condition
-defers.
+Up to 32 spamd servers are supported. When a server fails to respond to the
+connection attempt, all other servers are tried until one succeeds. If no
+server responds, the spam condition defers.
+
+Unix and TCP socket specifications may be mixed in any order. Each element of
+the list is a list itself, space-separated by default and changeable in the
+usual way (6.21); take care to not double the separator.
+
+For TCP socket specifications a host name or IP (v4 or v6, but subject to
+list-separator quoting rules) address can be used, and the port can be one or a
+dash-separated pair. In the latter case, the range is tried in strict order.
+
+Elements after the first for Unix sockets, or second for TCP socket, are
+options. The supported options are:
+
+pri=<priority> Selection priority
+weight=<value> Selection bias
+time=<start>-<end> Use only between these times of day
+retry=<timespec> Retry on connect fail
+tmo=<timespec> Connection time limit
+variant=rspamd Use Rspamd rather than SpamAssassin protocol
+
+The "pri" option specifies a priority for the server within the list, higher
+values being tried first. The default priority is 1.
+
+The "weight" option specifies a selection bias. Within a priority set servers
+are queried in a random fashion, weighted by this value. The default value for
+selection bias is 1.
+
+Time specifications for the "time" option are <hour>.<minute>.<second> in the
+local time zone; each element being one or more digits. Either the seconds or
+both minutes and seconds, plus the leading "." characters, may be omitted and
+will be taken as zero.
-Warning: It is not possible to use the UNIX socket connection method with
-multiple spamd servers.
+Timeout specifications for the "retry" and "tmo" options are the usual Exim
+time interval standard, e.g. "20s" or "1m".
+
+The "tmo" option specifies an overall timeout for communication. The default
+value is two minutes.
+
+The "retry" option specifies a time after which a single retry for a failed
+connect is made. The default is to not retry.
The spamd_address variable is expanded before use if it starts with a dollar
sign. In this case, the expansion may return a string that is used as the list
so that multiple spamd servers can be the result of an expansion.
+When a connection is made to the server the expansion variable $callout_address
+is set to record the actual address used.
+
-43.3 Calling SpamAssassin from an Exim ACL
+44.3 Calling SpamAssassin from an Exim ACL
------------------------------------------
Here is a simple example of the use of the spam condition in a DATA ACL:
The right-hand side of the spam condition specifies a name. This is relevant if
you have set up multiple SpamAssassin profiles. If you do not want to scan
using a specific profile, but rather use the SpamAssassin system-wide default
-profile, you can scan for an unknown name, or simply use "nobody". However, you
-must put something on the right-hand side.
+profile, you can scan for an unknown name, or simply use "nobody". Rspamd does
+not use this setting. However, you must put something on the right-hand side.
The name allows you to use per-domain or per-user antispam profiles in
principle, but this is not straightforward in practice, because a message may
have multiple recipients, not necessarily all in the same domain. Because the
-spam condition has to be called from a DATA ACL in order to be able to read the
-contents of the message, the variables $local_part and $domain are not set.
+spam condition has to be called from a DATA-time ACL in order to be able to
+read the contents of the message, the variables $local_part and $domain are not
+set. Careful enforcement of single-recipient messages (e.g. by responding with
+defer in the recipient ACL for all recipients after the first), or the use of
+PRDR, are needed to use this feature.
The right-hand side of the spam condition is expanded before being used, so you
can put lookups or conditions there. When the right-hand side evaluates to "0"
always return "true" by appending ":true" to the username.
When the spam condition is run, it sets up a number of expansion variables.
-These variables are saved with the received message, thus they are available
-for use at delivery time.
+Except for $spam_report, these variables are saved with the received message so
+are available for use at delivery time.
$spam_score
- The spam score of the message, for example "3.4" or "30.5". This is useful
+ The spam score of the message, for example, "3.4" or "30.5". This is useful
for inclusion in log or reject messages.
$spam_score_int
A string consisting of a number of "+" or "-" characters, representing the
integer part of the spam score value. A spam score of 4.4 would have a
$spam_bar value of "++++". This is useful for inclusion in warning headers,
- since MUAs can match on such strings.
+ since MUAs can match on such strings. The maximum length of the spam bar is
+ 50 characters.
$spam_report
A multiline text table, containing the full SpamAssassin report for the
- message. Useful for inclusion in headers or reject messages.
+ message. Useful for inclusion in headers or reject messages. This variable
+ is only usable in a DATA-time ACL. Beware that SpamAssassin may return
+ non-ASCII characters, especially when running in country-specific locales,
+ which are not legal unencoded in headers.
+
+$spam_action
+
+ For SpamAssassin either 'reject' or 'no action' depending on the spam score
+ versus threshold. For Rspamd, the recommended action.
The spam condition caches its results unless expansion in spamd_address was
used. If you call it again with the same user name, it does not scan again, but
condition = ${if >{$spam_score_int}{120}{1}{0}}
-43.4 Scanning MIME parts
+44.4 Scanning MIME parts
------------------------
The acl_smtp_mime global option specifies an ACL that is called once for each
You cannot use the malware or spam conditions in a MIME ACL; these can only be
used in the DATA or non-SMTP ACLs. However, you can use the regex condition to
match against the raw MIME part. You can also use the mime_regex condition to
-match against the decoded MIME part (see section 43.5).
+match against the decoded MIME part (see section 44.5).
At the start of a MIME ACL, a number of variables are set from the header
information for the relevant MIME part. These are described below. The contents
2. The string "default". In that case, the file is put in the temporary
"default" directory <spool_directory>/scan/<message_id>/ with a sequential
- file name consisting of the message id and a sequence number. The full path
+ filename consisting of the message id and a sequence number. The full path
and name is available in $mime_decoded_filename after decoding.
3. A full path name starting with a slash. If the full name is an existing
directory, it is used as a replacement for the default directory. The
filename is then sequentially assigned. If the path does not exist, it is
- used as the full path and file name.
+ used as the full path and filename.
4. If the string does not start with a slash, it is used as the filename, and
the default path is then used.
The MIME ACL supports the regex and mime_regex conditions. These can be used to
match regular expressions against raw and decoded MIME parts, respectively.
-They are described in section 43.5.
+They are described in section 44.5.
The following list describes all expansion variables that are available in the
MIME ACL:
$mime_decoded_filename
This variable is set only after the decode modifier (see above) has been
- successfully run. It contains the full path and file name of the file
+ successfully run. It contains the full path and filename of the file
containing the decoded data.
$mime_filename
This is perhaps the most important of the MIME variables. It contains a
proposed filename for an attachment, if one was found in either the
Content-Type: or Content-Disposition: headers. The filename will be RFC2047
- decoded, but no additional sanity checks are done. If no filename was
- found, this variable contains the empty string.
+ or RFC2231 decoded, but no additional sanity checks are done. If no
+ filename was found, this variable contains the empty string.
$mime_is_coverletter
As an example, the following will ban "HTML mail" (including that sent with
alternative plain text), while allowing HTML files to be attached. HTML
- coverletter mail attached to non-HMTL coverletter mail will also be
+ coverletter mail attached to non-HTML coverletter mail will also be
allowed:
deny message = HTML mail is not accepted here
$mime_is_multipart
This variable has the value 1 (true) when the current part has the main
- type "multipart", for example "multipart/alternative" or "multipart/mixed".
- Since multipart entities only serve as containers for other parts, you may
- not want to carry out specific actions on them.
+ type "multipart", for example, "multipart/alternative" or "multipart/
+ mixed". Since multipart entities only serve as containers for other parts,
+ you may not want to carry out specific actions on them.
$mime_is_rfc822
-1.
-43.5 Scanning with regular expressions
+44.5 Scanning with regular expressions
--------------------------------------
You can specify your own custom regular expression matches on the full body of
The conditions returns true if any one of the regular expressions matches. The
$regex_match_string expansion variable is then set up and contains the matching
-regular expression.
+regular expression. The expansion variables $regex1 $regex2 etc are set to any
+substrings captured by the regular expression.
Warning: With large messages, these conditions can be fairly CPU-intensive.
-43.6 The demime condition
--------------------------
-
-The demime ACL condition provides MIME unpacking, sanity checking and file
-extension blocking. It is usable only in the DATA and non-SMTP ACLs. The demime
-condition uses a simpler interface to MIME decoding than the MIME ACL
-functionality, but provides no additional facilities. Please note that this
-condition is deprecated and kept only for backward compatibility. You must set
-the WITH_OLD_DEMIME option in Local/Makefile at build time to be able to use
-the demime condition.
-
-The demime condition unpacks MIME containers in the message. It detects errors
-in MIME containers and can match file extensions found in the message against a
-list. Using this facility produces files containing the unpacked MIME parts of
-the message in the temporary scan directory. If you do antivirus scanning, it
-is recommended that you use the demime condition before the antivirus (malware)
-condition.
-
-On the right-hand side of the demime condition you can pass a colon-separated
-list of file extensions that it should match against. For example:
-
-deny message = Found blacklisted file attachment
- demime = vbs:com:bat:pif:prf:lnk
-
-If one of the file extensions is found, the condition is true, otherwise it is
-false. If there is a temporary error while demimeing (for example, "disk
-full"), the condition defers, and the message is temporarily rejected (unless
-the condition is on a warn verb).
-
-The right-hand side is expanded before being treated as a list, so you can have
-conditions and lookups there. If it expands to an empty string, "false", or
-zero ("0"), no demimeing is done and the condition is false.
-
-The demime condition set the following variables:
-
-$demime_errorlevel
-
- When an error is detected in a MIME container, this variable contains the
- severity of the error, as an integer number. The higher the value, the more
- severe the error (the current maximum value is 3). If this variable is
- unset or zero, no error occurred.
-
-$demime_reason
-
- When $demime_errorlevel is greater than zero, this variable contains a
- human-readable text string describing the MIME error that occurred.
-
-$found_extension
-
- When the demime condition is true, this variable contains the file
- extension it found.
-
-Both $demime_errorlevel and $demime_reason are set by the first call of the
-demime condition, and are not changed on subsequent calls.
-
-If you do not want to check for file extensions, but rather use the demime
-condition for unpacking or error checking purposes, pass "*" as the right-hand
-side value. Here is a more elaborate example of how to use this facility:
-
-# Reject messages with serious MIME container errors
-deny message = Found MIME error ($demime_reason).
- demime = *
- condition = ${if >{$demime_errorlevel}{2}{1}{0}}
-
-# Reject known virus spreading file extensions.
-# Accepting these is pretty much braindead.
-deny message = contains $found_extension file (blacklisted).
- demime = com:vbs:bat:pif:scr
-
-# Freeze .exe and .doc files. Postmaster can
-# examine them and eventually thaw them.
-deny log_message = Another $found_extension file.
- demime = exe:doc
- control = freeze
-
-
===============================================================================
-44. ADDING A LOCAL SCAN FUNCTION TO EXIM
+45. ADDING A LOCAL SCAN FUNCTION TO EXIM
In these days of email worms, viruses, and ever-increasing spam, some sites
want to apply a lot of checking to messages before accepting them.
-The content scanning extension (chapter 43) has facilities for passing messages
+The content scanning extension (chapter 44) has facilities for passing messages
to external virus and spam scanning software. You can also do a certain amount
in Exim itself through string expansions and the condition condition in the ACL
that runs after the SMTP DATA command or the ACL for non-SMTP messages (see
-chapter 42), but this has its limitations.
+chapter 43), but this has its limitations.
To allow for further customization to a site's own requirements, there is the
possibility of linking Exim with a private message scanning function, written
ends with a non-zero code. The incident is logged on the main and reject logs.
-44.1 Building Exim to use a local scan function
+45.1 Building Exim to use a local scan function
-----------------------------------------------
To make use of the local scan function feature, you must tell Exim where your
-function is before building Exim, by setting LOCAL_SCAN_SOURCE in your Local/
-Makefile. A recommended place to put it is in the Local directory, so you might
-set
+function is before building Exim, by setting
+both HAVE_LOCAL_SCAN and
+
+LOCAL_SCAN_SOURCE in your Local/Makefile. A recommended place to put it is in
+the Local directory, so you might set
+
+HAVE_LOCAL_SCAN=yes
LOCAL_SCAN_SOURCE=Local/local_scan.c
for example. The function must be called local_scan(). It is called by Exim
commented template function (that just accepts the message) in the file _src/
local_scan.c_.
-If you want to make use of Exim's run time configuration file to set options
-for your local_scan() function, you must also set
+If you want to make use of Exim's runtime configuration file to set options for
+your local_scan() function, you must also set
LOCAL_SCAN_HAS_OPTIONS=yes
-in Local/Makefile (see section 44.3 below).
+in Local/Makefile (see section 45.3 below).
-44.2 API for local_scan()
+45.2 API for local_scan()
-------------------------
You must include this line near the start of your code:
message is not written to the reject log. It has the effect of unsetting
the rejected_header log selector for just this rejection. If
rejected_header is already unset (see the discussion of the log_selection
- option in section 51.15), this code is the same as LOCAL_SCAN_REJECT.
+ option in section 52.15), this code is the same as LOCAL_SCAN_REJECT.
"LOCAL_SCAN_TEMPREJECT_NOLOGHDR"
command line options.
-44.3 Configuration options for local_scan()
+45.3 Configuration options for local_scan()
-------------------------------------------
It is possible to have option settings in the main configuration file that set
values of all the local_scan() options.
-44.4 Available Exim variables
+45.4 Available Exim variables
-----------------------------
The header local_scan.h gives you access to a number of C variables. These are
int body_linecount
- This variable contains the number of lines in the message's body.
+ This variable contains the number of lines in the message's body. It is not
+ valid if the spool_files_wireformat option is used.
int body_zerocount
This variable contains the number of binary zero bytes in the message's
- body.
+ body. It is not valid if the spool_files_wireformat option is used.
unsigned int debug_selector
it is a bitmap of debugging selectors. Two bits are identified for use in
local_scan(); they are defined as macros:
- * The "D_v" bit is set when -v was present on the command line. This is a
+ + The "D_v" bit is set when -v was present on the command line. This is a
testing option that is not privileged - any caller may set it. All the
other selector bits can be set only by admin users.
- * The "D_local_scan" bit is provided for use by local_scan(); it is set
+ + The "D_local_scan" bit is provided for use by local_scan(); it is set
by the "+local_scan" debug selector. It is not included in the default
set of debugging bits.
int store_pool
The contents of this variable control which pool of memory is used for new
- requests. See section 44.8 for details.
+ requests. See section 45.8 for details.
-44.5 Structure of header lines
+45.5 Structure of header lines
------------------------------
The header_line structure contains the members listed below. You can add
int type
A code identifying certain headers that Exim recognizes. The codes are
- printing characters, and are documented in chapter 55 of this manual.
+ printing characters, and are documented in chapter 56 of this manual.
Notice in particular that any header line whose type is * is not
transmitted with the message. This flagging is used for header lines that
have been rewritten, or are to be removed (for example, Envelope-sender:
followed by a zero byte. Internal newlines are preserved.
-44.6 Structure of recipient items
+45.6 Structure of recipient items
---------------------------------
The recipient_item structure contains these members:
field is NULL for all recipients.
-44.7 Available Exim functions
+45.7 Available Exim functions
-----------------------------
The header local_scan.h gives you access to a number of Exim functions. These
seconds) to expire. A timeout value of zero means wait as long as it takes.
The return value is as follows:
- * >= 0
+ + >= 0
The process terminated by a normal exit and the value is the process
ending status.
- * < 0 and > -256
+ + < 0 and > -256
The process was terminated by a signal and the value is the negation of
the signal number.
- * -256
+ + -256
The process timed out.
- * -257
+ + -257
The was some other error in wait(); errno is still set.
failure. If expansion does not change the string, the return value is the
pointer to the input string. Otherwise, the return value points to a new
block of memory that was obtained by a call to store_get(). See section
- 44.8 below for a discussion of memory handling.
+ 45.8 below for a discussion of memory handling.
void header_add(int type, char *format, ...)
See the next section for more discussion.
-44.8 More about Exim's memory handling
+45.8 More about Exim's memory handling
--------------------------------------
No function is provided for freeing memory, because that is never needed. The
===============================================================================
-45. SYSTEM-WIDE MESSAGE FILTERING
+46. SYSTEM-WIDE MESSAGE FILTERING
The previous chapters (on ACLs and the local scan function) describe checks
that can be applied to messages before they are accepted by a host. There is
to individual recipient addresses, such as $local_part and $domain, are not
set, and the "personal" condition is not meaningful. If you want to run a
centrally-specified filter for each recipient address independently, you can do
-so by setting up a suitable redirect router, as described in section 45.8
+so by setting up a suitable redirect router, as described in section 46.8
below.
-45.1 Specifying a system filter
+46.1 Specifying a system filter
-------------------------------
The name of the file that contains the system filter must be specified by
any messages generated by the reply command.
-45.2 Testing a system filter
+46.2 Testing a system filter
----------------------------
You can run simple tests of a system filter in the same way as for a user
you can use both -bF and -bf on the same command line.
-45.3 Contents of a system filter
+46.3 Contents of a system filter
--------------------------------
The language used to specify system filters is the same as for users' filter
filter files can refer.
-45.4 Additional variable for system filters
+46.4 Additional variable for system filters
-------------------------------------------
The expansion variable $recipients, containing a list of all the recipients of
filters. It is not available in users' filters for privacy reasons.
-45.5 Defer, freeze, and fail commands for system filters
+46.5 Defer, freeze, and fail commands for system filters
--------------------------------------------------------
There are three extra commands (defer, freeze and fail) which are always
take place.
-45.6 Adding and removing headers in a system filter
+46.6 Adding and removing headers in a system filter
---------------------------------------------------
Two filter commands that are available only in system filters are:
that are added by a system filter are visible to users' filter files and to all
routers and transports. This contrasts with the manipulation of header lines by
routers and transports, which is not immediate, but which instead is saved up
-until the message is actually being written (see section 46.17).
+until the message is actually being written (see section 47.17).
If the message is not delivered at the first attempt, header lines that were
added by the system filter are stored with the message, and so are still
headers remove "Old-Subject"
-45.7 Setting an errors address in a system filter
+46.7 Setting an errors address in a system filter
-------------------------------------------------
In a system filter, if a deliver command is followed by
address if its delivery failed.
-45.8 Per-address filtering
+46.8 Per-address filtering
--------------------------
In contrast to the system filter, which is run just once per message for each
===============================================================================
-46. MESSAGE PROCESSING
+47. MESSAGE PROCESSING
Exim performs various transformations on the sender and recipient addresses of
all messages that it handles, and also on the messages' header lines. Some of
that there are appropriate entries in your ACLs.
-46.1 Submission mode for non-local messages
+47.1 Submission mode for non-local messages
-------------------------------------------
Processing that happens automatically for locally-originated messages (unless
control = submission
-in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 42.21
-and 42.22). This makes Exim treat the message as a local submission, and is
+in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 43.21
+and 43.22). This makes Exim treat the message as a local submission, and is
normally used when the source of the message is known to be an MUA running on a
client host (as opposed to an MTA). For example, to set submission mode for
messages originating on the IPv4 loopback interface, you could include the
control = submission/domain=some.domain
-The domain may be empty. How this value is used is described in sections 46.11
-and 46.16. There is also a name option that allows you to specify the user's
+The domain may be empty. How this value is used is described in sections 47.11
+and 47.16. There is also a name option that allows you to specify the user's
full name for inclusion in a created Sender: or From: header line. For example:
accept authenticated = *
spoof another's address.
-46.2 Line endings
+47.2 Line endings
-----------------
RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
header line.
-46.3 Unqualified addresses
+47.3 Unqualified addresses
--------------------------
By default, Exim expects every envelope address it receives from an external
and recipient_unqualified_hosts,
-46.4 The UUCP From line
+47.4 The UUCP From line
-----------------------
Messages that have come from UUCP (and some other applications) often begin
SMTP message from a source that is not permitted to send them.
-46.5 Resent- header lines
+47.5 Resent- header lines
-------------------------
RFC 2822 makes provision for sets of header lines starting with the string
Resent- header lines are present.
-46.6 The Auto-Submitted: header line
+47.6 The Auto-Submitted: header line
------------------------------------
Whenever Exim generates an autoreply, a bounce, or a delay warning message, it
Auto-Submitted: auto-replied
-46.7 The Bcc: header line
+47.7 The Bcc: header line
-------------------------
If Exim is called with the -t option, to take recipient addresses from a
existing Bcc: is not removed.
-46.8 The Date: header line
+47.8 The Date: header line
--------------------------
If a locally-generated or submission-mode message has no Date: header line,
suppress_local_fixups control has been specified.
-46.9 The Delivery-date: header line
+47.9 The Delivery-date: header line
-----------------------------------
Delivery-date: header lines are not part of the standard RFC 2822 header set.
(the default), Exim removes Delivery-date: header lines from incoming messages.
-46.10 The Envelope-to: header line
+47.10 The Envelope-to: header line
----------------------------------
Envelope-to: header lines are not part of the standard RFC 2822 header set.
default), Exim removes Envelope-to: header lines from incoming messages.
-46.11 The From: header line
+47.11 The From: header line
---------------------------
If a submission-mode message does not contain a From: header line, Exim adds
If a locally-generated incoming message does not contain a From: header line,
and the suppress_local_fixups control is not set, Exim adds one containing the
sender's address. The calling user's login name and full name are used to
-construct the address, as described in section 46.18. They are obtained from
+construct the address, as described in section 47.18. They are obtained from
the password data by calling getpwuid() (but see the unknown_login
configuration option). The address is qualified with qualify_domain.
For compatibility with Sendmail, if an incoming, non-SMTP message has a From:
header line containing just the unqualified login name of the calling user,
this is replaced by an address containing the user's login name and full name
-as described in section 46.18.
+as described in section 47.18.
-46.12 The Message-ID: header line
+47.12 The Message-ID: header line
---------------------------------
If a locally-generated or submission-mode incoming message does not contain a
message_id_header_text and/or message_id_header_domain options.
-46.13 The Received: header line
+47.13 The Received: header line
-------------------------------
A Received: header line is added at the start of every message. The contents
-H spool file is written) the earliest time at which delivery could start.
-46.14 The References: header line
+47.14 The References: header line
---------------------------------
Messages created by the autoreply transport include a References: header line.
message ID of the incoming message.
-46.15 The Return-path: header line
+47.15 The Return-path: header line
----------------------------------
Return-path: header lines are defined as something an MTA may insert when it
Return-path: header lines from incoming messages.
-46.16 The Sender: header line
+47.16 The Sender: header line
-----------------------------
For a locally-originated message from an untrusted user, Exim may remove an
in the case of submission mode when sender_retain is specified.
-46.17 Adding and removing header lines in routers and transports
+47.17 Adding and removing header lines in routers and transports
----------------------------------------------------------------
When a message is delivered, the addition and removal of header lines can be
specified in a system filter, or on any of the routers and transports that
-process the message. Section 45.6 contains details about modifying headers in a
+process the message. Section 46.6 contains details about modifying headers in a
system filter. Header lines can also be added in an ACL as a message is
-received (see section 42.24).
+received (see section 43.24).
In contrast to what happens in a system filter, header modifications that are
specified on routers and transports apply only to the particular recipient
Multiple headers_remove options for a single router or transport can be
specified; the arguments will append to a single header-names list. Each item
-is separately expanded.
+is separately expanded. Note that colons in complex expansions which are used
+to form all or part of a headers_remove list will act as list separators.
When headers_add or headers_remove is specified on a router, items are expanded
at routing time, and then associated with all addresses that are accepted by
redirect router that has the one_time option set.
-46.18 Constructed addresses
+47.18 Constructed addresses
---------------------------
When Exim constructs a sender address for a locally-generated message, it uses
with codes greater than 127) count as printing characters or not.
-46.19 Case of local parts
+47.19 Case of local parts
-------------------------
RFC 2822 states that the case of letters in the local parts of addresses cannot
with the correct case in a case-sensitive manner.
-46.20 Dots in local parts
+47.20 Dots in local parts
-------------------------
RFC 2822 forbids empty components in local parts. That is, an unquoted local
empty components for compatibility.
-46.21 Rewriting addresses
+47.21 Rewriting addresses
-------------------------
Rewriting of sender and recipient addresses, and addresses in headers, can
===============================================================================
-47. SMTP PROCESSING
+48. SMTP PROCESSING
Exim supports a number of different ways of using the SMTP protocol, and its
LMTP variant, which is an interactive protocol for transferring messages into a
to contain the envelope information.
-47.1 Outgoing SMTP and LMTP over TCP/IP
+48.1 Outgoing SMTP and LMTP over TCP/IP
---------------------------------------
Outgoing SMTP and LMTP over TCP/IP is implemented by the smtp transport. The
If the remote server advertises support for the STARTTLS command, and Exim was
built to support TLS encryption, it tries to start a TLS session unless the
-server matches hosts_avoid_tls. See chapter 41 for more details. Either a match
+server matches hosts_avoid_tls. See chapter 42 for more details. Either a match
in that or hosts_verify_avoid_tls apply when the transport is called for
verification.
square bracket of the IP address.
-47.2 Errors in outgoing SMTP
+48.2 Errors in outgoing SMTP
----------------------------
Three different kinds of error are recognized for outgoing SMTP: host errors,
A host error is not associated with a particular message or with a
particular recipient of a message. The host errors are:
- * Connection refused or timed out,
+ + Connection refused or timed out,
- * Any error response code on connection,
+ + Any error response code on connection,
- * Any error response code to EHLO or HELO,
+ + Any error response code to EHLO or HELO,
- * Loss of connection at any time, except after ".",
+ + Loss of connection at any time, except after ".",
- * I/O errors at any time,
+ + I/O errors at any time,
- * Timeouts during the session, other than in response to MAIL, RCPT or
+ + Timeouts during the session, other than in response to MAIL, RCPT or
the "." at the end of the data.
For a host error, a permanent error response on connection, or in response
particular host, but not with a particular recipient of the message. The
message errors are:
- * Any error response code to MAIL, DATA, or the "." that terminates the
+ + Any error response code to MAIL, DATA, or the "." that terminates the
data,
- * Timeout after MAIL,
+ + Timeout after MAIL,
- * Timeout or loss of connection after the "." that terminates the data. A
+ + Timeout or loss of connection after the "." that terminates the data. A
timeout after the DATA command itself is treated as a host error, as is
loss of connection at any other time.
A recipient error is associated with a particular recipient of a message.
The recipient errors are:
- * Any error response to RCPT,
+ + Any error response to RCPT,
- * Timeout after RCPT.
+ + Timeout after RCPT.
For a recipient error, a permanent error response (5xx) causes the
recipient address to be failed, and a bounce message to be returned to the
error, in order not to delay other messages to the same host.
-47.3 Incoming SMTP messages over TCP/IP
+48.3 Incoming SMTP messages over TCP/IP
---------------------------------------
Incoming SMTP messages can be accepted in one of two ways: by running a
available with inetd.
Exim can be configured to verify addresses in incoming SMTP commands as they
-are received. See chapter 42 for details. It can also be configured to rewrite
+are received. See chapter 43 for details. It can also be configured to rewrite
addresses at this time - before any syntax checking is done. See section 31.9.
Exim can also be configured to limit the rate at which a client host submits
option.
-47.4 Unrecognized SMTP commands
+48.4 Unrecognized SMTP commands
-------------------------------
If Exim receives more than smtp_max_unknown_commands unrecognized SMTP commands
circumstances, a number of non-SMTP lines are sent first.
-47.5 Syntax and protocol errors in SMTP commands
+48.5 Syntax and protocol errors in SMTP commands
------------------------------------------------
A syntax error is detected if an SMTP command is recognized, but there is
loop sending bad commands (yes, it has been seen).
-47.6 Use of non-mail SMTP commands
+48.6 Use of non-mail SMTP commands
----------------------------------
The "non-mail" SMTP commands are those other than MAIL, RCPT, and DATA. Exim
you can exclude any specific badly-behaved hosts that you have to live with.
-47.7 The VRFY and EXPN commands
+48.7 The VRFY and EXPN commands
-------------------------------
When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the
ACL specified by acl_smtp_vrfy or acl_smtp_expn (as appropriate) in order to
-decide whether the command should be accepted or not. If no ACL is defined, the
-command is rejected.
+decide whether the command should be accepted or not.
-When VRFY is accepted, it runs exactly the same code as when Exim is called
-with the -bv option.
+When no ACL is defined for VRFY, or if it rejects without setting an explicit
+response code, the command is accepted (with a 252 SMTP response code) in order
+to support awkward clients that do a VRFY before every RCPT. When VRFY is
+accepted, it runs exactly the same code as when Exim is called with the -bv
+option, and returns 250/451/550 SMTP response codes.
-When EXPN is accepted, a single-level expansion of the address is done. EXPN is
-treated as an "address test" (similar to the -bt option) rather than a
-verification (the -bv option). If an unqualified local part is given as the
-argument to EXPN, it is qualified with qualify_domain. Rejections of VRFY and
-EXPN commands are logged on the main and reject logs, and VRFY verification
-failures are logged on the main log for consistency with RCPT failures.
+If no ACL for EXPN is defined, the command is rejected. When EXPN is accepted,
+a single-level expansion of the address is done. EXPN is treated as an "address
+test" (similar to the -bt option) rather than a verification (the -bv option).
+If an unqualified local part is given as the argument to EXPN, it is qualified
+with qualify_domain. Rejections of VRFY and EXPN commands are logged on the
+main and reject logs, and VRFY verification failures are logged on the main log
+for consistency with RCPT failures.
-47.8 The ETRN command
+48.8 The ETRN command
---------------------
RFC 1985 describes an SMTP command called ETRN that is designed to overcome the
to change them before running the command.
-47.9 Incoming local SMTP
+48.9 Incoming local SMTP
------------------------
Some user agents use SMTP to pass messages to their local MTA using the
This accepts SMTP messages from local processes without doing any other tests.
-47.10 Outgoing batched SMTP
+48.10 Outgoing batched SMTP
---------------------------
Both the appendfile and pipe transports can be used for handling batched SMTP.
(unless there are more than 1000 recipients).
-47.11 Incoming batched SMTP
+48.11 Incoming batched SMTP
---------------------------
The -bS command line option causes Exim to accept one or more messages by
===============================================================================
-48. CUSTOMIZING BOUNCE AND WARNING MESSAGES
+49. CUSTOMIZING BOUNCE AND WARNING MESSAGES
-When a message fails to be delivered, or remains on the queue for more than a
+When a message fails to be delivered, or remains in the queue for more than a
configured amount of time, Exim sends a message to the original sender, or to
an alternative configured address. The text of these messages is built into the
code of Exim, but it is possible to change it, either by adding a single
to all warning and bounce messages,
-48.1 Customizing bounce messages
+49.1 Customizing bounce messages
--------------------------------
If bounce_message_text is set, its contents are included in the default message
* The third item is used to introduce any text from pipe transports that is
to be returned to the sender. It is omitted if there is no such text.
- * The fourth item is used to introduce the copy of the message that is
- returned as part of the error report.
-
- * The fifth item is added after the fourth one if the returned message is
- truncated because it is bigger than return_size_limit.
-
- * The sixth item is added after the copy of the original message.
+ * The fourth, fifth and sixth items will be ignored and may be empty. The
+ fields exist for back-compatibility
The default state (bounce_message_file unset) is equivalent to the following
file, in which the sixth item is empty. The Subject: and some other lines have
****
-48.2 Customizing warning messages
+49.2 Customizing warning messages
---------------------------------
The option warn_message_file can be pointed at a template file for use when
<$sender_address>
}}has not been delivered to all of its recipients after
-more than $warn_message_delay on the queue on $primary_hostname.
+more than $warn_message_delay in the queue on $primary_hostname.
The message identifier is: $message_exim_id
The subject of the message is: $h_subject
===============================================================================
-49. SOME COMMON CONFIGURATION SETTINGS
+50. SOME COMMON CONFIGURATION SETTINGS
This chapter discusses some configuration settings that seem to be fairly
common. More examples and discussion can be found in the Exim book.
-49.1 Sending mail to a smart host
+50.1 Sending mail to a smart host
---------------------------------
If you want to send all mail for non-local domains to a "smart host", you
You can use the smart host's IP address instead of the name if you wish. If you
are using Exim only to submit messages to a smart host, and not for receiving
incoming messages, you can arrange for it to do the submission synchronously by
-setting the mua_wrapper option (see chapter 50).
+setting the mua_wrapper option (see chapter 51).
-49.2 Using Exim to handle mailing lists
+50.2 Using Exim to handle mailing lists
---------------------------------------
Exim can be used to run simple mailing lists, but for large and/or complicated
routers are tried, and so the whole delivery fails.
The forbid_pipe and forbid_file options prevent a local part from being
-expanded into a file name or a pipe delivery, which is usually inappropriate in
+expanded into a filename or a pipe delivery, which is usually inappropriate in
a mailing list.
The errors_to option specifies that any delivery errors caused by addresses
request, are also possible.
-49.3 Syntax errors in mailing lists
+50.3 Syntax errors in mailing lists
-----------------------------------
If an entry in redirection data contains a syntax error, Exim normally defers
syntax_errors_to to the same address as errors_to.
-49.4 Re-expansion of mailing lists
+50.4 Re-expansion of mailing lists
----------------------------------
Exim remembers every individual address to which a message has been delivered,
level of expansion anyway.
-49.5 Closed mailing lists
+50.5 Closed mailing lists
-------------------------
The examples so far have assumed open mailing lists, to which anybody may send
the address, giving a suitable error message.
-49.6 Variable Envelope Return Paths (VERP)
+50.6 Variable Envelope Return Paths (VERP)
------------------------------------------
-Variable Envelope Return Paths - see http://cr.yp.to/proto/verp.txt - are a way
-of helping mailing list administrators discover which subscription address is
-the cause of a particular delivery failure. The idea is to encode the original
-recipient address in the outgoing envelope sender address, so that if the
-message is forwarded by another host and then subsequently bounces, the
+Variable Envelope Return Paths - see https://cr.yp.to/proto/verp.txt - are a
+way of helping mailing list administrators discover which subscription address
+is the cause of a particular delivery failure. The idea is to encode the
+original recipient address in the outgoing envelope sender address, so that if
+the message is forwarded by another host and then subsequently bounces, the
original recipient can be extracted from the recipient address of the bounce.
Envelope sender addresses can be modified by Exim using two different
used).
-49.7 Virtual domains
+50.7 Virtual domains
--------------------
The phrase virtual domain is unfortunately used with two rather different
ensures that if the lookup fails (leading to data being an empty string), Exim
gives up on the address without trying any subsequent routers.
-This one router can handle all the virtual domains because the alias file names
+This one router can handle all the virtual domains because the alias filenames
follow a fixed pattern. Permissions can be arranged so that appropriate people
can edit the different alias files. A successful aliasing operation results in
a new envelope recipient address, which is then routed from scratch.
information about the domains.
-49.8 Multiple user mailboxes
+50.8 Multiple user mailboxes
----------------------------
Heavy email users often want to operate with multiple mailboxes, into which
as a default.
-49.9 Simplified vacation processing
+50.9 Simplified vacation processing
-----------------------------------
The traditional way of running the vacation program is for a user to set up a
use of arbitrary pipes by users is locked out.
-49.10 Taking copies of mail
+50.10 Taking copies of mail
---------------------------
Some installations have policies that require archive copies of all messages to
of delivery by sites that insist on doing such things.
-49.11 Intermittently connected hosts
+50.11 Intermittently connected hosts
------------------------------------
It has become quite common (because it is cheaper) for hosts to connect to the
Nevertheless there are some features that can be used.
-49.12 Exim on the upstream server host
+50.12 Exim on the upstream server host
--------------------------------------
It is tempting to arrange for incoming mail for the intermittently connected
-host to remain on Exim's queue until the client connects. However, this
+host to remain in Exim's queue until the client connects. However, this
approach does not scale very well. Two different kinds of waiting message are
being mixed up in the same queue - those that cannot be delivered because of
some temporary problem, and those that are waiting for their destination host
This stops a lot of failed delivery attempts from occurring, but Exim remembers
which messages it has queued up for that host. Once the intermittent host comes
online, forcing delivery of one message (either by using the -M or -R options,
-or by using the ETRN SMTP command (see section 47.8) causes all the queued up
+or by using the ETRN SMTP command (see section 48.8) causes all the queued up
messages to be delivered, often down a single SMTP connection. While the host
remains connected, any new messages get delivered immediately.
separate transport for the intermittently connected ones.
-49.13 Exim on the intermittently connected client host
+50.13 Exim on the intermittently connected client host
------------------------------------------------------
The value of smtp_accept_queue_per_connection should probably be increased, or
===============================================================================
-50. USING EXIM AS A NON-QUEUEING CLIENT
+51. USING EXIM AS A NON-QUEUEING CLIENT
On a personal computer, it is a common requirement for all email to be sent to
a "smart host". There are plenty of MUAs that can be configured to operate that
the message, failing if there is any kind of problem. Because no local
deliveries are done and no daemon can be run, Exim does not need root
privilege. It should be possible to run it setuid to exim instead of setuid to
-root. See section 54.3 for a general discussion about the advantages and
+root. See section 55.3 for a general discussion about the advantages and
disadvantages of running without root privilege.
===============================================================================
-51. LOG FILES
+52. LOG FILES
Exim writes three different logs, referred to as the main log, the reject log,
and the panic log:
in the main log. Some of them are optional, in which case the log_selector
option controls whether they are included or not. A Perl script called
eximstats, which does simple analysis of main log files, is provided in the
- Exim distribution (see section 52.7).
+ Exim distribution (see section 53.7).
* The reject log records information from messages that are rejected as a
result of a configuration option (that is, for policy reasons). The first
2003-04-25 11:17:07 +0100 Start queue run: pid=12762
Exim does not include its process id in log lines by default, but you can
-request that it does so by specifying the "pid" log selector (see section 51.15
+request that it does so by specifying the "pid" log selector (see section 52.15
). When this is set, the process id is output, in square brackets, immediately
after the time and date.
-51.1 Where the logs are written
+52.1 Where the logs are written
-------------------------------
The logs may be written to local files, or to syslog, or both. However, it
this has been seen to make syslog take 90% plus of CPU time.
The destination for Exim's logs is configured by setting LOG_FILE_PATH in Local
-/Makefile or by setting log_file_path in the run time configuration. This
-latter string is expanded, so it can contain, for example, references to the
-host name:
+/Makefile or by setting log_file_path in the runtime configuration. This latter
+string is expanded, so it can contain, for example, references to the host
+name:
log_file_path = /var/log/$primary_hostname/exim_%slog
It is generally advisable, however, to set the string in Local/Makefile rather
-than at run time, because then the setting is available right from the start of
+than at runtime, because then the setting is available right from the start of
Exim's execution. Otherwise, if there's something it wants to log before it has
read the configuration file (for example, an error in the configuration file)
it will not use the path you want, and may not be able to log at all.
log_file_path = $spool_directory/log/%slog
-If you do not specify anything at build time or run time, that is where the
-logs are written.
+If you do not specify anything at build time or runtime, or if you unset the
+option at runtime (i.e. "log_file_path = "), that is where the logs are
+written.
-A log file path may also contain "%D" or "%M" if datestamped log file names are
-in use - see section 51.3 below.
+A log file path may also contain "%D" or "%M" if datestamped log filenames are
+in use - see section 52.3 below.
Here are some examples of possible settings:
error is logged.
-51.2 Logging to local files that are periodically "cycled"
+52.2 Logging to local files that are periodically "cycled"
----------------------------------------------------------
Some operating systems provide centralized and standardized methods for cycling
log files. For those that do not, a utility script called exicyclog is provided
-(see section 52.6). This renames and compresses the main and reject logs each
+(see section 53.6). This renames and compresses the main and reject logs each
time it is called. The maximum number of old logs to keep can be set. It is
suggested this script is run as a daily cron job.
some time, but no Exim processes should write to it once it has been renamed.
-51.3 Datestamped log files
+52.3 Datestamped log files
--------------------------
Instead of cycling the main and reject log files by renaming them periodically,
/var/log/exim/panic
-51.4 Logging to syslog
+52.4 Logging to syslog
----------------------
The use of syslog does not change what Exim logs or the format of its messages,
is.
-51.5 Log line flags
+52.5 Log line flags
-------------------
One line is written to the main log for each message received, and for each
timestamp. The flags are:
<= message arrival
+(= message fakereject
=> normal message delivery
-> additional address in same delivery
>> cutthrough message delivery
== delivery deferred; temporary problem
-51.6 Logging message reception
+52.6 Logging message reception
------------------------------
The format of the single-line entry in the main log that is written for every
other).
The log_selector option can be used to request the logging of additional data
-when a message is received. See section 51.15 below.
+when a message is received. See section 52.15 below.
-51.7 Logging deliveries
+52.7 Logging deliveries
-----------------------
The format of the single-line entry in the main log that is written for every
delivery is shown in one of the examples below, for local and remote
-deliveries, respectively. Each example has been split into two lines in order
-to fit it on the page:
+deliveries, respectively. Each example has been split into multiple lines in
+order to fit it on the page:
2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv
<marv@hitch.fict.example> R=localuser T=local_delivery
SMTP RCPT commands in one transaction) the second and subsequent addresses are
flagged with "->" instead of "=>". When two or more messages are delivered down
a single SMTP connection, an asterisk follows the IP address in the log lines
-for the second and subsequent messages.
+for the second and subsequent messages. When two or more messages are delivered
+down a single TLS connection, the DNS and some TLS-related information logged
+for the first message delivered will not be present in the log lines for the
+second and subsequent messages. TLS cipher information is still available.
When delivery is done in cutthrough mode it is flagged with ">>" and the log
line precedes the reception line, since cutthrough waits for a possible
to the addressee, preceded by ">".
The log_selector option can be used to request the logging of additional data
-when a message is delivered. See section 51.15 below.
+when a message is delivered. See section 52.15 below.
-51.8 Discarded deliveries
+52.8 Discarded deliveries
-------------------------
When a message is discarded as a result of the command "seen finish" being
<hole@nowhere.example> R=blackhole_router
-51.9 Deferred deliveries
+52.9 Deferred deliveries
------------------------
When a delivery is deferred, a line of the following form is logged:
appropriate value in log_selector.
-51.10 Delivery failures
+52.10 Delivery failures
-----------------------
If a delivery fails because an address cannot be routed, a line of the
"**".
-51.11 Fake deliveries
+52.11 Fake deliveries
---------------------
If a delivery does not actually take place because the -N option has been used
is replaced by "*>".
-51.12 Completion
+52.12 Completion
----------------
A line of the form
at the end of its processing.
-51.13 Summary of Fields in Log Lines
+52.13 Summary of Fields in Log Lines
------------------------------------
A summary of the field identifiers that are used in log lines is shown in the
command list for "no mail in SMTP session"
CV certificate verification status
D duration of "no mail in SMTP session"
+DKIM domain verified in incoming message
DN distinguished name from peer certificate
+DS DNSSEC secured lookups
DT on => lines: time taken for a delivery
F sender address (on delivery lines)
H host name and IP address
I local interface used
id message id for incoming message
+K CHUNKING extension used
+L on <= and => lines: PIPELINING extension used
+M8S 8BITMIME status for incoming message
P on <= lines: protocol used
on => and ** lines: return path
+PRDR PRDR extension used
+PRX on <= and => lines: proxy address
+Q alternate queue name
QT on => lines: time spent on queue so far
on "Completed" lines: time spent on queue
R on <= lines: reference for local bounce
- on => ** and == lines: router name
-S size of message
+ on => >> ** and == lines: router name
+RT on <= lines: time taken for reception
+S size of message in bytes
SNI server name indication from TLS client hello
ST shadow transport name
T on <= lines: message subject (topic)
+TFO connection took advantage of TCP Fast Open
on => ** and == lines: transport name
U local user or RFC 1413 identity
X TLS cipher suite
-51.14 Other log entries
+52.14 Other log entries
-----------------------
Various other types of log entry are written from time to time. Most should be
failed. The delivery was discarded.
+ * DKIM: d= Verbose results of a DKIM verification attempt, if enabled for
+ logging and the message has a DKIM signature header.
+
-51.15 Reducing or increasing what is logged
+52.15 Reducing or increasing what is logged
-------------------------------------------
By setting the log_selector global option, you can disable some of Exim's
*delay_delivery immediate delivery delayed
deliver_time time taken to perform delivery
delivery_size add S=nnn to => lines
+*dkim DKIM verified domain on <= lines
+ dkim_verbose separate full DKIM verification result line, per signature
*dnslist_defer defers of DNS list (aka RBL) lookups
+ dnssec DNSSEC secured lookups
*etrn ETRN commands
*host_lookup_failed as it says
ident_timeout timeout for ident connection
- incoming_interface incoming interface on <= lines
- incoming_port incoming port on <= lines
+ incoming_interface local interface on <= and => lines
+ incoming_port remote port on <= lines
*lost_incoming_connection as it says (includes timeouts)
+ millisec millisecond timestamps and RT,QT,DT,D times
+ outgoing_interface local interface on => lines
outgoing_port add remote port to => lines
*queue_run start and end queue runs
queue_time time on queue for one recipient
queue_time_overall time on queue for whole message
pid Exim process id
+ pipelining PIPELINING use, on <= and => lines
+ proxy proxy address on <= and => lines
+ receive_time time taken to receive message
received_recipients recipients on <= lines
received_sender sender on <= lines
*rejected_header header contents on reject log
*size_reject rejection because too big
*skip_delivery delivery skipped in a queue run
*smtp_confirmation SMTP confirmation on => lines
- smtp_connection SMTP connections
+ smtp_connection incoming SMTP connections
smtp_incomplete_transaction incomplete SMTP transactions
smtp_mailauth AUTH argument to MAIL commands
smtp_no_mail session with no MAIL commands
smtp_protocol_error SMTP protocol errors
smtp_syntax_error SMTP syntax errors
subject contents of Subject: on <= lines
- tls_certificate_verified certificate verification status
+*tls_certificate_verified certificate verification status
*tls_cipher TLS cipher suite on <= and => lines
tls_peerdn TLS peer DN on <= and => lines
tls_sni TLS SNI on <= lines
all all of the above
+See also the slow_lookup_log main configuration option, section 14.4
+
More details on each of these items follows:
* 8bitmime: This causes Exim to log any 8BITMIME status of received messages,
* deliver_time: For each delivery, the amount of real time it has taken to
perform the actual delivery is logged as DT=<time>, for example, "DT=1s".
+ If millisecond logging is enabled, short times will be shown with greater
+ precision, eg. "DT=0.304s".
* delivery_size: For each delivery, the size of message delivered is added to
the "=>" line, tagged with S=.
+ * dkim: For message acceptance log lines, when an DKIM signature in the
+ header verifies successfully a tag of DKIM is added, with one of the
+ verified domains.
+
+ * dkim_verbose: A log entry is written for each attempted DKIM verification.
+
* dnslist_defer: A log entry is written if an attempt to look up a host in a
DNS black list suffers a temporary error.
+ * dnssec: For message acceptance and (attempted) delivery log lines, when dns
+ lookups gave secure results a tag of DS is added. For acceptance this
+ covers the reverse and forward lookups for host name verification. It does
+ not cover helo-name verification. For delivery this covers the SRV, MX, A
+ and/or AAAA lookups.
+
* etrn: Every valid ETRN command that is received is logged, before the ACL
is run to determine whether or not it is actually accepted. An invalid ETRN
command, or one received within a message transaction is not logged by this
* incoming_interface: The interface on which a message was received is added
to the "<=" line as an IP address in square brackets, tagged by I= and
followed by a colon and the port number. The local interface and port are
- also added to other SMTP log lines, for example "SMTP connection from", and
- to rejection lines.
+ also added to other SMTP log lines, for example, "SMTP connection from", to
+ rejection lines, and (despite the name) to outgoing "=>" and "->" lines.
+ The latter can be disabled by turning off the outgoing_interface option.
+
+ * proxy: The internal (closest to the system running Exim) IP address of the
+ proxy, tagged by PRX=, on the "<=" line for a message accepted on a proxied
+ connection or the "=>" line for a message delivered on a proxied
+ connection. See 58.1 for more information.
* incoming_port: The remote port number from which a message was received is
added to log entries and Received: header lines, following the IP address
* lost_incoming_connection: A log line is written when an incoming SMTP
connection is unexpectedly dropped.
+ * millisec: Timestamps have a period and three decimal places of finer
+ granularity appended to the seconds value.
+
+ * outgoing_interface: If incoming_interface is turned on, then the interface
+ on which a message was sent is added to delivery lines as an I= tag
+ followed by IP address in square brackets. You can disable this by turning
+ off the outgoing_interface option.
+
* outgoing_port: The remote port number is added to delivery log lines (those
- containing => tags) following the IP address. This option is not included
- in the default setting, because for most ordinary configurations, the
- remote port number is always 25 (the SMTP port).
+ containing => tags) following the IP address. The local port is also added
+ if incoming_interface and outgoing_interface are both enabled. This option
+ is not included in the default setting, because for most ordinary
+ configurations, the remote port number is always 25 (the SMTP port), and
+ the local port is a random ephemeral port.
* pid: The current process id is added to every log line, in square brackets,
immediately after the time and date.
+ * pipelining: A field is added to delivery and accept log lines when the
+ ESMTP PIPELINING extension was used. The field is a single "L".
+
+ On accept lines, where PIPELINING was offered but not used by the client,
+ the field has a minus appended.
+
* queue_run: The start and end of every queue run are logged.
* queue_time: The amount of time the message has been in the queue on the
includes reception time as well as the delivery time for the current
address. This means that it may be longer than the difference between the
arrival and delivery log line times, because the arrival log line is not
- written until the message has been successfully received.
+ written until the message has been successfully received. If millisecond
+ logging is enabled, short times will be shown with greater precision, eg.
+ "QT=1.578s".
* queue_time_overall: The amount of time the message has been in the queue on
the local host is logged as QT=<time> on "Completed" lines, for example,
"QT=3m45s". The clock starts when Exim starts to receive the message, so it
includes reception time as well as the total delivery time.
+ * receive_time: For each message, the amount of real time it has taken to
+ perform the reception is logged as RT=<time>, for example, "RT=1s". If
+ millisecond logging is enabled, short times will be shown with greater
+ precision, eg. "RT=0.204s".
+
* received_recipients: The recipients of a message are listed in the main log
as soon as the message is received. The list appears at the end of the log
line that is written when a message is received, preceded by the word
* rejected_header: If a message's header has been received at the time a
rejection is written to the reject log, the complete header is added to the
log. Header logging can be turned off individually for messages that are
- rejected by the local_scan() function (see section 44.2).
+ rejected by the local_scan() function (see section 45.2).
* retry_defer: A log line is written if a delivery is deferred because a
retry time has not yet been reached. However, this "retry time not reached"
"C="<text>. A number of MTAs (including Exim) return an identifying string
in this response.
- * smtp_connection: A log line is written whenever an SMTP connection is
- established or closed, unless the connection is from a host that matches
+ * smtp_connection: A log line is written whenever an incoming SMTP connection
+ is established or closed, unless the connection is from a host that matches
hosts_connection_nolog. (In contrast, lost_incoming_connection applies only
when the closure is unexpected.) This applies to connections from local
processes that use -bs as well as to TCP/IP connections. If a connection is
shows that the client issued QUIT straight after EHLO. If there were fewer
than 20 commands, they are all listed. If there were more than 20 commands,
the last 20 are listed, preceded by "...". However, with the default
- setting of 10 for smtp_accep_max_nonmail, the connection will in any case
+ setting of 10 for smtp_accept_max_nonmail, the connection will in any case
have been aborted before 20 non-mail commands are processed.
* smtp_mailauth: A third subfield with the authenticated sender,
* tls_certificate_verified: An extra item is added to <= and => log lines
when TLS is in use. The item is "CV=yes" if the peer's certificate was
- verified, and "CV=no" if not.
+ verified using a CA trust anchor, "CA=dane" if using a DNS trust anchor,
+ and "CV=no" if not.
* tls_cipher: When a message is sent or received over an encrypted
connection, the cipher suite used is added to the log line, preceded by X=.
result of a list match is failure because a DNS lookup failed.
-51.16 Message log
+52.16 Message log
-----------------
In addition to the general log files, Exim writes a log file for each message
===============================================================================
-52. EXIM UTILITIES
+53. EXIM UTILITIES
A number of utility scripts and programs are supplied with Exim and are
described in this chapter. There is also the Exim Monitor, which is covered in
the next chapter. The utilities described here are:
- 52.1 exiwhat list what Exim processes are doing
- 52.2 exiqgrep grep the queue
- 52.3 exiqsumm summarize the queue
- 52.4 exigrep search the main log
- 52.5 exipick select messages on various criteria
- 52.6 exicyclog cycle (rotate) log files
- 52.7 eximstats extract statistics from the log
- 52.8 exim_checkaccess check address acceptance from given IP
- 52.9 exim_dbmbuild build a DBM file
- 52.10 exinext extract retry information
- 52.11 exim_dumpdb dump a hints database
- 52.11 exim_tidydb clean up a hints database
- 52.11 exim_fixdb patch a hints database
- 52.15 exim_lock lock a mailbox file
+ 53.1 exiwhat list what Exim processes are doing
+ 53.2 exiqgrep grep the queue
+ 53.3 exiqsumm summarize the queue
+ 53.4 exigrep search the main log
+ 53.5 exipick select messages on various criteria
+ 53.6 exicyclog cycle (rotate) log files
+ 53.7 eximstats extract statistics from the log
+ 53.8 exim_checkaccess check address acceptance from given IP
+ 53.9 exim_dbmbuild build a DBM file
+ 53.10 exinext extract retry information
+ 53.11 exim_dumpdb dump a hints database
+ 53.11 exim_tidydb clean up a hints database
+ 53.11 exim_fixdb patch a hints database
+ 53.15 exim_lock lock a mailbox file
Another utility that might be of use to sites with many MTAs is Tom Kistner's
-exilog. It provides log visualizations across multiple Exim servers. See http:/
-/duncanthrax.net/exilog/ for details.
+exilog. It provides log visualizations across multiple Exim servers. See https:
+//duncanthrax.net/exilog/ for details.
-52.1 Finding out what Exim processes are doing (exiwhat)
+53.1 Finding out what Exim processes are doing (exiwhat)
--------------------------------------------------------
On operating systems that can restart a system call after receiving a signal
been split here, in order to fit it on the page.
-52.2 Selective queue listing (exiqgrep)
+53.2 Selective queue listing (exiqgrep)
---------------------------------------
This utility is a Perl script contributed by Matt Hubbard. It runs
-r <regex>
- Match a recipient address using a case-insensitve search. The field that is
- tested is not enclosed in angle brackets.
+ Match a recipient address using a case-insensitive search. The field that
+ is tested is not enclosed in angle brackets.
-s <regex>
There is one more option, -h, which outputs a list of options.
-52.3 Summarizing the queue (exiqsumm)
+53.3 Summarizing the queue (exiqsumm)
-------------------------------------
The exiqsumm utility is a Perl script which reads the output of "exim -bp" and
-produces a summary of the messages on the queue. Thus, you use it by running a
+produces a summary of the messages in the queue. Thus, you use it by running a
command such as
exim -bp | exiqsumm
redirect router has been used to convert them into "top level" addresses).
-52.4 Extracting specific information from the log (exigrep)
+53.4 Extracting specific information from the log (exigrep)
-----------------------------------------------------------
The exigrep utility is a Perl script that searches one or more main log files
associated with a specific message, it is included in exigrep's output without
any additional lines. The usage is:
-exigrep [-t<n>] [-I] [-l] [-v] <pattern> [<log file>] ...
+exigrep [-t<n>] [-I] [-l] [-
M] [-v] <pattern> [<log file>] ...
-If no log file names are given on the command line, the standard input is read.
+If no log filenames are given on the command line, the standard input is read.
The -t argument specifies a number of seconds. It adds an additional condition
for message selection. Messages that are complete are shown only if they spent
-more than <n> seconds on the queue.
+more than <n> seconds in the queue.
By default, exigrep does case-insensitive matching. The -I option makes it
case-sensitive. This may give a performance improvement when searching large
The -v option inverts the matching condition. That is, a line is selected if it
does not match the pattern.
+The -M options means "related messages". exigrep will show messages that are
+generated as a result/response to a message that exigrep matched normally.
+
+Example of -M: user_a sends a message to user_b, which generates a bounce back
+to user_b. If exigrep is used to search for "user_a", only the first message
+will be displayed. But if exigrep is used to search for "user_b", the first and
+the second (bounce) message will be displayed. Using -M with exigrep when
+searching for "user_a" will show both messages since the bounce is "related" to
+or a "result" of the first message that was found by the search term.
+
If the location of a zcat command is known from the definition of ZCAT_COMMAND
in Local/Makefile, exigrep automatically passes any file whose name ends in
-COMPRESS_SUFFIX through zcat as it searches it.
+COMPRESS_SUFFIX through zcat as it searches it. If the ZCAT_COMMAND is not
+executable, exigrep tries to use autodetection of some well known compression
+extensions.
-52.5 Selecting messages by various criteria (exipick)
+53.5 Selecting messages by various criteria (exipick)
-----------------------------------------------------
John Jetmore's exipick utility is included in the Exim distribution. It lists
messages from the queue according to a variety of criteria. For details of
-exipick's facilities, visit the web page at http://www.exim.org/eximwiki/
-ToolExipickManPage or run exipick with the --help option.
+exipick's facilities, run exipick with the --help option.
-52.6 Cycling log files (exicyclog)
+53.6 Cycling log files (exicyclog)
----------------------------------
The exicyclog script can be used to cycle (rotate) mainlog and rejectlog files.
This is not necessary if only syslog is being used, or if you are using log
-files with datestamps in their names (see section 51.3). Some operating systems
+files with datestamps in their names (see section 52.3). Some operating systems
have their own standard mechanisms for log cycling, and these can be used
instead of exicyclog if preferred. There are two command line options for
exicyclog:
the script's default, which is to find the setting from Exim's
configuration.
-Each time exicyclog is run the file names get "shuffled down" by one. If the
-main log file name is mainlog (the default) then when exicyclog is run mainlog
+Each time exicyclog is run the filenames get "shuffled down" by one. If the
+main log filename is mainlog (the default) then when exicyclog is run mainlog
becomes mainlog.01, the previous mainlog.01 becomes mainlog.02 and so on, up to
the limit that is set in the script or by the -k option. Log files whose
numbers exceed the limit are discarded. Reject logs are handled similarly.
as root if you wish, but there is no need.
-52.7 Mail statistics (eximstats)
+53.7 Mail statistics (eximstats)
--------------------------------
A Perl script called eximstats is provided for extracting statistical
-information from log files. The output is either plain text, or HTML. Exim log
-files are also supported by the Lire system produced by the LogReport
-Foundation http://www.logreport.org.
+information from log files. The output is either plain text, or HTML.
The eximstats script has been hacked about quite a bit over time. The latest
version is the result of some extensive revision by Steve Campbell. A lot of
The remainder of the output is in sections that can be independently disabled
or modified by various options. It consists of a summary of deliveries by
transport, histograms of messages received and delivered per time interval
-(default per hour), information about the time messages spent on the queue, a
+(default per hour), information about the time messages spent in the queue, a
list of relayed messages, lists of the top fifty sending hosts, local senders,
destination hosts, and destination local users by count and by volume, and a
list of delivery errors that occurred.
perldoc /usr/exim/bin/eximstats
-52.8 Checking access policy (exim_checkaccess)
+53.8 Checking access policy (exim_checkaccess)
----------------------------------------------
The -bh command line argument allows you to run a fake SMTP session with
this is not yet available in a "packaged" form.
-52.9 Making DBM files (exim_dbmbuild)
+53.9 Making DBM files (exim_dbmbuild)
-------------------------------------
The exim_dbmbuild program reads an input file containing keys and data in the
well.
If the native DB interface is in use (USE_DB is set in a compile-time
-configuration file - this is common in free versions of Unix) the two file
-names must be different, because in this mode the Berkeley DB functions create
-a single output file using exactly the name given. For example,
+configuration file - this is common in free versions of Unix) the two filenames
+must be different, because in this mode the Berkeley DB functions create a
+single output file using exactly the name given. For example,
exim_dbmbuild /etc/aliases /etc/aliases.db
suffixes are added to the second argument of exim_dbmbuild, so it can be the
same as the first. This is also the case when the Berkeley functions are used
in compatibility mode (though this is not recommended), because in that case it
-adds a .db suffix to the file name.
+adds a .db suffix to the filename.
If a duplicate key is encountered, the program outputs a warning, and when it
finishes, its return code is 1 rather than zero, unless the -noduperr option is
doesn't actually make a new file, the return code is 2.
-52.10 Finding individual retry times (exinext)
+53.10 Finding individual retry times (exinext)
----------------------------------------------
A utility called exinext (mostly a Perl script) provides the ability to fish
retry information for that local part in your default domain. A message id can
be used to obtain retry information pertaining to a specific message. This
exists only when an attempt to deliver a message to a remote host suffers a
-message-specific error (see section 47.2). exinext is not particularly
+message-specific error (see section 48.2). exinext is not particularly
efficient, but then it is not expected to be run very often.
The exinext utility calls Exim to find out information such as the location of
environments where more than one configuration file is in use.
-52.11 Hints database maintenance
+53.11 Hints database maintenance
--------------------------------
Three utility programs are provided for maintaining the DBM files that Exim
* Serializing delivery to a specific host (when serialize_hosts is set in an
smtp transport)
+ * Limiting the concurrency of specific transports (when max_parallel is set
+ in a transport)
+
-52.12 exim_dumpdb
+53.12 exim_dumpdb
-----------------
The entire contents of a database are written to the standard output by the
cross-references.
-52.13 exim_tidydb
+53.13 exim_tidydb
-----------------
The exim_tidydb utility program is used to tidy up the contents of a hints
likely to keep on increasing.
-52.14 exim_fixdb
+53.14 exim_fixdb
----------------
The exim_fixdb program is a utility for interactively modifying databases. Its
used as optional separators.
-52.15 Mailbox maintenance (exim_lock)
+53.15 Mailbox maintenance (exim_lock)
-------------------------------------
The exim_lock utility locks a mailbox file using the same algorithm as Exim.
create a lock file and also to use fcntl() locking on the mailbox, which is the
same as Exim's default. The use of -flock or -fcntl requires that the file be
writeable; the use of -lockfile requires that the directory containing the file
-be writeable. Locking by lock file does not last for ever; Exim assumes that a
+be writeable. Locking by lock file does not last forever; Exim assumes that a
lock file is expired if it is more than 30 minutes old.
The -mbx option can be used with either or both of -fcntl or -flock. It assumes
===============================================================================
-53. THE EXIM MONITOR
+54. THE EXIM MONITOR
The Exim monitor is an application which displays in an X window information
about the state of Exim's queue and what Exim is doing. An admin user can
monitor itself makes use of the command line to perform any actions requested.
-53.1 Running the monitor
+54.1 Running the monitor
------------------------
The monitor is started by running the script called eximon. This is a shell
Eximon*highlight: gray
End
-In order to see the contents of messages on the queue, and to operate on them,
+In order to see the contents of messages in the queue, and to operate on them,
eximon must either be run as root or by an admin user.
The command-line parameters of eximon are passed to eximon.bin and may contain
different parts of the display.
-53.2 The stripcharts
+54.2 The stripcharts
--------------------
-The first stripchart is always a count of messages on the queue. Its name can
+The first stripchart is always a count of messages in the queue. Its name can
be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file.
The remaining stripcharts are defined in the configuration script by regular
expression matches on log file entries, making it possible to display, for
file.
-53.3 Main action buttons
+54.3 Main action buttons
------------------------
Below the stripcharts there is an action button for quitting the monitor. Next
START_SMALL=yes in Local/eximon.conf.
-53.4 The log display
+54.4 The log display
--------------------
The second section of the window is an area in which a display of the tail of
expense of having unwanted items in the search popup window.
-53.5 The queue display
+54.5 The queue display
----------------------
The bottom section of the monitor window contains a list of all messages that
-are on the queue, which includes those currently being received or delivered,
+are in the queue, which includes those currently being received or delivered,
as well as those awaiting delivery. The size of this subwindow is controlled by
parameters in the configuration file Local/eximon.conf, and the frequency at
which it is updated is controlled by another parameter in the same file - the
an update of the queue display at any time.
When a host is down for some time, a lot of pending mail can build up for it,
-and this can make it hard to deal with other messages on the queue. To help
+and this can make it hard to deal with other messages in the queue. To help
with this situation there is a button next to "Update" called "Hide". If
pressed, a dialogue box called "Hide addresses ending with" is put up. If you
type anything in here and press "Return", the text is added to a chain of such
pressing the "Hide" button.
The queue display contains, for each unhidden queued message, the length of
-time it has been on the queue, the size of the message, the message id, the
+time it has been in the queue, the size of the message, the message id, the
message sender, and the first undelivered recipient, all on one line. If it is
a bounce message, the sender is shown as "<>". If there is more than one
recipient to which the message has not yet been delivered, subsequent ones are
display is updated.
-53.6 The queue menu
+54.6 The queue menu
-------------------
If the shift key is held down and the left button is clicked when the mouse
in a new text window.
* headers: Information from the spool file that contains the envelope
- information and headers is displayed in a new text window. See chapter 55
+ information and headers is displayed in a new text window. See chapter 56
for a description of the format of spool files.
* body: The contents of the spool file containing the body of the message are
displayed in a new text window. There is a default limit of 20,000 bytes to
the amount of data displayed. This can be changed by setting the BODY_MAX
- option at compile time, or the EXIMON_BODY_MAX option at run time.
+ option at compile time, or the EXIMON_BODY_MAX option at runtime.
* deliver message: A call to Exim is made using the -M option to request
delivery of the message. This causes an automatic thaw if the message is
===============================================================================
-54. SECURITY CONSIDERATIONS
+55. SECURITY CONSIDERATIONS
This chapter discusses a number of issues concerned with security, some of
which are also covered in other parts of this manual.
as soon as possible.
-54.1 Building a more "hardened" Exim
+55.1 Building a more "hardened" Exim
------------------------------------
There are a number of build-time options that can be set in Local/Makefile to
penetrated the Exim (but not the root) account. These options are as follows:
* ALT_CONFIG_PREFIX can be set to a string that is required to match the
- start of any file names used with the -C option. When it is set, these file
- names are also not allowed to contain the sequence "/../". (However, if the
- value of the -C option is identical to the value of CONFIGURE_FILE in Local
- /Makefile, Exim ignores -C and proceeds as usual.) There is no default
+ start of any filenames used with the -C option. When it is set, these
+ filenames are also not allowed to contain the sequence "/../". (However, if
+ the value of the -C option is identical to the value of CONFIGURE_FILE in
+ Local/Makefile, Exim ignores -C and proceeds as usual.) There is no default
setting for ALT_CONFIG_PREFIX.
If the permitted configuration files are confined to a directory to which
to get root.
-54.2 Root privilege
+55.2 Root privilege
-------------------
The Exim binary is normally setuid to root, which means that it gains root
obviously more secure if Exim does not run as root except when necessary. For
this reason, a user and group for Exim to use must be defined in Local/Makefile
. These are known as "the Exim user" and "the Exim group". Their values can be
-changed by the run time configuration, though this is not recommended. Often a
+changed by the runtime configuration, though this is not recommended. Often a
user called exim is used, but some sites use mail or another user name
altogether.
the routing is done in the same environment as a message delivery.
-54.3 Running Exim without privilege
+55.3 Running Exim without privilege
-----------------------------------
Some installations like to run Exim in an unprivileged state for more of its
gateway host that does no local deliveries, setting deliver_drop_privilege
gives more security at essentially no cost.
-If you are using the mua_wrapper facility (see chapter 50),
+If you are using the mua_wrapper facility (see chapter 51),
deliver_drop_privilege is forced to be true.
-54.4 Delivering to local files
+55.4 Delivering to local files
------------------------------
Full details of the checks applied by appendfile before it writes to a file are
given in chapter 26.
-54.5 Running local commands
+55.5 Running local commands
---------------------------
There are a number of ways in which an administrator can configure Exim to run
* Administrators who use embedded Perl are advised to explore how Perl's
taint checking might apply to their usage.
- * Use of ${expand...} is somewhat analagous to shell's eval builtin and
+ * Use of ${expand...} is somewhat analogous to shell's eval builtin and
administrators are well advised to view its use with suspicion, in case
(for instance) it allows a local-part to contain embedded Exim directives.
the use of the inlisti expansion condition instead.
-54.6 Trust in configuration data
+55.6 Trust in configuration data
--------------------------------
If configuration data for Exim can come from untrustworthy sources, there are
only expected to yield one result.
-54.7 IPv4 source routing
+55.7 IPv4 source routing
------------------------
Many operating systems suppress IP source-routed packets in the kernel, but
IPv6. No special checking is currently done.
-54.8 The VRFY, EXPN, and ETRN commands in SMTP
+55.8 The VRFY, EXPN, and ETRN commands in SMTP
----------------------------------------------
Support for these SMTP commands is disabled by default. If required, they can
be enabled by defining suitable ACLs.
-54.9 Privileged users
+55.9 Privileged users
---------------------
Exim recognizes two sets of users with special privileges. Trusted users are
unprivileged), Exim must be built to allow group read access to its spool
files.
+By default, regular users are trusted to perform basic testing and
+introspection commands, as themselves. This setting can be tightened by setting
+the commandline_checks_require_admin option. This affects most of the checking
+options, such as -be and anything else -b*.
+
-54.10 Spool files
+55.10 Spool files
-----------------
Exim's spool directory and everything it contains is owned by the Exim user and
is a member of the Exim group can access these files.
-54.11 Use of argv[0]
+55.11 Use of argv[0]
--------------------
Exim examines the last component of argv[0], and if it matches one of a set of
it with the option -bS. There are no security implications in this.
-54.12 Use of %f formatting
+55.12 Use of %f formatting
--------------------------
The only use made of "%f" by Exim is in formatting load average values. These
converted output.
-54.13 Embedded Exim path
+55.13 Embedded Exim path
------------------------
Exim uses its own path name, which is embedded in the code, only when it needs
arbitrary program's being run as exim, not as root.
-54.14 Dynamic module directory
+55.14 Dynamic module directory
------------------------------
Any dynamically loadable modules must be installed into the directory defined
in "LOOKUP_MODULE_DIR" in Local/Makefile for Exim to permit loading it.
-54.15 Use of sprintf()
+55.15 Use of sprintf()
----------------------
A large number of occurrences of "sprintf" in the code are actually calls to
output buffer is known to be sufficiently long to contain the converted string.
-54.16 Use of debug_printf() and log_write()
+55.16 Use of debug_printf() and log_write()
-------------------------------------------
Arbitrary strings are passed to both these functions, but they do their
format string itself, and checks the length of each conversion.
-54.17 Use of strcat() and strcpy()
+55.17 Use of strcat() and strcpy()
----------------------------------
These are used only in cases where the output buffer is known to be large
===============================================================================
-55. FORMAT OF SPOOL FILES
+56. FORMAT OF SPOOL FILES
A message on Exim's queue consists of two files, whose names are the message id
followed by -D and -H, respectively. The data portion of the message is kept in
is insurance against disk crashes where the directory is lost but the files
themselves are recoverable.
+The file formats may be changed, or new formats added, at any release. Spool
+files are not intended as an interface to other programs and should not be used
+as such.
+
Some people are tempted into editing -D files in order to modify messages. You
need to be extremely careful if you do this; it is not recommended and you are
on your own if you do it. Here are some of the pitfalls:
the lock will be lost at the instant of rename.
* If you change the number of lines in the file, the value of $body_linecount
- , which is stored in the -H file, will be incorrect. At present, this value
- is not used by Exim, but there is no guarantee that this will always be the
- case.
+ , which is stored in the -H file, will be incorrect and can cause
+ incomplete transmission of messages or undeliverable messages.
* If the message is in MIME format, you must take care not to break it.
-J file and uses it to update the -H file before starting the next delivery
attempt.
+Files whose names end with -K or .eml may also be seen in the spool. These are
+temporaries used for DKIM or malware processing, when that is used. They should
+be tidied up by normal operations; any old ones are probably relics of crashes
+and can be removed.
+
-55.1 Format of the -H file
+56.1 Format of the -H file
--------------------------
The second line of the -H file contains the login name for the uid of the
-body_linecount <number>
- This records the number of lines in the body of the message, and is always
- present.
+ This records the number of lines in the body of the message, and is present
+ unless -spool_file_wireformat is.
-body_zerocount <number>
If a message was scanned by SpamAssassin, this is present. It records the
value of $spam_score_int.
+-spool_file_wireformat
+
+ The -D file for this message is in wire-format (for ESMTP CHUNKING) rather
+ than Unix-format. The line-ending is CRLF rather than newline. There is
+ still, however, no leading-dot-stuffing.
+
-tls_certificate_verified
A TLS certificate was received from the client that sent this message, and
unqualified domain foundation.
+56.2 Format of the -D file
+--------------------------
+
+The data file is traditionally in Unix-standard format: lines are ended with an
+ASCII newline character. However, when the spool_wireformat main option is used
+some -D files can have an alternate format. This is flagged by a
+-spool_file_wireformat line in the corresponding -H file. The -D file lines
+(not including the first name-component line) are suitable for direct copying
+to the wire when transmitting using the ESMTP CHUNKING option, meaning lower
+processing overhead. Lines are terminated with an ASCII CRLF pair. There is no
+dot-stuffing (and no dot-termination).
+
+
===============================================================================
-56. SUPPORT FOR DKIM (DOMAINKEYS IDENTIFIED MAIL)
+57. DKIM AND SPF
+
+
+57.1 DKIM (DomainKeys Identified Mail)
+--------------------------------------
DKIM is a mechanism by which messages sent by some entity can be provably
linked to a domain which that entity controls. It permits reputation to be
tracked on a per-domain basis, rather than merely upon source IP address. DKIM
-is documented in RFC 4871.
+is documented in RFC 6376.
-Since version 4.70, DKIM support is compiled into Exim by default. It can be
-disabled by setting DISABLE_DKIM=yes in Local/Makefile.
+As DKIM relies on the message being unchanged in transit, messages handled by a
+mailing-list (which traditionally adds to the message) will not match any
+original DKIM signature.
-Exim's DKIM implementation allows to
+DKIM support is compiled into Exim by default if TLS support is present. It can
+be disabled by setting DISABLE_DKIM=yes in Local/Makefile.
- 1. Sign outgoing messages: This function is implemented in the SMTP transport.
- It can co-exist with all other Exim features (including transport filters)
- except cutthrough delivery.
+Exim's DKIM implementation allows for
- 2. Verify signatures in incoming messages: This is implemented by an
+ 1. Signing outgoing messages: This function is implemented in the SMTP
+ transport. It can co-exist with all other Exim features (including
+ transport filters) except cutthrough delivery.
+
+ 2. Verifying signatures in incoming messages: This is implemented by an
additional ACL (acl_smtp_dkim), which can be called several times per
message, with different signature contexts.
standard controls.
Please note that verification of DKIM signatures in incoming mail is turned on
-by default for logging purposes. For each signature in incoming email, exim
-will log a line displaying the most important signature details, and the
-signature status. Here is an example (with line-breaks added for clarity):
+by default for logging (in the <= line) purposes.
+
+Additional log detail can be enabled using the dkim_verbose log_selector. When
+set, for each signature in incoming email, exim will log a line displaying the
+most important signature details, and the signature status. Here is an example
+(with line-breaks added for clarity):
2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
d=facebookmail.com s=q1-2009b
accept mail from relay sources (internal hosts or authenticated senders).
-56.1 Signing outgoing messages
+57.2 Signing outgoing messages
------------------------------
-Signing is implemented by setting private options on the SMTP transport. These
+For signing to be usable you must have published a DKIM record in DNS. Note
+that RFC 8301 says:
+
+rsa-sha1 MUST NOT be used for signing or verifying.
+
+Signers MUST use RSA keys of at least 1024 bits for all keys.
+Signers SHOULD use RSA keys of at least 2048 bits.
+
+Note also that the key content (the 'p=' field) in the DNS record is different
+between RSA and EC keys; for the former it is the base64 of the ASN.1 for the
+RSA public key (equivalent to the private-key .pem with the header/trailer
+stripped) but for EC keys it is the base64 of the pure key; no ASN.1 wrapping.
+
+Signing is enabled by setting private options on the SMTP transport. These
options take (expandable) strings as arguments.
-+-----------+---------+-------------+--------------+
-|dkim_domain|Use: smtp|Type: string*|Default: unset|
-+-----------+---------+-------------+--------------+
++-------------------------------------------------+
+|dkim_domain|Use: smtp|Type: string|Default: list*|
++-------------------------------------------------+
-MANDATORY: The domain you want to sign with. The result of this expanded option
-is put into the $dkim_domain expansion variable.
+The domain(s) you want to sign with. After expansion, this can be a list. Each
+element in turn is put into the $dkim_domain expansion variable while expanding
+the remaining signing options. If it is empty after expansion, DKIM signing is
+not done, and no error will result even if dkim_strict is set.
-+-------------+---------+-------------+--------------+
-|dkim_selector|Use: smtp|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++---------------------------------------------------+
+|dkim_selector|Use: smtp|Type: string|Default: list*|
++---------------------------------------------------+
-MANDATORY: This sets the key selector string. You can use the $dkim_domain
-expansion variable to look up a matching selector. The result is put in the
-expansion variable $dkim_selector which should be used in the dkim_private_key
-option along with $dkim_domain.
+This sets the key selector string. After expansion, which can use $dkim_domain,
+this can be a list. Each element in turn is put in the expansion variable
+$dkim_selector which may be used in the dkim_private_key option along with
+$dkim_domain. If the option is empty after expansion, DKIM signing is not done
+for this domain, and no error will result even if dkim_strict is set.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|dkim_private_key|Use: smtp|Type: string*|Default: unset|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
-MANDATORY: This sets the private key to use. You can use the $dkim_domain and
+This sets the private key to use. You can use the $dkim_domain and
$dkim_selector expansion variables to determine the private key to use. The
result can either
- * be a valid RSA private key in ASCII armor, including line breaks.
+ * be a valid RSA private key in ASCII armor (.pem file), including line
+ breaks
+
+ * with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, be a valid Ed25519 private key
+ (same format as above)
* start with a slash, in which case it is treated as a file that contains the
- private key.
+ private key
* be "0", "false" or the empty string, in which case the message will not be
signed. This case will not result in an error, even if dkim_strict is set.
-+----------+---------+-------------+--------------+
+To generate keys under OpenSSL:
+
+openssl genrsa -out dkim_rsa.private 2048
+openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM
+
+Take the base-64 lines from the output of the second command, concatenated, for
+the DNS TXT record. See section 3.6 of RFC6376 for the record specification.
+
+Under GnuTLS:
+
+certtool --generate-privkey --rsa --bits=2048 --password='' -8 --outfile=dkim_rsa.private
+certtool --load-privkey=dkim_rsa.private --pubkey-info
+
+Note that RFC 8301 says:
+
+Signers MUST use RSA keys of at least 1024 bits for all keys.
+Signers SHOULD use RSA keys of at least 2048 bits.
+
+Support for EC keys is being developed under https://datatracker.ietf.org/doc/
+draft-ietf-dcrup-dkim-crypto/. They are considerably smaller than RSA keys for
+equivalent protection. As they are a recent development, users should consider
+dual-signing (by setting a list of selectors, and an expansion for this option)
+for some transition period. The "_CRYPTO_SIGN_ED25519" macro will be defined if
+support is present for EC keys.
+
+OpenSSL 1.1.1 and GnuTLS 3.6.0 can create Ed25519 private keys:
+
+openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
+certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private
+
+To produce the required public key value for a DNS record:
+
+openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
+certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64
+
+Note that the format of Ed25519 keys in DNS has not yet been decided; this
+release supports both of the leading candidates at this time, a future release
+will probably drop support for whichever proposal loses.
+
++-------------------------------------------------+
+|dkim_hash|Use: smtp|Type: string*|Default: sha256|
++-------------------------------------------------+
+
+Can be set to any one of the supported hash methods, which are:
+
+ * "sha1" - should not be used, is old and insecure
+
+ * "sha256" - the default
+
+ * "sha512" - possibly more secure but less well supported
+
+Note that RFC 8301 says:
+
+rsa-sha1 MUST NOT be used for signing or verifying.
+
++----------------------------------------------------+
+|dkim_identity|Use: smtp|Type: string*|Default: unset|
++----------------------------------------------------+
+
+If set after expansion, the value is used to set an "i=" tag in the signing
+header. The DKIM standards restrict the permissible syntax of this optional tag
+to a mail address, with possibly-empty local part, an @, and a domain identical
+to or subdomain of the "d=" tag value. Note that Exim does not check the value.
+
++-------------------------------------------------+
|dkim_canon|Use: smtp|Type: string*|Default: unset|
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
-OPTIONAL: This option sets the canonicalization method used when signing a
-message. The DKIM RFC currently supports two methods: "simple" and "relaxed".
-The option defaults to "relaxed" when unset. Note: the current implementation
-only supports using the same canonicalization method for both headers and body.
+This option sets the canonicalization method used when signing a message. The
+DKIM RFC currently supports two methods: "simple" and "relaxed". The option
+defaults to "relaxed" when unset. Note: the current implementation only
+supports signing with the same canonicalization method for both headers and
+body.
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
|dkim_strict|Use: smtp|Type: string*|Default: unset|
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
-OPTIONAL: This option defines how Exim behaves when signing a message that
-should be signed fails for some reason. When the expansion evaluates to either
-"1" or "true", Exim will defer. Otherwise Exim will send the message unsigned.
-You can use the $dkim_domain and $dkim_selector expansion variables here.
+This option defines how Exim behaves when signing a message that should be
+signed fails for some reason. When the expansion evaluates to either "1" or
+"true", Exim will defer. Otherwise Exim will send the message unsigned. You can
+use the $dkim_domain and $dkim_selector expansion variables here.
-+-----------------+---------+-------------+--------------+
-|dkim_sign_headers|Use: smtp|Type: string*|Default: unset|
-+-----------------+---------+-------------+--------------+
++------------------------------------------------------------+
+|dkim_sign_headers|Use: smtp|Type: string*|Default: see below|
++------------------------------------------------------------+
-OPTIONAL: When set, this option must expand to (or be specified as) a
-colon-separated list of header names. Headers with these names will be included
-in the message signature. When unspecified, the header names recommended in
-RFC4871 will be used.
+If set, this option must expand to a colon-separated list of header names.
+Headers with these names, or the absence or such a header, will be included in
+the message signature. When unspecified, the header names listed in RFC4871
+will be used, whether or not each header is present in the message. The default
+list is available for the expansion in the macro "_DKIM_SIGN_HEADERS".
+If a name is repeated, multiple headers by that name (or the absence thereof)
+will be signed. The textually later headers in the headers part of the message
+are signed first, if there are multiples.
-56.2 Verifying DKIM signatures in incoming mail
+A name can be prefixed with either an '=' or a '+' character. If an '=' prefix
+is used, all headers that are present with this name will be signed. If a '+'
+prefix if used, all headers that are present with this name will be signed, and
+one signature added for a missing header with the name will be appended.
+
++-------------------------------------------------------+
+|dkim_timestamps|Use: smtp|Type: integer*|Default: unset|
++-------------------------------------------------------+
+
+This option controls the inclusion of timestamp information in the signature.
+If not set, no such information will be included. Otherwise, must be an
+unsigned number giving an offset in seconds from the current time for the
+expiry tag (eg. 1209600 for two weeks); both creation (t=) and expiry (x=) tags
+will be included.
+
+RFC 6376 lists these tags as RECOMMENDED.
+
+
+57.3 Verifying DKIM signatures in incoming mail
-----------------------------------------------
-Verification of DKIM signatures in incoming email is implemented via the
-acl_smtp_dkim ACL. By default, this ACL is called once for each syntactically
-(!) correct signature in the incoming message. A missing ACL definition
-defaults to accept. If any ACL call does not acccept, the message is not
-accepted. If a cutthrough delivery was in progress for the message it is
-summarily dropped (having wasted the transmission effort).
+Verification of DKIM signatures in SMTP incoming email is done for all messages
+for which an ACL control dkim_disable_verify has not been set. Performing
+verification sets up information used by the $authresults expansion item.
+
+The acl_smtp_dkim ACL, which can examine and modify them. By default, this ACL
+is called once for each syntactically(!) correct signature in the incoming
+message. A missing ACL definition defaults to accept. If any ACL call does not
+accept, the message is not accepted. If a cutthrough delivery was in progress
+for the message, that is summarily dropped (having wasted the transmission
+effort).
-To evaluate the signature in the ACL a large number of expansion variables
-containing the signature status and its details are set up during the runtime
-of the ACL.
+To evaluate the verification result in the ACL a large number of expansion
+variables containing the signature status and its details are set up during the
+runtime of the ACL.
Calling the ACL only for existing signatures is not sufficient to build more
advanced policies. For that reason, the global option dkim_verify_signers, and
If a domain or identity is listed several times in the (expanded) value of
dkim_verify_signers, the ACL is only called once for that domain or identity.
+If multiple signatures match a domain (or identity), the ACL is called once for
+each matching signature.
+
Inside the acl_smtp_dkim, the following expansion variables are available (from
most to least important):
$dkim_verify_status
- A string describing the general status of the signature. One of
+ Within the DKIM ACL, a string describing the general status of the
+ signature. One of
- * none: There is no signature in the message for the current domain or
+ + none: There is no signature in the message for the current domain or
identity (as reflected by $dkim_cur_signer).
- * invalid: The signature could not be verified due to a processing error.
+ + invalid: The signature could not be verified due to a processing error.
More detail is available in $dkim_verify_reason.
- * fail: Verification of the signature failed. More detail is available in
+ + fail: Verification of the signature failed. More detail is available in
$dkim_verify_reason.
- * pass: The signature passed verification. It is valid.
+ + pass: The signature passed verification. It is valid.
+
+ This variable can be overwritten using an ACL 'set' modifier. This might,
+ for instance, be done to enforce a policy restriction on hash-method or
+ key-size:
+
+ warn condition = ${if eq {$dkim_verify_status}{pass}}
+ condition = ${if eq {${length_3:$dkim_algo}}{rsa}}
+ condition = ${if or {{eq {$dkim_algo}{rsa-sha1}} \
+ {< {$dkim_key_length}{1024}}}}
+ logwrite = NOTE: forcing DKIM verify fail (was pass)
+ set dkim_verify_status = fail
+ set dkim_verify_reason = hash too weak or key too short
+
+ So long as a DKIM ACL is defined (it need do no more than accept), after
+ all the DKIM ACL runs have completed, the value becomes a colon-separated
+ list of the values after each run. This is maintained for the mime, prdr
+ and data ACLs.
$dkim_verify_reason
- A string giving a litte bit more detail when $dkim_verify_status is either
+ A string giving a little bit more detail when $dkim_verify_status is either
"fail" or "invalid". One of
- * pubkey_unavailable (when $dkim_verify_status="invalid"): The public key
+ + pubkey_unavailable (when $dkim_verify_status="invalid"): The public key
for the domain could not be retrieved. This may be a temporary problem.
- * pubkey_syntax (when $dkim_verify_status="invalid"): The public key
+ + pubkey_syntax (when $dkim_verify_status="invalid"): The public key
record for the domain is syntactically invalid.
- * bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated
+ + bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated
body hash does not match the one specified in the signature header.
This means that the message body was modified in transit.
- * signature_incorrect (when $dkim_verify_status="fail"): The signature
+ + signature_incorrect (when $dkim_verify_status="fail"): The signature
could not be verified. This may mean that headers were modified,
re-written or otherwise changed in a way which is incompatible with
DKIM verification. It may of course also mean that the signature is
forged.
+ This variable can be overwritten, with any value, using an ACL 'set'
+ modifier.
+
$dkim_domain
The signing domain. IMPORTANT: This variable is only populated if there is
$dkim_algo
- The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
+ The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. If running under
+ GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, may also be 'ed25519-sha256'. The
+ "_CRYPTO_SIGN_ED25519" macro will be defined if support is present for EC
+ keys.
+
+ Note that RFC 8301 says:
+
+ rsa-sha1 MUST NOT be used for signing or verifying.
+
+ DKIM signatures identified as having been signed with historic
+ algorithms (currently, rsa-sha1) have permanently failed evaluation
+
+ To enforce this you must have a DKIM ACL which checks this variable and
+ overwrites the $dkim_verify_status variable as discussed above.
$dkim_canon_body
The body canonicalization method. One of 'relaxed' or 'simple'.
-dkim_canon_headers
+$dkim_canon_headers
The header canonicalization method. One of 'relaxed' or 'simple'.
$dkim_copiedheaders
A transcript of headers and their values which are included in the
- signature (copied from the 'z=' tag of the signature).
+ signature (copied from the 'z=' tag of the signature). Note that RFC6376
+ requires that verification fail if the From: header is not included in the
+ signature. Exim does not enforce this; sites wishing strict enforcement
+ should code the check explicitly.
$dkim_bodylength
limit was set by the signer, "9999999999999" is returned. This makes sure
that this variable always expands to an integer value.
+ Note: The presence of the signature tag specifying a signing body length is
+ one possible route to spoofing of valid DKIM signatures. A paranoid
+ implementation might wish to regard signature where this variable shows
+ less than the "no limit" return as being invalid.
+
$dkim_created
UNIX timestamp reflecting the date and time when the signature was created.
UNIX timestamp reflecting the date and time when the signer wants the
signature to be treated as "expired". When this was not specified by the
signer, "9999999999999" is returned. This makes it possible to do useful
- integer size comparisons against this value.
+ integer size comparisons against this value. Note that Exim does not check
+ this value.
$dkim_headernames
Notes from the key record (tag n=).
+$dkim_key_length
+
+ Number of bits in the key.
+
+ Note that RFC 8301 says:
+
+ Verifiers MUST NOT consider signatures using RSA keys of
+ less than 1024 bits as valid signatures.
+
+ To enforce this you must have a DKIM ACL which checks this variable and
+ overwrites the $dkim_verify_status variable as discussed above. As EC keys
+ are much smaller, the check should only do this for RSA keys.
+
In addition, two ACL conditions are provided:
dkim_signers
verifying (reflected by $dkim_cur_signer). This is typically used to
restrict an ACL verb to a group of domains or identities. For example:
- # Warn when Mail purportedly from GMail has no signature at all
- warn log_message = GMail sender without DKIM signature
+ # Warn when Mail purportedly from GMail has no gmail signature
+ warn log_message = GMail sender without gmail.com DKIM signature
sender_domains = gmail.com
dkim_signers = gmail.com
dkim_status = none
+ Note that the above does not check for a total lack of DKIM signing; for
+ that check for empty $h_DKIM-Signature: in the data ACL.
+
dkim_status
ACL condition that checks a colon-separated list of possible DKIM
above for more information of what they mean.
+57.4 SPF (Sender Policy Framework)
+----------------------------------
+
+SPF is a mechanism whereby a domain may assert which IP addresses may transmit
+messages with its domain in the envelope from, documented by RFC 7208. For more
+information on SPF see http://www.openspf.org.
+
+Messages sent by a system not authorised will fail checking of such assertions.
+This includes retransmissions done by traditional forwarders.
+
+SPF verification support is built into Exim if SUPPORT_SPF=yes is set in Local/
+Makefile. The support uses the libspf2 library https://www.libspf2.org/. There
+is no Exim involvement in the transmission of messages; publishing certain DNS
+records is all that is required.
+
+For verification, an ACL condition and an expansion lookup are provided.
+Performing verification sets up information used by the $authresults expansion
+item.
+
+The ACL condition "spf" can be used at or after the MAIL ACL. It takes as an
+argument a list of strings giving the outcome of the SPF check, and will
+succeed for any matching outcome. Valid strings are:
+
+pass
+
+ The SPF check passed, the sending host is positively verified by SPF.
+
+fail
+
+ The SPF check failed, the sending host is NOT allowed to send mail for the
+ domain in the envelope-from address.
+
+softfail
+
+ The SPF check failed, but the queried domain can't absolutely confirm that
+ this is a forgery.
+
+none
+
+ The queried domain does not publish SPF records.
+
+neutral
+
+ The SPF check returned a "neutral" state. This means the queried domain has
+ published a SPF record, but wants to allow outside servers to send mail
+ under its domain as well. This should be treated like "none".
+
+permerror
+
+ This indicates a syntax error in the SPF record of the queried domain. You
+ may deny messages when this occurs.
+
+temperror
+
+ This indicates a temporary error during all processing, including Exim's
+ SPF processing. You may defer messages when this occurs.
+
+You can prefix each string with an exclamation mark to invert its meaning, for
+example "!fail" will match all results but "fail". The string list is evaluated
+left-to-right, in a short-circuit fashion.
+
+Example:
+
+deny spf = fail
+ message = $sender_host_address is not allowed to send mail from \
+ ${if def:sender_address_domain \
+ {$sender_address_domain}{$sender_helo_name}}. \
+ Please see http://www.openspf.org/Why?scope=\
+ ${if def:sender_address_domain {mfrom}{helo}};\
+ identity=${if def:sender_address_domain \
+ {$sender_address}{$sender_helo_name}};\
+ ip=$sender_host_address
+
+When the spf condition has run, it sets up several expansion variables:
+
+$spf_header_comment
+
+ This contains a human-readable string describing the outcome of the SPF
+ check. You can add it to a custom header or use it for logging purposes.
+
+$spf_received
+
+ This contains a complete Received-SPF: header that can be added to the
+ message. Please note that according to the SPF draft, this header must be
+ added at the top of the header list. Please see section 10 on how you can
+ do this.
+
+ Note: in case of "Best-guess" (see below), the convention is to put this
+ string in a header called X-SPF-Guess: instead.
+
+$spf_result
+
+ This contains the outcome of the SPF check in string form, one of pass,
+ fail, softfail, none, neutral, permerror or temperror.
+
+$spf_result_guessed
+
+ This boolean is true only if a best-guess operation was used and required
+ in order to obtain a result.
+
+$spf_smtp_comment
+
+ This contains a string that can be used in a SMTP response to the calling
+ party. Useful for "fail".
+
+In addition to SPF, you can also perform checks for so-called "Best-guess".
+Strictly speaking, "Best-guess" is not standard SPF, but it is supported by the
+same framework that enables SPF capability. Refer to http://www.openspf.org/FAQ
+/Best_guess_record for a description of what it means.
+
+To access this feature, simply use the spf_guess condition in place of the spf
+one. For example:
+
+deny spf_guess = fail
+ message = $sender_host_address doesn't look trustworthy to me
+
+In case you decide to reject messages based on this check, you should note that
+although it uses the same framework, "Best-guess" is not SPF, and therefore you
+should not mention SPF at all in your reject message.
+
+When the spf_guess condition has run, it sets up the same expansion variables
+as when spf condition is run, described above.
+
+Additionally, since Best-guess is not standardized, you may redefine what
+"Best-guess" means to you by redefining the main configuration spf_guess
+option. For example, the following:
+
+spf_guess = v=spf1 a/16 mx/16 ptr ?all
+
+would relax host matching rules to a broader network range.
+
+A lookup expansion is also available. It takes an email address as the key and
+an IP address as the database:
+
+ ${lookup {username@domain} spf {ip.ip.ip.ip}}
+
+The lookup will return the same result strings as can appear in $spf_result
+(pass,fail,softfail,neutral,none,err_perm,err_temp). Currently, only IPv4
+addresses are supported.
+
+
+
+===============================================================================
+58. PROXIES
+
+A proxy is an intermediate system through which communication is passed.
+Proxies may provide a security, availability or load-distribution function.
+
+
+58.1 Inbound proxies
+--------------------
+
+Exim has support for receiving inbound SMTP connections via a proxy that uses
+"Proxy Protocol" to speak to it. To include this support, include
+"SUPPORT_PROXY=yes" in Local/Makefile.
+
+It was built on the HAProxy specification, found at https://www.haproxy.org/
+download/1.8/doc/proxy-protocol.txt.
+
+The purpose of this facility is so that an application load balancer, such as
+HAProxy, can sit in front of several Exim servers to distribute load. Exim uses
+the local protocol communication with the proxy to obtain the remote SMTP
+system IP address and port information. There is no logging if a host passes or
+fails Proxy Protocol negotiation, but it can easily be determined and recorded
+in an ACL (example is below).
+
+Use of a proxy is enabled by setting the hosts_proxy main configuration option
+to a hostlist; connections from these hosts will use Proxy Protocol. Exim
+supports both version 1 and version 2 of the Proxy Protocol and automatically
+determines which version is in use.
+
+The Proxy Protocol header is the first data received on a TCP connection and is
+inserted before any TLS-on-connect handshake from the client; Exim negotiates
+TLS between Exim-as-server and the remote client, not between Exim and the
+proxy server.
+
+The following expansion variables are usable ("internal" and "external" here
+refer to the interfaces of the proxy):
+
+proxy_external_address
+ IP of host being proxied or IP of remote interface of proxy
+proxy_external_port
+ Port of host being proxied or Port on remote interface of proxy
+proxy_local_address
+ IP of proxy server inbound or IP of local interface of proxy
+proxy_local_port
+ Port of proxy server inbound or Port on local interface of proxy
+proxy_session boolean: SMTP connection via proxy
+
+If $proxy_session is set but $proxy_external_address is empty there was a
+protocol error.
+
+Since the real connections are all coming from the proxy, and the per host
+connection tracking is done before Proxy Protocol is evaluated,
+smtp_accept_max_per_host must be set high enough to handle all of the parallel
+volume you expect per inbound proxy. With the option set so high, you lose the
+ability to protect your server from many connections from one IP. In order to
+prevent your server from overload, you need to add a per connection ratelimit
+to your connect ACL. A possible solution is:
+
+ # Set max number of connections per host
+ LIMIT = 5
+ # Or do some kind of IP lookup in a flat file or database
+ # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}}
+
+ defer message = Too many connections from this IP right now
+ ratelimit = LIMIT / 5s / per_conn / strict
+
+
+58.2 Outbound proxies
+---------------------
+
+Exim has support for sending outbound SMTP via a proxy using a protocol called
+SOCKS5 (defined by RFC1928). The support can be optionally included by defining
+SUPPORT_SOCKS=yes in Local/Makefile.
+
+Use of a proxy is enabled by setting the socks_proxy option on an smtp
+transport. The option value is expanded and should then be a list
+(colon-separated by default) of proxy specifiers. Each proxy specifier is a
+list (space-separated by default) where the initial element is an IP address
+and any subsequent elements are options.
+
+Options are a string <name>=<value>. The list of options is in the following
+table:
+
+auth authentication method
+name authentication username
+pass authentication password
+port tcp port
+tmo connection timeout
+pri priority
+weight selection bias
+
+More details on each of these options follows:
+
+ * auth: Either "none" (default) or "name". Using "name" selects username/
+ password authentication per RFC 1929 for access to the proxy. Default is
+ "none".
+
+ * name: sets the username for the "name" authentication method. Default is
+ empty.
+
+ * pass: sets the password for the "name" authentication method. Default is
+ empty.
+
+ * port: the TCP port number to use for the connection to the proxy. Default
+ is 1080.
+
+ * tmo: sets a connection timeout in seconds for this proxy. Default is 5.
+
+ * pri: specifies a priority for the proxy within the list, higher values
+ being tried first. The default priority is 1.
+
+ * weight: specifies a selection bias. Within a priority set servers are
+ queried in a random fashion, weighted by this value. The default value for
+ selection bias is 1.
+
+Proxies from the list are tried according to their priority and weight settings
+until one responds. The timeout for the overall connection applies to the set
+of proxied attempts.
+
+
+58.3 Logging
+------------
+
+To log the (local) IP of a proxy in the incoming or delivery logline, add
+"+proxy" to the log_selector option. This will add a component tagged with "PRX
+=" to the line.
+
+
===============================================================================
-57. ADDING NEW DRIVERS OR LOOKUP TYPES
+59. INTERNATIONALISATION
+
+Exim has support for Internationalised mail names. To include this it must be
+built with SUPPORT_I18N and the libidn library. Standards supported are RFCs
+2060, 5890, 6530 and 6533.
+
+If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not
+instead of it) then IDNA2008 is supported; this adds an extra library
+requirement, upon libidn2.
+
+
+59.1 MTA operations
+-------------------
+
+The main configuration option smtputf8_advertise_hosts specifies a host list.
+If this matches the sending host and accept_8bitmime is true (the default) then
+the ESMTP option SMTPUTF8 will be advertised.
+
+If the sender specifies the SMTPUTF8 option on a MAIL command international
+handling for the message is enabled and the expansion variable
+$message_smtputf8 will have value TRUE.
+
+The option allow_utf8_domains is set to true for this message. All DNS lookups
+are converted to a-label form whatever the setting of allow_utf8_domains when
+Exim is built with SUPPORT_I18N.
+
+Both localparts and domain are maintained as the original UTF-8 form
+internally; any comparison or regular-expression use will require appropriate
+care. Filenames created, eg. by the appendfile transport, will have UTF-8
+names.
+
+HELO names sent by the smtp transport will have any UTF-8 components expanded
+to a-label form, and any certificate name checks will be done using the a-label
+form of the name.
+
+Log lines and Received-by: header lines will acquire a "utf8" prefix on the
+protocol element, eg. utf8esmtp.
+
+The following expansion operators can be used:
+
+${utf8_domain_to_alabel:str}
+${utf8_domain_from_alabel:str}
+${utf8_localpart_to_alabel:str}
+${utf8_localpart_from_alabel:str}
+
+The RCPT ACL may use the following modifier:
+
+control = utf8_downconvert
+control = utf8_downconvert/<value>
+
+This sets a flag requiring that addresses are converted to a-label form before
+smtp delivery, for use in a Message Submission Agent context. If a value is
+appended it may be:
+
+1 (default) mandatory downconversion
+0 no downconversion
+-1 if SMTPUTF8 not supported by destination host
+
+If mua_wrapper is set, the utf8_downconvert control is initially set to -1.
+
+The smtp transport has an option utf8_downconvert. If set it must expand to one
+of the three values described above, and it overrides any previously set value.
+
+There is no explicit support for VRFY and EXPN. Configurations supporting these
+should inspect $smtp_command_argument for an SMTPUTF8 argument.
+
+There is no support for LMTP on Unix sockets. Using the "lmtp" protocol option
+on an smtp transport, for LMTP over TCP, should work as expected.
+
+There is no support for DSN unitext handling, and no provision for converting
+logging from or to UTF-8.
+
+
+59.2 MDA operations
+-------------------
+
+To aid in constructing names suitable for IMAP folders the following expansion
+operator can be used:
+
+${imapfolder {<string>} {<sep>} {<specials>}}
+
+The string is converted from the charset specified by the "headers charset"
+command (in a filter file) or headers_charset main configuration option
+(otherwise), to the modified UTF-7 encoding specified by RFC 2060, with the
+following exception: All occurrences of <sep> (which has to be a single
+character) are replaced with periods ("."), and all periods and slashes that
+are not <sep> and are not in the <specials> string are BASE64 encoded.
+
+The third argument can be omitted, defaulting to an empty string. The second
+argument can be omitted, defaulting to "/".
+
+This is the encoding used by Courier for Maildir names on disk, and followed by
+many other IMAP servers.
+
+Examples:
+
+${imapfolder {Foo/Bar}} yields Foo.Bar
+${imapfolder {Foo/Bar}{.}{/}} yields Foo&AC8-Bar
+${imapfolder {R?ksm?rg?s}} yields R&AOQ-ksm&APY-rg&AOU-s
+
+Note that the source charset setting is vital, and also that characters must be
+representable in UTF-16.
+
+
+
+===============================================================================
+60. EVENTS
+
+The events mechanism in Exim can be used to intercept processing at a number of
+points. It was originally invented to give a way to do customised logging
+actions (for example, to a database) but can also be used to modify some
+processing actions.
+
+Most installations will never need to use Events. The support can be left out
+of a build by defining DISABLE_EVENT=yes in Local/Makefile.
+
+There are two major classes of events: main and transport. The main
+configuration option event_action controls reception events; a transport option
+event_action controls delivery events.
+
+Both options are a string which is expanded when the event fires. An example
+might look like:
+
+event_action = ${if eq {msg:delivery}{$event_name} \
+{${lookup pgsql {SELECT * FROM record_Delivery( \
+ '${quote_pgsql:$sender_address_domain}',\
+ '${quote_pgsql:${lc:$sender_address_local_part}}', \
+ '${quote_pgsql:$domain}', \
+ '${quote_pgsql:${lc:$local_part}}', \
+ '${quote_pgsql:$host_address}', \
+ '${quote_pgsql:${lc:$host}}', \
+ '${quote_pgsql:$message_exim_id}')}} \
+} {}}
+
+Events have names which correspond to the point in process at which they fire.
+The name is placed in the variable $event_name and the event action expansion
+must check this, as it will be called for every possible event type.
+
+The current list of events is:
+
+dane:fail after transport per connection
+msg:complete after main per message
+msg:delivery after transport per recipient
+msg:rcpt:host:defer after transport per recipient per host
+msg:rcpt:defer after transport per recipient
+msg:host:defer after transport per attempt
+msg:fail:delivery after transport per recipient
+msg:fail:internal after main per recipient
+tcp:connect before transport per connection
+tcp:close after transport per connection
+tls:cert before both per certificate in verification chain
+smtp:connect after transport per connection
+
+New event types may be added in future.
+
+The event name is a colon-separated list, defining the type of event in a tree
+of possibilities. It may be used as a list or just matched on as a whole. There
+will be no spaces in the name.
+
+The second column in the table above describes whether the event fires before
+or after the action is associates with. Those which fire before can be used to
+affect that action (more on this below).
+
+The third column in the table above says what section of the configuration
+should define the event action.
+
+An additional variable, $event_data, is filled with information varying with
+the event type:
+
+dane:fail failure reason
+msg:delivery smtp confirmation message
+msg:fail:internal failure reason
+msg:fail:delivery smtp error message
+msg:rcpt:host:defer error string
+msg:rcpt:defer error string
+msg:host:defer error string
+tls:cert verification chain depth
+smtp:connect smtp banner
+
+The :defer events populate one extra variable: $event_defer_errno.
+
+For complex operations an ACL expansion can be used in event_action however due
+to the multiple contexts that Exim operates in during the course of its
+processing:
+
+ * variables set in transport events will not be visible outside that
+ transport call
+
+ * acl_m variables in a server context are lost on a new connection, and after
+ smtp helo/ehlo/mail/starttls/rset commands
+
+Using an ACL expansion with the logwrite modifier can be a useful way of
+writing to the main log.
+
+The expansion of the event_action option should normally return an empty
+string. Should it return anything else the following will be forced:
+
+tcp:connect do not connect
+tls:cert refuse verification
+smtp:connect close connection
+
+All other message types ignore the result string, and no other use is made of
+it.
+
+For a tcp:connect event, if the connection is being made to a proxy then the
+address and port variables will be that of the proxy and not the target system.
+
+For tls:cert events, if GnuTLS is in use this will trigger only per chain
+element received on the connection. For OpenSSL it will trigger for every chain
+element including those loaded locally.
+
+
+
+===============================================================================
+61. ADDING NEW DRIVERS OR LOOKUP TYPES
The following actions have to be taken in order to add a new router, transport,
authenticator, or lookup type to Exim:
, src/auths, or src/lookups); add a line for the new driver or lookup type
and add it to the definition of OBJ.
- 7. Create newdriver.h and newdriver.c in the appropriate sub-directory of src.
+ 7. Edit OS/Makefile-Base adding a .o file for the predefined-macros, to the
+ definition of OBJ_MACRO. Add a set of line to do the compile also.
+
+ 8. Create newdriver.h and newdriver.c in the appropriate sub-directory of src.
- 8. Edit scripts/MakeLinks and add commands to link the .h and .c files as for
+ 9. Edit scripts/MakeLinks and add commands to link the .h and .c files as for
other drivers and lookups.
Then all you need to do is write the code! A good way to start is to make a
HCoop / hcoop / debian / exim4.git / blobdiff