Specification of the Exim Mail Transfer Agent - Exim Internet Mailer

530 Pages·2016·2.59 MB·English

Specification of the Exim Mail
Transfer Agent

Exim Maintainers
Specification of the Exim Mail Transfer Agent
Author: Exim Maintainers

Copyright © 2022 The Exim Maintainers
Revision 4.96 25 Jun 2022
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................................................................................................ 16
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 PCRE2 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............................................................................. 20
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” ........................................................................................................... 22
4.13 Overriding build-time options for Exim............................................................................ 22
4.14 OS-specific header files.................................................................................................... 24
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 ................................................................................................................................. 26

iii
4.20 Replacing another MTA with Exim .................................................................................. 27
4.21 Running the daemon ......................................................................................................... 27
4.22 Upgrading Exim.................................................................................................................. 27
4.23 Stopping the Exim daemon on Solaris ........................................................................... 27

5. The Exim command line ......................................................................................................... 29

5.1 Setting options by program name...................................................................................... 29
5.2 Trusted and admin users .................................................................................................... 29
5.3 Command line options ........................................................................................................ 30

6. The Exim runtime configuration file.................................................................................... 55

6.1 Using a different configuration file ..................................................................................... 55
6.2 Configuration file format ...................................................................................................... 56
6.3 File inclusions in the configuration file .............................................................................. 57
6.4 Macros in the configuration file .......................................................................................... 57
6.5 Macro substitution................................................................................................................ 57
6.6 Redefining macros ............................................................................................................... 58
6.7 Overriding macro values ..................................................................................................... 58
6.8 Example of macro usage .................................................................................................... 58
6.9 Builtin macros ....................................................................................................................... 58
6.10 Conditional skips in the configuration file....................................................................... 59
6.11 Common option syntax ..................................................................................................... 59
6.12 Boolean options ................................................................................................................. 59
6.13 Integer values ..................................................................................................................... 60
6.14 Octal integer values........................................................................................................... 60
6.15 Fixed point numbers .......................................................................................................... 60
6.16 Time intervals ..................................................................................................................... 60
6.17 String values ....................................................................................................................... 60
6.18 Expanded strings ............................................................................................................... 61
6.19 User and group names ..................................................................................................... 61
6.20 List construction ................................................................................................................. 61
6.21 Changing list separators ................................................................................................... 61
6.22 Empty items in lists............................................................................................................ 62
6.23 Format of driver configurations ........................................................................................ 62

7. The default configuration file ................................................................................................ 64

7.1 Macros ................................................................................................................................... 64
7.2 Main configuration settings................................................................................................. 64
7.3 ACL configuration................................................................................................................. 67
7.4 Router configuration ............................................................................................................ 70
7.5 Transport configuration........................................................................................................ 73
7.6 Default retry rule................................................................................................................... 75
7.7 Rewriting configuration........................................................................................................ 75
7.8 Authenticators configuration............................................................................................... 75

8. Regular expressions................................................................................................................ 77

9. File and database lookups ..................................................................................................... 78

9.1 Examples of different lookup syntax ................................................................................. 78
9.2 Lookup types ........................................................................................................................ 79
9.3 Single-key lookup types ...................................................................................................... 79
9.4 Query-style lookup types .................................................................................................... 82
9.5 Temporary errors in lookups............................................................................................... 83
9.6 Default values in single-key lookups ................................................................................. 83

iv
9.7 Partial matching in single-key lookups.............................................................................. 84
9.8 Lookup caching .................................................................................................................... 85
9.9 Quoting lookup data ............................................................................................................ 85
9.10 More about dnsdb.............................................................................................................. 86
9.11 Dnsdb lookup modifiers .................................................................................................... 86
9.12 Pseudo dnsdb record types ............................................................................................. 87
9.13 Multiple dnsdb lookups ..................................................................................................... 88
9.14 More about LDAP .............................................................................................................. 88
9.15 Format of LDAP queries ................................................................................................... 88
9.16 LDAP quoting...................................................................................................................... 89
9.17 LDAP connections ............................................................................................................. 89
9.18 LDAP authentication and control information ................................................................ 90
9.19 Format of data returned by LDAP ................................................................................... 92
9.20 More about NIS+................................................................................................................ 93
9.21 SQL lookups ....................................................................................................................... 94
9.22 More about MySQL, PostgreSQL, Oracle, InterBase, and Redis .............................. 94
9.23 Specifying the server in the query................................................................................... 95
9.24 Special MySQL features ................................................................................................... 95
9.25 Special PostgreSQL features........................................................................................... 96
9.26 More about SQLite ............................................................................................................ 96
9.27 More about Redis .............................................................................................................. 96

10. Domain, host, address, and local part lists .................................................................... 98

10.1 Expansion of lists ............................................................................................................... 98
10.2 Negated items in lists ........................................................................................................ 98
10.3 File names in lists .............................................................................................................. 99
10.4 An lsearch file is not an out-of-line list............................................................................ 99
10.5 Results of list checking ..................................................................................................... 99
10.6 Named lists ....................................................................................................................... 100
10.7 Named lists compared with macros.............................................................................. 101
10.8 Named list caching .......................................................................................................... 101
10.9 Domain lists ...................................................................................................................... 101
10.10 Host lists ......................................................................................................................... 104
10.11 Special host list patterns .............................................................................................. 104
10.12 Host list patterns that match by IP address .............................................................. 104
10.13 Host list patterns for single-key lookups by host address ....................................... 105
10.14 Host list patterns that match by host name ............................................................... 106
10.15 Behaviour when an IP address or name cannot be found...................................... 107
10.16 Mixing wildcarded host names and addresses in host lists.................................... 107
10.17 Temporary DNS errors when looking up host information ...................................... 108
10.18 Host list patterns for single-key lookups by host name ........................................... 108
10.19 Host list patterns for query-style lookups .................................................................. 108
10.20 Address lists ................................................................................................................... 109
10.21 Case of letters in address lists .................................................................................... 111
10.22 Local part lists ................................................................................................................ 111

11. String expansions ................................................................................................................ 112

11.1 Literal text in expanded strings...................................................................................... 112
11.2 Character escape sequences in expanded strings .................................................... 112
11.3 Testing string expansions ............................................................................................... 112
11.4 Forced expansion failure ................................................................................................ 113
11.5 Expansion items .............................................................................................................. 113
11.6 Expansion operators ....................................................................................................... 126
11.7 Expansion conditions ...................................................................................................... 133
11.8 Combining expansion conditions .................................................................................. 140
11.9 Expansion variables ........................................................................................................ 140

v
12. Embedded Perl...................................................................................................................... 162

12.1 Setting up so Perl can be used ..................................................................................... 162
12.2 Calling Perl subroutines.................................................................................................. 162
12.3 Calling Exim functions from Perl ................................................................................... 163
12.4 Use of standard output and error by Perl..................................................................... 163

13. Starting the daemon and the use of network interfaces ........................................... 164

13.1 Starting a listening daemon ........................................................................................... 164
13.2 Special IP listening addresses ...................................................................................... 165
13.3 Overriding local_interfaces and daemon_smtp_ports ............................................... 165
13.4 Support for the submissions (aka SSMTP or SMTPS) protocol .............................. 165
13.5 IPv6 address scopes....................................................................................................... 166
13.6 Disabling IPv6 .................................................................................................................. 166
13.7 Examples of starting a listening daemon..................................................................... 166
13.8 Recognizing the local host ............................................................................................. 167
13.9 Delivering to a remote host ............................................................................................ 167

14. Main configuration............................................................................................................... 168

14.1 Miscellaneous .................................................................................................................. 168
14.2 Exim parameters.............................................................................................................. 168
14.3 Privilege controls ............................................................................................................. 168
14.4 Logging.............................................................................................................................. 169
14.5 Frozen messages ............................................................................................................ 169
14.6 Data lookups .................................................................................................................... 169
14.7 Message ids ..................................................................................................................... 169
14.8 Embedded Perl Startup .................................................................................................. 169
14.9 Daemon............................................................................................................................. 169
14.10 Resource control ........................................................................................................... 170
14.11 Policy controls ................................................................................................................ 170
14.12 Callout cache ................................................................................................................. 171
14.13 TLS .................................................................................................................................. 171
14.14 Local user handling ....................................................................................................... 171
14.15 All incoming messages (SMTP and non-SMTP)...................................................... 172
14.16 Non-SMTP incoming messages ................................................................................. 172
14.17 Incoming SMTP messages.......................................................................................... 172
14.18 SMTP extensions .......................................................................................................... 173
14.19 Processing messages .................................................................................................. 173
14.20 System filter.................................................................................................................... 173
14.21 Routing and delivery ..................................................................................................... 173
14.22 Bounce and warning messages.................................................................................. 174
14.23 Alphabetical list of main options.................................................................................. 174

15. Generic options for routers ............................................................................................... 226

16. The accept router ................................................................................................................. 241

17. The dnslookup router ......................................................................................................... 242

17.1 Problems with DNS lookups .......................................................................................... 242
17.2 Declining addresses by dnslookup ............................................................................... 242
17.3 Private options for dnslookup ........................................................................................ 243
17.4 Effect of qualify_single and search_parents ............................................................... 245

18. The ipliteral router ............................................................................................................... 246

vi
19. The iplookup router ............................................................................................................. 247

20. The manualroute router...................................................................................................... 249

20.1 Private options for manualroute .................................................................................... 249
20.2 Routing rules in route_list............................................................................................... 250
20.3 Routing rules in route_data............................................................................................ 251
20.4 Format of the list of hosts ............................................................................................... 251
20.5 Format of one host item.................................................................................................. 252
20.6 How the list of hosts is used .......................................................................................... 252
20.7 How the options are used............................................................................................... 253
20.8 Manualroute examples.................................................................................................... 253

21. The queryprogram router................................................................................................... 256

22. The redirect router ............................................................................................................... 258

22.1 Redirection data............................................................................................................... 258
22.2 Forward files and address verification.......................................................................... 259
22.3 Interpreting redirection data........................................................................................... 259
22.4 Items in a non-filter redirection list ................................................................................ 259
22.5 Redirecting to a local mailbox........................................................................................ 259
22.6 Special items in redirection lists .................................................................................... 260
22.7 Duplicate addresses........................................................................................................ 262
22.8 Repeated redirection expansion ................................................................................... 262
22.9 Errors in redirection lists ................................................................................................. 262
22.10 Private options for the redirect router......................................................................... 263

23. Environment for running local transports..................................................................... 271

23.1 Concurrent deliveries ...................................................................................................... 271
23.2 Uids and gids.................................................................................................................... 271
23.3 Current and home directories ........................................................................................ 272
23.4 Expansion variables derived from the address........................................................... 272

24. Generic options for transports......................................................................................... 273

25. Address batching in local transports ............................................................................. 280

26. The appendfile transport.................................................................................................... 282

26.1 The file and directory options ........................................................................................ 282
26.2 Private options for appendfile ........................................................................................ 283
26.3 Operational details for appending ................................................................................. 293
26.4 Operational details for delivery to a new file................................................................ 294
26.5 Maildir delivery ................................................................................................................. 295
26.6 Using tags to record message sizes............................................................................. 296
26.7 Using a maildirsize file .................................................................................................... 296
26.8 Mailstore delivery............................................................................................................. 296
26.9 Non-special new file delivery ......................................................................................... 297

27. The autoreply transport...................................................................................................... 298

27.1 Private options for autoreply .......................................................................................... 298

28. The lmtp transport ............................................................................................................... 301

vii
29. The pipe transport ............................................................................................................... 303

29.1 Concurrent delivery ......................................................................................................... 303
29.2 Returned status and data............................................................................................... 303
29.3 How the command is run................................................................................................ 304
29.4 Environment variables .................................................................................................... 305
29.5 Private options for pipe ................................................................................................... 305
29.6 Using an external local delivery agent ......................................................................... 310

30. The smtp transport .............................................................................................................. 312

30.1 Multiple messages on a single connection.................................................................. 312
30.2 Use of the $host and $host_address variables........................................................... 312
30.3 Use of $tls_cipher and $tls_peerdn .............................................................................. 312
30.4 Private options for smtp .................................................................................................. 312
30.5 How the limits for the number of hosts to try are used .............................................. 325

31. Address rewriting................................................................................................................. 327

31.1 Explicitly configured address rewriting ......................................................................... 327
31.2 When does rewriting happen?....................................................................................... 327
31.3 Testing the rewriting rules that apply on input............................................................. 328
31.4 Rewriting rules ................................................................................................................. 328
31.5 Rewriting patterns............................................................................................................ 329
31.6 Rewriting replacements .................................................................................................. 330
31.7 Rewriting flags.................................................................................................................. 330
31.8 Flags specifying which headers and envelope addresses to rewrite ...................... 330
31.9 The SMTP-time rewriting flag ........................................................................................ 330
31.10 Flags controlling the rewriting process ...................................................................... 331
31.11 Rewriting examples....................................................................................................... 331

32. Retry configuration.............................................................................................................. 333

32.1 Changing retry rules........................................................................................................ 333
32.2 Format of retry rules........................................................................................................ 333
32.3 Choosing which retry rule to use for address errors .................................................. 334
32.4 Choosing which retry rule to use for host and message errors................................ 334
32.5 Retry rules for specific errors......................................................................................... 335
32.6 Retry rules for specified senders .................................................................................. 336
32.7 Retry parameters............................................................................................................. 337
32.8 Retry rule examples ........................................................................................................ 337
32.9 Timeout of retry data....................................................................................................... 338
32.10 Long-term failures ......................................................................................................... 338
32.11 Deliveries that work intermittently............................................................................... 339

33. SMTP authentication ........................................................................................................... 340

33.1 Generic options for authenticators................................................................................ 341
33.2 The AUTH parameter on MAIL commands ................................................................. 343
33.3 Authentication on an Exim server ................................................................................. 343
33.4 Testing server authentication ......................................................................................... 344
33.5 Authentication by an Exim client ................................................................................... 345

34. The plaintext authenticator ............................................................................................... 346

34.1 Avoiding cleartext use ..................................................................................................... 346
34.2 Plaintext server options .................................................................................................. 346
34.3 Using plaintext in a server .............................................................................................. 346

viii
34.4 The PLAIN authentication mechanism......................................................................... 347
34.5 The LOGIN authentication mechanism........................................................................ 348
34.6 Support for different kinds of authentication................................................................ 348
34.7 Using plaintext in a client................................................................................................ 348

35. The cram_md5 authenticator............................................................................................ 350

35.1 Using cram_md5 as a server......................................................................................... 350
35.2 Using cram_md5 as a client........................................................................................... 350

36. The cyrus_sasl authenticator ........................................................................................... 352

36.1 Using cyrus_sasl as a server......................................................................................... 352

37. The dovecot authenticator................................................................................................. 354

38. The gsasl authenticator...................................................................................................... 355

38.1 gsasl auth variables......................................................................................................... 357

39. The heimdal_gssapi authenticator.................................................................................. 359

39.1 heimdal_gssapi auth variables ...................................................................................... 359

40. The spa authenticator ......................................................................................................... 360

40.1 Using spa as a server ..................................................................................................... 360
40.2 Using spa as a client ....................................................................................................... 360

41. The external authenticator................................................................................................. 362

41.1 External options ............................................................................................................... 362
41.2 Using external in a server .............................................................................................. 362
41.3 Using external in a client ................................................................................................ 363

42. The tls authenticator ........................................................................................................... 364

43. Encrypted SMTP connections using TLS/SSL............................................................. 365

43.1 Support for the “submissions” (aka “ssmtp” and “smtps”) protocol ......................... 365
43.2 OpenSSL vs GnuTLS ..................................................................................................... 365
43.3 GnuTLS parameter computation................................................................................... 366
43.4 Requiring specific ciphers in OpenSSL........................................................................ 367
43.5 Requiring specific ciphers or other parameters in GnuTLS...................................... 368
43.6 Configuring an Exim server to use TLS ....................................................................... 369
43.7 Requesting and verifying client certificates ................................................................. 370
43.8 Revoked certificates ........................................................................................................ 371
43.9 Caching of static server configuration items ............................................................... 372
43.10 Configuring an Exim client to use TLS....................................................................... 372
43.11 Caching of static client configuration items ............................................................... 373
43.12 Use of TLS Server Name Indication........................................................................... 374
43.13 Multiple messages on the same encrypted TCP/IP connection ............................ 375
43.14 Certificates and all that................................................................................................. 375
43.15 Certificate chains........................................................................................................... 376
43.16 Self-signed certificates ................................................................................................. 376
43.17 TLS Resumption............................................................................................................ 377
43.18 DANE............................................................................................................................... 378

ix
44. Access control lists............................................................................................................. 381

44.1 Testing ACLs .................................................................................................................... 381
44.2 Specifying when ACLs are used ................................................................................... 381
44.3 The non-SMTP ACLs ...................................................................................................... 382
44.4 The SMTP connect ACL................................................................................................. 382
44.5 The EHLO/HELO ACL .................................................................................................... 382
44.6 The DATA ACLs................................................................................................................ 382
44.7 The SMTP DKIM ACL..................................................................................................... 383
44.8 The SMTP MIME ACL .................................................................................................... 383
44.9 The SMTP PRDR ACL ................................................................................................... 383
44.10 The QUIT ACL ............................................................................................................... 384
44.11 The not-QUIT ACL ........................................................................................................ 384
44.12 Finding an ACL to use .................................................................................................. 384
44.13 ACL return codes .......................................................................................................... 385
44.14 Unset ACL options ........................................................................................................ 385
44.15 Data for message ACLs ............................................................................................... 386
44.16 Data for non-message ACLs ....................................................................................... 386
44.17 Format of an ACL .......................................................................................................... 386
44.18 ACL verbs ....................................................................................................................... 387
44.19 ACL variables ................................................................................................................. 388
44.20 Condition and modifier processing ............................................................................. 389
44.21 ACL modifiers................................................................................................................. 390
44.22 Use of the control modifier ........................................................................................... 394
44.23 Summary of message fixup control ............................................................................ 398
44.24 Adding header lines in ACLs ....................................................................................... 399
44.25 Removing header lines in ACLs.................................................................................. 400
44.26 ACL conditions............................................................................................................... 401
44.27 Using DNS lists.............................................................................................................. 405
44.28 Specifying the IP address for a DNS list lookup....................................................... 406
44.29 DNS lists keyed on domain names............................................................................. 407
44.30 Multiple explicit keys for a DNS list ............................................................................. 407
44.31 Data returned by DNS lists .......................................................................................... 408
44.32 Variables set from DNS lists ........................................................................................ 408
44.33 Additional matching conditions for DNS lists ............................................................ 409
44.34 Negated DNS matching conditions ............................................................................ 409
44.35 Handling multiple DNS records from a DNS list ....................................................... 410
44.36 Detailed information from merged DNS lists............................................................. 411
44.37 DNS lists and IPv6 ........................................................................................................ 411
44.38 Previously seen user and hosts .................................................................................. 412
44.39 Rate limiting incoming messages ............................................................................... 412
44.40 Ratelimit options for what is being measured ........................................................... 413
44.41 Ratelimit update modes................................................................................................ 414
44.42 Ratelimit options for handling fast clients .................................................................. 414
44.43 Limiting the rate of different events............................................................................. 415
44.44 Using rate limiting.......................................................................................................... 415
44.45 Address verification....................................................................................................... 416
44.46 Callout verification ......................................................................................................... 417
44.47 Additional parameters for callouts .............................................................................. 418
44.48 Callout caching .............................................................................................................. 420
44.49 Quota caching................................................................................................................ 421
44.50 Sender address verification reporting ........................................................................ 421
44.51 Redirection while verifying ........................................................................................... 421
44.52 Client SMTP authorization (CSA) ............................................................................... 422
44.53 Bounce address tag validation .................................................................................... 423
44.54 Using an ACL to control relaying ................................................................................ 424
44.55 Checking a relay configuration .................................................................................... 425

x