Exim Maintainers
-Copyright (c) 2014 University of Cambridge
+Copyright (c) 2017 University of Cambridge
+
+Revision 4.89 07 Mar 2017 EM
-+-----------------------------------------------------------------------------+
-+-------------------------------------+--------------------------------+------+
-|Revision 4.84 |11 Aug 2014 |EM |
-+-------------------------------------+--------------------------------+------+
-------------------------------------------------------------------------------
TABLE OF CONTENTS
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
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
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 legacy "ssmtp" (aka "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
+
+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
+
+57. Support for DKIM (DomainKeys Identified Mail)
+
+ 57.1. Signing outgoing messages
+ 57.2. Verifying DKIM signatures in incoming mail
+
+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
1.1 Exim documentation
----------------------
-This edition of the Exim specification applies to version 4.84 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.89 of Exim.
+Substantive changes from the 4.88 edition are marked in some renditions of the
document; this paragraph is so marked if the rendition is capable of showing a
change indicator.
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
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.
(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
+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 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
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
spool files when processing of a message is complete. The use of individual
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
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
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) into which the following files are placed:
+exim-4.89) into which the following files are placed:
ACKNOWLEDGMENTS contains some acknowledgments
CHANGES contains a reference to where changes are documented
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
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/
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.
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
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-1. The script then arranges for a symbolic link called
+for example exim-4.89-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).
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
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 run time
+ 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.
authenticator_list, and a complete list of all drivers with their option
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 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
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.
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
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
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
+
+ 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 option.
+
-MCP
This option is not intended for use by external callers. It is used
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.
-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>
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
+ process exits. See chapter 51 for a way of setting up a restricted
configuration that never queues messages.
-odi
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
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
be done. If a message requires any remote deliveries, it remains on 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.
+
===============================================================================
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.
on a line by itself. Double quotes round the file name 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 file name 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
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
+ _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,
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:
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:
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
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
+
+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.2 ACL configuration
---------------------
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.
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
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
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
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.
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.
+ 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.
+
+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.11 Pseudo dnsdb record types
+
+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
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}}
+
+
===============================================================================
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
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.
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
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
${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
The difference between rheader, bheader, and header 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
+ + 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
filter. Header lines that are added to a particular copy of a message by a
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.
+ For incoming SMTP messages, no header lines are visible in
+
+ ACLs that are 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
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
${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
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>}}
${readsocket{<name>}{<request>}{<timeout>}{<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}}
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
yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of
the regular expression from string expansion.
+${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. 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
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>
# exim -be '${addresses:From: "Last, First" <user@example.com>}'
user@example.com
+${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>}
The string must consist entirely of decimal digits. The number is converted
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
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>}
This forces the letters in the string into lower-case, for example:
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
${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.
+
+${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.
- 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.
+ 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.
${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>}
This replaces any invalid utf-8 sequence in the string by the character "?
".
+${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 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.
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 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
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
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
been compiled. This serves to distinguish different compilations of the
same version of the program.
-$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_cur_signer, $dkim_verify_status, $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
+ chapter 57.
+
+$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
+ chapter 57.
$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>
$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".
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
$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
$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
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
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
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.
$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.
$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.
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.
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.20. 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 ; \
* 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
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
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
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
+chapter 57 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. 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.
+
++----------------------------------------------------+
+|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
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 chapter 57.
+
++--------------------------------------------------------------------+
|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_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
See http://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
manually. The option is overridden if a message delivery is forced with the -M,
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
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
+impose any security risk. Keep in mind that during the startup phase Exim is
+running with an effective UID 0 in most installations. As the default value is
+an empty list, the default environment for using libraries, running embedded
+Perl code, or running external binaries is empty, and does not not even contain
+PATH or HOME.
+
+Actually the list is interpreted as a list of patterns (10.1), except that it
+is not expanded first.
+
+WARNING: Macro substitution is still done first, so having a macro FOO and
+having FOO_HOME in your keep_environment option may have unexpected results.
+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 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
the event of failure to negotiate TLS, the action taken is controlled by
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
+name. If no specific path is set for the log files at compile or run time, or
+if the option is unset at run time (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: main|Type: string list|Default: +no_sslv2 +single_dh_use|
++-----------------------------------------------------------------------------+
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.
-+--------------+---------+------------+------------------+
++--------------------------------------------------------+
|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.
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
|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
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
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
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
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
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
-+-------------+---------+------------+------------------+
++--------------------------------------------------------------+
+|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: see below|
-+-------------+---------+------------+------------------+
++-------------------------------------------------------+
This option is available when Exim is compiled with the content-scanning
extension. It specifies how Exim connects to SpamAssassin's spamd daemon. The
127.0.0.1 783
-See section 43.2 for more details.
+See section 44.2 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
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.
-+-------------------+---------+----------+-----------+
++----------------------------------------------------+
|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
messages remain on 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|
-+---------------+---------+-------------+--------------+
++------------------------------------------------------+
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
+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
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.
-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_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.
+
+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).
+
++---------------------------------------------------------------+
|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
details, see section 13.4.
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
|tls_privatekey|Use: main|Type: string*|Default: unset|
-+--------------+---------+-------------+--------------+
++-----------------------------------------------------+
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.
+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 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 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 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
+. 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.20), 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), 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), 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.
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.
------------------------------
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.
-
-+----------------------+--------------+------------------+--------------+
-|dnssec_require_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. 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.
+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.
-+----------+--------------+------------------+--------------+
++-----------------------------------------------------------+
|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>
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.
+described in section 6.20.
If the list of hosts was obtained from a route_list item, the following
variables are set during its expansion:
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
---------------------
* 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
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
configured transport. This should normally be an appendfile transport. When it
is running, the file name 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), 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); 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
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
names 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
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".
-+------------------+---------------+-------------+-------------+
++--------------------------------------------------------------+
|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
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
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
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
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:
++---------------------------------------------------+
+|path|Use: pipe|Type: string*|Default: /bin:/usr/bin|
++---------------------------------------------------+
-/bin:/usr/bin
+This option is expanded and
-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.
+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.
-+------------+---------+----------+-----------+
++---------------------------------------------+
|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_domain|Use: smtp|Type: string*|Default: unset|
++--------------------------------------------------+
+
++----------------------------------------------------+
+|dkim_selector|Use: smtp|Type: string*|Default: unset|
++----------------------------------------------------+
+
++-------------------------------------------------------+
+|dkim_private_key|Use: smtp|Type: string*|Default: unset|
++-------------------------------------------------------+
+
++-------------------------------------------------+
+|dkim_canon|Use: smtp|Type: string*|Default: unset|
++-------------------------------------------------+
+
++--------------------------------------------------+
+|dkim_strict|Use: smtp|Type: string*|Default: unset|
++--------------------------------------------------+
+
++--------------------------------------------------------+
+|dkim_sign_headers|Use: smtp|Type: string*|Default: unset|
++--------------------------------------------------------+
+
+DKIM signing options. For details see section 57.1.
+
++--------------------------------------------------------+
|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_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_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_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.
+
++----------------------------------------------------+
+|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
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
"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.
-+--------+---------+------------+-------------+
++---------------------------------------------+
|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.
-+------------------------+---------+-------------+-------------+
-|retry_include_ip_address|Use: smtp|Type: boolean|Default: true|
-+------------------------+---------+-------------+-------------+
++---------------------------------------------------------------+
+|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: *|
++---------------------------------------------------------------+
+
+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.
+
+There is no equivalent checking on client certificates.
+
++---------------------------------------------------------------+
+|tls_verify_certificates|Use: smtp|Type: string*|Default: system|
++---------------------------------------------------------------+
-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.
+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.
-For back-compatability, if neither tls_verify_hosts nor tls_try_verify_hosts
-are set and certificate verification fails the TLS connection is closed.
+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.
-+----------------+---------+----------------------+--------+
-|tls_verify_hosts|Use: smtp|Type: host list* unset|Default:|
-+----------------+---------+----------------------+--------+
+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.
-This option gives a list of hosts for which. on encrypted connections,
+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.
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
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.
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
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
refer to it subsequently during delivery of the message. 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
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 on and the
+transport running. For example, with a manualroute router given a host name,
+and DNS "round-robin" use 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
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.
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
authentication. The public_name option must specify an authentication mechanism
particular new authentication mechanism will be supported without code changes
in Exim.
-+---------------------+----------+-------------+--------------+
++-------------------------------------------------------------+
|server_channelbinding|Use: gsasl|Type: boolean|Default: false|
-+---------------------+----------+-------------+--------------+
++-------------------------------------------------------------+
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
option causes some clients to start failing. Some future release of Exim may
switch the default to be true.
-+---------------+----------+-------------+------------------+
++-----------------------------------------------------------+
|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 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 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 the client cert is on the
+wire in-clear, including the SAN, whereas a 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 legacy "ssmtp" (aka "smtps") protocol
----------------------------------------------------------
Early implementations of encrypted SMTP used a different TCP port from normal
tls_on_connect_ports; it forces the legacy 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
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
{HIGH:!MD5:!SHA1}}
-41.5 Requiring specific ciphers or other parameters in GnuTLS
+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
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.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 http://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
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.
+
+Further protection requires some further configuration at the server end.
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,
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.
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.
+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,
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, must name a file or, for OpenSSL only (not GnuTLS), 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
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
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
http://www.rtfm.com/openssl-examples/
-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
===============================================================================
-42. ACCESS CONTROL LISTS
+43. ACCESS CONTROL LISTS
Access Control Lists (ACLs) are defined in a separate section of the run time
configuration file, headed by "begin acl". Each ACL definition starts with a
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 chapter 57.
-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
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.
+ 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
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):
+ Logging 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 chapter 57.
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
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).
-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
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,
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
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
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
rejections of MAIL and rejections of RCPT in callouts.
-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
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
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
+before use. The usual list-parsing of the content (see 6.20) applies. The
following scanner types are supported in this release:
+avast
+
+ This is the scanner daemon of Avast. It has been tested with Avast Core
+ Security (currently at version 1.1.7). You can get a trial version at http:
+ //www.avast.com or for Linux at http://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. Any further options are given, on
+ separate lines, to the daemon as options before the main scan command. For
+ example:
+
+ av_scanner = avast:/var/run/avast/scan.sock: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
+
aveserver
This is the scanner daemon of Kaspersky Version 5. You can get a trial
This daemon-type scanner is GPL and free. You can get it at http://
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
+ "local" option, 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
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 (http://www.sald.com/) 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 show above are used.
+
fsecure
The F-Secure daemon scanner (http://www.f-secure.com) takes one argument
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:
+ 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:
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).
-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 "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 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 http://spamassassin.apache.org and
+http://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 387
-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:
+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.
+
+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 file name
+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):
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; 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
-Warning: It is not possible to use the UNIX socket connection method with
-multiple spamd servers.
+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.
+
+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
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
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:
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
-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
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
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
configured amount of time, Exim sends a message to the original sender, or to
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
===============================================================================
-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
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
used).
-49.7 Virtual domains
+50.7 Virtual domains
--------------------
The phrase virtual domain is unfortunately used with two rather different
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
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
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 run time, or if you unset the
+option at run time (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.
+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
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
CV certificate verification status
D duration of "no mail in SMTP session"
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
+K CHUNKING extension used
id message id 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
+S size of message in bytes
SNI server name indication from TLS client hello
ST shadow transport name
T on <= lines: message subject (topic)
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.
-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
deliver_time time taken to perform delivery
delivery_size add S=nnn to => lines
*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)
+ 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
+ proxy proxy address on <= and => lines
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,
* 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.
+ * 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.
* 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,
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.
-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
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.
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
ToolExipickManPage or 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:
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
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
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.
===============================================================================
-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
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
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
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
===============================================================================
-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
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
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
files.
-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
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.
attempt.
-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
===============================================================================
-56. SUPPORT FOR DKIM (DOMAINKEYS IDENTIFIED MAIL)
+57. SUPPORT FOR 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.
-Since version 4.70, DKIM support is compiled into Exim by default. It can be
-disabled by setting DISABLE_DKIM=yes in Local/Makefile.
+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.
-Exim's DKIM implementation allows to
+Exim's DKIM implementation allows for
- 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.
+ 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. Verify signatures in incoming messages: This is implemented by an
+ 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.
accept mail from relay sources (internal hosts or authenticated senders).
-56.1 Signing outgoing messages
+57.1 Signing outgoing messages
------------------------------
-Signing is implemented by setting private options on the SMTP transport. These
+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|
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
MANDATORY: The domain you want to sign with. The result of this expanded option
-is put into the $dkim_domain expansion variable.
+is put into the $dkim_domain expansion variable. If it is empty after
+expansion, DKIM signing is not done.
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
|dkim_selector|Use: smtp|Type: string*|Default: unset|
-+-------------+---------+-------------+--------------+
++----------------------------------------------------+
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
+expansion variable $dkim_selector which may be used in the dkim_private_key
option along with $dkim_domain.
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
|dkim_private_key|Use: smtp|Type: string*|Default: unset|
-+----------------+---------+-------------+--------------+
++-------------------------------------------------------+
MANDATORY: 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
* 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.
-+----------+---------+-------------+--------------+
++-------------------------------------------------+
|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.
-+-----------+---------+-------------+--------------+
++--------------------------------------------------+
|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.
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
|dkim_sign_headers|Use: smtp|Type: string*|Default: unset|
-+-----------------+---------+-------------+--------------+
++--------------------------------------------------------+
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
RFC4871 will be used.
-56.2 Verifying DKIM signatures in incoming mail
+57.2 Verifying DKIM signatures in incoming mail
-----------------------------------------------
-Verification of DKIM signatures in incoming email is implemented via the
+Verification of DKIM signatures in SMTP 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
+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 it is
summarily dropped (having wasted the transmission effort).
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.
$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
$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
Notes from the key record (tag n=).
+$dkim_key_length
+
+ Number of bits in the key.
+
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
===============================================================================
-57. ADDING NEW DRIVERS OR LOOKUP TYPES
+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 specifications from: (http://haproxy.1wt.eu/download/1.5/doc/
+proxy-protocol.txt). That URL was revised in May 2014 to version 2 spec: (http:
+//git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e).
+
+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.
+
+
+
+===============================================================================
+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}
+
+ACLs 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.
+
+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 occurences 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:
+
+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 main 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).
+
+An additional variable, $event_data, is filled with information varying with
+the event type:
+
+msg:delivery smtp confirmation 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:
+
+msg:delivery (ignored)
+msg:host:defer (ignored)
+msg:fail:delivery (ignored)
+tcp:connect do not connect
+tcp:close (ignored)
+tls:cert refuse verification
+smtp:connect close connection
+
+No other use is made of the result string.
+
+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:
HCoop / hcoop / debian / exim4.git / blobdiff