Specification of the Exim MailTransfer Agent

Exim Maintainers

Specification of the Exim Mail Transfer Agent

Author: Exim Maintainers

Copyright © 2020 University of Cambridge

Revision 4.94 01 Jun 2020

Contents

1. Introduction .................................................................................................................................. 1 1.1 Exim documentation .............................................................................................................. 1 1.2 FTP site and websites ........................................................................................................... 2 1.3 Mailing lists .............................................................................................................................. 2 1.4 Bug reports .............................................................................................................................. 3 1.5 Where to find the Exim distribution ...................................................................................... 3 1.6 Limitations ............................................................................................................................... 4 1.7 Runtime configuration ............................................................................................................ 4 1.8 Calling interface ...................................................................................................................... 4 1.9 Terminology ............................................................................................................................. 4 2. Incorporated code ...................................................................................................................... 6 3. How Exim receives and delivers mail ................................................................................... 8 3.1 Overall philosophy .................................................................................................................. 8 3.2 Policy control ........................................................................................................................... 8 3.3 User filters ............................................................................................................................... 8 3.4 Message identification ........................................................................................................... 9 3.5 Receiving mail ........................................................................................................................ 9 3.6 Handling an incoming message ........................................................................................ 10 3.7 Life of a message ................................................................................................................. 10 3.8 Processing an address for delivery ................................................................................... 11 3.9 Processing an address for verification .............................................................................. 12 3.10 Running an individual router ............................................................................................ 12 3.11 Duplicate addresses .......................................................................................................... 13 3.12 Router preconditions ......................................................................................................... 13 3.13 Delivery in detail ................................................................................................................. 14 3.14 Retry mechanism ............................................................................................................... 15 3.15 Temporary delivery failure ................................................................................................ 15 3.16 Permanent delivery failure ................................................................................................ 15 3.17 Failures to deliver bounce messages ............................................................................. 16 4. Building and installing Exim ................................................................................................. 17 4.1 Unpacking ............................................................................................................................. 17 4.2 Multiple machine architectures and operating systems ................................................. 17 4.3 PCRE library ......................................................................................................................... 17 4.4 DBM libraries ........................................................................................................................ 17 4.5 Pre-building configuration ................................................................................................... 19 4.6 Support for iconv() ............................................................................................................... 19 4.7 Including TLS/SSL encryption support ............................................................................. 19 4.8 Use of tcpwrappers .............................................................................................................. 20 4.9 Including support for IPv6 ................................................................................................... 21 4.10 Dynamically loaded lookup module support .................................................................. 21 4.11 The building process ......................................................................................................... 21 4.12 Output from “make” ........................................................................................................... 21 4.13 Overriding build-time options for Exim ............................................................................ 22 4.14 OS-specific header files .................................................................................................... 23 4.15 Overriding build-time options for the monitor ................................................................ 24 4.16 Installing Exim binaries and scripts ................................................................................. 24 4.17 Installing info documentation ........................................................................................... 25 4.18 Setting up the spool directory .......................................................................................... 25 4.19 Testing ................................................................................................................................. 25

iii

4.20 Replacing another MTA with Exim .................................................................................. 26 4.21 Upgrading Exim .................................................................................................................. 27 4.22 Stopping the Exim daemon on Solaris ........................................................................... 27 5. The Exim command line ......................................................................................................... 28 5.1 Setting options by program name ...................................................................................... 28 5.2 Trusted and admin users .................................................................................................... 28 5.3 Command line options ........................................................................................................ 29 6. The Exim runtime configuration file .................................................................................... 52 6.1 Using a different configuration file ..................................................................................... 52 6.2 Configuration file format ...................................................................................................... 53 6.3 File inclusions in the configuration file .............................................................................. 54 6.4 Macros in the configuration file .......................................................................................... 54 6.5 Macro substitution ................................................................................................................ 54 6.6 Redefining macros ............................................................................................................... 55 6.7 Overriding macro values ..................................................................................................... 55 6.8 Example of macro usage .................................................................................................... 55 6.9 Builtin macros ....................................................................................................................... 55 6.10 Conditional skips in the configuration file ....................................................................... 56 6.11 Common option syntax ..................................................................................................... 56 6.12 Boolean options ................................................................................................................. 56 6.13 Integer values ..................................................................................................................... 57 6.14 Octal integer values ........................................................................................................... 57 6.15 Fixed point numbers .......................................................................................................... 57 6.16 Time intervals ..................................................................................................................... 57 6.17 String values ....................................................................................................................... 57 6.18 Expanded strings ............................................................................................................... 58 6.19 User and group names ..................................................................................................... 58 6.20 List construction ................................................................................................................. 58 6.21 Changing list separators ................................................................................................... 58 6.22 Empty items in lists ............................................................................................................ 59 6.23 Format of driver configurations ........................................................................................ 59 7. The default configuration file ................................................................................................ 61 7.1 Macros ................................................................................................................................... 61 7.2 Main configuration settings ................................................................................................. 61 7.3 ACL configuration ................................................................................................................. 64 7.4 Router configuration ............................................................................................................ 67 7.5 Transport configuration ........................................................................................................ 70 7.6 Default retry rule ................................................................................................................... 72 7.7 Rewriting configuration ........................................................................................................ 72 7.8 Authenticators configuration ............................................................................................... 72 8. Regular expressions ................................................................................................................ 74 9. File and database lookups ..................................................................................................... 75 9.1 Examples of different lookup syntax ................................................................................. 75 9.2 Lookup types ........................................................................................................................ 76 9.3 Single-key lookup types ...................................................................................................... 76 9.4 Query-style lookup types .................................................................................................... 79 9.5 Temporary errors in lookups ............................................................................................... 80 9.6 Default values in single-key lookups ................................................................................. 80 9.7 Partial matching in single-key lookups .............................................................................. 80

iv

9.8 Lookup caching .................................................................................................................... 82 9.9 Quoting lookup data ............................................................................................................ 82 9.10 More about dnsdb .............................................................................................................. 82 9.11 Dnsdb lookup modifiers .................................................................................................... 83 9.12 Pseudo dnsdb record types ............................................................................................. 84 9.13 Multiple dnsdb lookups ..................................................................................................... 84 9.14 More about LDAP .............................................................................................................. 84 9.15 Format of LDAP queries ................................................................................................... 85 9.16 LDAP quoting ...................................................................................................................... 85 9.17 LDAP connections ............................................................................................................. 86 9.18 LDAP authentication and control information ................................................................ 87 9.19 Format of data returned by LDAP ................................................................................... 88 9.20 More about NIS+ ................................................................................................................ 89 9.21 SQL lookups ....................................................................................................................... 89 9.22 More about MySQL, PostgreSQL, Oracle, InterBase, and Redis .............................. 90 9.23 Specifying the server in the query ................................................................................... 90 9.24 Special MySQL features ................................................................................................... 91 9.25 Special PostgreSQL features ........................................................................................... 91 9.26 More about SQLite ............................................................................................................ 92 9.27 More about Redis .............................................................................................................. 92 10. Domain, host, address, and local part lists .................................................................... 93 10.1 Expansion of lists ............................................................................................................... 93 10.2 Negated items in lists ........................................................................................................ 93 10.3 File names in lists .............................................................................................................. 94 10.4 An lsearch file is not an out-of-line list ............................................................................ 94 10.5 Results of list checking ..................................................................................................... 94 10.6 Named lists ......................................................................................................................... 95 10.7 Named lists compared with macros ................................................................................ 96 10.8 Named list caching ............................................................................................................ 96 10.9 Domain lists ........................................................................................................................ 96 10.10 Host lists ............................................................................................................................ 99 10.11 Special host list patterns ................................................................................................ 99 10.12 Host list patterns that match by IP address ................................................................. 99 10.13 Host list patterns for single-key lookups by host address ....................................... 100 10.14 Host list patterns that match by host name ............................................................... 101 10.15 Behaviour when an IP address or name cannot be found ...................................... 102 10.16 Mixing wildcarded host names and addresses in host lists .................................... 102 10.17 Temporary DNS errors when looking up host information ...................................... 102 10.18 Host list patterns for single-key lookups by host name ........................................... 103 10.19 Host list patterns for query-style lookups .................................................................. 103 10.20 Address lists ................................................................................................................... 103 10.21 Case of letters in address lists .................................................................................... 106 10.22 Local part lists ................................................................................................................ 106 11. String expansions ................................................................................................................ 107 11.1 Literal text in expanded strings ...................................................................................... 107 11.2 Character escape sequences in expanded strings .................................................... 107 11.3 Testing string expansions ............................................................................................... 107 11.4 Forced expansion failure ................................................................................................ 108 11.5 Expansion items .............................................................................................................. 108 11.6 Expansion operators ....................................................................................................... 120 11.7 Expansion conditions ...................................................................................................... 127 11.8 Combining expansion conditions .................................................................................. 134 11.9 Expansion variables ........................................................................................................ 135

v

12. Embedded Perl ...................................................................................................................... 155 12.1 Setting up so Perl can be used ..................................................................................... 155 12.2 Calling Perl subroutines .................................................................................................. 155 12.3 Calling Exim functions from Perl ................................................................................... 156 12.4 Use of standard output and error by Perl ..................................................................... 156 13. Starting the daemon and the use of network interfaces ........................................... 157 13.1 Starting a listening daemon ........................................................................................... 157 13.2 Special IP listening addresses ...................................................................................... 158 13.3 Overriding local_interfaces and daemon_smtp_ports ............................................... 158 13.4 Support for the submissions (aka SSMTP or SMTPS) protocol .............................. 158 13.5 IPv6 address scopes ....................................................................................................... 159 13.6 Disabling IPv6 .................................................................................................................. 159 13.7 Examples of starting a listening daemon ..................................................................... 159 13.8 Recognizing the local host ............................................................................................. 160 13.9 Delivering to a remote host ............................................................................................ 160 14. Main configuration ............................................................................................................... 161 14.1 Miscellaneous .................................................................................................................. 161 14.2 Exim parameters .............................................................................................................. 161 14.3 Privilege controls ............................................................................................................. 161 14.4 Logging .............................................................................................................................. 162 14.5 Frozen messages ............................................................................................................ 162 14.6 Data lookups .................................................................................................................... 162 14.7 Message ids ..................................................................................................................... 162 14.8 Embedded Perl Startup .................................................................................................. 162 14.9 Daemon ............................................................................................................................. 162 14.10 Resource control ........................................................................................................... 163 14.11 Policy controls ................................................................................................................ 163 14.12 Callout cache ................................................................................................................. 164 14.13 TLS .................................................................................................................................. 164 14.14 Local user handling ....................................................................................................... 164 14.15 All incoming messages (SMTP and non-SMTP) ...................................................... 165 14.16 Non-SMTP incoming messages ................................................................................. 165 14.17 Incoming SMTP messages .......................................................................................... 165 14.18 SMTP extensions .......................................................................................................... 166 14.19 Processing messages .................................................................................................. 166 14.20 System filter .................................................................................................................... 166 14.21 Routing and delivery ..................................................................................................... 166 14.22 Bounce and warning messages .................................................................................. 167 14.23 Alphabetical list of main options .................................................................................. 167 15. Generic options for routers ............................................................................................... 217 16. The accept router ................................................................................................................. 232 17. The dnslookup router ......................................................................................................... 233 17.1 Problems with DNS lookups .......................................................................................... 233 17.2 Declining addresses by dnslookup ............................................................................... 233 17.3 Private options for dnslookup ........................................................................................ 234 17.4 Effect of qualify_single and search_parents ............................................................... 236 18. The ipliteral router ............................................................................................................... 237

vi

19. The iplookup router ............................................................................................................. 238 20. The manualroute router ...................................................................................................... 240 20.1 Private options for manualroute .................................................................................... 240 20.2 Routing rules in route_list ............................................................................................... 241 20.3 Routing rules in route_data ............................................................................................ 242 20.4 Format of the list of hosts ............................................................................................... 242 20.5 Format of one host item .................................................................................................. 243 20.6 How the list of hosts is used .......................................................................................... 243 20.7 How the options are used ............................................................................................... 244 20.8 Manualroute examples .................................................................................................... 244 21. The queryprogram router ................................................................................................... 247 22. The redirect router ............................................................................................................... 249 22.1 Redirection data ............................................................................................................... 249 22.2 Forward files and address verification .......................................................................... 250 22.3 Interpreting redirection data ........................................................................................... 250 22.4 Items in a non-filter redirection list ................................................................................ 250 22.5 Redirecting to a local mailbox ........................................................................................ 250 22.6 Special items in redirection lists .................................................................................... 251 22.7 Duplicate addresses ........................................................................................................ 253 22.8 Repeated redirection expansion ................................................................................... 253 22.9 Errors in redirection lists ................................................................................................. 253 22.10 Private options for the redirect router ......................................................................... 254 23. Environment for running local transports ..................................................................... 262 23.1 Concurrent deliveries ...................................................................................................... 262 23.2 Uids and gids .................................................................................................................... 262 23.3 Current and home directories ........................................................................................ 263 23.4 Expansion variables derived from the address ........................................................... 263 24. Generic options for transports ......................................................................................... 264 25. Address batching in local transports ............................................................................. 271 26. The appendfile transport .................................................................................................... 273 26.1 The file and directory options ........................................................................................ 273 26.2 Private options for appendfile ........................................................................................ 274 26.3 Operational details for appending ................................................................................. 283 26.4 Operational details for delivery to a new file ................................................................ 285 26.5 Maildir delivery ................................................................................................................. 285 26.6 Using tags to record message sizes ............................................................................. 286 26.7 Using a maildirsize file .................................................................................................... 287 26.8 Mailstore delivery ............................................................................................................. 287 26.9 Non-special new file delivery ......................................................................................... 287 27. The autoreply transport ...................................................................................................... 288 27.1 Private options for autoreply .......................................................................................... 288 28. The lmtp transport ............................................................................................................... 291 29. The pipe transport ............................................................................................................... 293

vii

29.1 Concurrent delivery ......................................................................................................... 293 29.2 Returned status and data ............................................................................................... 293 29.3 How the command is run ................................................................................................ 294 29.4 Environment variables .................................................................................................... 295 29.5 Private options for pipe ................................................................................................... 295 29.6 Using an external local delivery agent ......................................................................... 300 30. The smtp transport .............................................................................................................. 302 30.1 Multiple messages on a single connection .................................................................. 302 30.2 Use of the $host and $host_address variables ........................................................... 302 30.3 Use of $tls_cipher and $tls_peerdn .............................................................................. 302 30.4 Private options for smtp .................................................................................................. 302 30.5 How the limits for the number of hosts to try are used .............................................. 314 31. Address rewriting ................................................................................................................. 316 31.1 Explicitly configured address rewriting ......................................................................... 316 31.2 When does rewriting happen? ....................................................................................... 316 31.3 Testing the rewriting rules that apply on input ............................................................. 317 31.4 Rewriting rules ................................................................................................................. 317 31.5 Rewriting patterns ............................................................................................................ 318 31.6 Rewriting replacements .................................................................................................. 319 31.7 Rewriting flags .................................................................................................................. 319 31.8 Flags specifying which headers and envelope addresses to rewrite ...................... 319 31.9 The SMTP-time rewriting flag ........................................................................................ 319 31.10 Flags controlling the rewriting process ...................................................................... 320 31.11 Rewriting examples ....................................................................................................... 320 32. Retry configuration .............................................................................................................. 322 32.1 Changing retry rules ........................................................................................................ 322 32.2 Format of retry rules ........................................................................................................ 322 32.3 Choosing which retry rule to use for address errors .................................................. 323 32.4 Choosing which retry rule to use for host and message errors ................................ 323 32.5 Retry rules for specific errors ......................................................................................... 324 32.6 Retry rules for specified senders .................................................................................. 325 32.7 Retry parameters ............................................................................................................. 326 32.8 Retry rule examples ........................................................................................................ 326 32.9 Timeout of retry data ....................................................................................................... 327 32.10 Long-term failures ......................................................................................................... 327 32.11 Deliveries that work intermittently ............................................................................... 328 33. SMTP authentication ........................................................................................................... 329 33.1 Generic options for authenticators ................................................................................ 330 33.2 The AUTH parameter on MAIL commands ................................................................. 332 33.3 Authentication on an Exim server ................................................................................. 332 33.4 Testing server authentication ......................................................................................... 333 33.5 Authentication by an Exim client ................................................................................... 334 34. The plaintext authenticator ............................................................................................... 335 34.1 Avoiding cleartext use ..................................................................................................... 335 34.2 Plaintext server options .................................................................................................. 335 34.3 Using plaintext in a server .............................................................................................. 335 34.4 The PLAIN authentication mechanism ......................................................................... 336

viii

34.5 The LOGIN authentication mechanism ........................................................................ 337 34.6 Support for different kinds of authentication ................................................................ 337 34.7 Using plaintext in a client ................................................................................................ 337 35. The cram_md5 authenticator ............................................................................................ 339 35.1 Using cram_md5 as a server ......................................................................................... 339 35.2 Using cram_md5 as a client ........................................................................................... 339 36. The cyrus_sasl authenticator ........................................................................................... 341 36.1 Using cyrus_sasl as a server ......................................................................................... 341 37. The dovecot authenticator ................................................................................................. 343 38. The gsasl authenticator ...................................................................................................... 344 38.1 gsasl auth variables ......................................................................................................... 346 39. The heimdal_gssapi authenticator .................................................................................. 347 39.1 heimdal_gssapi auth variables ...................................................................................... 347 40. The spa authenticator ......................................................................................................... 348 40.1 Using spa as a server ..................................................................................................... 348 40.2 Using spa as a client ....................................................................................................... 348 41. The external authenticator ................................................................................................. 350 41.1 External options ............................................................................................................... 350 41.2 Using external in a server .............................................................................................. 350 41.3 Using external in a client ................................................................................................ 351 42. The tls authenticator ........................................................................................................... 352 43. Encrypted SMTP connections using TLS/SSL ............................................................. 353 43.1 Support for the “submissions” (aka “ssmtp” and “smtps”) protocol ......................... 353 43.2 OpenSSL vs GnuTLS ..................................................................................................... 353 43.3 GnuTLS parameter computation ................................................................................... 354 43.4 Requiring specific ciphers in OpenSSL ........................................................................ 355 43.5 Requiring specific ciphers or other parameters in GnuTLS ...................................... 356 43.6 Configuring an Exim server to use TLS ....................................................................... 357 43.7 Requesting and verifying client certificates ................................................................. 358 43.8 Revoked certificates ........................................................................................................ 359 43.9 Configuring an Exim client to use TLS ......................................................................... 360 43.10 Use of TLS Server Name Indication ........................................................................... 361 43.11 Multiple messages on the same encrypted TCP/IP connection ............................ 362 43.12 Certificates and all that ................................................................................................. 362 43.13 Certificate chains ........................................................................................................... 362 43.14 Self-signed certificates ................................................................................................. 363 43.15 DANE ............................................................................................................................... 363 44. Access control lists ............................................................................................................. 367 44.1 Testing ACLs .................................................................................................................... 367 44.2 Specifying when ACLs are used ................................................................................... 367

ix

44.3 The non-SMTP ACLs ...................................................................................................... 368 44.4 The SMTP connect ACL ................................................................................................. 368 44.5 The EHLO/HELO ACL .................................................................................................... 368 44.6 The DATA ACLs ................................................................................................................ 368 44.7 The SMTP DKIM ACL ..................................................................................................... 369 44.8 The SMTP MIME ACL .................................................................................................... 369 44.9 The SMTP PRDR ACL ................................................................................................... 369 44.10 The QUIT ACL ............................................................................................................... 369 44.11 The not-QUIT ACL ........................................................................................................ 370 44.12 Finding an ACL to use .................................................................................................. 370 44.13 ACL return codes .......................................................................................................... 371 44.14 Unset ACL options ........................................................................................................ 371 44.15 Data for message ACLs ............................................................................................... 372 44.16 Data for non-message ACLs ....................................................................................... 372 44.17 Format of an ACL .......................................................................................................... 372 44.18 ACL verbs ....................................................................................................................... 373 44.19 ACL variables ................................................................................................................. 374 44.20 Condition and modifier processing ............................................................................. 375 44.21 ACL modifiers ................................................................................................................. 376 44.22 Use of the control modifier ........................................................................................... 380 44.23 Summary of message fixup control ............................................................................ 384 44.24 Adding header lines in ACLs ....................................................................................... 384 44.25 Removing header lines in ACLs .................................................................................. 385 44.26 ACL conditions ............................................................................................................... 386 44.27 Using DNS lists .............................................................................................................. 390 44.28 Specifying the IP address for a DNS list lookup ....................................................... 391 44.29 DNS lists keyed on domain names ............................................................................. 391 44.30 Multiple explicit keys for a DNS list ............................................................................. 392 44.31 Data returned by DNS lists .......................................................................................... 393 44.32 Variables set from DNS lists ........................................................................................ 393 44.33 Additional matching conditions for DNS lists ............................................................ 393 44.34 Negated DNS matching conditions ............................................................................ 394 44.35 Handling multiple DNS records from a DNS list ....................................................... 395 44.36 Detailed information from merged DNS lists ............................................................. 395 44.37 DNS lists and IPv6 ........................................................................................................ 396 44.38 Rate limiting incoming messages ............................................................................... 397 44.39 Ratelimit options for what is being measured ........................................................... 397 44.40 Ratelimit update modes ................................................................................................ 398 44.41 Ratelimit options for handling fast clients .................................................................. 399 44.42 Limiting the rate of different events ............................................................................. 399 44.43 Using rate limiting .......................................................................................................... 399 44.44 Address verification ....................................................................................................... 400 44.45 Callout verification ......................................................................................................... 401 44.46 Additional parameters for callouts .............................................................................. 402 44.47 Callout caching .............................................................................................................. 404 44.48 Sender address verification reporting ........................................................................ 405 44.49 Redirection while verifying ........................................................................................... 405 44.50 Client SMTP authorization (CSA) ............................................................................... 405 44.51 Bounce address tag validation .................................................................................... 406 44.52 Using an ACL to control relaying ................................................................................ 408 44.53 Checking a relay configuration .................................................................................... 408 45. Content scanning at ACL time .......................................................................................... 409 45.1 Scanning for viruses ........................................................................................................ 409 45.2 Scanning with SpamAssassin and Rspamd ................................................................ 414 45.3 Calling SpamAssassin from an Exim ACL ................................................................... 415 45.4 Scanning MIME parts ..................................................................................................... 416

x

45.5 Scanning with regular expressions ............................................................................... 419 46. Adding a local scan function to Exim ............................................................................. 420 46.1 Building Exim to use a local scan function .................................................................. 420 46.2 API for local_scan() ......................................................................................................... 420 46.3 Configuration options for local_scan() .......................................................................... 422 46.4 Available Exim variables ................................................................................................. 423 46.5 Structure of header lines ................................................................................................ 424 46.6 Structure of recipient items ............................................................................................ 425 46.7 Available Exim functions ................................................................................................. 425 46.8 More about Exim’s memory handling ........................................................................... 429 47. System-wide message filtering ........................................................................................ 430 47.1 Specifying a system filter ................................................................................................ 430 47.2 Testing a system filter ..................................................................................................... 430 47.3 Contents of a system filter .............................................................................................. 430 47.4 Additional variable for system filters ............................................................................. 431 47.5 Defer, freeze, and fail commands for system filters ................................................... 431 47.6 Adding and removing headers in a system filter ......................................................... 432 47.7 Setting an errors address in a system filter ................................................................. 432 47.8 Per-address filtering ........................................................................................................ 433 48. Message processing ........................................................................................................... 434 48.1 Submission mode for non-local messages .................................................................. 434 48.2 Line endings ..................................................................................................................... 435 48.3 Unqualified addresses .................................................................................................... 435 48.4 The UUCP From line ....................................................................................................... 436 48.5 Resent- header lines ....................................................................................................... 436 48.6 The Auto-Submitted: header line .................................................................................. 437 48.7 The Bcc: header line ....................................................................................................... 437 48.8 The Date: header line ..................................................................................................... 437 48.9 The Delivery-date: header line ...................................................................................... 437 48.10 The Envelope-to: header line ...................................................................................... 437 48.11 The From: header line .................................................................................................. 437 48.12 The Message-ID: header line ...................................................................................... 438 48.13 The Received: header line ........................................................................................... 438 48.14 The References: header line ....................................................................................... 438 48.15 The Return-path: header line ...................................................................................... 438 48.16 The Sender: header line ............................................................................................... 438 48.17 Adding and removing header lines in routers and transports ................................ 439 48.18 Constructed addresses ................................................................................................ 440 48.19 Case of local parts ........................................................................................................ 441 48.20 Dots in local parts .......................................................................................................... 441 48.21 Rewriting addresses ..................................................................................................... 441 49. SMTP processing ................................................................................................................. 442 49.1 Outgoing SMTP and LMTP over TCP/IP ..................................................................... 442 49.2 Errors in outgoing SMTP ................................................................................................ 443 49.3 Incoming SMTP messages over TCP/IP ..................................................................... 444 49.4 Unrecognized SMTP commands .................................................................................. 446 49.5 Syntax and protocol errors in SMTP commands ........................................................ 446 49.6 Use of non-mail SMTP commands ............................................................................... 446 49.7 The VRFY and EXPN commands ................................................................................. 446 49.8 The ETRN command ...................................................................................................... 446

xi

49.9 Incoming local SMTP ...................................................................................................... 447 49.10 Outgoing batched SMTP .............................................................................................. 447 49.11 Incoming batched SMTP .............................................................................................. 448 50. Customizing bounce and warning messages .............................................................. 449 50.1 Customizing bounce messages .................................................................................... 449 50.2 Customizing warning messages ................................................................................... 450 51. Some common configuration settings ........................................................................... 451 51.1 Sending mail to a smart host ......................................................................................... 451 51.2 Using Exim to handle mailing lists ................................................................................ 451 51.3 Syntax errors in mailing lists .......................................................................................... 451 51.4 Re-expansion of mailing lists ......................................................................................... 452 51.5 Closed mailing lists .......................................................................................................... 452 51.6 Variable Envelope Return Paths (VERP) ..................................................................... 453 51.7 Virtual domains ................................................................................................................ 454 51.8 Multiple user mailboxes .................................................................................................. 455 51.9 Simplified vacation processing ...................................................................................... 456 51.10 Taking copies of mail ..................................................................................................... 456 51.11 Intermittently connected hosts .................................................................................... 456 51.12 Exim on the upstream server host .............................................................................. 456 51.13 Exim on the intermittently connected client host ...................................................... 457 52. Using Exim as a non-queueing client ............................................................................. 458 53. Log files .................................................................................................................................. 460 53.1 Where the logs are written ............................................................................................. 460 53.2 Logging to local files that are periodically “cycled” ..................................................... 461 53.3 Datestamped log files ..................................................................................................... 461 53.4 Logging to syslog ............................................................................................................. 462 53.5 Log line flags .................................................................................................................... 463 53.6 Logging message reception ........................................................................................... 463 53.7 Logging deliveries ............................................................................................................ 464 53.8 Discarded deliveries ........................................................................................................ 465 53.9 Deferred deliveries .......................................................................................................... 465 53.10 Delivery failures ............................................................................................................. 465 53.11 Fake deliveries ............................................................................................................... 466 53.12 Completion ..................................................................................................................... 466 53.13 Summary of Fields in Log Lines ................................................................................. 466 53.14 Other log entries ............................................................................................................ 467 53.15 Reducing or increasing what is logged ...................................................................... 467 53.16 Message log ................................................................................................................... 472 54. Exim utilities .......................................................................................................................... 473 54.1 Finding out what Exim processes are doing (exiwhat) .............................................. 473 54.2 Selective queue listing (exiqgrep) ................................................................................. 473 54.3 Summarizing the queue (exiqsumm) ............................................................................ 474 54.4 Extracting specific information from the log (exigrep) ................................................ 475 54.5 Selecting messages by various criteria (exipick) ........................................................ 475 54.6 Cycling log files (exicyclog) ............................................................................................ 476 54.7 Mail statistics (eximstats) ............................................................................................... 476 54.8 Checking access policy (exim_checkaccess) ............................................................. 477 54.9 Making DBM files (exim_dbmbuild) .............................................................................. 477 54.10 Finding individual retry times (exinext) ....................................................................... 478

xii

54.11 Hints database maintenance ....................................................................................... 478 54.12 exim_dumpdb ................................................................................................................. 479 54.13 exim_tidydb .................................................................................................................... 479 54.14 exim_fixdb ....................................................................................................................... 480 54.15 Mailbox maintenance (exim_lock) ............................................................................... 480 55. The Exim monitor ................................................................................................................. 482 55.1 Running the monitor ........................................................................................................ 482 55.2 The stripcharts ................................................................................................................. 482 55.3 Main action buttons ......................................................................................................... 483 55.4 The log display ................................................................................................................. 483 55.5 The queue display ........................................................................................................... 484 55.6 The queue menu .............................................................................................................. 484 56. Security considerations ..................................................................................................... 487 56.1 Building a more “hardened” Exim ................................................................................. 487 56.2 Root privilege ................................................................................................................... 487 56.3 Running Exim without privilege ..................................................................................... 489 56.4 Delivering to local files .................................................................................................... 490 56.5 Running local commands ............................................................................................... 490 56.6 Trust in configuration data .............................................................................................. 490 56.7 IPv4 source routing ......................................................................................................... 491 56.8 The VRFY, EXPN, and ETRN commands in SMTP ................................................... 491 56.9 Privileged users ............................................................................................................... 491 56.10 Spool files ....................................................................................................................... 491 56.11 Use of argv[0] ................................................................................................................. 492 56.12 Use of %f formatting ..................................................................................................... 492 56.13 Embedded Exim path ................................................................................................... 492 56.14 Dynamic module directory ........................................................................................... 492 56.15 Use of sprintf() ............................................................................................................... 492 56.16 Use of debug_printf() and log_write() ........................................................................ 492 56.17 Use of strcat() and strcpy() .......................................................................................... 492 57. Format of spool files ........................................................................................................... 493 57.1 Format of the -H file ......................................................................................................... 493 57.2 Format of the -D file ......................................................................................................... 497 58. DKIM, SPF and DMARC ...................................................................................................... 498 58.1 DKIM (DomainKeys Identified Mail) .............................................................................. 498 58.2 Signing outgoing messages ........................................................................................... 498 58.3 Verifying DKIM signatures in incoming mail ................................................................ 501 58.4 SPF (Sender Policy Framework) ................................................................................... 504 58.5 DMARC ............................................................................................................................. 506 59. Proxies .................................................................................................................................... 509 59.1 Inbound proxies ............................................................................................................... 509 59.2 Outbound proxies ............................................................................................................ 509 59.3 Logging .............................................................................................................................. 510 60. Internationalisation .............................................................................................................. 511 60.1 MTA operations ................................................................................................................ 511 60.2 MDA operations ............................................................................................................... 512

xiii

61. Events ..................................................................................................................................... 513 62. Adding new drivers or lookup types ............................................................................... 515 Options index ................................................................................................................................ 516 Variables index ............................................................................................................................. 523 Concept index ............................................................................................................................... 525

xiv

1. Introduction

Exim is a mail transfer agent (MTA) for hosts that are running Unix or Unix-like operating systems. Itwas designed on the assumption that it would be run on hosts that are permanently connected to theInternet. However, it can be used on intermittently connected hosts with suitable configurationadjustments.

Configuration files currently exist for the following operating systems: AIX, BSD/OS (aka BSDI),Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, OpenUNIX, QNX, SCO, SCO SVR4.2 (akaUNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare. Some of these operating systems are no longer current and cannoteasily be tested, so the configuration files may no longer work in practice.

There are also configuration files for compiling Exim in the Cygwin environment that can be installedon systems running Windows. However, this document does not contain any information about run-ning Exim in the Cygwin environment.

The terms and conditions for the use and distribution of Exim are contained in the file NOTICE. Eximis distributed under the terms of the GNU General Public Licence, a copy of which may be found inthe file LICENCE.

The use, supply, or promotion of Exim for the purpose of sending bulk, unsolicited electronic mail isincompatible with the basic aims of Exim, which revolve around the free provision of a service thatenhances the quality of personal communications. The author of Exim regards indiscriminate mass-mailing as an antisocial, irresponsible abuse of the Internet.

Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the experience of running andworking on the Smail 3 code, I could never have contemplated starting to write a new MTA. Many ofthe ideas and user interfaces were originally taken from Smail 3, though the actual code of Exim isentirely new, and has developed far beyond the initial concept.

Many people, both in Cambridge and around the world, have contributed to the development and thetesting of Exim, and to porting it to various operating systems. I am grateful to them all. Thedistribution now contains a file called ACKNOWLEDGMENTS, in which I have started recording thenames of contributors.

1.1 Exim documentation

This edition of the Exim specification applies to version 4.94 of Exim. Substantive changes from the4.93 edition are marked in some renditions of this document; this paragraph is so marked if therendition is capable of showing a change indicator.

This document is very much a reference manual; it is not a tutorial. The reader is expected to havesome familiarity with the SMTP mail transfer protocol and with general Unix system administration.Although there are some discussions and examples in places, the information is mostly organized in away that makes it easy to look up, rather than in a natural order for sequential reading. Furthermore,this manual aims to cover every aspect of Exim in detail, including a number of rarely-used, special-purpose features that are unlikely to be of very wide interest.

An “easier” discussion of Exim which provides more in-depth explanatory, introductory, and tutorialmaterial can be found in a book entitled The Exim SMTP Mail Server (second edition, 2007), pub-lished by UIT Cambridge (https://www.uit.co.uk/exim-book/).

The book also contains a chapter that gives a general introduction to SMTP and Internet mail.Inevitably, however, the book is unlikely to be fully up-to-date with the latest release of Exim. (Notethat the earlier book about Exim, published by O’Reilly, covers Exim 3, and many things havechanged in Exim 4.)

If you are using a Debian distribution of Exim, you will find information about Debian-specificfeatures in the file /usr/share/doc/exim4-base/README.Debian. The command man update-exim.confis another source of Debian-specific information.

1 Introduction (1)

As Exim develops, there may be features in newer versions that have not yet made it into thisdocument, which is updated only when the most significant digit of the fractional part of the versionnumber changes. Specifications of new features that are not yet in this manual are placed in the filedoc/NewStuff in the Exim distribution.

Some features may be classified as “experimental”. These may change incompatibly while they aredeveloping, or even be withdrawn. For this reason, they are not documented in this manual.Information about experimental features can be found in the file doc/experimental.txt.

All changes to Exim (whether new features, bug fixes, or other kinds of change) are noted briefly inthe file called doc/ChangeLog.

This specification itself is available as an ASCII file in doc/spec.txt so that it can easily be searchedwith a text editor. Other files in the doc directory are:

OptionLists.txt list of all options in alphabetical orderdbm.discuss.txt discussion about DBM librariesexim.8 a man page of Exim’s command line optionsexperimental.txt documentation of experimental featuresfilter.txt specification of the filter languageExim3.upgrade upgrade notes from release 2 to release 3Exim4.upgrade upgrade notes from release 3 to release 4openssl.txt installing a current OpenSSL release

The main specification and the specification of the filtering language are also available in otherformats (HTML, PostScript, PDF, and Texinfo). Section 1.5 below tells you how to get hold of these.

1.2 FTP site and websites

The primary site for Exim source distributions is the exim.org FTP site, available over HTTPS, HTTPand FTP. These services, and the exim.org website, are hosted at the University of Cambridge.

As well as Exim distribution tar files, the Exim website contains a number of differently formattedversions of the documentation. A recent addition to the online information is the Exim wiki(https://wiki.exim.org), which contains what used to be a separate FAQ, as well as various otherexamples, tips, and know-how that have been contributed by Exim users. The wiki site should alwaysredirect to the correct place, which is currently provided by GitHub, and is open to editing by anyonewith a GitHub account.

An Exim Bugzilla exists at https://bugs.exim.org. You can use this to report bugs, and also to additems to the wish list. Please search first to check that you are not duplicating a previous entry. Pleasedo not ask for configuration help in the bug-tracker.

1.3 Mailing lists

The following Exim mailing lists exist:

exim-announce@exim.org Moderated, low volume announcements listexim-users@exim.org General discussion listexim-dev@exim.org Discussion of bugs, enhancements, etc.exim-cvs@exim.org Automated commit messages from the VCS

You can subscribe to these lists, change your existing subscriptions, and view or search the archivesvia the mailing lists link on the Exim home page. If you are using a Debian distribution of Exim, youmay wish to subscribe to the Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org viathis web page:

https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users

Please ask Debian-specific questions on that list and not on the general Exim lists.

2 Introduction (1)

1.4 Bug reports

Reports of obvious bugs can be emailed to bugs@exim.org or reported via the Bugzilla(https://bugs.exim.org). However, if you are unsure whether some behaviour is a bug or not, the bestthing to do is to post a message to the exim-dev mailing list and have it discussed.

1.5 Where to find the Exim distribution

The master distribution site for the Exim distribution is

https://downloads.exim.org/

The service is available over HTTPS, HTTP and FTP. We encourage people to migrate to HTTPS.

The content served at https://downloads.exim.org/ is identical to the content served athttps://ftp.exim.org/pub/exim and ftp://ftp.exim.org/pub/exim.

If accessing via a hostname containing ftp, then the file references that follow are relative to the eximdirectories at these sites. If accessing via the hostname downloads then the subdirectories describedhere are top-level directories.

There are now quite a number of independent mirror sites around the world. Those that I know aboutare listed in the file called Mirrors.

Within the top exim directory there are subdirectories called exim3 (for previous Exim 3 distri-butions), exim4 (for the latest Exim 4 distributions), and Testing for testing versions. In the exim4subdirectory, the current release can always be found in files called

exim-n.nn.tar.xzexim-n.nn.tar.gzexim-n.nn.tar.bz2

where n.nn is the highest such version number in the directory. The three files contain identical data;the only difference is the type of compression. The .xz file is usually the smallest, while the .gz file isthe most portable to old systems.

The distributions will be PGP signed by an individual key of the Release Coordinator. This key willhave a uid containing an email address in the exim.org domain and will have signatures from otherpeople, including other Exim maintainers. We expect that the key will be in the "strong set" of PGPkeys. There should be a trust path to that key from the Exim Maintainer’s PGP keys, a version ofwhich can be found in the release directory in the file Exim-Maintainers-Keyring.asc. All keys usedwill be available in public keyserver pools, such as pool.sks-keyservers.net.

At the time of the last update, releases were being made by Jeremy Harris and signed with key0xBCE58C8CE41F32DF. Other recent keys used for signing are those of Heiko Schlittermann,0x26101B62F69376CE, and of Phil Pennock, 0x4D1E900E14C1CC04.

The signatures for the tar bundles are in:

exim-n.nn.tar.xz.ascexim-n.nn.tar.gz.ascexim-n.nn.tar.bz2.asc

For each released version, the log of changes is made available in a separate file in the directoryChangeLogs so that it is possible to find out what has changed without having to download the entiredistribution.

The main distribution contains ASCII versions of this specification and other documentation; otherformats of the documents are available in separate files inside the exim4 directory of the FTP site:

exim-html-n.nn.tar.gzexim-pdf-n.nn.tar.gzexim-postscript-n.nn.tar.gzexim-texinfo-n.nn.tar.gz

3 Introduction (1)

These tar files contain only the doc directory, not the complete distribution, and are also available in.bz2 and .xz forms.

1.6 Limitations

• Exim is designed for use as an Internet MTA, and therefore handles addresses in RFC 2822 domainformat only. It cannot handle UUCP “bang paths”, though simple two-component bang paths canbe converted by a straightforward rewriting configuration. This restriction does not prevent Eximfrom being interfaced to UUCP as a transport mechanism, provided that domain addresses areused.

• Exim insists that every address it handles has a domain attached. For incoming local messages,domainless addresses are automatically qualified with a configured domain value. Configurationoptions specify from which remote systems unqualified addresses are acceptable. These are thenqualified on arrival.

• The only external transport mechanisms that are currently implemented are SMTP and LMTP overa TCP/IP network (including support for IPv6). However, a pipe transport is available, and thereare facilities for writing messages to files and pipes, optionally in batched SMTP format; thesefacilities can be used to send messages to other transport mechanisms such as UUCP, provided theycan handle domain-style addresses. Batched SMTP input is also catered for.

• Exim is not designed for storing mail for dial-in hosts. When the volumes of such mail are large, itis better to get the messages “delivered” into files (that is, off Exim’s queue) and subsequentlypassed on to the dial-in hosts by other means.

• Although Exim does have basic facilities for scanning incoming messages, these are not compre-hensive enough to do full virus or spam scanning. Such operations are best carried out usingadditional specialized software packages. If you compile Exim with the content-scanning exten-sion, straightforward interfaces to a number of common scanners are provided.

1.7 Runtime configuration

Exim’s runtime configuration is held in a single text file that is divided into a number of sections. Theentries in this file consist of keywords and values, in the style of Smail 3 configuration files. A defaultconfiguration file which is suitable for simple online installations is provided in the distribution, andis described in chapter 7 below.

1.8 Calling interface

Like many MTAs, Exim has adopted the Sendmail command line interface so that it can be a straightreplacement for /usr/lib/sendmail or /usr/sbin/sendmail when sending mail, but you do not need toknow anything about Sendmail in order to run Exim. For actions other than sending messages,Sendmail-compatible options also exist, but those that produce output (for example, -bp, which liststhe messages in the queue) do so in Exim’s own format. There are also some additional options thatare compatible with Smail 3, and some further options that are new to Exim. Chapter 5 documents allExim’s command line options. This information is automatically made into the man page that formspart of the Exim distribution.

Control of messages in the queue can be done via certain privileged command line options. There isalso an optional monitor program called eximon, which displays current information in an X window,and which contains a menu interface to Exim’s command line administration options.

1.9 Terminology

The body of a message is the actual data that the sender wants to transmit. It is the last part of amessage and is separated from the header (see below) by a blank line.

When a message cannot be delivered, it is normally returned to the sender in a delivery failuremessage or a “non-delivery report” (NDR). The term bounce is commonly used for this action, andthe error reports are often called bounce messages. This is a convenient shorthand for “delivery failure

4 Introduction (1)

error report”. Such messages have an empty sender address in the message’s envelope (see below) toensure that they cannot themselves give rise to further bounce messages.

The term default appears frequently in this manual. It is used to qualify a value which is used in theabsence of any setting in the configuration. It may also qualify an action which is taken unless aconfiguration setting specifies otherwise.

The term defer is used when the delivery of a message to a specific destination cannot immediatelytake place for some reason (a remote host may be down, or a user’s local mailbox may be full). Suchdeliveries are deferred until a later time.

The word domain is sometimes used to mean all but the first component of a host’s name. It is notused in that sense here, where it normally refers to the part of an email address following the @ sign.

A message in transit has an associated envelope, as well as a header and a body. The envelopecontains a sender address (to which bounce messages should be delivered), and any number ofrecipient addresses. References to the sender or the recipients of a message usually mean theaddresses in the envelope. An MTA uses these addresses for delivery, and for returning bouncemessages, not the addresses that appear in the header lines.

The header of a message is the first part of a message’s text, consisting of a number of lines, each ofwhich has a name such as From:, To:, Subject:, etc. Long header lines can be split over several textlines by indenting the continuations. The header is separated from the body by a blank line.

The term local part, which is taken from RFC 2822, is used to refer to the part of an email addressthat precedes the @ sign. The part that follows the @ sign is called the domain or mail domain.

The terms local delivery and remote delivery are used to distinguish delivery to a file or a pipe on thelocal host from delivery by SMTP over TCP/IP to another host. As far as Exim is concerned, all hostsother than the host it is running on are remote.

Return path is another name that is used for the sender address in a message’s envelope.

The term queue is used to refer to the set of messages awaiting delivery because this term is inwidespread use in the context of MTAs. However, in Exim’s case, the reality is more like a pool thana queue, because there is normally no ordering of waiting messages.

The term queue runner is used to describe a process that scans the queue and attempts to deliver thosemessages whose retry times have come. This term is used by other MTAs and also relates to thecommand runq, but in Exim the waiting messages are normally processed in an unpredictable order.

The term spool directory is used for a directory in which Exim keeps the messages in its queue – thatis, those that it is in the process of delivering. This should not be confused with the directory in whichlocal mailboxes are stored, which is called a “spool directory” by some people. In the Exim documen-tation, “spool” is always used in the first sense.

5 Introduction (1)

2. Incorporated code

A number of pieces of external code are included in the Exim distribution.

• Regular expressions are supported in the main Exim program and in the Exim mo