Specification of the Exim Mail Transfer Agent

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. Specifying the server in the query

9.23. Special MySQL features

9.24. Special PostgreSQL features

9.25. 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. Temporary DNS errors when looking up host information

10.16. Host list patterns for single-key lookups by host name

10.17. Host list patterns for query-style lookups

10.18. Mixing wildcarded host names and addresses in host lists

10.19. Address lists

10.20. Case of letters in address lists

10.21. 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 and $host_address variables

30.3. Use of $tls_cipher and $tls_peerdn

30.4. Private options for smtp

30.5. 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. The not-QUIT ACL

40.10. Finding an ACL to use

40.11. ACL return codes

40.12. Unset ACL options

40.13. Data for message ACLs

40.14. Data for non-message ACLs

40.15. Format of an ACL

40.16. ACL verbs

40.17. ACL variables

40.18. Condition and modifier processing

40.19. ACL modifiers

40.20. Use of the control modifier

40.21. Summary of message fixup control

40.22. Adding header lines in ACLs

40.23. ACL conditions

40.24. Using DNS lists

40.25. Specifying the IP address for a DNS list lookup

40.26. DNS lists keyed on domain names

40.27. Multiple explicit keys for a DNS list

40.28. Data returned by DNS lists

40.29. Variables set from DNS lists

40.30. Additional matching conditions for DNS lists

40.31. Negated DNS matching conditions

40.32. Handling multiple DNS records from a DNS list

40.33. Detailed information from merged DNS lists

40.34. DNS lists and IPv6

40.35. Rate limiting incoming messages

40.36. Ratelimit options for what is being measured

40.37. Ratelimit options for handling fast clients

40.38. Using rate limiting

40.39. Reading ratelimit data without updating

40.40. Address verification

40.41. Callout verification

40.42. Additional parameters for callouts

40.43. Callout caching

40.44. Sender address verification reporting

40.45. Redirection while verifying

40.46. Client SMTP authorization (CSA)

40.47. Bounce address tag validation

40.48. Using an ACL to control relaying

40.49. 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