Specification of the Exim MailTransfer Agent

Exim Maintainers

Specification of the Exim Mail Transfer Agent

Author: Exim Maintainers

Copyright ' 2018 University of Cambridge

Revision 4.91 15 Apr 2018

Contents

1. Introduction .................................................................................................................................. 1 1.1 Exim documentation .............................................................................................................. 1 1.2 FTP and web sites ................................................................................................................. 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 Run time 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 ................................................................................................... 18 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 ................................................................................................... 20 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 ............................................................................ 21 4.14 OS-specific header files .................................................................................................... 23 4.15 Overriding build-time options for the monitor ................................................................ 23 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 run time configuration file ................................................................................... 51 6.1 Using a different configuration file ..................................................................................... 51 6.2 Configuration file format ...................................................................................................... 52 6.3 File inclusions in the configuration file .............................................................................. 53 6.4 Macros in the configuration file .......................................................................................... 53 6.5 Macro substitution ................................................................................................................ 53 6.6 Redefining macros ............................................................................................................... 54 6.7 Overriding macro values ..................................................................................................... 54 6.8 Example of macro usage .................................................................................................... 54 6.9 Builtin macros ....................................................................................................................... 54 6.10 Conditional skips in the configuration file ....................................................................... 55 6.11 Common option syntax ..................................................................................................... 55 6.12 Boolean options ................................................................................................................. 55 6.13 Integer values ..................................................................................................................... 56 6.14 Octal integer values ........................................................................................................... 56 6.15 Fixed point numbers .......................................................................................................... 56 6.16 Time intervals ..................................................................................................................... 56 6.17 String values ....................................................................................................................... 56 6.18 Expanded strings ............................................................................................................... 57 6.19 User and group names ..................................................................................................... 57 6.20 List construction ................................................................................................................. 57 6.21 Changing list separators ................................................................................................... 57 6.22 Empty items in lists ............................................................................................................ 58 6.23 Format of driver configurations ........................................................................................ 58 7. The default configuration file ................................................................................................ 60 7.1 Main configuration settings ................................................................................................. 60 7.2 ACL configuration ................................................................................................................. 63 7.3 Router configuration ............................................................................................................ 66 7.4 Transport configuration ........................................................................................................ 68 7.5 Default retry rule ................................................................................................................... 69 7.6 Rewriting configuration ........................................................................................................ 69 7.7 Authenticators configuration ............................................................................................... 69 8. Regular expressions ................................................................................................................ 71 9. File and database lookups ..................................................................................................... 72 9.1 Examples of different lookup syntax ................................................................................. 72 9.2 Lookup types ........................................................................................................................ 73 9.3 Single-key lookup types ...................................................................................................... 73 9.4 Query-style lookup types .................................................................................................... 75 9.5 Temporary errors in lookups ............................................................................................... 76 9.6 Default values in single-key lookups ................................................................................. 76 9.7 Partial matching in single-key lookups .............................................................................. 77 9.8 Lookup caching .................................................................................................................... 78

iv

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

v

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

vi

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

vii

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

viii

35. The cram_md5 authenticator ............................................................................................ 328 35.1 Using cram_md5 as a server ......................................................................................... 328 35.2 Using cram_md5 as a client ........................................................................................... 328 36. The cyrus_sasl authenticator ........................................................................................... 330 36.1 Using cyrus_sasl as a server ......................................................................................... 330 37. The dovecot authenticator ................................................................................................. 332 38. The gsasl authenticator ...................................................................................................... 333 38.1 gsasl auth variables ......................................................................................................... 334 39. The heimdal_gssapi authenticator .................................................................................. 335 39.1 heimdal_gssapi auth variables ...................................................................................... 335 40. The spa authenticator ......................................................................................................... 336 40.1 Using spa as a server ..................................................................................................... 336 40.2 Using spa as a client ....................................................................................................... 336 41. The tls authenticator ........................................................................................................... 338 42. Encrypted SMTP connections using TLS/SSL ............................................................. 339 42.1 Support for the submissions (aka ssmtp and smtps) protocol ......................... 339 42.2 OpenSSL vs GnuTLS ..................................................................................................... 339 42.3 GnuTLS parameter computation ................................................................................... 340 42.4 Requiring specific ciphers in OpenSSL ........................................................................ 341 42.5 Requiring specific ciphers or other parameters in GnuTLS ...................................... 342 42.6 Configuring an Exim server to use TLS ....................................................................... 343 42.7 Requesting and verifying client certificates ................................................................. 344 42.8 Revoked certificates ........................................................................................................ 345 42.9 Configuring an Exim client to use TLS ......................................................................... 345 42.10 Use of TLS Server Name Indication ........................................................................... 346 42.11 Multiple messages on the same encrypted TCP/IP connection ............................ 347 42.12 Certificates and all that ................................................................................................. 348 42.13 Certificate chains ........................................................................................................... 348 42.14 Self-signed certificates ................................................................................................. 348 42.15 DANE ............................................................................................................................... 349 43. Access control lists ............................................................................................................. 352 43.1 Testing ACLs .................................................................................................................... 352 43.2 Specifying when ACLs are used ................................................................................... 352 43.3 The non-SMTP ACLs ...................................................................................................... 353 43.4 The SMTP connect ACL ................................................................................................. 353 43.5 The EHLO/HELO ACL .................................................................................................... 353 43.6 The DATA ACLs ................................................................................................................ 353 43.7 The SMTP DKIM ACL ..................................................................................................... 354 43.8 The SMTP MIME ACL .................................................................................................... 354 43.9 The SMTP PRDR ACL ................................................................................................... 354 43.10 The QUIT ACL ............................................................................................................... 354 43.11 The not-QUIT ACL ........................................................................................................ 355

ix

43.12 Finding an ACL to use .................................................................................................. 355 43.13 ACL return codes .......................................................................................................... 356 43.14 Unset ACL options ........................................................................................................ 356 43.15 Data for message ACLs ............................................................................................... 357 43.16 Data for non-message ACLs ....................................................................................... 357 43.17 Format of an ACL .......................................................................................................... 357 43.18 ACL verbs ....................................................................................................................... 358 43.19 ACL variables ................................................................................................................. 359 43.20 Condition and modifier processing ............................................................................. 360 43.21 ACL modifiers ................................................................................................................. 361 43.22 Use of the control modifier ........................................................................................... 365 43.23 Summary of message fixup control ............................................................................ 369 43.24 Adding header lines in ACLs ....................................................................................... 369 43.25 Removing header lines in ACLs .................................................................................. 370 43.26 ACL conditions ............................................................................................................... 371 43.27 Using DNS lists .............................................................................................................. 375 43.28 Specifying the IP address for a DNS list lookup ....................................................... 376 43.29 DNS lists keyed on domain names ............................................................................. 376 43.30 Multiple explicit keys for a DNS list ............................................................................. 377 43.31 Data returned by DNS lists .......................................................................................... 377 43.32 Variables set from DNS lists ........................................................................................ 378 43.33 Additional matching conditions for DNS lists ............................................................ 378 43.34 Negated DNS matching conditions ............................................................................ 379 43.35 Handling multiple DNS records from a DNS list ....................................................... 379 43.36 Detailed information from merged DNS lists ............................................................. 380 43.37 DNS lists and IPv6 ........................................................................................................ 381 43.38 Rate limiting incoming messages ............................................................................... 381 43.39 Ratelimit options for what is being measured ........................................................... 382 43.40 Ratelimit update modes ................................................................................................ 383 43.41 Ratelimit options for handling fast clients .................................................................. 383 43.42 Limiting the rate of different events ............................................................................. 384 43.43 Using rate limiting .......................................................................................................... 384 43.44 Address verification ....................................................................................................... 385 43.45 Callout verification ......................................................................................................... 386 43.46 Additional parameters for callouts .............................................................................. 387 43.47 Callout caching .............................................................................................................. 389 43.48 Sender address verification reporting ........................................................................ 389 43.49 Redirection while verifying ........................................................................................... 390 43.50 Client SMTP authorization (CSA) ............................................................................... 390 43.51 Bounce address tag validation .................................................................................... 391 43.52 Using an ACL to control relaying ................................................................................ 392 43.53 Checking a relay configuration .................................................................................... 393 44. Content scanning at ACL time .......................................................................................... 394 44.1 Scanning for viruses ........................................................................................................ 394 44.2 Scanning with SpamAssassin and Rspamd ................................................................ 398 44.3 Calling SpamAssassin from an Exim ACL ................................................................... 400 44.4 Scanning MIME parts ..................................................................................................... 401 44.5 Scanning with regular expressions ............................................................................... 404 45. Adding a local scan function to Exim ............................................................................. 405 45.1 Building Exim to use a local scan function .................................................................. 405 45.2 API for local_scan() ......................................................................................................... 405 45.3 Configuration options for local_scan() .......................................................................... 406 45.4 Available Exim variables ................................................................................................. 407 45.5 Structure of header lines ................................................................................................ 409

x

45.6 Structure of recipient items ............................................................................................ 409 45.7 Available Exim functions ................................................................................................. 410 45.8 More about Exims memory handling ........................................................................... 414 46. System-wide message filtering ........................................................................................ 415 46.1 Specifying a system filter ................................................................................................ 415 46.2 Testing a system filter ..................................................................................................... 415 46.3 Contents of a system filter .............................................................................................. 415 46.4 Additional variable for system filters ............................................................................. 416 46.5 Defer, freeze, and fail commands for system filters ................................................... 416 46.6 Adding and removing headers in a system filter ......................................................... 417 46.7 Setting an errors address in a system filter ................................................................. 417 46.8 Per-address filtering ........................................................................................................ 418 47. Message processing ........................................................................................................... 419 47.1 Submission mode for non-local messages .................................................................. 419 47.2 Line endings ..................................................................................................................... 420 47.3 Unqualified addresses .................................................................................................... 420 47.4 The UUCP From line ....................................................................................................... 421 47.5 Resent- header lines ....................................................................................................... 421 47.6 The Auto-Submitted: header line .................................................................................. 422 47.7 The Bcc: header line ....................................................................................................... 422 47.8 The Date: header line ..................................................................................................... 422 47.9 The Delivery-date: header line ...................................................................................... 422 47.10 The Envelope-to: header line ...................................................................................... 422 47.11 The From: header line .................................................................................................. 422 47.12 The Message-ID: header line ...................................................................................... 423 47.13 The Received: header line ........................................................................................... 423 47.14 The References: header line ....................................................................................... 423 47.15 The Return-path: header line ...................................................................................... 423 47.16 The Sender: header line ............................................................................................... 423 47.17 Adding and removing header lines in routers and transports ................................ 424 47.18 Constructed addresses ................................................................................................ 425 47.19 Case of local parts ........................................................................................................ 426 47.20 Dots in local parts .......................................................................................................... 426 47.21 Rewriting addresses ..................................................................................................... 426 48. SMTP processing ................................................................................................................. 427 48.1 Outgoing SMTP and LMTP over TCP/IP ..................................................................... 427 48.2 Errors in outgoing SMTP ................................................................................................ 428 48.3 Incoming SMTP messages over TCP/IP ..................................................................... 429 48.4 Unrecognized SMTP commands .................................................................................. 431 48.5 Syntax and protocol errors in SMTP commands ........................................................ 431 48.6 Use of non-mail SMTP commands ............................................................................... 431 48.7 The VRFY and EXPN commands ................................................................................. 431 48.8 The ETRN command ...................................................................................................... 431 48.9 Incoming local SMTP ...................................................................................................... 432 48.10 Outgoing batched SMTP .............................................................................................. 432 48.11 Incoming batched SMTP .............................................................................................. 433 49. Customizing bounce and warning messages .............................................................. 434 49.1 Customizing bounce messages .................................................................................... 434 49.2 Customizing warning messages ................................................................................... 435

xi

50. Some common configuration settings ........................................................................... 436 50.1 Sending mail to a smart host ......................................................................................... 436 50.2 Using Exim to handle mailing lists ................................................................................ 436 50.3 Syntax errors in mailing lists .......................................................................................... 436 50.4 Re-expansion of mailing lists ......................................................................................... 437 50.5 Closed mailing lists .......................................................................................................... 437 50.6 Variable Envelope Return Paths (VERP) ..................................................................... 438 50.7 Virtual domains ................................................................................................................ 439 50.8 Multiple user mailboxes .................................................................................................. 440 50.9 Simplified vacation processing ...................................................................................... 441 50.10 Taking copies of mail ..................................................................................................... 441 50.11 Intermittently connected hosts .................................................................................... 441 50.12 Exim on the upstream server host .............................................................................. 441 50.13 Exim on the intermittently connected client host ...................................................... 442 51. Using Exim as a non-queueing client ............................................................................. 443 52. Log files .................................................................................................................................. 445 52.1 Where the logs are written ............................................................................................. 445 52.2 Logging to local files that are periodically cycled ..................................................... 446 52.3 Datestamped log files ..................................................................................................... 446 52.4 Logging to syslog ............................................................................................................. 447 52.5 Log line flags .................................................................................................................... 448 52.6 Logging message reception ........................................................................................... 448 52.7 Logging deliveries ............................................................................................................ 449 52.8 Discarded deliveries ........................................................................................................ 450 52.9 Deferred deliveries .......................................................................................................... 450 52.10 Delivery failures ............................................................................................................. 450 52.11 Fake deliveries ............................................................................................................... 451 52.12 Completion ..................................................................................................................... 451 52.13 Summary of Fields in Log Lines ................................................................................. 451 52.14 Other log entries ............................................................................................................ 452 52.15 Reducing or increasing what is logged ...................................................................... 452 52.16 Message log ................................................................................................................... 457 53. Exim utilities .......................................................................................................................... 458 53.1 Finding out what Exim processes are doing (exiwhat) .............................................. 458 53.2 Selective queue listing (exiqgrep) ................................................................................. 458 53.3 Summarizing the queue (exiqsumm) ............................................................................ 459 53.4 Extracting specific information from the log (exigrep) ................................................ 460 53.5 Selecting messages by various criteria (exipick) ........................................................ 460 53.6 Cycling log files (exicyclog) ............................................................................................ 461 53.7 Mail statistics (eximstats) ............................................................................................... 461 53.8 Checking access policy (exim_checkaccess) ............................................................. 462 53.9 Making DBM files (exim_dbmbuild) .............................................................................. 462 53.10 Finding individual retry times (exinext) ....................................................................... 463 53.11 Hints database maintenance ....................................................................................... 463 53.12 exim_dumpdb ................................................................................................................. 464 53.13 exim_tidydb .................................................................................................................... 464 53.14 exim_fixdb ....................................................................................................................... 465 53.15 Mailbox maintenance (exim_lock) ............................................................................... 465 54. The Exim monitor ................................................................................................................. 467 54.1 Running the monitor ........................................................................................................ 467

xii

54.2 The stripcharts ................................................................................................................. 467 54.3 Main action buttons ......................................................................................................... 468 54.4 The log display ................................................................................................................. 468 54.5 The queue display ........................................................................................................... 469 54.6 The queue menu .............................................................................................................. 469 55. Security considerations ..................................................................................................... 472 55.1 Building a more hardened Exim ................................................................................. 472 55.2 Root privilege ................................................................................................................... 472 55.3 Running Exim without privilege ..................................................................................... 474 55.4 Delivering to local files .................................................................................................... 475 55.5 Running local commands ............................................................................................... 475 55.6 Trust in configuration data .............................................................................................. 475 55.7 IPv4 source routing ......................................................................................................... 476 55.8 The VRFY, EXPN, and ETRN commands in SMTP ................................................... 476 55.9 Privileged users ............................................................................................................... 476 55.10 Spool files ....................................................................................................................... 476 55.11 Use of argv[0] ................................................................................................................. 477 55.12 Use of %f formatting ..................................................................................................... 477 55.13 Embedded Exim path ................................................................................................... 477 55.14 Dynamic module directory ........................................................................................... 477 55.15 Use of sprintf() ............................................................................................................... 477 55.16 Use of debug_printf() and log_write() ........................................................................ 477 55.17 Use of strcat() and strcpy() .......................................................................................... 477 56. Format of spool files ........................................................................................................... 478 56.1 Format of the -H file ......................................................................................................... 478 56.2 Format of the -D file ......................................................................................................... 482 57. DKIM and SPF ....................................................................................................................... 483 57.1 DKIM (DomainKeys Identified Mail) .............................................................................. 483 57.2 Signing outgoing messages ........................................................................................... 483 57.3 Verifying DKIM signatures in incoming mail ................................................................ 485 57.4 SPF (Sender Policy Framework) ................................................................................... 489 58. Proxies .................................................................................................................................... 491 58.1 Inbound proxies ............................................................................................................... 491 58.2 Outbound proxies ............................................................................................................ 491 58.3 Logging .............................................................................................................................. 492 59. Internationalisation .............................................................................................................. 493 59.1 MTA operations ................................................................................................................ 493 59.2 MDA operations ............................................................................................................... 493 60. Events ..................................................................................................................................... 495 61. Adding new drivers or lookup types ............................................................................... 497 Options index ................................................................................................................................ 498 Variables index ............................................................................................................................. 505 Concept index ............................................................................................................................... 507

xiii

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

Conguration les 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 conguration les may no longer work in practice.

There are also conguration les 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 le NOTICE. Eximis distributed under the terms of the GNU General Public Licence, a copy of which may be found inthe le LICENCE.

The use, supply or promotion of Exim for the purpose of sending bulk, unsolicited electronic mail isincompatible with the basic aims of the program, which revolve around the free provision of a servicethat enhances the quality of personal communications. The author of Exim regards indiscriminatemass-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 le called ACKNOWLEDGMENTS, in which I have started recording thenames of contributors.

1.1 Exim documentation

This edition of the Exim specication applies to version 4.91 of Exim. Substantive changes from the4.90 edition are marked in some renditions of the 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,the manual aims to cover every aspect of Exim in detail, including a number of rarely-used, special-purpose features that are unlikely to be of very wide interest.

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 (http://www.uit.co.uk/exim-book/).

This 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 OReilly, covers Exim 3, and many things havechanged in Exim 4.)

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

1 Introduction (1)

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

Some features may be classied 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 le doc/experimental.txt.

All changes to the program (whether new features, bug xes, or other kinds of change) are notedbriefly in the le called doc/ChangeLog.

This specication itself is available as an ASCII le in doc/spec.txt so that it can easily be searchedwith a text editor. Other les 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 Exims command line optionsexperimental.txt documentation of experimental featuresfilter.txt specication of the lter 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 specication and the specication of the ltering 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 and web sites

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 les, the Exim web site contains a number of differently formattedversions of the documentation. A recent addition to the online information is the Exim wiki(http://wiki.exim.org), which contains what used to be a separate FAQ, as well as various otherexamples, tips, and know-how that have been contributed by Exim users.

The wiki site should always redirect to the correct place, which is currently provided by GitHub, andis open to editing by anyone with 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 rst to check that you are not duplicating a previous entry.

Please do not ask for conguration 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-specic mailing list pkg-exim4-users@lists.alioth.debian.org viathis web page:

http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users

Please ask Debian-specic questions on this 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 le 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 le 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 les 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 les contain identical data;the only difference is the type of compression.

The .xz le is usually the smallest, while the .gz le is the 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 Nigel Metheringhams PGP key, a version ofwhich can be found in the release directory in the le nigel-pubkey.asc. All keys used will be availablein public keyserver pools, such as pool.sks-keyservers.net.

At time of 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 separately available in a separate le in thedirectory ChangeLogs so that it is possible to nd out what has changed without having to downloadthe entire distribution.

The main distribution contains ASCII versions of this specication and other documentation; otherformats of the documents are available in separate les 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 les 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 conguration. 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 qualied with a congured domain value. Congurationoptions specify from which remote systems unqualied addresses are acceptable. These are thenqualied 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 les 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 les (that is, off Exims 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 Run time configuration

Exims run time conguration is held in a single text le that is divided into a number of sections. Theentries in this le consist of keywords and values, in the style of Smail 3 conguration les. A defaultconguration le 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 on the queue) do so in Exims 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 allExims command line options. This information is automatically made into the man page that formspart of the Exim distribution.

Control of messages on 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 Exims 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 messages 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 conguration. It may also qualify an action which is taken unless aconguration setting species otherwise.

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

The word domain is sometimes used to mean all but the rst component of a hosts 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 rst part of a messages 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 that 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 le 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 messages 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 Exims case the reality is more like a pool than aqueue, 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 on 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 rst 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 monitor using thefreely-distributable PCRE library, copyright ' University of Cambridge. The source to PCRE is nolonger shipped with Exim, so you will need to use the version of PCRE shipped with your system,or obtain and install the full version of the library fromftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre.

Support for the cdb (Constant DataBase) lookup method is provided by code contributed by NigelMetheringham of (at the time he contributed it) Planet Online Ltd. The implementation is com-pletely contained within the code of Exim. It does not link against an external cdb library. The codecontains the following statements:

Copyright ' 1998 Nigel Metheringham, Planet Online Ltd

This program is free software; you can redistribute it and/or modify it under the terms ofthe GNU General Public License as published by the Free Software Foundation; eitherversion 2 of the License, or (at your option) any later version. This code implementsDan Bernsteins Constant DataBase (cdb) spec. Information, the spec and sample codefor cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This implemen-tation borrows some code from Dan Bernsteins implementation (which has no licenserestrictions applied to it).

Client support for Microsofts Secure Password Authentication is provided by code contributed byMarc Prudhommeaux. Server support was contributed by Tom Kistner. This includes code takenfrom the Samba project, which is released under the Gnu GPL.

Support for calling