Specification of the Exim Mail Transfer Agent

Philip Hazel

Revision 4.67 10 April 2007 PH

Table of Contents

1. Introduction
1.1. Exim documentation
1.2. FTP and web sites
1.3. Mailing lists
1.4. Exim training
1.5. Bug reports
1.6. Where to find the Exim distribution
1.7. Limitations
1.8. Run time configuration
1.9. Calling interface
1.10. Terminology
2. Incorporated code
3. How Exim receives and delivers mail
3.1. Overall philosophy
3.2. Policy control
3.3. User filters
3.4. Message identification
3.5. Receiving mail
3.6. Handling an incoming message
3.7. Life of a message
3.8. Processing an address for delivery
3.9. Processing an address for verification
3.10. Running an individual router
3.11. Duplicate addresses
3.12. Router preconditions
3.13. Delivery in detail
3.14. Retry mechanism
3.15. Temporary delivery failure
3.16. Permanent delivery failure
3.17. Failures to deliver bounce messages
4. Building and installing Exim
4.1. Unpacking
4.2. Multiple machine architectures and operating systems
4.3. DBM libraries
4.4. Pre-building configuration
4.5. Support for iconv()
4.6. Including TLS/SSL encryption support
4.7. Use of tcpwrappers
4.8. Including support for IPv6
4.9. The building process
4.10. Output from “make
4.11. Overriding build-time options for Exim
4.12. OS-specific header files
4.13. Overriding build-time options for the monitor
4.14. Installing Exim binaries and scripts
4.15. Installing info documentation
4.16. Setting up the spool directory
4.17. Testing
4.18. Replacing another MTA with Exim
4.19. Upgrading Exim
4.20. Stopping the Exim daemon on Solaris
5. The Exim command line
5.1. Setting options by program name
5.2. Trusted and admin users
5.3. Command line options
6. The Exim run time configuration file
6.1. Using a different configuration file
6.2. Configuration file format
6.3. File inclusions in the configuration file
6.4. Macros in the configuration file
6.5. Macro substitution
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
7. The default configuration file
7.1. Main configuration settings
7.2. ACL configuration
7.3. Router configuration
7.4. Transport configuration
7.5. Default retry rule
7.6. Rewriting configuration
7.7. Authenticators configuration
8. Regular expressions
8.1. Testing regular expressions
9. File and database lookups
9.1. Examples of different lookup syntax
9.2. Lookup types
9.3. Single-key lookup types
9.4. Query-style lookup types
9.5. Temporary errors in lookups
9.6. Default values in single-key lookups
9.7. Partial matching in single-key lookups
9.8. Lookup caching
9.9. Quoting lookup data
9.10. More about dnsdb
9.11. Pseudo dnsdb record types
9.12. Multiple dnsdb lookups
9.13. More about LDAP
9.14. Format of LDAP queries
9.15. LDAP quoting
9.16. LDAP connections
9.17. LDAP authentication and control information
9.18. Format of data returned by LDAP
9.19. More about NIS+
9.20. SQL lookups
9.21. More about MySQL, PostgreSQL, Oracle, and InterBase
9.22. Special MySQL features
9.23. Special PostgreSQL features
9.24. More about SQLite
10. Domain, host, address, and local part lists
10.1. Expansion of lists
10.2. Negated items in lists
10.3. File names in lists
10.4. An lsearch file is not an out-of-line list
10.5. Named lists
10.6. Named lists compared with macros
10.7. Named list caching
10.8. Domain lists
10.9. Host lists
10.10. Special host list patterns
10.11. Host list patterns that match by IP address
10.12. Host list patterns for single-key lookups by host address
10.13. Host list patterns that match by host name
10.14. Behaviour when an IP address or name cannot be found
10.15. Host list patterns for single-key lookups by host name
10.16. Host list patterns for query-style lookups
10.17. Mixing wildcarded host names and addresses in host lists
10.18. Address lists
10.19. Case of letters in address lists
10.20. Local part lists
11. String expansions
11.1. Literal text in expanded strings
11.2. Character escape sequences in expanded strings
11.3. Testing string expansions
11.4. Forced expansion failure
11.5. Expansion items
11.6. Expansion operators
11.7. Expansion conditions
11.8. Combining expansion conditions
11.9. Expansion variables
12. Embedded Perl
12.1. Setting up so Perl can be used
12.2. Calling Perl subroutines
12.3. Calling Exim functions from Perl
12.4. Use of standard output and error by Perl
13. Starting the daemon and the use of network interfaces
13.1. Starting a listening daemon
13.2. Special IP listening addresses
13.3. Overriding local_interfaces and daemon_smtp_ports
13.4. Support for the obsolete SSMTP (or SMTPS) protocol
13.5. IPv6 address scopes
13.6. Disabling IPv6
13.7. Examples of starting a listening daemon
13.8. Recognizing the local host
13.9. Delivering to a remote host
14. Main configuration
14.1. Miscellaneous
14.2. Exim parameters
14.3. Privilege controls
14.4. Logging
14.5. Frozen messages
14.6. Data lookups
14.7. Message ids
14.8. Embedded Perl Startup
14.9. Daemon
14.10. Resource control
14.11. Policy controls
14.12. Callout cache
14.13. TLS
14.14. Local user handling
14.15. All incoming messages (SMTP and non-SMTP)
14.16. Non-SMTP incoming messages
14.17. Incoming SMTP messages
14.18. SMTP extensions
14.19. Processing messages
14.20. System filter
14.21. Routing and delivery
14.22. Bounce and warning messages
14.23. Alphabetical list of main options
15. Generic options for routers
16. The accept router
17. The dnslookup router
17.1. Problems with DNS lookups
17.2. Private options for dnslookup
17.3. Effect of qualify_single and search_parents
18. The ipliteral router
19. The iplookup router
20. The manualroute router
20.1. Private options for manualroute
20.2. Routing rules in route_list
20.3. Routing rules in route_data
20.4. Format of the list of hosts
20.5. Format of one host item
20.6. How the list of hosts is used
20.7. How the options are used
20.8. Manualroute examples
21. The queryprogram router
22. The redirect router
22.1. Redirection data
22.2. Forward files and address verification
22.3. Interpreting redirection data
22.4. Items in a non-filter redirection list
22.5. Redirecting to a local mailbox
22.6. Special items in redirection lists
22.7. Duplicate addresses
22.8. Repeated redirection expansion
22.9. Errors in redirection lists
22.10. Private options for the redirect router
23. Environment for running local transports
23.1. Concurrent deliveries
23.2. Uids and gids
23.3. Current and home directories
23.4. Expansion variables derived from the address
24. Generic options for transports
25. Address batching in local transports
26. The appendfile transport
26.1. The file and directory options
26.2. Private options for appendfile
26.3. Operational details for appending
26.4. Operational details for delivery to a new file
26.5. Maildir delivery
26.6. Using tags to record message sizes
26.7. Using a maildirsize file
26.8. Mailstore delivery
26.9. Non-special new file delivery
27. The autoreply transport
27.1. Private options for autoreply
28. The lmtp transport
29. The pipe transport
29.1. Concurrent delivery
29.2. Returned status and data
29.3. How the command is run
29.4. Environment variables
29.5. Private options for pipe
29.6. Using an external local delivery agent
30. The smtp transport
30.1. Multiple messages on a single connection
30.2. Use of the $host variable
30.3. Private options for smtp
30.4. How the limits for the number of hosts to try are used
31. Address rewriting
31.1. Explicitly configured address rewriting
31.2. When does rewriting happen?
31.3. Testing the rewriting rules that apply on input
31.4. Rewriting rules
31.5. Rewriting patterns
31.6. Rewriting replacements
31.7. Rewriting flags
31.8. Flags specifying which headers and envelope addresses to rewrite
31.9. The SMTP-time rewriting flag
31.10. Flags controlling the rewriting process
31.11. Rewriting examples
32. Retry configuration
32.1. Changing retry rules
32.2. Format of retry rules
32.3. Choosing which retry rule to use for address errors
32.4. Choosing which retry rule to use for host and message errors
32.5. Retry rules for specific errors
32.6. Retry rules for specified senders
32.7. Retry parameters
32.8. Retry rule examples
32.9. Timeout of retry data
32.10. Long-term failures
32.11. Deliveries that work intermittently
33. SMTP authentication
33.1. Generic options for authenticators
33.2. The AUTH parameter on MAIL commands
33.3. Authentication on an Exim server
33.4. Testing server authentication
33.5. Authentication by an Exim client
34. The plaintext authenticator
34.1. Plaintext options
34.2. Using plaintext in a server
34.3. The PLAIN authentication mechanism
34.4. The LOGIN authentication mechanism
34.5. Support for different kinds of authentication
34.6. Using plaintext in a client
35. The cram_md5 authenticator
35.1. Using cram_md5 as a server
35.2. Using cram_md5 as a client
36. The cyrus_sasl authenticator
36.1. Using cyrus_sasl as a server
37. The dovecot authenticator
38. The spa authenticator
38.1. Using spa as a server
38.2. Using spa as a client
39. Encrypted SMTP connections using TLS/SSL
39.1. Support for the legacy “ssmtp” (aka “smtps”) protocol
39.2. OpenSSL vs GnuTLS
39.3. GnuTLS parameter computation
39.4. Requiring specific ciphers in OpenSSL
39.5. Requiring specific ciphers or other parameters in GnuTLS
39.6. Configuring an Exim server to use TLS
39.7. Requesting and verifying client certificates
39.8. Revoked certificates
39.9. Configuring an Exim client to use TLS
39.10. Multiple messages on the same encrypted TCP/IP connection
39.11. Certificates and all that
39.12. Certificate chains
39.13. Self-signed certificates
40. Access control lists
40.1. Testing ACLs
40.2. Specifying when ACLs are used
40.3. The non-SMTP ACLs
40.4. The SMTP connect ACL
40.5. The EHLO/HELO ACL
40.6. The DATA ACLs
40.7. The SMTP MIME ACL
40.8. The QUIT ACL
40.9. Finding an ACL to use
40.10. ACL return codes
40.11. Unset ACL options
40.12. Data for message ACLs
40.13. Data for non-message ACLs
40.14. Format of an ACL
40.15. ACL verbs
40.16. ACL variables
40.17. Condition and modifier processing
40.18. ACL modifiers
40.19. Use of the control modifier
40.20. Summary of message fixup control
40.21. Adding header lines in ACLs
40.22. ACL conditions
40.23. Using DNS lists
40.24. Specifying the IP address for a DNS list lookup
40.25. DNS lists keyed on domain names
40.26. Multiple explicit keys for a DNS list
40.27. Data returned by DNS lists
40.28. Variables set from DNS lists
40.29. Additional matching conditions for DNS lists
40.30. Negated DNS matching conditions
40.31. Handling multiple DNS records from a DNS list
40.32. Detailed information from merged DNS lists
40.33. DNS lists and IPv6
40.34. Rate limiting senders
40.35. Address verification
40.36. Callout verification
40.37. Additional parameters for callouts
40.38. Callout caching
40.39. Sender address verification reporting
40.40. Redirection while verifying
40.41. Client SMTP authorization (CSA)
40.42. Bounce address tag validation
40.43. Using an ACL to control relaying
40.44. Checking a relay configuration
41. Content scanning at ACL time
41.1. Scanning for viruses
41.2. Scanning with SpamAssassin
41.3. Calling SpamAssassin from an Exim ACL
41.4. Scanning MIME parts
41.5. Scanning with regular expressions
41.6. The demime condition
42. Adding a local scan function to Exim
42.1. Building Exim to use a local scan function
42.2. API for local_scan()
42.3. Configuration options for local_scan()
42.4. Available Exim variables
42.5. Structure of header lines
42.6. Structure of recipient items
42.7. Available Exim functions
42.8. More about Exim’s memory handling
43. System-wide message filtering
43.1. Specifying a system filter
43.2. Testing a system filter
43.3. Contents of a system filter
43.4. Additional variable for system filters
43.5. Defer, freeze, and fail commands for system filters
43.6. Adding and removing headers in a system filter
43.7. Setting an errors address in a system filter
43.8. Per-address filtering
44. Message processing
44.1. Submission mode for non-local messages
44.2. Line endings
44.3. Unqualified addresses
44.4. The UUCP From line
44.5. Resent- header lines
44.6. The Auto-Submitted: header line
44.7. The Bcc: header line
44.8. The Date: header line
44.9. The Delivery-date: header line
44.10. The Envelope-to: header line
44.11. The From: header line
44.12. The Message-ID: header line
44.13. The Received: header line
44.14. The References: header line
44.15. The Return-path: header line
44.16. The Sender: header line
44.17. Adding and removing header lines in routers and transports
44.18. Constructed addresses
44.19. Case of local parts
44.20. Dots in local parts
44.21. Rewriting addresses
45. SMTP processing
45.1. Outgoing SMTP and LMTP over TCP/IP
45.2. Errors in outgoing SMTP
45.3. Incoming SMTP messages over TCP/IP
45.4. Unrecognized SMTP commands
45.5. Syntax and protocol errors in SMTP commands
45.6. Use of non-mail SMTP commands
45.7. The VRFY and EXPN commands
45.8. The ETRN command
45.9. Incoming local SMTP
45.10. Outgoing batched SMTP
45.11. Incoming batched SMTP
46. Customizing bounce and warning messages
46.1. Customizing bounce messages
46.2. Customizing warning messages
47. Some common configuration settings
47.1. Sending mail to a smart host
47.2. Using Exim to handle mailing lists
47.3. Syntax errors in mailing lists
47.4. Re-expansion of mailing lists
47.5. Closed mailing lists
47.6. Variable Envelope Return Paths (VERP)
47.7. Virtual domains
47.8. Multiple user mailboxes
47.9. Simplified vacation processing
47.10. Taking copies of mail
47.11. Intermittently connected hosts
47.12. Exim on the upstream server host
47.13. Exim on the intermittently connected client host
48. Using Exim as a non-queueing client
49. Log files
49.1. Where the logs are written
49.2. Logging to local files that are periodically “cycled
49.3. Datestamped log files
49.4. Logging to syslog
49.5. Log line flags
49.6. Logging message reception
49.7. Logging deliveries
49.8. Discarded deliveries
49.9. Deferred deliveries
49.10. Delivery failures
49.11. Fake deliveries
49.12. Completion
49.13. Summary of Fields in Log Lines
49.14. Other log entries
49.15. Reducing or increasing what is logged
49.16. Message log
50. Exim utilities
50.1. Finding out what Exim processes are doing (exiwhat)
50.2. Selective queue listing (exiqgrep)
50.3. Summarizing the queue (exiqsumm)
50.4. Extracting specific information from the log (exigrep)
50.5. Selecting messages by various criteria (exipick)
50.6. Cycling log files (exicyclog)
50.7. Mail statistics (eximstats)
50.8. Checking access policy (exim_checkaccess)
50.9. Making DBM files (exim_dbmbuild)
50.10. Finding individual retry times (exinext)
50.11. Hints database maintenance
50.12. exim_dumpdb
50.13. exim_tidydb
50.14. exim_fixdb
50.15. Mailbox maintenance (exim_lock)
51. The Exim monitor
51.1. Running the monitor
51.2. The stripcharts
51.3. Main action buttons
51.4. The log display
51.5. The queue display
51.6. The queue menu
52. Security considerations
52.1. Building a more “hardened” Exim
52.2. Root privilege
52.3. Running Exim without privilege
52.4. Delivering to local files
52.5. IPv4 source routing
52.6. The VRFY, EXPN, and ETRN commands in SMTP
52.7. Privileged users
52.8. Spool files
52.9. Use of argv[0]
52.10. Use of %f formatting
52.11. Embedded Exim path
52.12. Use of sprintf()
52.13. Use of debug_printf() and log_write()
52.14. Use of strcat() and strcpy()
53. Format of spool files
53.1. Format of the -H file
54. Adding new drivers or lookup types
Index