Spec

891 views
805 views

Published on

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
891
On SlideShare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
5
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Spec

  1. 1. Specification of the Exim Mail Transfer Agent Exim Maintainers
  2. 2. Specification of the Exim Mail Transfer AgentAuthor: Exim MaintainersCopyright © 2009 University of CambridgeRevision 4.73 19 Nov 2010
  3. 3. Contents1. Introduction .................................................................................................................................. 1 1.1 Exim documentation .............................................................................................................. 1 1.2 FTP and web sites ................................................................................................................. 2 1.3 Mailing lists .............................................................................................................................. 2 1.4 Exim training ........................................................................................................................... 3 1.5 Bug reports .............................................................................................................................. 3 1.6 Where to find the Exim distribution ...................................................................................... 3 1.7 Limitations ............................................................................................................................... 3 1.8 Run time configuration ........................................................................................................... 4 1.9 Calling interface ...................................................................................................................... 4 1.10 Terminology ........................................................................................................................... 42. Incorporated code ...................................................................................................................... 63. 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 ............................................................................. 164. 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 The building process ......................................................................................................... 21 4.11 Output from “make” ........................................................................................................... 21 4.12 Overriding build-time options for Exim ............................................................................ 21 4.13 OS-specific header files .................................................................................................... 23 4.14 Overriding build-time options for the monitor ................................................................ 23 4.15 Installing Exim binaries and scripts ................................................................................. 23 4.16 Installing info documentation ........................................................................................... 24 4.17 Setting up the spool directory .......................................................................................... 25 4.18 Testing ................................................................................................................................. 25 iii
  4. 4. 4.19 Replacing another MTA with Exim .................................................................................. 26 4.20 Upgrading Exim .................................................................................................................. 26 4.21 Stopping the Exim daemon on Solaris ........................................................................... 265. The Exim command line ......................................................................................................... 27 5.1 Setting options by program name ...................................................................................... 27 5.2 Trusted and admin users .................................................................................................... 27 5.3 Command line options ........................................................................................................ 286. The Exim run time configuration file ................................................................................... 49 6.1 Using a different configuration file ..................................................................................... 49 6.2 Configuration file format ...................................................................................................... 50 6.3 File inclusions in the configuration file .............................................................................. 51 6.4 Macros in the configuration file .......................................................................................... 51 6.5 Macro substitution ................................................................................................................ 51 6.6 Redefining macros ............................................................................................................... 52 6.7 Overriding macro values ..................................................................................................... 52 6.8 Example of macro usage .................................................................................................... 52 6.9 Conditional skips in the configuration file ......................................................................... 52 6.10 Common option syntax ..................................................................................................... 53 6.11 Boolean options ................................................................................................................. 53 6.12 Integer values ..................................................................................................................... 53 6.13 Octal integer values ........................................................................................................... 53 6.14 Fixed point numbers .......................................................................................................... 54 6.15 Time intervals ..................................................................................................................... 54 6.16 String values ....................................................................................................................... 54 6.17 Expanded strings ............................................................................................................... 54 6.18 User and group names ..................................................................................................... 55 6.19 List construction ................................................................................................................. 55 6.20 Changing list separators ................................................................................................... 55 6.21 Empty items in lists ............................................................................................................ 55 6.22 Format of driver configurations ........................................................................................ 567. The default configuration file ................................................................................................ 58 7.1 Main configuration settings ................................................................................................. 58 7.2 ACL configuration ................................................................................................................. 60 7.3 Router configuration ............................................................................................................ 63 7.4 Transport configuration ........................................................................................................ 66 7.5 Default retry rule ................................................................................................................... 66 7.6 Rewriting configuration ........................................................................................................ 67 7.7 Authenticators configuration ............................................................................................... 678. Regular expressions ................................................................................................................ 689. File and database lookups ..................................................................................................... 69 9.1 Examples of different lookup syntax ................................................................................. 69 9.2 Lookup types ........................................................................................................................ 69 9.3 Single-key lookup types ...................................................................................................... 70 9.4 Query-style lookup types .................................................................................................... 72 9.5 Temporary errors in lookups ............................................................................................... 73 9.6 Default values in single-key lookups ................................................................................. 73 9.7 Partial matching in single-key lookups .............................................................................. 74 9.8 Lookup caching .................................................................................................................... 75 9.9 Quoting lookup data ............................................................................................................ 75 iv
  5. 5. 9.10 More about dnsdb .............................................................................................................. 75 9.11 Pseudo dnsdb record types ............................................................................................. 76 9.12 Multiple dnsdb lookups ..................................................................................................... 77 9.13 More about LDAP .............................................................................................................. 77 9.14 Format of LDAP queries ................................................................................................... 78 9.15 LDAP quoting ...................................................................................................................... 78 9.16 LDAP connections ............................................................................................................. 79 9.17 LDAP authentication and control information ................................................................ 80 9.18 Format of data returned by LDAP ................................................................................... 81 9.19 More about NIS+ ................................................................................................................ 81 9.20 SQL lookups ....................................................................................................................... 82 9.21 More about MySQL, PostgreSQL, Oracle, and InterBase ........................................... 82 9.22 Specifying the server in the query ................................................................................... 83 9.23 Special MySQL features ................................................................................................... 83 9.24 Special PostgreSQL features ........................................................................................... 83 9.25 More about SQLite ............................................................................................................ 8410. Domain, host, address, and local part lists .................................................................... 85 10.1 Expansion of lists ............................................................................................................... 85 10.2 Negated items in lists ........................................................................................................ 85 10.3 File names in lists .............................................................................................................. 85 10.4 An lsearch file is not an out-of-line list ............................................................................ 86 10.5 Named lists ......................................................................................................................... 86 10.6 Named lists compared with macros ................................................................................ 87 10.7 Named list caching ............................................................................................................ 87 10.8 Domain lists ........................................................................................................................ 88 10.9 Host lists .............................................................................................................................. 90 10.10 Special host list patterns ................................................................................................ 90 10.11 Host list patterns that match by IP address ................................................................. 90 10.12 Host list patterns for single-key lookups by host address ......................................... 91 10.13 Host list patterns that match by host name ................................................................. 92 10.14 Behaviour when an IP address or name cannot be found ........................................ 93 10.15 Temporary DNS errors when looking up host information ........................................ 93 10.16 Host list patterns for single-key lookups by host name ............................................. 93 10.17 Host list patterns for query-style lookups ..................................................................... 94 10.18 Mixing wildcarded host names and addresses in host lists ...................................... 94 10.19 Address lists ..................................................................................................................... 94 10.20 Case of letters in address lists ...................................................................................... 97 10.21 Local part lists .................................................................................................................. 9711. String expansions .................................................................................................................. 98 11.1 Literal text in expanded strings ........................................................................................ 98 11.2 Character escape sequences in expanded strings ...................................................... 98 11.3 Testing string expansions ................................................................................................. 98 11.4 Forced expansion failure ................................................................................................... 99 11.5 Expansion items ................................................................................................................. 99 11.6 Expansion operators ....................................................................................................... 108 11.7 Expansion conditions ...................................................................................................... 113 11.8 Combining expansion conditions .................................................................................. 119 11.9 Expansion variables ........................................................................................................ 11912. Embedded Perl ...................................................................................................................... 135 12.1 Setting up so Perl can be used ..................................................................................... 135 12.2 Calling Perl subroutines .................................................................................................. 135 12.3 Calling Exim functions from Perl ................................................................................... 136 v
  6. 6. 12.4 Use of standard output and error by Perl ..................................................................... 13613. Starting the daemon and the use of network interfaces ........................................... 137 13.1 Starting a listening daemon ........................................................................................... 137 13.2 Special IP listening addresses ...................................................................................... 138 13.3 Overriding local_interfaces and daemon_smtp_ports ............................................... 138 13.4 Support for the obsolete SSMTP (or SMTPS) protocol ............................................. 138 13.5 IPv6 address scopes ....................................................................................................... 139 13.6 Disabling IPv6 .................................................................................................................. 139 13.7 Examples of starting a listening daemon ..................................................................... 139 13.8 Recognizing the local host ............................................................................................. 140 13.9 Delivering to a remote host ............................................................................................ 14014. Main configuration ............................................................................................................... 141 14.1 Miscellaneous .................................................................................................................. 141 14.2 Exim parameters .............................................................................................................. 141 14.3 Privilege controls ............................................................................................................. 141 14.4 Logging .............................................................................................................................. 141 14.5 Frozen messages ............................................................................................................ 142 14.6 Data lookups .................................................................................................................... 142 14.7 Message ids ..................................................................................................................... 142 14.8 Embedded Perl Startup .................................................................................................. 142 14.9 Daemon ............................................................................................................................. 142 14.10 Resource control ........................................................................................................... 142 14.11 Policy controls ................................................................................................................ 143 14.12 Callout cache ................................................................................................................. 144 14.13 TLS .................................................................................................................................. 144 14.14 Local user handling ....................................................................................................... 144 14.15 All incoming messages (SMTP and non-SMTP) ...................................................... 144 14.16 Non-SMTP incoming messages ................................................................................. 144 14.17 Incoming SMTP messages .......................................................................................... 144 14.18 SMTP extensions .......................................................................................................... 145 14.19 Processing messages .................................................................................................. 145 14.20 System filter .................................................................................................................... 146 14.21 Routing and delivery ..................................................................................................... 146 14.22 Bounce and warning messages .................................................................................. 146 14.23 Alphabetical list of main options .................................................................................. 14615. Generic options for routers ............................................................................................... 18716. The accept router ................................................................................................................. 20017. The dnslookup router ......................................................................................................... 201 17.1 Problems with DNS lookups .......................................................................................... 201 17.2 Private options for dnslookup ........................................................................................ 201 17.3 Effect of qualify_single and search_parents ............................................................... 20318. The ipliteral router ............................................................................................................... 20519. The iplookup router ............................................................................................................. 20620. The manualroute router ...................................................................................................... 208 20.1 Private options for manualroute .................................................................................... 208 20.2 Routing rules in route_list ............................................................................................... 209 vi
  7. 7. 20.3 Routing rules in route_data ............................................................................................ 210 20.4 Format of the list of hosts ............................................................................................... 210 20.5 Format of one host item .................................................................................................. 211 20.6 How the list of hosts is used .......................................................................................... 211 20.7 How the options are used ............................................................................................... 212 20.8 Manualroute examples .................................................................................................... 21221. The queryprogram router ................................................................................................... 21522. The redirect router ............................................................................................................... 217 22.1 Redirection data ............................................................................................................... 217 22.2 Forward files and address verification .......................................................................... 217 22.3 Interpreting redirection data ........................................................................................... 218 22.4 Items in a non-filter redirection list ................................................................................ 218 22.5 Redirecting to a local mailbox ........................................................................................ 218 22.6 Special items in redirection lists .................................................................................... 219 22.7 Duplicate addresses ........................................................................................................ 221 22.8 Repeated redirection expansion ................................................................................... 221 22.9 Errors in redirection lists ................................................................................................. 221 22.10 Private options for the redirect router ......................................................................... 22123. Environment for running local transports ..................................................................... 229 23.1 Concurrent deliveries ...................................................................................................... 229 23.2 Uids and gids .................................................................................................................... 229 23.3 Current and home directories ........................................................................................ 230 23.4 Expansion variables derived from the address ........................................................... 23024. Generic options for transports ......................................................................................... 23125. Address batching in local transports ............................................................................. 23726. The appendfile transport .................................................................................................... 239 26.1 The file and directory options ........................................................................................ 239 26.2 Private options for appendfile ........................................................................................ 240 26.3 Operational details for appending ................................................................................. 249 26.4 Operational details for delivery to a new file ................................................................ 251 26.5 Maildir delivery ................................................................................................................. 251 26.6 Using tags to record message sizes ............................................................................. 252 26.7 Using a maildirsize file .................................................................................................... 252 26.8 Mailstore delivery ............................................................................................................. 253 26.9 Non-special new file delivery ......................................................................................... 25327. The autoreply transport ...................................................................................................... 254 27.1 Private options for autoreply .......................................................................................... 25428. The lmtp transport ............................................................................................................... 25729. The pipe transport ............................................................................................................... 259 29.1 Concurrent delivery ......................................................................................................... 259 29.2 Returned status and data ............................................................................................... 259 29.3 How the command is run ................................................................................................ 260 29.4 Environment variables .................................................................................................... 260 29.5 Private options for pipe ................................................................................................... 261 vii
  8. 8. 29.6 Using an external local delivery agent ......................................................................... 26530. The smtp transport .............................................................................................................. 267 30.1 Multiple messages on a single connection .................................................................. 267 30.2 Use of the $host and $host_address variables ........................................................... 267 30.3 Use of $tls_cipher and $tls_peerdn .............................................................................. 267 30.4 Private options for smtp .................................................................................................. 267 30.5 How the limits for the number of hosts to try are used .............................................. 27531. Address rewriting ................................................................................................................. 277 31.1 Explicitly configured address rewriting ......................................................................... 277 31.2 When does rewriting happen? ....................................................................................... 277 31.3 Testing the rewriting rules that apply on input ............................................................. 278 31.4 Rewriting rules ................................................................................................................. 278 31.5 Rewriting patterns ............................................................................................................ 279 31.6 Rewriting replacements .................................................................................................. 280 31.7 Rewriting flags .................................................................................................................. 280 31.8 Flags specifying which headers and envelope addresses to rewrite ...................... 280 31.9 The SMTP-time rewriting flag ........................................................................................ 280 31.10 Flags controlling the rewriting process ...................................................................... 281 31.11 Rewriting examples ....................................................................................................... 28132. Retry configuration .............................................................................................................. 283 32.1 Changing retry rules ........................................................................................................ 283 32.2 Format of retry rules ........................................................................................................ 283 32.3 Choosing which retry rule to use for address errors .................................................. 284 32.4 Choosing which retry rule to use for host and message errors ................................ 284 32.5 Retry rules for specific errors ......................................................................................... 285 32.6 Retry rules for specified senders .................................................................................. 286 32.7 Retry parameters ............................................................................................................. 287 32.8 Retry rule examples ........................................................................................................ 287 32.9 Timeout of retry data ....................................................................................................... 288 32.10 Long-term failures ......................................................................................................... 288 32.11 Deliveries that work intermittently ............................................................................... 28933. SMTP authentication ........................................................................................................... 290 33.1 Generic options for authenticators ................................................................................ 291 33.2 The AUTH parameter on MAIL commands ................................................................. 292 33.3 Authentication on an Exim server ................................................................................. 293 33.4 Testing server authentication ......................................................................................... 294 33.5 Authentication by an Exim client ................................................................................... 29434. The plaintext authenticator ............................................................................................... 296 34.1 Plaintext options ............................................................................................................... 296 34.2 Using plaintext in a server .............................................................................................. 296 34.3 The PLAIN authentication mechanism ......................................................................... 296 34.4 The LOGIN authentication mechanism ........................................................................ 297 34.5 Support for different kinds of authentication ................................................................ 298 34.6 Using plaintext in a client ................................................................................................ 29835. The cram_md5 authenticator ............................................................................................ 300 35.1 Using cram_md5 as a server ......................................................................................... 300 viii
  9. 9. 35.2 Using cram_md5 as a client ........................................................................................... 30036. The cyrus_sasl authenticator ........................................................................................... 302 36.1 Using cyrus_sasl as a server ......................................................................................... 30237. The dovecot authenticator ................................................................................................. 30438. The spa authenticator ......................................................................................................... 305 38.1 Using spa as a server ..................................................................................................... 305 38.2 Using spa as a client ....................................................................................................... 30539. Encrypted SMTP connections using TLS/SSL ............................................................. 307 39.1 Support for the legacy “ssmtp” (aka “smtps”) protocol .............................................. 307 39.2 OpenSSL vs GnuTLS ..................................................................................................... 307 39.3 GnuTLS parameter computation ................................................................................... 308 39.4 Requiring specific ciphers in OpenSSL ........................................................................ 308 39.5 Requiring specific ciphers or other parameters in GnuTLS ...................................... 309 39.6 Configuring an Exim server to use TLS ....................................................................... 310 39.7 Requesting and verifying client certificates ................................................................. 311 39.8 Revoked certificates ........................................................................................................ 312 39.9 Configuring an Exim client to use TLS ......................................................................... 312 39.10 Multiple messages on the same encrypted TCP/IP connection ............................ 312 39.11 Certificates and all that ................................................................................................. 313 39.12 Certificate chains ........................................................................................................... 313 39.13 Self-signed certificates ................................................................................................. 31340. Access control lists ............................................................................................................. 315 40.1 Testing ACLs .................................................................................................................... 315 40.2 Specifying when ACLs are used ................................................................................... 315 40.3 The non-SMTP ACLs ...................................................................................................... 316 40.4 The SMTP connect ACL ................................................................................................. 316 40.5 The EHLO/HELO ACL .................................................................................................... 316 40.6 The DATA ACLs ................................................................................................................ 316 40.7 The SMTP DKIM ACL ..................................................................................................... 317 40.8 The SMTP MIME ACL .................................................................................................... 317 40.9 The QUIT ACL .................................................................................................................. 317 40.10 The not-QUIT ACL ........................................................................................................ 317 40.11 Finding an ACL to use .................................................................................................. 318 40.12 ACL return codes .......................................................................................................... 318 40.13 Unset ACL options ........................................................................................................ 319 40.14 Data for message ACLs ............................................................................................... 319 40.15 Data for non-message ACLs ....................................................................................... 319 40.16 Format of an ACL .......................................................................................................... 320 40.17 ACL verbs ....................................................................................................................... 320 40.18 ACL variables ................................................................................................................. 322 40.19 Condition and modifier processing ............................................................................. 322 40.20 ACL modifiers ................................................................................................................. 323 40.21 Use of the control modifier ........................................................................................... 327 40.22 Summary of message fixup control ............................................................................ 330 40.23 Adding header lines in ACLs ....................................................................................... 330 40.24 ACL conditions ............................................................................................................... 331 40.25 Using DNS lists .............................................................................................................. 335 40.26 Specifying the IP address for a DNS list lookup ....................................................... 336 40.27 DNS lists keyed on domain names ............................................................................. 336 ix
  10. 10. 40.28 Multiple explicit keys for a DNS list ............................................................................. 336 40.29 Data returned by DNS lists .......................................................................................... 337 40.30 Variables set from DNS lists ........................................................................................ 337 40.31 Additional matching conditions for DNS lists ............................................................ 338 40.32 Negated DNS matching conditions ............................................................................ 338 40.33 Handling multiple DNS records from a DNS list ....................................................... 339 40.34 Detailed information from merged DNS lists ............................................................. 340 40.35 DNS lists and IPv6 ........................................................................................................ 340 40.36 Rate limiting incoming messages ............................................................................... 341 40.37 Ratelimit options for what is being measured ........................................................... 342 40.38 Ratelimit options for handling fast clients .................................................................. 342 40.39 Using rate limiting .......................................................................................................... 342 40.40 Reading ratelimit data without updating .................................................................... 343 40.41 Address verification ....................................................................................................... 344 40.42 Callout verification ......................................................................................................... 344 40.43 Additional parameters for callouts .............................................................................. 345 40.44 Callout caching .............................................................................................................. 347 40.45 Sender address verification reporting ........................................................................ 348 40.46 Redirection while verifying ........................................................................................... 348 40.47 Client SMTP authorization (CSA) ............................................................................... 349 40.48 Bounce address tag validation .................................................................................... 350 40.49 Using an ACL to control relaying ................................................................................ 351 40.50 Checking a relay configuration .................................................................................... 35241. Content scanning at ACL time .......................................................................................... 353 41.1 Scanning for viruses ........................................................................................................ 353 41.2 Scanning with SpamAssassin ....................................................................................... 356 41.3 Calling SpamAssassin from an Exim ACL ................................................................... 357 41.4 Scanning MIME parts ..................................................................................................... 358 41.5 Scanning with regular expressions ............................................................................... 360 41.6 The demime condition .................................................................................................... 36142. Adding a local scan function to Exim ............................................................................. 363 42.1 Building Exim to use a local scan function .................................................................. 363 42.2 API for local_scan() ......................................................................................................... 363 42.3 Configuration options for local_scan() .......................................................................... 364 42.4 Available Exim variables ................................................................................................. 365 42.5 Structure of header lines ................................................................................................ 367 42.6 Structure of recipient items ............................................................................................ 367 42.7 Available Exim functions ................................................................................................. 368 42.8 More about Exim’s memory handling ........................................................................... 37243. System-wide message filtering ........................................................................................ 373 43.1 Specifying a system filter ................................................................................................ 373 43.2 Testing a system filter ..................................................................................................... 373 43.3 Contents of a system filter .............................................................................................. 373 43.4 Additional variable for system filters ............................................................................. 374 43.5 Defer, freeze, and fail commands for system filters ................................................... 374 43.6 Adding and removing headers in a system filter ......................................................... 375 43.7 Setting an errors address in a system filter ................................................................. 375 43.8 Per-address filtering ........................................................................................................ 37644. Message processing ........................................................................................................... 377 44.1 Submission mode for non-local messages .................................................................. 377 x
  11. 11. 44.2 Line endings ..................................................................................................................... 378 44.3 Unqualified addresses .................................................................................................... 378 44.4 The UUCP From line ....................................................................................................... 379 44.5 Resent- header lines ....................................................................................................... 379 44.6 The Auto-Submitted: header line .................................................................................. 380 44.7 The Bcc: header line ....................................................................................................... 380 44.8 The Date: header line ..................................................................................................... 380 44.9 The Delivery-date: header line ...................................................................................... 380 44.10 The Envelope-to: header line ...................................................................................... 380 44.11 The From: header line .................................................................................................. 380 44.12 The Message-ID: header line ...................................................................................... 381 44.13 The Received: header line ........................................................................................... 381 44.14 The References: header line ....................................................................................... 381 44.15 The Return-path: header line ...................................................................................... 381 44.16 The Sender: header line ............................................................................................... 381 44.17 Adding and removing header lines in routers and transports ................................ 382 44.18 Constructed addresses ................................................................................................ 383 44.19 Case of local parts ........................................................................................................ 383 44.20 Dots in local parts .......................................................................................................... 384 44.21 Rewriting addresses ..................................................................................................... 38445. SMTP processing ................................................................................................................. 385 45.1 Outgoing SMTP and LMTP over TCP/IP ..................................................................... 385 45.2 Errors in outgoing SMTP ................................................................................................ 386 45.3 Incoming SMTP messages over TCP/IP ..................................................................... 387 45.4 Unrecognized SMTP commands .................................................................................. 389 45.5 Syntax and protocol errors in SMTP commands ........................................................ 389 45.6 Use of non-mail SMTP commands ............................................................................... 389 45.7 The VRFY and EXPN commands ................................................................................. 389 45.8 The ETRN command ...................................................................................................... 389 45.9 Incoming local SMTP ...................................................................................................... 390 45.10 Outgoing batched SMTP .............................................................................................. 390 45.11 Incoming batched SMTP .............................................................................................. 39146. Customizing bounce and warning messages .............................................................. 392 46.1 Customizing bounce messages .................................................................................... 392 46.2 Customizing warning messages ................................................................................... 39347. Some common configuration settings ........................................................................... 394 47.1 Sending mail to a smart host ......................................................................................... 394 47.2 Using Exim to handle mailing lists ................................................................................ 394 47.3 Syntax errors in mailing lists .......................................................................................... 394 47.4 Re-expansion of mailing lists ......................................................................................... 395 47.5 Closed mailing lists .......................................................................................................... 395 47.6 Variable Envelope Return Paths (VERP) ..................................................................... 396 47.7 Virtual domains ................................................................................................................ 397 47.8 Multiple user mailboxes .................................................................................................. 398 47.9 Simplified vacation processing ...................................................................................... 399 47.10 Taking copies of mail ..................................................................................................... 399 47.11 Intermittently connected hosts .................................................................................... 399 47.12 Exim on the upstream server host .............................................................................. 399 47.13 Exim on the intermittently connected client host ...................................................... 40048. Using Exim as a non-queueing client ............................................................................. 401 xi
  12. 12. 49. Log files .................................................................................................................................. 403 49.1 Where the logs are written ............................................................................................. 403 49.2 Logging to local files that are periodically “cycled” ..................................................... 404 49.3 Datestamped log files ..................................................................................................... 404 49.4 Logging to syslog ............................................................................................................. 405 49.5 Log line flags .................................................................................................................... 406 49.6 Logging message reception ........................................................................................... 406 49.7 Logging deliveries ............................................................................................................ 407 49.8 Discarded deliveries ........................................................................................................ 408 49.9 Deferred deliveries .......................................................................................................... 408 49.10 Delivery failures ............................................................................................................. 408 49.11 Fake deliveries ............................................................................................................... 408 49.12 Completion ..................................................................................................................... 408 49.13 Summary of Fields in Log Lines ................................................................................. 409 49.14 Other log entries ............................................................................................................ 409 49.15 Reducing or increasing what is logged ...................................................................... 410 49.16 Message log ................................................................................................................... 41350. Exim utilities .......................................................................................................................... 415 50.1 Finding out what Exim processes are doing (exiwhat) .............................................. 415 50.2 Selective queue listing (exiqgrep) ................................................................................. 415 50.3 Summarizing the queue (exiqsumm) ............................................................................ 416 50.4 Extracting specific information from the log (exigrep) ................................................ 417 50.5 Selecting messages by various criteria (exipick) ........................................................ 417 50.6 Cycling log files (exicyclog) ............................................................................................ 417 50.7 Mail statistics (eximstats) ............................................................................................... 418 50.8 Checking access policy (exim_checkaccess) ............................................................. 419 50.9 Making DBM files (exim_dbmbuild) .............................................................................. 419 50.10 Finding individual retry times (exinext) ....................................................................... 420 50.11 Hints database maintenance ....................................................................................... 420 50.12 exim_dumpdb ................................................................................................................. 420 50.13 exim_tidydb .................................................................................................................... 421 50.14 exim_fixdb ....................................................................................................................... 421 50.15 Mailbox maintenance (exim_lock) ............................................................................... 42251. The Exim monitor ................................................................................................................. 424 51.1 Running the monitor ........................................................................................................ 424 51.2 The stripcharts ................................................................................................................. 424 51.3 Main action buttons ......................................................................................................... 425 51.4 The log display ................................................................................................................. 425 51.5 The queue display ........................................................................................................... 426 51.6 The queue menu .............................................................................................................. 42652. Security considerations ..................................................................................................... 428 52.1 Building a more “hardened” Exim ................................................................................. 428 52.2 Root privilege ................................................................................................................... 428 52.3 Running Exim without privilege ..................................................................................... 430 52.4 Delivering to local files .................................................................................................... 431 52.5 IPv4 source routing ......................................................................................................... 431 52.6 The VRFY, EXPN, and ETRN commands in SMTP ................................................... 431 52.7 Privileged users ............................................................................................................... 431 52.8 Spool files ......................................................................................................................... 431 52.9 Use of argv[0] ................................................................................................................... 432 52.10 Use of %f formatting ..................................................................................................... 432 xii
  13. 13. 52.11 Embedded Exim path ................................................................................................... 432 52.12 Use of sprintf() ............................................................................................................... 432 52.13 Use of debug_printf() and log_write() ........................................................................ 432 52.14 Use of strcat() and strcpy() .......................................................................................... 43253. Format of spool files ........................................................................................................... 433 53.1 Format of the -H file ......................................................................................................... 43354. Support for DKIM (DomainKeys Identified Mail) - RFC4871 ..................................... 438 54.1 Signing outgoing messages ........................................................................................... 438 54.2 Verifying DKIM signatures in incoming mail ................................................................ 43955. Adding new drivers or lookup types ............................................................................... 442Options index ................................................................................................................................ 443Variables index ............................................................................................................................. 449Concept index ............................................................................................................................... 451 xiii
  14. 14. 1. IntroductionExim is a mail transfer agent (MTA) for hosts that are running Unix or Unix-like operating systems. Itwas designed on the assumption that it would be run on hosts that are permanently connected to theInternet. However, it can be used on intermittently connected hosts with suitable configurationadjustments.Configuration files currently exist for the following operating systems: AIX, BSD/OS (aka BSDI),Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, OpenUNIX, QNX, SCO, SCO SVR4.2 (akaUNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating systems are no longer current and cannoteasily be tested, so the configuration files may no longer work in practice.There are also configuration files for compiling Exim in the Cygwin environment that can be installedon systems running Windows. However, this document does not contain any information about run-ning Exim in the Cygwin environment.The terms and conditions for the use and distribution of Exim are contained in the file NOTICE. Eximis distributed under the terms of the GNU General Public Licence, a copy of which may be found inthe file LICENCE.The use, supply or promotion of Exim for the purpose of sending bulk, unsolicited electronic mail isincompatible with the basic aims of 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 file called ACKNOWLEDGMENTS, in which I have started recording thenames of contributors.1.1 Exim documentationThis edition of the Exim specification applies to version 4.73 of Exim. Substantive changes from the4.72 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 O’Reilly, covers Exim 3, and many things havechanged in Exim 4.)If you are using a Debian distribution of Exim, you will find information about Debian-specificfeatures in the file /usr/share/doc/exim4-base/README.Debian. The command man update-exim.confis another source of Debian-specific information. 1 Introduction (1)
  15. 15. 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 significant digit of the fractional part of the versionnumber changes. Specifications of new features that are not yet in this manual are placed in the filedoc/NewStuff in the Exim distribution.Some features may be classified as “experimental”. These may change incompatibly while they aredeveloping, or even be withdrawn. For this reason, they are not documented in this manual.Information about experimental features can be found in the file doc/experimental.txt.All changes to the program (whether new features, bug fixes, or other kinds of change) are notedbriefly in the file called doc/ChangeLog.This specification itself is available as an ASCII file in doc/spec.txt so that it can easily be searchedwith a text editor. Other files in the doc directory are:OptionLists.txt list of all options in alphabetical orderdbm.discuss.txt discussion about DBM librariesexim.8 a man page of Exim’s command line optionsexperimental.txt documentation of experimental featuresfilter.txt specification of the filter languageExim3.upgrade upgrade notes from release 2 to release 3Exim4.upgrade upgrade notes from release 3 to release 4The main specification and the specification of the filtering language are also available in otherformats (HTML, PostScript, PDF, and Texinfo). Section 1.6 below tells you how to get hold of these.1.2 FTP and web sitesThe primary site for Exim source distributions is currently the University of Cambridge’s FTP site,whose contents are described in Where to find the Exim distribution below. In addition, there is a website and an FTP site at exim.org. These are now also hosted at the University of Cambridge. Theexim.org site was previously hosted for a number of years by Energis Squared, formerly PlanetOnline Ltd, whose support I gratefully acknowledge.As well as Exim distribution tar files, 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.An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report bugs, and also to additems to the wish list. Please search first to check that you are not duplicating a previous entry.1.3 Mailing listsThe following Exim mailing lists exist:exim-users@exim.org General discussion listexim-dev@exim.org Discussion of bugs, enhancements, etc.exim-announce@exim.org Moderated, low volume announcements listexim-future@exim.org Discussion of long-term developmentYou can subscribe to these lists, change your existing subscriptions, and view or search the archivesvia the mailing lists link on the Exim home page. If you are using a Debian distribution of Exim, youmay wish to subscribe to the Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org viathis web page: http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-usersPlease ask Debian-specific questions on this list and not on the general Exim lists. 2 Introduction (1)
  16. 16. 1.4 Exim trainingTraining courses in Cambridge (UK) used to be run annually by the author of Exim, before he retired.At the time of writing, there are no plans to run further Exim courses in Cambridge. However, if thatchanges, relevant information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/.1.5 Bug reportsReports of obvious bugs can be emailed to bugs@exim.org or reported via the Bugzilla(http://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.6 Where to find the Exim distributionThe master ftp site for the Exim distribution is ftp://ftp.csx.cam.ac.uk/pub/software/email/eximThis is mirrored by ftp://ftp.exim.org/pub/eximThe file references that follow are relative to the exim directories at these sites. There are now quite anumber of independent mirror sites around the world. Those that I know about are listed in the filecalled Mirrors.Within the exim directory there are subdirectories called exim3 (for previous Exim 3 distributions),exim4 (for the latest Exim 4 distributions), and Testing for testing versions. In the exim4 subdirectory,the current release can always be found in files called exim-n.nn.tar.gz exim-n.nn.tar.bz2where n.nn is the highest such version number in the directory. The two files contain identical data;the only difference is the type of compression. The .bz2 file is usually a lot smaller than the .gz file.The distributions are currently signed with Nigel Metheringham’s GPG key. The corresponding pub-lic key is available from a number of keyservers, and there is also a copy in the file nigel-pubkey.asc.The signatures for the tar bundles are in: exim-n.nn.tar.gz.asc exim-n.nn.tar.bz2.ascFor each released version, the log of changes is made separately available in a separate file in thedirectory ChangeLogs so that it is possible to find out what has changed without having to downloadthe entire distribution.The main distribution contains ASCII versions of this specification and other documentation; otherformats of the documents are available in separate files inside the exim4 directory of the FTP site: exim-html-n.nn.tar.gz exim-pdf-n.nn.tar.gz exim-postscript-n.nn.tar.gz exim-texinfo-n.nn.tar.gzThese tar files contain only the doc directory, not the complete distribution, and are also available in.bz2 as well as .gz forms.1.7 Limitations• Exim is designed for use as an Internet MTA, and therefore handles addresses in RFC 2822 domain format only. It cannot handle UUCP “bang paths”, though simple two-component bang paths can be converted by a straightforward rewriting configuration. This restriction does not prevent Exim from being interfaced to UUCP as a transport mechanism, provided that domain addresses are used. 3 Introduction (1)
  17. 17. • Exim insists that every address it handles has a domain attached. For incoming local messages, domainless addresses are automatically qualified with a configured domain value. Configuration options specify from which remote systems unqualified addresses are acceptable. These are then qualified on arrival.• The only external transport mechanisms that are currently implemented are SMTP and LMTP over a TCP/IP network (including support for IPv6). However, a pipe transport is available, and there are facilities for writing messages to files and pipes, optionally in batched SMTP format; these facilities can be used to send messages to other transport mechanisms such as UUCP, provided they can 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, it is better to get the messages “delivered” into files (that is, off Exim’s queue) and subsequently passed 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 using additional specialized software packages. If you compile Exim with the content-scanning exten- sion, straightforward interfaces to a number of common scanners are provided.1.8 Run time configurationExim’s run time configuration is held in a single text file that is divided into a number of sections. Theentries in this file consist of keywords and values, in the style of Smail 3 configuration files. A defaultconfiguration file which is suitable for simple online installations is provided in the distribution, andis described in chapter 7 below.1.9 Calling interfaceLike 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 Exim’s own format. There are also some additional options thatare compatible with Smail 3, and some further options that are new to Exim. Chapter 5 documents allExim’s command line options. This information is automatically made into the man page that formspart of the Exim distribution.Control of messages 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 Exim’s command line administration options.1.10 TerminologyThe 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 failureerror report”. Such messages have an empty sender address in the message’s envelope (see below) toensure that they cannot themselves give rise to further bounce messages.The term default appears frequently in this manual. It is used to qualify a value which is used in theabsence of any setting in the configuration. It may also qualify an action which is taken unless aconfiguration setting specifies otherwise.The term defer is used when the delivery of a message to a specific destination cannot immediatelytake place for some reason (a remote host may be down, or a user’s local mailbox may be full). Suchdeliveries are deferred until a later time. 4 Introduction (1)
  18. 18. The word domain is sometimes used to mean all but the first component of a host’s name. It is notused in that sense here, where it normally refers to the part of an email address following the @ sign.A message in transit has an associated envelope, as well as a header and a body. The envelopecontains a sender address (to which bounce messages should be delivered), and any number ofrecipient addresses. References to the sender or the recipients of a message usually mean theaddresses in the envelope. An MTA uses these addresses for delivery, and for returning bouncemessages, not the addresses that appear in the header lines.The header of a message is the first part of a message’s text, consisting of a number of lines, each ofwhich has a name such as From:, To:, Subject:, etc. Long header lines can be split over several textlines by indenting the continuations. The header is separated from the body by a blank line.The term local part, which is taken from RFC 2822, is used to refer to 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 file or a pipe on thelocal host from delivery by SMTP over TCP/IP to another host. As far as Exim is concerned, all hostsother than the host it is running on are remote.Return path is another name that is used for the sender address in a message’s envelope.The term queue is used to refer to the set of messages awaiting delivery, because this term is inwidespread use in the context of MTAs. However, in Exim’s case the reality is more like a pool 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 first sense. 5 Introduction (1)
  19. 19. 2. Incorporated codeA 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 the freely-distributable PCRE library, copyright © University of Cambridge. The source to PCRE is no longer 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 from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre.• Support for the cdb (Constant DataBase) lookup method is provided by code contributed by Nigel Metheringham 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 code contains 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 of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This code implements Dan Bernstein’s Constant DataBase (cdb) spec. Information, the spec and sample code for cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This implemen- tation borrows some code from Dan Bernstein’s implementation (which has no license restrictions applied to it).• Client support for Microsoft’s Secure Password Authentication is provided by code contributed by Marc Prud’hommeaux. Server support was contributed by Tom Kistner. This includes code taken from the Samba project, which is released under the Gnu GPL.• Support for calling the Cyrus pwcheck and saslauthd daemons is provided by code taken from the Cyrus-SASL library and adapted by Alexander S. Sabourenkov. The permission notice appears below, in accordance with the conditions expressed therein. Copyright © 2001 Carnegie Mellon University. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: (1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. (2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. (3) The name “Carnegie Mellon University” must not be used to endorse or promote products derived from this software without prior written permission. For per- mission or any other legal details, please contact Office of Technology Transfer Carnegie Mellon University 5000 Forbes Avenue Pittsburgh, PA 15213-3890 (412) 268-4387, fax: (412) 268-7395 tech-transfer@andrew.cmu.edu (4) Redistributions of any form whatsoever must retain the following acknowledgment: “This product includes software developed by Computing Services at Carnegie Mellon University (http://www.cmu.edu/computing/.” CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES 6 Incorporated code (2)
  20. 20. OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.• The Exim Monitor program, which is an X-Window application, includes modified versions of the Athena StripChart and TextPop widgets. This code is copyright by DEC and MIT, and their permission notice appears below, in accordance with the conditions expressed therein. Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, and the Massachusetts Institute of Technology, Cambridge, Massachusetts. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Digital or MIT not be used in advertising or publicity pertaining to distribution of the software without specific, writ- ten prior permission. DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.• Many people have contributed code fragments, some large, some small, that were not covered by any specific licence requirements. It is assumed that the contributors are happy to see their code incorporated into Exim under the GPL. 7 Incorporated code (2)

×