# HG changeset patch # User Heiko Schlittermann (JUMPER) # Date 1297633353 -3600 # Node ID 525826c63ebad278789b394b7b1af86ce78f8d4c # Parent 3269aa4bc6c31089cb70951afebd4df7c978d8bd updated the doc about maildir tags diff -r 3269aa4bc6c3 -r 525826c63eba doc.maildir_tag --- a/doc.maildir_tag Sun Feb 13 14:27:01 2011 +0100 +++ b/doc.maildir_tag Sun Feb 13 22:42:33 2011 +0100 @@ -1,20 +1,31869 @@ # HG changeset patch -# Parent edb5de053fb4b1e81d7ae2eeb4b5afd977fb1978 -diff -r edb5de053fb4 -r ceca9fed510e doc/spec.txt ---- a/doc/spec.txt Fri Feb 11 21:12:38 2011 +0100 -+++ b/doc/spec.txt Fri Feb 11 21:35:49 2011 +0100 -@@ -18794,6 +18794,14 @@ - empty, it is ignored. If it starts with an alphanumeric character, a leading - colon is inserted. - +# Parent 0000000000000000000000000000000000000000 + +diff --git a/doc/spec.txt b/doc/spec.txt +new file mode 100644 +--- /dev/null ++++ b/doc/spec.txt +@@ -0,0 +1,31861 @@ ++Specification of the Exim Mail Transfer Agent ++ ++Exim Maintainers ++ ++Copyright (c) 2011 University of Cambridge ++ +++-----------------------------------------------------------------------------+ ++|-----------------------------------------------------------------------------| ++|Revision 4.74 |21 Jan 2011 |EM | +++-----------------------------------------------------------------------------+ ++------------------------------------------------------------------------------- ++ ++TABLE OF CONTENTS ++ ++1. Introduction ++ ++ 1.1. Exim documentation ++ 1.2. FTP and web sites ++ 1.3. Mailing lists ++ 1.4. Exim training ++ 1.5. Bug reports ++ 1.6. Where to find the Exim distribution ++ 1.7. Limitations ++ 1.8. Run time configuration ++ 1.9. Calling interface ++ 1.10. Terminology ++ ++2. Incorporated code ++3. How Exim receives and delivers mail ++ ++ 3.1. Overall philosophy ++ 3.2. Policy control ++ 3.3. User filters ++ 3.4. Message identification ++ 3.5. Receiving mail ++ 3.6. Handling an incoming message ++ 3.7. Life of a message ++ 3.8. Processing an address for delivery ++ 3.9. Processing an address for verification ++ 3.10. Running an individual router ++ 3.11. Duplicate addresses ++ 3.12. Router preconditions ++ 3.13. Delivery in detail ++ 3.14. Retry mechanism ++ 3.15. Temporary delivery failure ++ 3.16. Permanent delivery failure ++ 3.17. Failures to deliver bounce messages ++ ++4. Building and installing Exim ++ ++ 4.1. Unpacking ++ 4.2. Multiple machine architectures and operating systems ++ 4.3. PCRE library ++ 4.4. DBM libraries ++ 4.5. Pre-building configuration ++ 4.6. Support for iconv() ++ 4.7. Including TLS/SSL encryption support ++ 4.8. Use of tcpwrappers ++ 4.9. Including support for IPv6 ++ 4.10. Dynamically loaded lookup module support ++ 4.11. The building process ++ 4.12. Output from "make" ++ 4.13. Overriding build-time options for Exim ++ 4.14. OS-specific header files ++ 4.15. Overriding build-time options for the monitor ++ 4.16. Installing Exim binaries and scripts ++ 4.17. Installing info documentation ++ 4.18. Setting up the spool directory ++ 4.19. Testing ++ 4.20. Replacing another MTA with Exim ++ 4.21. Upgrading Exim ++ 4.22. Stopping the Exim daemon on Solaris ++ ++5. The Exim command line ++ ++ 5.1. Setting options by program name ++ 5.2. Trusted and admin users ++ 5.3. Command line options ++ ++6. The Exim run time configuration file ++ ++ 6.1. Using a different configuration file ++ 6.2. Configuration file format ++ 6.3. File inclusions in the configuration file ++ 6.4. Macros in the configuration file ++ 6.5. Macro substitution ++ 6.6. Redefining macros ++ 6.7. Overriding macro values ++ 6.8. Example of macro usage ++ 6.9. Conditional skips in the configuration file ++ 6.10. Common option syntax ++ 6.11. Boolean options ++ 6.12. Integer values ++ 6.13. Octal integer values ++ 6.14. Fixed point numbers ++ 6.15. Time intervals ++ 6.16. String values ++ 6.17. Expanded strings ++ 6.18. User and group names ++ 6.19. List construction ++ 6.20. Changing list separators ++ 6.21. Empty items in lists ++ 6.22. Format of driver configurations ++ ++7. The default configuration file ++ ++ 7.1. Main configuration settings ++ 7.2. ACL configuration ++ 7.3. Router configuration ++ 7.4. Transport configuration ++ 7.5. Default retry rule ++ 7.6. Rewriting configuration ++ 7.7. Authenticators configuration ++ ++8. Regular expressions ++9. File and database lookups ++ ++ 9.1. Examples of different lookup syntax ++ 9.2. Lookup types ++ 9.3. Single-key lookup types ++ 9.4. Query-style lookup types ++ 9.5. Temporary errors in lookups ++ 9.6. Default values in single-key lookups ++ 9.7. Partial matching in single-key lookups ++ 9.8. Lookup caching ++ 9.9. Quoting lookup data ++ 9.10. More about dnsdb ++ 9.11. Pseudo dnsdb record types ++ 9.12. Multiple dnsdb lookups ++ 9.13. More about LDAP ++ 9.14. Format of LDAP queries ++ 9.15. LDAP quoting ++ 9.16. LDAP connections ++ 9.17. LDAP authentication and control information ++ 9.18. Format of data returned by LDAP ++ 9.19. More about NIS+ ++ 9.20. SQL lookups ++ 9.21. More about MySQL, PostgreSQL, Oracle, and InterBase ++ 9.22. Specifying the server in the query ++ 9.23. Special MySQL features ++ 9.24. Special PostgreSQL features ++ 9.25. More about SQLite ++ ++10. Domain, host, address, and local part lists ++ ++ 10.1. Expansion of lists ++ 10.2. Negated items in lists ++ 10.3. File names in lists ++ 10.4. An lsearch file is not an out-of-line list ++ 10.5. Named lists ++ 10.6. Named lists compared with macros ++ 10.7. Named list caching ++ 10.8. Domain lists ++ 10.9. Host lists ++ 10.10. Special host list patterns ++ 10.11. Host list patterns that match by IP address ++ 10.12. Host list patterns for single-key lookups by host address ++ 10.13. Host list patterns that match by host name ++ 10.14. Behaviour when an IP address or name cannot be found ++ 10.15. Temporary DNS errors when looking up host information ++ 10.16. Host list patterns for single-key lookups by host name ++ 10.17. Host list patterns for query-style lookups ++ 10.18. Mixing wildcarded host names and addresses in host lists ++ 10.19. Address lists ++ 10.20. Case of letters in address lists ++ 10.21. Local part lists ++ ++11. String expansions ++ ++ 11.1. Literal text in expanded strings ++ 11.2. Character escape sequences in expanded strings ++ 11.3. Testing string expansions ++ 11.4. Forced expansion failure ++ 11.5. Expansion items ++ 11.6. Expansion operators ++ 11.7. Expansion conditions ++ 11.8. Combining expansion conditions ++ 11.9. Expansion variables ++ ++12. Embedded Perl ++ ++ 12.1. Setting up so Perl can be used ++ 12.2. Calling Perl subroutines ++ 12.3. Calling Exim functions from Perl ++ 12.4. Use of standard output and error by Perl ++ ++13. Starting the daemon and the use of network interfaces ++ ++ 13.1. Starting a listening daemon ++ 13.2. Special IP listening addresses ++ 13.3. Overriding local_interfaces and daemon_smtp_ports ++ 13.4. Support for the obsolete SSMTP (or SMTPS) protocol ++ 13.5. IPv6 address scopes ++ 13.6. Disabling IPv6 ++ 13.7. Examples of starting a listening daemon ++ 13.8. Recognizing the local host ++ 13.9. Delivering to a remote host ++ ++14. Main configuration ++ ++ 14.1. Miscellaneous ++ 14.2. Exim parameters ++ 14.3. Privilege controls ++ 14.4. Logging ++ 14.5. Frozen messages ++ 14.6. Data lookups ++ 14.7. Message ids ++ 14.8. Embedded Perl Startup ++ 14.9. Daemon ++ 14.10. Resource control ++ 14.11. Policy controls ++ 14.12. Callout cache ++ 14.13. TLS ++ 14.14. Local user handling ++ 14.15. All incoming messages (SMTP and non-SMTP) ++ 14.16. Non-SMTP incoming messages ++ 14.17. Incoming SMTP messages ++ 14.18. SMTP extensions ++ 14.19. Processing messages ++ 14.20. System filter ++ 14.21. Routing and delivery ++ 14.22. Bounce and warning messages ++ 14.23. Alphabetical list of main options ++ ++15. Generic options for routers ++16. The accept router ++17. The dnslookup router ++ ++ 17.1. Problems with DNS lookups ++ 17.2. Private options for dnslookup ++ 17.3. Effect of qualify_single and search_parents ++ ++18. The ipliteral router ++19. The iplookup router ++20. The manualroute router ++ ++ 20.1. Private options for manualroute ++ 20.2. Routing rules in route_list ++ 20.3. Routing rules in route_data ++ 20.4. Format of the list of hosts ++ 20.5. Format of one host item ++ 20.6. How the list of hosts is used ++ 20.7. How the options are used ++ 20.8. Manualroute examples ++ ++21. The queryprogram router ++22. The redirect router ++ ++ 22.1. Redirection data ++ 22.2. Forward files and address verification ++ 22.3. Interpreting redirection data ++ 22.4. Items in a non-filter redirection list ++ 22.5. Redirecting to a local mailbox ++ 22.6. Special items in redirection lists ++ 22.7. Duplicate addresses ++ 22.8. Repeated redirection expansion ++ 22.9. Errors in redirection lists ++ 22.10. Private options for the redirect router ++ ++23. Environment for running local transports ++ ++ 23.1. Concurrent deliveries ++ 23.2. Uids and gids ++ 23.3. Current and home directories ++ 23.4. Expansion variables derived from the address ++ ++24. Generic options for transports ++25. Address batching in local transports ++26. The appendfile transport ++ ++ 26.1. The file and directory options ++ 26.2. Private options for appendfile ++ 26.3. Operational details for appending ++ 26.4. Operational details for delivery to a new file ++ 26.5. Maildir delivery ++ 26.6. Using tags to record message sizes ++ 26.7. Using a maildirsize file ++ 26.8. Mailstore delivery ++ 26.9. Non-special new file delivery ++ ++27. The autoreply transport ++ ++ 27.1. Private options for autoreply ++ ++28. The lmtp transport ++29. The pipe transport ++ ++ 29.1. Concurrent delivery ++ 29.2. Returned status and data ++ 29.3. How the command is run ++ 29.4. Environment variables ++ 29.5. Private options for pipe ++ 29.6. Using an external local delivery agent ++ ++30. The smtp transport ++ ++ 30.1. Multiple messages on a single connection ++ 30.2. Use of the $host and $host_address variables ++ 30.3. Use of $tls_cipher and $tls_peerdn ++ 30.4. Private options for smtp ++ 30.5. How the limits for the number of hosts to try are used ++ ++31. Address rewriting ++ ++ 31.1. Explicitly configured address rewriting ++ 31.2. When does rewriting happen? ++ 31.3. Testing the rewriting rules that apply on input ++ 31.4. Rewriting rules ++ 31.5. Rewriting patterns ++ 31.6. Rewriting replacements ++ 31.7. Rewriting flags ++ 31.8. Flags specifying which headers and envelope addresses to rewrite ++ 31.9. The SMTP-time rewriting flag ++ 31.10. Flags controlling the rewriting process ++ 31.11. Rewriting examples ++ ++32. Retry configuration ++ ++ 32.1. Changing retry rules ++ 32.2. Format of retry rules ++ 32.3. Choosing which retry rule to use for address errors ++ 32.4. Choosing which retry rule to use for host and message errors ++ 32.5. Retry rules for specific errors ++ 32.6. Retry rules for specified senders ++ 32.7. Retry parameters ++ 32.8. Retry rule examples ++ 32.9. Timeout of retry data ++ 32.10. Long-term failures ++ 32.11. Deliveries that work intermittently ++ ++33. SMTP authentication ++ ++ 33.1. Generic options for authenticators ++ 33.2. The AUTH parameter on MAIL commands ++ 33.3. Authentication on an Exim server ++ 33.4. Testing server authentication ++ 33.5. Authentication by an Exim client ++ ++34. The plaintext authenticator ++ ++ 34.1. Plaintext options ++ 34.2. Using plaintext in a server ++ 34.3. The PLAIN authentication mechanism ++ 34.4. The LOGIN authentication mechanism ++ 34.5. Support for different kinds of authentication ++ 34.6. Using plaintext in a client ++ ++35. The cram_md5 authenticator ++ ++ 35.1. Using cram_md5 as a server ++ 35.2. Using cram_md5 as a client ++ ++36. The cyrus_sasl authenticator ++ ++ 36.1. Using cyrus_sasl as a server ++ ++37. The dovecot authenticator ++38. The spa authenticator ++ ++ 38.1. Using spa as a server ++ 38.2. Using spa as a client ++ ++39. Encrypted SMTP connections using TLS/SSL ++ ++ 39.1. Support for the legacy "ssmtp" (aka "smtps") protocol ++ 39.2. OpenSSL vs GnuTLS ++ 39.3. GnuTLS parameter computation ++ 39.4. Requiring specific ciphers in OpenSSL ++ 39.5. Requiring specific ciphers or other parameters in GnuTLS ++ 39.6. Configuring an Exim server to use TLS ++ 39.7. Requesting and verifying client certificates ++ 39.8. Revoked certificates ++ 39.9. Configuring an Exim client to use TLS ++ 39.10. Multiple messages on the same encrypted TCP/IP connection ++ 39.11. Certificates and all that ++ 39.12. Certificate chains ++ 39.13. Self-signed certificates ++ ++40. Access control lists ++ ++ 40.1. Testing ACLs ++ 40.2. Specifying when ACLs are used ++ 40.3. The non-SMTP ACLs ++ 40.4. The SMTP connect ACL ++ 40.5. The EHLO/HELO ACL ++ 40.6. The DATA ACLs ++ 40.7. The SMTP DKIM ACL ++ 40.8. The SMTP MIME ACL ++ 40.9. The QUIT ACL ++ 40.10. The not-QUIT ACL ++ 40.11. Finding an ACL to use ++ 40.12. ACL return codes ++ 40.13. Unset ACL options ++ 40.14. Data for message ACLs ++ 40.15. Data for non-message ACLs ++ 40.16. Format of an ACL ++ 40.17. ACL verbs ++ 40.18. ACL variables ++ 40.19. Condition and modifier processing ++ 40.20. ACL modifiers ++ 40.21. Use of the control modifier ++ 40.22. Summary of message fixup control ++ 40.23. Adding header lines in ACLs ++ 40.24. ACL conditions ++ 40.25. Using DNS lists ++ 40.26. Specifying the IP address for a DNS list lookup ++ 40.27. DNS lists keyed on domain names ++ 40.28. Multiple explicit keys for a DNS list ++ 40.29. Data returned by DNS lists ++ 40.30. Variables set from DNS lists ++ 40.31. Additional matching conditions for DNS lists ++ 40.32. Negated DNS matching conditions ++ 40.33. Handling multiple DNS records from a DNS list ++ 40.34. Detailed information from merged DNS lists ++ 40.35. DNS lists and IPv6 ++ 40.36. Rate limiting incoming messages ++ 40.37. Ratelimit options for what is being measured ++ 40.38. Ratelimit options for handling fast clients ++ 40.39. Using rate limiting ++ 40.40. Reading ratelimit data without updating ++ 40.41. Address verification ++ 40.42. Callout verification ++ 40.43. Additional parameters for callouts ++ 40.44. Callout caching ++ 40.45. Sender address verification reporting ++ 40.46. Redirection while verifying ++ 40.47. Client SMTP authorization (CSA) ++ 40.48. Bounce address tag validation ++ 40.49. Using an ACL to control relaying ++ 40.50. Checking a relay configuration ++ ++41. Content scanning at ACL time ++ ++ 41.1. Scanning for viruses ++ 41.2. Scanning with SpamAssassin ++ 41.3. Calling SpamAssassin from an Exim ACL ++ 41.4. Scanning MIME parts ++ 41.5. Scanning with regular expressions ++ 41.6. The demime condition ++ ++42. Adding a local scan function to Exim ++ ++ 42.1. Building Exim to use a local scan function ++ 42.2. API for local_scan() ++ 42.3. Configuration options for local_scan() ++ 42.4. Available Exim variables ++ 42.5. Structure of header lines ++ 42.6. Structure of recipient items ++ 42.7. Available Exim functions ++ 42.8. More about Exim's memory handling ++ ++43. System-wide message filtering ++ ++ 43.1. Specifying a system filter ++ 43.2. Testing a system filter ++ 43.3. Contents of a system filter ++ 43.4. Additional variable for system filters ++ 43.5. Defer, freeze, and fail commands for system filters ++ 43.6. Adding and removing headers in a system filter ++ 43.7. Setting an errors address in a system filter ++ 43.8. Per-address filtering ++ ++44. Message processing ++ ++ 44.1. Submission mode for non-local messages ++ 44.2. Line endings ++ 44.3. Unqualified addresses ++ 44.4. The UUCP From line ++ 44.5. Resent- header lines ++ 44.6. The Auto-Submitted: header line ++ 44.7. The Bcc: header line ++ 44.8. The Date: header line ++ 44.9. The Delivery-date: header line ++ 44.10. The Envelope-to: header line ++ 44.11. The From: header line ++ 44.12. The Message-ID: header line ++ 44.13. The Received: header line ++ 44.14. The References: header line ++ 44.15. The Return-path: header line ++ 44.16. The Sender: header line ++ 44.17. Adding and removing header lines in routers and transports ++ 44.18. Constructed addresses ++ 44.19. Case of local parts ++ 44.20. Dots in local parts ++ 44.21. Rewriting addresses ++ ++45. SMTP processing ++ ++ 45.1. Outgoing SMTP and LMTP over TCP/IP ++ 45.2. Errors in outgoing SMTP ++ 45.3. Incoming SMTP messages over TCP/IP ++ 45.4. Unrecognized SMTP commands ++ 45.5. Syntax and protocol errors in SMTP commands ++ 45.6. Use of non-mail SMTP commands ++ 45.7. The VRFY and EXPN commands ++ 45.8. The ETRN command ++ 45.9. Incoming local SMTP ++ 45.10. Outgoing batched SMTP ++ 45.11. Incoming batched SMTP ++ ++46. Customizing bounce and warning messages ++ ++ 46.1. Customizing bounce messages ++ 46.2. Customizing warning messages ++ ++47. Some common configuration settings ++ ++ 47.1. Sending mail to a smart host ++ 47.2. Using Exim to handle mailing lists ++ 47.3. Syntax errors in mailing lists ++ 47.4. Re-expansion of mailing lists ++ 47.5. Closed mailing lists ++ 47.6. Variable Envelope Return Paths (VERP) ++ 47.7. Virtual domains ++ 47.8. Multiple user mailboxes ++ 47.9. Simplified vacation processing ++ 47.10. Taking copies of mail ++ 47.11. Intermittently connected hosts ++ 47.12. Exim on the upstream server host ++ 47.13. Exim on the intermittently connected client host ++ ++48. Using Exim as a non-queueing client ++49. Log files ++ ++ 49.1. Where the logs are written ++ 49.2. Logging to local files that are periodically "cycled" ++ 49.3. Datestamped log files ++ 49.4. Logging to syslog ++ 49.5. Log line flags ++ 49.6. Logging message reception ++ 49.7. Logging deliveries ++ 49.8. Discarded deliveries ++ 49.9. Deferred deliveries ++ 49.10. Delivery failures ++ 49.11. Fake deliveries ++ 49.12. Completion ++ 49.13. Summary of Fields in Log Lines ++ 49.14. Other log entries ++ 49.15. Reducing or increasing what is logged ++ 49.16. Message log ++ ++50. Exim utilities ++ ++ 50.1. Finding out what Exim processes are doing (exiwhat) ++ 50.2. Selective queue listing (exiqgrep) ++ 50.3. Summarizing the queue (exiqsumm) ++ 50.4. Extracting specific information from the log (exigrep) ++ 50.5. Selecting messages by various criteria (exipick) ++ 50.6. Cycling log files (exicyclog) ++ 50.7. Mail statistics (eximstats) ++ 50.8. Checking access policy (exim_checkaccess) ++ 50.9. Making DBM files (exim_dbmbuild) ++ 50.10. Finding individual retry times (exinext) ++ 50.11. Hints database maintenance ++ 50.12. exim_dumpdb ++ 50.13. exim_tidydb ++ 50.14. exim_fixdb ++ 50.15. Mailbox maintenance (exim_lock) ++ ++51. The Exim monitor ++ ++ 51.1. Running the monitor ++ 51.2. The stripcharts ++ 51.3. Main action buttons ++ 51.4. The log display ++ 51.5. The queue display ++ 51.6. The queue menu ++ ++52. Security considerations ++ ++ 52.1. Building a more "hardened" Exim ++ 52.2. Root privilege ++ 52.3. Running Exim without privilege ++ 52.4. Delivering to local files ++ 52.5. IPv4 source routing ++ 52.6. The VRFY, EXPN, and ETRN commands in SMTP ++ 52.7. Privileged users ++ 52.8. Spool files ++ 52.9. Use of argv[0] ++ 52.10. Use of %f formatting ++ 52.11. Embedded Exim path ++ 52.12. Dynamic module directory ++ 52.13. Use of sprintf() ++ 52.14. Use of debug_printf() and log_write() ++ 52.15. Use of strcat() and strcpy() ++ ++53. Format of spool files ++ ++ 53.1. Format of the -H file ++ ++54. Support for DKIM (DomainKeys Identified Mail) - RFC4871 ++ ++ 54.1. Signing outgoing messages ++ 54.2. Verifying DKIM signatures in incoming mail ++ ++55. Adding new drivers or lookup types ++ ++1. Introduction ++ ++Exim is a mail transfer agent (MTA) for hosts that are running Unix or ++Unix-like operating systems. It was designed on the assumption that it would be ++run on hosts that are permanently connected to the Internet. However, it can be ++used on intermittently connected hosts with suitable configuration adjustments. ++ ++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 (aka UNIX-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 cannot easily 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 installed on systems running Windows. However, this document does ++not contain any information about running Exim in the Cygwin environment. ++ ++The terms and conditions for the use and distribution of Exim are contained in ++the file NOTICE. Exim is distributed under the terms of the GNU General Public ++Licence, a copy of which may be found in the file LICENCE. ++ ++The use, supply or promotion of Exim for the purpose of sending bulk, ++unsolicited electronic mail is incompatible with the basic aims of the program, ++which revolve around the free provision of a service that enhances the quality ++of personal communications. The author of Exim regards indiscriminate ++mass-mailing as an antisocial, irresponsible abuse of the Internet. ++ ++Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the ++experience of running and working on the Smail 3 code, I could never have ++contemplated starting to write a new MTA. Many of the ideas and user interfaces ++were originally taken from Smail 3, though the actual code of Exim is entirely ++new, and has developed far beyond the initial concept. ++ ++Many people, both in Cambridge and around the world, have contributed to the ++development and the testing of Exim, and to porting it to various operating ++systems. I am grateful to them all. The distribution now contains a file called ++ACKNOWLEDGMENTS, in which I have started recording the names of contributors. ++ ++1.1 Exim documentation ++ ++This edition of the Exim specification applies to version 4.74 of Exim. ++Substantive changes from the 4.72 edition are marked in some renditions of the ++document; this paragraph is so marked if the rendition 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 have some 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 a way 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 tutorial material can be found in a book entitled The Exim ++SMTP Mail Server (second edition, 2007), published 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. (Note that the earlier book about Exim, ++published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) ++ ++If you are using a Debian distribution of Exim, you will find information about ++Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian. ++The command man update-exim.conf is another source of Debian-specific ++information. ++ ++As the program develops, there may be features in newer versions that have not ++yet made it into this document, which is updated only when the most significant ++digit of the fractional part of the version number changes. Specifications of ++new features that are not yet in this manual are placed in the file doc/ ++NewStuff in the Exim distribution. ++ ++Some features may be classified as "experimental". These may change ++incompatibly while they are developing, 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 noted briefly 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 searched with a text editor. Other files in the doc directory ++are: ++ ++OptionLists.txt list of all options in alphabetical order ++dbm.discuss.txt discussion about DBM libraries ++exim.8 a man page of Exim's command line options ++experimental.txt documentation of experimental features ++filter.txt specification of the filter language ++Exim3.upgrade upgrade notes from release 2 to release 3 ++Exim4.upgrade upgrade notes from release 3 to release 4 ++ ++The main specification and the specification of the filtering language are also ++available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6 ++below tells you how to get hold of these. ++ ++1.2 FTP and web sites ++ ++The 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 web site and an FTP site at ++exim.org. These are now also hosted at the University of Cambridge. The ++exim.org site was previously hosted for a number of years by Energis Squared, ++formerly Planet Online Ltd, whose support I gratefully acknowledge. ++ ++As well as Exim distribution tar files, the Exim web site contains a number of ++differently formatted versions 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 other examples, 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 add items to the wish list. Please search first to check that ++you are not duplicating a previous entry. ++ ++1.3 Mailing lists ++ ++The following Exim mailing lists exist: ++ ++exim-users@exim.org General discussion list ++exim-dev@exim.org Discussion of bugs, enhancements, etc. ++exim-announce@exim.org Moderated, low volume announcements list ++exim-future@exim.org Discussion of long-term development ++ ++You can subscribe to these lists, change your existing subscriptions, and view ++or search the archives via the mailing lists link on the Exim home page. If you ++are using a Debian distribution of Exim, you may wish to subscribe to the ++Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this ++web page: ++ ++http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users ++ ++Please ask Debian-specific questions on this list and not on the general Exim ++lists. ++ ++1.4 Exim training ++ ++Training 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 that changes, relevant ++information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/. ++ ++1.5 Bug reports ++ ++Reports 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 best thing to do is to post a message to the ++exim-dev mailing list and have it discussed. ++ ++1.6 Where to find the Exim distribution ++ ++The master ftp site for the Exim distribution is ++ ++ftp://ftp.csx.cam.ac.uk/pub/software/email/exim ++ ++This is mirrored by ++ ++ftp://ftp.exim.org/pub/exim ++ ++The file references that follow are relative to the exim directories at these ++sites. There are now quite a number of independent mirror sites around the ++world. Those that I know about are listed in the file called 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.bz2 ++ ++where 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 public 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.asc ++ ++For each released version, the log of changes is made separately available in a ++separate file in the directory ChangeLogs so that it is possible to find out ++what has changed without having to download the entire distribution. ++ ++The main distribution contains ASCII versions of this specification and other ++documentation; other formats 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.gz ++ ++These 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. ++ ++ * 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 comprehensive 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 extension, ++ straightforward interfaces to a number of common scanners are provided. ++ ++1.8 Run time configuration ++ ++Exim's run time configuration is held in a single text file that is divided ++into a number of sections. The entries in this file consist of keywords and ++values, in the style of Smail 3 configuration files. A default configuration ++file which is suitable for simple online installations is provided in the ++distribution, and is described in chapter 7 below. ++ ++1.9 Calling interface ++ ++Like many MTAs, Exim has adopted the Sendmail command line interface so that it ++can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when ++sending mail, but you do not need to know 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 lists the ++messages on the queue) do so in Exim's own format. There are also some ++additional options that are compatible with Smail 3, and some further options ++that are new to Exim. Chapter 5 documents all Exim's command line options. This ++information is automatically made into the man page that forms part of the Exim ++distribution. ++ ++Control of messages on the queue can be done via certain privileged command ++line options. There is also 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 Terminology ++ ++The body of a message is the actual data that the sender wants to transmit. It ++is the last part of a message, 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 failure message or a "non-delivery report" (NDR). The term bounce is ++commonly used for this action, and the error reports are often called bounce ++messages. This is a convenient shorthand for "delivery failure error report". ++Such messages have an empty sender address in the message's envelope (see ++below) to ensure 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 the absence of any setting in the configuration. It may ++also qualify an action which is taken unless a configuration setting specifies ++otherwise. ++ ++The term defer is used when the delivery of a message to a specific destination ++cannot immediately take place for some reason (a remote host may be down, or a ++user's local mailbox may be full). Such deliveries are deferred until a later ++time. ++ ++The word domain is sometimes used to mean all but the first component of a ++host's name. It is not used 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 envelope contains a sender address (to which bounce messages should ++be delivered), and any number of recipient addresses. References to the sender ++or the recipients of a message usually mean the addresses in the envelope. An ++MTA uses these addresses for delivery, and for returning bounce messages, 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 of which has a name such as From:, To:, Subject:, etc. ++Long header lines can be split over several text lines 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 address that 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 the local host from delivery by SMTP over TCP/IP to ++another host. As far as Exim is concerned, all hosts other 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 in widespread use in the context of MTAs. However, in ++Exim's case the reality is more like a pool than a queue, because there is ++normally no ordering of waiting messages. ++ ++The term queue runner is used to describe a process that scans the queue and ++attempts to deliver those messages whose retry times have come. This term is ++used by other MTAs, and also relates to the command 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 - that is, those that it is in the process of delivering. ++This should not be confused with the directory in which local mailboxes are ++stored, which is called a "spool directory" by some people. In the Exim ++documentation, "spool" is always used in the first sense. ++ ++2. Incorporated code ++ ++A number of pieces of external code are included in the Exim distribution. ++ ++ * Regular expressions are supported in the main Exim program and in the Exim ++ monitor using the freely-distributable PCRE library, copyright (c) ++ 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 completely contained within the code of ++ Exim. It does not link against an external cdb library. The code contains ++ the following statements: ++ ++ Copyright (c) 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 ++ implementation 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 (c) 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 permission 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 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, written 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. ++ ++3. How Exim receives and delivers mail ++ ++3.1 Overall philosophy ++ ++Exim is designed to work efficiently on systems that are permanently connected ++to the Internet and are handling a general mix of mail. In such circumstances, ++most messages can be delivered immediately. Consequently, Exim does not ++maintain independent queues of messages for specific domains or hosts, though ++it does try to send several messages in a single SMTP connection after a host ++has been down, and it also maintains per-host retry information. ++ ++3.2 Policy control ++ ++Policy controls are now an important feature of MTAs that are connected to the ++Internet. Perhaps their most important job is to stop MTAs being abused as ++"open relays" by misguided individuals who send out vast amounts of unsolicited ++junk, and want to disguise its source. Exim provides flexible facilities for ++specifying policy controls on incoming mail: ++ ++ * Exim 4 (unlike previous versions of Exim) implements policy controls on ++ incoming mail by means of Access Control Lists (ACLs). Each list is a ++ series of statements that may either grant or deny access. ACLs can be used ++ at several places in the SMTP dialogue while receiving a message from a ++ remote host. However, the most common places are after each RCPT command, ++ and at the very end of the message. The sysadmin can specify conditions for ++ accepting or rejecting individual recipients or the entire message, ++ respectively, at these two points (see chapter 40). Denial of access ++ results in an SMTP error code. ++ ++ * An ACL is also available for locally generated, non-SMTP messages. In this ++ case, the only available actions are to accept or deny the entire message. ++ ++ * When Exim is compiled with the content-scanning extension, facilities are ++ provided in the ACL mechanism for passing the message to external virus and ++ /or spam scanning software. The result of such a scan is passed back to the ++ ACL, which can then use it to decide what to do with the message. ++ ++ * When a message has been received, either from a remote host or from the ++ local host, but before the final acknowledgment has been sent, a locally ++ supplied C function called local_scan() can be run to inspect the message ++ and decide whether to accept it or not (see chapter 42). If the message is ++ accepted, the list of recipients can be modified by the function. ++ ++ * Using the local_scan() mechanism is another way of calling external scanner ++ software. The SA-Exim add-on package works this way. It does not require ++ Exim to be compiled with the content-scanning extension. ++ ++ * After a message has been accepted, a further checking mechanism is ++ available in the form of the system filter (see chapter 43). This runs at ++ the start of every delivery process. ++ ++3.3 User filters ++ ++In a conventional Exim configuration, users are able to run private filters by ++setting up appropriate .forward files in their home directories. See chapter 22 ++(about the redirect router) for the configuration needed to support this, and ++the separate document entitled Exim's interfaces to mail filtering for user ++details. Two different kinds of filtering are available: ++ ++ * Sieve filters are written in the standard filtering language that is ++ defined by RFC 3028. ++ ++ * Exim filters are written in a syntax that is unique to Exim, but which is ++ more powerful than Sieve, which it pre-dates. ++ ++User filters are run as part of the routing process, described below. ++ ++3.4 Message identification ++ ++Every message handled by Exim is given a message id which is sixteen characters ++long. It is divided into three parts, separated by hyphens, for example ++"16VDhn-0001bo-D3". Each part is a sequence of letters and digits, normally ++encoding numbers in base 62. However, in the Darwin operating system (Mac OS X) ++and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of ++lower case letters) is used instead, because the message id is used to ++construct file names, and the names of files in those systems are not always ++case-sensitive. ++ ++The detail of the contents of the message id have changed as Exim has evolved. ++Earlier versions relied on the operating system not re-using a process id (pid) ++within one second. On modern operating systems, this assumption can no longer ++be made, so the algorithm had to be changed. To retain backward compatibility, ++the format of the message id was retained, which is why the following rules are ++somewhat eccentric: ++ ++ * The first six characters of the message id are the time at which the ++ message started to be received, to a granularity of one second. That is, ++ this field contains the number of seconds since the start of the epoch (the ++ normal Unix way of representing the date and time of day). ++ ++ * After the first hyphen, the next six characters are the id of the process ++ that received the message. ++ ++ * There are two different possibilities for the final two characters: ++ ++ 1. If localhost_number is not set, this value is the fractional part of ++ the time of reception, normally in units of 1/2000 of a second, but for ++ systems that must use base 36 instead of base 62 (because of ++ case-insensitive file systems), the units are 1/1000 of a second. ++ ++ 2. If localhost_number is set, it is multiplied by 200 (100) and added to ++ the fractional part of the time, which in this case is in units of 1/ ++ 200 (1/100) of a second. ++ ++After a message has been received, Exim waits for the clock to tick at the ++appropriate resolution before proceeding, so that if another message is ++received by the same process, or by another process with the same (re-used) ++pid, it is guaranteed that the time will be different. In most cases, the clock ++will already have ticked while the message was being received. ++ ++3.5 Receiving mail ++ ++The only way Exim can receive mail from another host is using SMTP over TCP/IP, ++in which case the sender and recipient addresses are transferred using SMTP ++commands. However, from a locally running process (such as a user's MUA), there ++are several possibilities: ++ ++ * If the process runs Exim with the -bm option, the message is read ++ non-interactively (usually via a pipe), with the recipients taken from the ++ command line, or from the body of the message if -t is also used. ++ ++ * If the process runs Exim with the -bS option, the message is also read ++ non-interactively, but in this case the recipients are listed at the start ++ of the message in a series of SMTP RCPT commands, terminated by a DATA ++ command. This is so-called "batch SMTP" format, but it isn't really SMTP. ++ The SMTP commands are just another way of passing envelope addresses in a ++ non-interactive submission. ++ ++ * If the process runs Exim with the -bs option, the message is read ++ interactively, using the SMTP protocol. A two-way pipe is normally used for ++ passing data between the local process and the Exim process. This is "real" ++ SMTP and is handled in the same way as SMTP over TCP/IP. For example, the ++ ACLs for SMTP commands are used for this form of submission. ++ ++ * A local process may also make a TCP/IP call to the host's loopback address ++ (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim ++ does not treat the loopback address specially. It treats all such ++ connections in the same way as connections from other hosts. ++ ++In the three cases that do not involve TCP/IP, the sender address is ++constructed from the login name of the user that called Exim and a default ++qualification domain (which can be set by the qualify_domain configuration ++option). For local or batch SMTP, a sender address that is passed using the ++SMTP MAIL command is ignored. However, the system administrator may allow ++certain users ("trusted users") to specify a different sender address ++unconditionally, or all users to specify certain forms of different sender ++address. The -f option or the SMTP MAIL command is used to specify these ++different addresses. See section 5.2 for details of trusted users, and the ++untrusted_set_sender option for a way of allowing untrusted users to change ++sender addresses. ++ ++Messages received by either of the non-interactive mechanisms are subject to ++checking by the non-SMTP ACL, if one is defined. Messages received using SMTP ++(either over TCP/IP, or interacting with a local process) can be checked by a ++number of ACLs that operate at different times during the SMTP session. Either ++individual recipients, or the entire message, can be rejected if local policy ++requirements are not met. The local_scan() function (see chapter 42) is run for ++all incoming messages. ++ ++Exim can be configured not to start a delivery process when a message is ++received; this can be unconditional, or depend on the number of incoming SMTP ++connections or the system load. In these situations, new messages wait on the ++queue until a queue runner process picks them up. However, in standard ++configurations under normal conditions, delivery is started as soon as a ++message is received. ++ ++3.6 Handling an incoming message ++ ++When Exim accepts a message, it writes two files in its spool directory. The ++first contains the envelope information, the current status of the message, and ++the header lines, and the second contains the body of the message. The names of ++the two spool files consist of the message id, followed by "-H" for the file ++containing the envelope and header, and "-D" for the data file. ++ ++By default all these message files are held in a single directory called input ++inside the general Exim spool directory. Some operating systems do not perform ++very well if the number of files in a directory gets large; to improve ++performance in such cases, the split_spool_directory option can be used. This ++causes Exim to split up the input files into 62 sub-directories whose names are ++single letters or digits. When this is done, the queue is processed one ++sub-directory at a time instead of all at once, which can improve overall ++performance even when there are not enough files in each directory to affect ++file system performance. ++ ++The envelope information consists of the address of the message's sender and ++the addresses of the recipients. This information is entirely separate from any ++addresses contained in the header lines. The status of the message includes a ++list of recipients who have already received the message. The format of the ++first spool file is described in chapter 53. ++ ++Address rewriting that is specified in the rewrite section of the configuration ++(see chapter 31) is done once and for all on incoming addresses, both in the ++header lines and the envelope, at the time the message is accepted. If during ++the course of delivery additional addresses are generated (for example, via ++aliasing), these new addresses are rewritten as soon as they are generated. At ++the time a message is actually delivered (transported) further rewriting can ++take place; because this is a transport option, it can be different for ++different forms of delivery. It is also possible to specify the addition or ++removal of certain header lines at the time the message is delivered (see ++chapters 15 and 24). ++ ++3.7 Life of a message ++ ++A message remains in the spool directory until it is completely delivered to ++its recipients or to an error address, or until it is deleted by an ++administrator or by the user who originally created it. In cases when delivery ++cannot proceed - for example, when a message can neither be delivered to its ++recipients nor returned to its sender, the message is marked "frozen" on the ++spool, and no more deliveries are attempted. ++ ++An administrator can "thaw" such messages when the problem has been corrected, ++and can also freeze individual messages by hand if necessary. In addition, an ++administrator can force a delivery error, causing a bounce message to be sent. ++ ++There are options called ignore_bounce_errors_after and timeout_frozen_after, ++which discard frozen messages after a certain time. The first applies only to ++frozen bounces, the second to any frozen messages. ++ ++While Exim is working on a message, it writes information about each delivery ++attempt to its main log file. This includes successful, unsuccessful, and ++delayed deliveries for each recipient (see chapter 49). The log lines are also ++written to a separate message log file for each message. These logs are solely ++for the benefit of the administrator, and are normally deleted along with the ++spool files when processing of a message is complete. The use of individual ++message logs can be disabled by setting no_message_logs; this might give an ++improvement in performance on very busy systems. ++ ++All the information Exim itself needs to set up a delivery is kept in the first ++spool file, along with the header lines. When a successful delivery occurs, the ++address is immediately written at the end of a journal file, whose name is the ++message id followed by "-J". At the end of a delivery run, if there are some ++addresses left to be tried again later, the first spool file (the "-H" file) is ++updated to indicate which these are, and the journal file is then deleted. ++Updating the spool file is done by writing a new file and renaming it, to ++minimize the possibility of data loss. ++ ++Should the system or the program crash after a successful delivery but before ++the spool file has been updated, the journal is left lying around. The next ++time Exim attempts to deliver the message, it reads the journal file and ++updates the spool file before proceeding. This minimizes the chances of double ++deliveries caused by crashes. ++ ++3.8 Processing an address for delivery ++ ++The main delivery processing elements of Exim are called routers and transports ++, and collectively these are known as drivers. Code for a number of them is ++provided in the source distribution, and compile-time options specify which ++ones are included in the binary. Run time options specify which ones are ++actually used for delivering messages. ++ ++Each driver that is specified in the run time configuration is an instance of ++that particular driver type. Multiple instances are allowed; for example, you ++can set up several different smtp transports, each with different option values ++that might specify different ports or different timeouts. Each instance has its ++own identifying name. In what follows we will normally use the instance name ++when discussing one particular instance (that is, one specific configuration of ++the driver), and the generic driver name when discussing the driver's features ++in general. ++ ++A router is a driver that operates on an address, either determining how its ++delivery should happen, by assigning it to a specific transport, or converting ++the address into one or more new addresses (for example, via an alias file). A ++router may also explicitly choose to fail an address, causing it to be bounced. ++ ++A transport is a driver that transmits a copy of the message from Exim's spool ++to some destination. There are two kinds of transport: for a local transport, ++the destination is a file or a pipe on the local host, whereas for a remote ++transport the destination is some other host. A message is passed to a specific ++transport as a result of successful routing. If a message has several ++recipients, it may be passed to a number of different transports. ++ ++An address is processed by passing it to each configured router instance in ++turn, subject to certain preconditions, until a router accepts the address or ++specifies that it should be bounced. We will describe this process in more ++detail shortly. First, as a simple example, we consider how each recipient ++address in a message is processed in a small configuration of three routers. ++ ++To make this a more concrete example, it is described in terms of some actual ++routers, but remember, this is only an example. You can configure Exim's ++routers in many different ways, and there may be any number of routers in a ++configuration. ++ ++The first router that is specified in a configuration is often one that handles ++addresses in domains that are not recognized specially by the local host. These ++are typically addresses for arbitrary domains on the Internet. A precondition ++is set up which looks for the special domains known to the host (for example, ++its own domain name), and the router is run for addresses that do not match. ++Typically, this is a router that looks up domains in the DNS in order to find ++the hosts to which this address routes. If it succeeds, the address is assigned ++to a suitable SMTP transport; if it does not succeed, the router is configured ++to fail the address. ++ ++The second router is reached only when the domain is recognized as one that ++"belongs" to the local host. This router does redirection - also known as ++aliasing and forwarding. When it generates one or more new addresses from the ++original, each of them is routed independently from the start. Otherwise, the ++router may cause an address to fail, or it may simply decline to handle the ++address, in which case the address is passed to the next router. ++ ++The final router in many configurations is one that checks to see if the ++address belongs to a local mailbox. The precondition may involve a check to see ++if the local part is the name of a login account, or it may look up the local ++part in a file or a database. If its preconditions are not met, or if the ++router declines, we have reached the end of the routers. When this happens, the ++address is bounced. ++ ++3.9 Processing an address for verification ++ ++As well as being used to decide how to deliver to an address, Exim's routers ++are also used for address verification. Verification can be requested as one of ++the checks to be performed in an ACL for incoming messages, on both sender and ++recipient addresses, and it can be tested using the -bv and -bvs command line ++options. ++ ++When an address is being verified, the routers are run in "verify mode". This ++does not affect the way the routers work, but it is a state that can be ++detected. By this means, a router can be skipped or made to behave differently ++when verifying. A common example is a configuration in which the first router ++sends all messages to a message-scanning program, unless they have been ++previously scanned. Thus, the first router accepts all addresses without any ++checking, making it useless for verifying. Normally, the no_verify option would ++be set for such a router, causing it to be skipped in verify mode. ++ ++3.10 Running an individual router ++ ++As explained in the example above, a number of preconditions are checked before ++running a router. If any are not met, the router is skipped, and the address is ++passed to the next router. When all the preconditions on a router are met, the ++router is run. What happens next depends on the outcome, which is one of the ++following: ++ ++ * accept: The router accepts the address, and either assigns it to a ++ transport, or generates one or more "child" addresses. Processing the ++ original address ceases, unless the unseen option is set on the router. ++ This option can be used to set up multiple deliveries with different ++ routing (for example, for keeping archive copies of messages). When unseen ++ is set, the address is passed to the next router. Normally, however, an ++ accept return marks the end of routing. ++ ++ Any child addresses generated by the router are processed independently, ++ starting with the first router by default. It is possible to change this by ++ setting the redirect_router option to specify which router to start at for ++ child addresses. Unlike pass_router (see below) the router specified by ++ redirect_router may be anywhere in the router configuration. ++ ++ * pass: The router recognizes the address, but cannot handle it itself. It ++ requests that the address be passed to another router. By default the ++ address is passed to the next router, but this can be changed by setting ++ the pass_router option. However, (unlike redirect_router) the named router ++ must be below the current router (to avoid loops). ++ ++ * decline: The router declines to accept the address because it does not ++ recognize it at all. By default, the address is passed to the next router, ++ but this can be prevented by setting the no_more option. When no_more is ++ set, all the remaining routers are skipped. In effect, no_more converts ++ decline into fail. ++ ++ * fail: The router determines that the address should fail, and queues it for ++ the generation of a bounce message. There is no further processing of the ++ original address unless unseen is set on the router. ++ ++ * defer: The router cannot handle the address at the present time. (A ++ database may be offline, or a DNS lookup may have timed out.) No further ++ processing of the address happens in this delivery attempt. It is tried ++ again next time the message is considered for delivery. ++ ++ * error: There is some error in the router (for example, a syntax error in ++ its configuration). The action is as for defer. ++ ++If an address reaches the end of the routers without having been accepted by ++any of them, it is bounced as unrouteable. The default error message in this ++situation is "unrouteable address", but you can set your own message by making ++use of the cannot_route_message option. This can be set for any router; the ++value from the last router that "saw" the address is used. ++ ++Sometimes while routing you want to fail a delivery when some conditions are ++met but others are not, instead of passing the address on for further routing. ++You can do this by having a second router that explicitly fails the delivery ++when the relevant conditions are met. The redirect router has a "fail" facility ++for this purpose. ++ ++3.11 Duplicate addresses ++ ++Once routing is complete, Exim scans the addresses that are assigned to local ++and remote transports, and discards any duplicates that it finds. During this ++check, local parts are treated as case-sensitive. This happens only when ++actually delivering a message; when testing routers with -bt, all the routed ++addresses are shown. ++ ++3.12 Router preconditions ++ ++The preconditions that are tested for each router are listed below, in the ++order in which they are tested. The individual configuration options are ++described in more detail in chapter 15. ++ ++ * The local_part_prefix and local_part_suffix options can specify that the ++ local parts handled by the router may or must have certain prefixes and/or ++ suffixes. If a mandatory affix (prefix or suffix) is not present, the ++ router is skipped. These conditions are tested first. When an affix is ++ present, it is removed from the local part before further processing, ++ including the evaluation of any other conditions. ++ ++ * Routers can be designated for use only when not verifying an address, that ++ is, only when routing it for delivery (or testing its delivery routing). If ++ the verify option is set false, the router is skipped when Exim is ++ verifying an address. Setting the verify option actually sets two options, ++ verify_sender and verify_recipient, which independently control the use of ++ the router for sender and recipient verification. You can set these options ++ directly if you want a router to be used for only one type of verification. ++ ++ * If the address_test option is set false, the router is skipped when Exim is ++ run with the -bt option to test an address routing. This can be helpful ++ when the first router sends all new messages to a scanner of some sort; it ++ makes it possible to use -bt to test subsequent delivery routing without ++ having to simulate the effect of the scanner. ++ ++ * Routers can be designated for use only when verifying an address, as ++ opposed to routing it for delivery. The verify_only option controls this. ++ ++ * Individual routers can be explicitly skipped when running the routers to ++ check an address given in the SMTP EXPN command (see the expn option). ++ ++ * If the domains option is set, the domain of the address must be in the set ++ of domains that it defines. ++ ++ * If the local_parts option is set, the local part of the address must be in ++ the set of local parts that it defines. If local_part_prefix or ++ local_part_suffix is in use, the prefix or suffix is removed from the local ++ part before this check. If you want to do precondition tests on local parts ++ that include affixes, you can do so by using a condition option (see below) ++ that uses the variables $local_part, $local_part_prefix, and ++ $local_part_suffix as necessary. ++ ++ * If the check_local_user option is set, the local part must be the name of ++ an account on the local host. If this check succeeds, the uid and gid of ++ the local user are placed in $local_user_uid and $local_user_gid and the ++ user's home directory is placed in $home; these values can be used in the ++ remaining preconditions. ++ ++ * If the router_home_directory option is set, it is expanded at this point, ++ because it overrides the value of $home. If this expansion were left till ++ later, the value of $home as set by check_local_user would be used in ++ subsequent tests. Having two different values of $home in the same router ++ could lead to confusion. ++ ++ * If the senders option is set, the envelope sender address must be in the ++ set of addresses that it defines. ++ ++ * If the require_files option is set, the existence or non-existence of ++ specified files is tested. ++ ++ * If the condition option is set, it is evaluated and tested. This option ++ uses an expanded string to allow you to set up your own custom ++ preconditions. Expanded strings are described in chapter 11. ++ ++Note that require_files comes near the end of the list, so you cannot use it to ++check for the existence of a file in which to lookup up a domain, local part, ++or sender. However, as these options are all expanded, you can use the exists ++expansion condition to make such tests within each condition. The require_files ++option is intended for checking files that the router may be going to use ++internally, or which are needed by a specific transport (for example, ++.procmailrc). ++ ++3.13 Delivery in detail ++ ++When a message is to be delivered, the sequence of events is as follows: ++ ++ * If a system-wide filter file is specified, the message is passed to it. The ++ filter may add recipients to the message, replace the recipients, discard ++ the message, cause a new message to be generated, or cause the message ++ delivery to fail. The format of the system filter file is the same as for ++ Exim user filter files, described in the separate document entitled Exim's ++ interfaces to mail filtering. (Note: Sieve cannot be used for system filter ++ files.) ++ ++ Some additional features are available in system filters - see chapter 43 ++ for details. Note that a message is passed to the system filter only once ++ per delivery attempt, however many recipients it has. However, if there are ++ several delivery attempts because one or more addresses could not be ++ immediately delivered, the system filter is run each time. The filter ++ condition first_delivery can be used to detect the first run of the system ++ filter. ++ ++ * Each recipient address is offered to each configured router in turn, ++ subject to its preconditions, until one is able to handle it. If no router ++ can handle the address, that is, if they all decline, the address is ++ failed. Because routers can be targeted at particular domains, several ++ locally handled domains can be processed entirely independently of each ++ other. ++ ++ * A router that accepts an address may assign it to a local or a remote ++ transport. However, the transport is not run at this time. Instead, the ++ address is placed on a list for the particular transport, which will be run ++ later. Alternatively, the router may generate one or more new addresses ++ (typically from alias, forward, or filter files). New addresses are fed ++ back into this process from the top, but in order to avoid loops, a router ++ ignores any address which has an identically-named ancestor that was ++ processed by itself. ++ ++ * When all the routing has been done, addresses that have been successfully ++ handled are passed to their assigned transports. When local transports are ++ doing real local deliveries, they handle only one address at a time, but if ++ a local transport is being used as a pseudo-remote transport (for example, ++ to collect batched SMTP messages for transmission by some other means) ++ multiple addresses can be handled. Remote transports can always handle more ++ than one address at a time, but can be configured not to do so, or to ++ restrict multiple addresses to the same domain. ++ ++ * Each local delivery to a file or a pipe runs in a separate process under a ++ non-privileged uid, and these deliveries are run one at a time. Remote ++ deliveries also run in separate processes, normally under a uid that is ++ private to Exim ("the Exim user"), but in this case, several remote ++ deliveries can be run in parallel. The maximum number of simultaneous ++ remote deliveries for any one message is set by the remote_max_parallel ++ option. The order in which deliveries are done is not defined, except that ++ all local deliveries happen before any remote deliveries. ++ ++ * When it encounters a local delivery during a queue run, Exim checks its ++ retry database to see if there has been a previous temporary delivery ++ failure for the address before running the local transport. If there was a ++ previous failure, Exim does not attempt a new delivery until the retry time ++ for the address is reached. However, this happens only for delivery ++ attempts that are part of a queue run. Local deliveries are always ++ attempted when delivery immediately follows message reception, even if ++ retry times are set for them. This makes for better behaviour if one ++ particular message is causing problems (for example, causing quota ++ overflow, or provoking an error in a filter file). ++ ++ * Remote transports do their own retry handling, since an address may be ++ deliverable to one of a number of hosts, each of which may have a different ++ retry time. If there have been previous temporary failures and no host has ++ reached its retry time, no delivery is attempted, whether in a queue run or ++ not. See chapter 32 for details of retry strategies. ++ ++ * If there were any permanent errors, a bounce message is returned to an ++ appropriate address (the sender in the common case), with details of the ++ error for each failing address. Exim can be configured to send copies of ++ bounce messages to other addresses. ++ ++ * If one or more addresses suffered a temporary failure, the message is left ++ on the queue, to be tried again later. Delivery of these addresses is said ++ to be deferred. ++ ++ * When all the recipient addresses have either been delivered or bounced, ++ handling of the message is complete. The spool files and message log are ++ deleted, though the message log can optionally be preserved if required. ++ ++3.14 Retry mechanism ++ ++Exim's mechanism for retrying messages that fail to get delivered at the first ++attempt is the queue runner process. You must either run an Exim daemon that ++uses the -q option with a time interval to start queue runners at regular ++intervals, or use some other means (such as cron) to start them. If you do not ++arrange for queue runners to be run, messages that fail temporarily at the ++first attempt will remain on your queue for ever. A queue runner process works ++its way through the queue, one message at a time, trying each delivery that has ++passed its retry time. You can run several queue runners at once. ++ ++Exim uses a set of configured rules to determine when next to retry the failing ++address (see chapter 32). These rules also specify when Exim should give up ++trying to deliver to the address, at which point it generates a bounce message. ++If no retry rules are set for a particular host, address, and error ++combination, no retries are attempted, and temporary errors are treated as ++permanent. ++ ++3.15 Temporary delivery failure ++ ++There are many reasons why a message may not be immediately deliverable to a ++particular address. Failure to connect to a remote machine (because it, or the ++connection to it, is down) is one of the most common. Temporary failures may be ++detected during routing as well as during the transport stage of delivery. ++Local deliveries may be delayed if NFS files are unavailable, or if a mailbox ++is on a file system where the user is over quota. Exim can be configured to ++impose its own quotas on local mailboxes; where system quotas are set they will ++also apply. ++ ++If a host is unreachable for a period of time, a number of messages may be ++waiting for it by the time it recovers, and sending them in a single SMTP ++connection is clearly beneficial. Whenever a delivery to a remote host is ++deferred, Exim makes a note in its hints database, and whenever a successful ++SMTP delivery has happened, it looks to see if any other messages are waiting ++for the same host. If any are found, they are sent over the same SMTP ++connection, subject to a configuration limit as to the maximum number in any ++one connection. ++ ++3.16 Permanent delivery failure ++ ++When a message cannot be delivered to some or all of its intended recipients, a ++bounce message is generated. Temporary delivery failures turn into permanent ++errors when their timeout expires. All the addresses that fail in a given ++delivery attempt are listed in a single message. If the original message has ++many recipients, it is possible for some addresses to fail in one delivery ++attempt and others to fail subsequently, giving rise to more than one bounce ++message. The wording of bounce messages can be customized by the administrator. ++See chapter 46 for details. ++ ++Bounce messages contain an X-Failed-Recipients: header line that lists the ++failed addresses, for the benefit of programs that try to analyse such messages ++automatically. ++ ++A bounce message is normally sent to the sender of the original message, as ++obtained from the message's envelope. For incoming SMTP messages, this is the ++address given in the MAIL command. However, when an address is expanded via a ++forward or alias file, an alternative address can be specified for delivery ++failures of the generated addresses. For a mailing list expansion (see section ++47.2) it is common to direct bounce messages to the manager of the list. ++ ++3.17 Failures to deliver bounce messages ++ ++If a bounce message (either locally generated or received from a remote host) ++itself suffers a permanent delivery failure, the message is left on the queue, ++but it is frozen, awaiting the attention of an administrator. There are options ++that can be used to make Exim discard such failed messages, or to keep them for ++only a short time (see timeout_frozen_after and ignore_bounce_errors_after). ++ ++4. Building and installing Exim ++ ++4.1 Unpacking ++ ++Exim is distributed as a gzipped or bzipped tar file which, when unpacked, ++creates a directory with the name of the current release (for example, ++exim-4.74) into which the following files are placed: ++ ++    ACKNOWLEDGMENTS contains some acknowledgments ++    CHANGES contains a reference to where changes are documented ++    LICENCE the GNU General Public Licence ++    Makefile top-level make file ++    NOTICE conditions for the use of Exim ++    README list of files, directories and simple build ++ instructions ++ ++Other files whose names begin with README may also be present. The following ++subdirectories are created: ++ ++    Local an empty directory for local configuration files ++    OS OS-specific files ++    doc documentation files ++    exim_monitor source files for the Exim monitor ++    scripts scripts used in the build process ++    src remaining source files ++    util independent utilities ++ ++The main utility programs are contained in the src directory, and are built ++with the Exim binary. The util directory contains a few optional scripts that ++may be useful to some sites. ++ ++4.2 Multiple machine architectures and operating systems ++ ++The building process for Exim is arranged to make it easy to build binaries for ++a number of different architectures and operating systems from the same set of ++source files. Compilation does not take place in the src directory. Instead, a ++build directory is created for each architecture and operating system. Symbolic ++links to the sources are installed in this directory, which is where the actual ++building takes place. In most cases, Exim can discover the machine architecture ++and operating system for itself, but the defaults can be overridden if ++necessary. ++ ++4.3 PCRE library ++ ++Exim no longer has an embedded PCRE library as the vast majority of modern ++systems include PCRE as a system library, although you may need to install the ++PCRE or PCRE development package for your operating system. If your system has ++a normal PCRE installation the Exim build process will need no further ++configuration. If the library or the headers are in an unusual location you ++will need to set the PCRE_LIBS and INCLUDE directives appropriately. If your ++operating system has no PCRE support then you will need to obtain and build the ++current PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. ++ ++4.4 DBM libraries ++ ++Even if you do not use any DBM files in your configuration, Exim still needs a ++DBM library in order to operate, because it uses indexed files for its hints ++databases. Unfortunately, there are a number of DBM libraries in existence, and ++different operating systems often have different ones installed. ++ ++If you are using Solaris, IRIX, one of the modern BSD systems, or a modern ++Linux distribution, the DBM configuration should happen automatically, and you ++may be able to ignore this section. Otherwise, you may have to learn more than ++you would like about DBM libraries from what follows. ++ ++Licensed versions of Unix normally contain a library of DBM functions operating ++via the ndbm interface, and this is what Exim expects by default. Free versions ++of Unix seem to vary in what they contain as standard. In particular, some ++early versions of Linux have no default DBM library, and different distributors ++have chosen to bundle different libraries with their packaged versions. ++However, the more recent releases seem to have standardized on the Berkeley DB ++library. ++ ++Different DBM libraries have different conventions for naming the files they ++use. When a program opens a file called dbmfile, there are several ++possibilities: ++ ++ 1. A traditional ndbm implementation, such as that supplied as part of ++ Solaris, operates on two files called dbmfile.dir and dbmfile.pag. ++ ++ 2. The GNU library, gdbm, operates on a single file. If used via its ndbm ++ compatibility interface it makes two different hard links to it with names ++ dbmfile.dir and dbmfile.pag, but if used via its native interface, the file ++ name is used unmodified. ++ ++ 3. The Berkeley DB package, if called via its ndbm compatibility interface, ++ operates on a single file called dbmfile.db, but otherwise looks to the ++ programmer exactly the same as the traditional ndbm implementation. ++ ++ 4. If the Berkeley package is used in its native mode, it operates on a single ++ file called dbmfile; the programmer's interface is somewhat different to ++ the traditional ndbm interface. ++ ++ 5. To complicate things further, there are several very different versions of ++ the Berkeley DB package. Version 1.85 was stable for a very long time, ++ releases 2.x and 3.x were current for a while, but the latest versions are ++ now numbered 4.x. Maintenance of some of the earlier releases has ceased. ++ All versions of Berkeley DB can be obtained from http://www.sleepycat.com/. ++ ++ 6. Yet another DBM library, called tdb, is available from http:// ++ download.sourceforge.net/tdb. It has its own interface, and also operates ++ on a single file. ++ ++Exim and its utilities can be compiled to use any of these interfaces. In order ++to use any version of the Berkeley DB package in native mode, you must set ++USE_DB in an appropriate configuration file (typically Local/Makefile). For ++example: ++ ++USE_DB=yes ++ ++Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is ++diagnosed if you set more than one of these. ++ ++At the lowest level, the build-time configuration sets none of these options, ++thereby assuming an interface of type (1). However, some operating system ++configuration files (for example, those for the BSD operating systems and ++Linux) assume type (4) by setting USE_DB as their default, and the ++configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile ++, however, overrides these system defaults. ++ ++As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to ++set DBMLIB, to cause inclusion of the appropriate library, as in one of these ++lines: ++ ++DBMLIB = -ldb ++DBMLIB = -ltdb ++ ++Settings like that will work if the DBM library is installed in the standard ++place. Sometimes it is not, and the library's header file may also not be in ++the default path. You may need to set INCLUDE to specify where the header file ++is, and to specify the path to the library more fully in DBMLIB, as in this ++example: ++ ++INCLUDE=-I/usr/local/include/db-4.1 ++DBMLIB=/usr/local/lib/db-4.1/libdb.a ++ ++There is further detailed discussion about the various DBM libraries in the ++file doc/dbm.discuss.txt in the Exim distribution. ++ ++4.5 Pre-building configuration ++ ++Before building Exim, a local configuration file that specifies options ++independent of any operating system has to be created with the name Local/ ++Makefile. A template for this file is supplied as the file src/EDITME, and it ++contains full descriptions of all the option settings therein. These ++descriptions are therefore not repeated here. If you are building Exim for the ++first time, the simplest thing to do is to copy src/EDITME to Local/Makefile, ++then read it and edit it appropriately. ++ ++There are three settings that you must supply, because Exim will not build ++without them. They are the location of the run time configuration file ++(CONFIGURE_FILE), the directory in which Exim binaries will be installed ++(BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe ++EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a ++colon-separated list of file names; Exim uses the first of them that exists. ++ ++There are a few other parameters that can be specified either at build time or ++at run time, to enable the same binary to be used on a number of different ++machines. However, if the locations of Exim's spool directory and log file ++directory (if not within the spool directory) are fixed, it is recommended that ++you specify them in Local/Makefile instead of at run time, so that errors ++detected early in Exim's execution (such as a malformed configuration file) can ++be logged. ++ ++Exim's interfaces for calling virus and spam scanning software directly from ++access control lists are not compiled by default. If you want to include these ++facilities, you need to set ++ ++WITH_CONTENT_SCAN=yes ++ ++in your Local/Makefile. For details of the facilities themselves, see chapter ++41. ++ ++If you are going to build the Exim monitor, a similar configuration process is ++required. The file exim_monitor/EDITME must be edited appropriately for your ++installation and saved under the name Local/eximon.conf. If you are happy with ++the default settings described in exim_monitor/EDITME, Local/eximon.conf can be ++empty, but it must exist. ++ ++This is all the configuration that is needed in straightforward cases for known ++operating systems. However, the building process is set up so that it is easy ++to override options that are set by default or by operating-system-specific ++configuration files, for example to change the name of the C compiler, which ++defaults to gcc. See section 4.13 below for details of how to do this. ++ ++4.6 Support for iconv() ++ ++The contents of header lines in messages may be encoded according to the rules ++described RFC 2047. This makes it possible to transmit characters that are not ++in the ASCII character set, and to label them as being in a particular ++character set. When Exim is inspecting header lines by means of the $h_ ++mechanism, it decodes them, and translates them into a specified character set ++(default ISO-8859-1). The translation is possible only if the operating system ++supports the iconv() function. ++ ++However, some of the operating systems that supply iconv() do not support very ++many conversions. The GNU libiconv library (available from http://www.gnu.org/ ++software/libiconv/) can be installed on such systems to remedy this deficiency, ++as well as on systems that do not supply iconv() at all. After installing ++libiconv, you should add ++ ++HAVE_ICONV=yes ++ ++to your Local/Makefile and rebuild Exim. ++ ++4.7 Including TLS/SSL encryption support ++ ++Exim can be built to support encrypted SMTP connections, using the STARTTLS ++command as per RFC 2487. It can also support legacy clients that expect to ++start a TLS session immediately on connection to a non-standard port (see the ++tls_on_connect_ports runtime option and the -tls-on-connect command line ++option). ++ ++If you want to build Exim with TLS support, you must first install either the ++OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for ++implementing SSL. ++ ++If OpenSSL is installed, you should set ++ ++SUPPORT_TLS=yes ++TLS_LIBS=-lssl -lcrypto ++ ++in Local/Makefile. You may also need to specify the locations of the OpenSSL ++library and include files. For example: ++ ++SUPPORT_TLS=yes ++TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto ++TLS_INCLUDE=-I/usr/local/openssl/include/ ++ ++If GnuTLS is installed, you should set ++ ++SUPPORT_TLS=yes ++USE_GNUTLS=yes ++TLS_LIBS=-lgnutls -ltasn1 -lgcrypt ++ ++in Local/Makefile, and again you may need to specify the locations of the ++library and include files. For example: ++ ++SUPPORT_TLS=yes ++USE_GNUTLS=yes ++TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt ++TLS_INCLUDE=-I/usr/gnu/include ++ ++You do not need to set TLS_INCLUDE if the relevant directory is already ++specified in INCLUDE. Details of how to configure Exim to make use of TLS are ++given in chapter 39. ++ ++4.8 Use of tcpwrappers ++ ++Exim can be linked with the tcpwrappers library in order to check incoming SMTP ++calls using the tcpwrappers control files. This may be a convenient alternative ++to Exim's own checking facilities for installations that are already making use ++of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS ++in Local/Makefile, arrange for the file tcpd.h to be available at compile time, ++and also ensure that the library libwrap.a is available at link time, typically ++by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed ++in /usr/local, you might have ++ ++USE_TCP_WRAPPERS=yes ++CFLAGS=-O -I/usr/local/include ++EXTRALIBS_EXIM=-L/usr/local/lib -lwrap ++ ++in Local/Makefile. The daemon name to use in the tcpwrappers control files is ++"exim". For example, the line ++ ++exim : LOCAL 192.168.1. .friendly.domain.example ++ ++in your /etc/hosts.allow file allows connections from the local host, from the ++subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other ++connections are denied. The daemon name used by tcpwrappers can be changed at ++build time by setting TCP_WRAPPERS_DAEMON_NAME in in Local/Makefile, or by ++setting tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers ++documentation for further details. ++ ++4.9 Including support for IPv6 ++ ++Exim contains code for use on systems that have IPv6 support. Setting ++"HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may ++also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6 ++support is not fully integrated into the normal include and library files. ++ ++Two different types of DNS record for handling IPv6 addresses have been ++defined. AAAA records (analogous to A records for IPv4) are in use, and are ++currently seen as the mainstream. Another record type called A6 was proposed as ++better than AAAA because it had more flexibility. However, it was felt to be ++over-complex, and its status was reduced to "experimental". It is not known if ++anyone is actually using A6 records. Exim has support for A6 records, but this ++is included only if you set "SUPPORT_A6=YES" in Local/Makefile. The support has ++not been tested for some time. ++ ++4.10 Dynamically loaded lookup module support ++ ++On some platforms, Exim supports not compiling all lookup types directly into ++the main binary, instead putting some into external modules which can be loaded ++on demand. This permits packagers to build Exim with support for lookups with ++extensive library dependencies without requiring all users to install all of ++those dependencies. Most, but not all, lookup types can be built this way. ++ ++Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be ++installed; Exim will only load modules from that directory, as a security ++measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your ++OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting ++"EXTRALIBS" may also be necessary, see src/EDITME for details. ++ ++Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"< ++lookup_type> flags to have the value "2" instead of "yes". For example, this ++will build in lsearch but load sqlite and mysql support on demand: ++ ++LOOKUP_LSEARCH=yes ++LOOKUP_SQLITE=2 ++LOOKUP_MYSQL=2 ++ ++4.11 The building process ++ ++Once Local/Makefile (and Local/eximon.conf, if required) have been created, run ++make at the top level. It determines the architecture and operating system ++types, and creates a build directory if one does not exist. For example, on a ++Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created. ++Symbolic links to relevant source files are installed in the build directory. ++ ++Warning: The -j (parallel) flag must not be used with make; the building ++process fails if it is set. ++ ++If this is the first time make has been run, it calls a script that builds a ++make file inside the build directory, using the configuration files from the ++Local directory. The new make file is then passed to another instance of make. ++This does the real work, building a number of utility scripts, and then ++compiling and linking the binaries for the Exim monitor (if configured), a ++number of utility programs, and finally Exim itself. The command "make ++makefile" can be used to force a rebuild of the make file in the build ++directory, should this ever be necessary. ++ ++If you have problems building Exim, check for any comments there may be in the ++README file concerning your operating system, and also take a look at the FAQ, ++where some common problems are covered. ++ ++4.12 Output from "make" ++ ++The output produced by the make process for compile lines is often very ++unreadable, because these lines can be very long. For this reason, the normal ++output is suppressed by default, and instead output similar to that which ++appears when compiling the 2.6 Linux kernel is generated: just a short line for ++each module that is being compiled or linked. However, it is still possible to ++get the full output, by calling make like this: ++ ++FULLECHO='' make -e ++ ++The value of FULLECHO defaults to "@", the flag character that suppresses ++command reflection in make. When you ask for the full output, it is given in ++addition to the short output. ++ ++4.13 Overriding build-time options for Exim ++ ++The main make file that is created at the beginning of the building process ++consists of the concatenation of a number of files which set configuration ++values, followed by a fixed set of make instructions. If a value is set more ++than once, the last setting overrides any previous ones. This provides a ++convenient way of overriding defaults. The files that are concatenated are, in ++order: ++ ++OS/Makefile-Default ++OS/Makefile- ++Local/Makefile ++Local/Makefile- ++Local/Makefile- ++Local/Makefile-- ++OS/Makefile-Base ++ ++where is the operating system type and is the architecture ++type. Local/Makefile is required to exist, and the building process fails if it ++is absent. The other three Local files are optional, and are often not needed. ++ ++The values used for and are obtained from scripts called ++scripts/os-type and scripts/arch-type respectively. If either of the ++environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are ++used, thereby providing a means of forcing particular settings. Otherwise, the ++scripts try to get values from the uname command. If this fails, the shell ++variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations ++are then applied, to produce the standard names that Exim expects. You can run ++these scripts directly from the shell in order to find out what values are ++being used on your system. ++ ++OS/Makefile-Default contains comments about the variables that are set therein. ++Some (but not all) are mentioned below. If there is something that needs ++changing, review the contents of this file and the contents of the make file ++for your operating system (OS/Makefile-) to see what the default values ++are. ++ ++If you need to change any of the values that are set in OS/Makefile-Default or ++in OS/Makefile-, or to add any new definitions, you do not need to ++change the original files. Instead, you should make the changes by putting the ++new values in an appropriate Local file. For example, when building Exim in ++many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1) ++operating system, it is necessary to specify that the C compiler is called cc ++rather than gcc. Also, the compiler must be called with the option -std1, to ++make it recognize some of the features of Standard C that Exim uses. (Most ++other compilers recognize Standard C by default.) To do this, you should create ++a file called Local/Makefile-OSF1 containing the lines ++ ++CC=cc ++CFLAGS=-std1 ++ ++If you are compiling for just one operating system, it may be easier to put ++these lines directly into Local/Makefile. ++ ++Keeping all your local configuration settings separate from the distributed ++files makes it easy to transfer them to new versions of Exim simply by copying ++the contents of the Local directory. ++ ++Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file ++lookup, but not all systems have these components installed, so the default is ++not to include the relevant code in the binary. All the different kinds of file ++and database lookup that Exim supports are implemented as separate code modules ++which are included only if the relevant compile-time options are set. In the ++case of LDAP, NIS, and NIS+, the settings for Local/Makefile are: ++ ++LOOKUP_LDAP=yes ++LOOKUP_NIS=yes ++LOOKUP_NISPLUS=yes ++ ++and similar settings apply to the other lookup types. They are all listed in ++src/EDITME. In many cases the relevant include files and interface libraries ++need to be installed before compiling Exim. However, there are some optional ++lookup types (such as cdb) for which the code is entirely contained within ++Exim, and no external include files or libraries are required. When a lookup ++type is not included in the binary, attempts to configure Exim to use it cause ++run time configuration errors. ++ ++Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines ++to be called during string expansion. To enable this facility, ++ ++EXIM_PERL=perl.o ++ ++must be defined in Local/Makefile. Details of this facility are given in ++chapter 12. ++ ++The location of the X11 libraries is something that varies a lot between ++operating systems, and there may be different versions of X11 to cope with. ++Exim itself makes no use of X11, but if you are compiling the Exim monitor, the ++X11 libraries must be available. The following three variables are set in OS/ ++Makefile-Default: ++ ++X11=/usr/X11R6 ++XINCLUDE=-I$(X11)/include ++XLFLAGS=-L$(X11)/lib ++ ++These are overridden in some of the operating-system configuration files. For ++example, in OS/Makefile-SunOS5 there is ++ ++X11=/usr/openwin ++XINCLUDE=-I$(X11)/include ++XLFLAGS=-L$(X11)/lib -R$(X11)/lib ++ ++If you need to override the default setting for your operating system, place a ++definition of all three of these variables into your Local/Makefile- ++file. ++ ++If you need to add any extra libraries to the link steps, these can be put in a ++variable called EXTRALIBS, which appears in all the link commands, but by ++default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command ++for linking the main Exim binary, and not for any associated utilities. ++ ++There is also DBMLIB, which appears in the link commands for binaries that use ++DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which ++appears only in the link step for the Exim monitor binary, and which can be ++used, for example, to include additional X11 libraries. ++ ++The make file copes with rebuilding Exim correctly if any of the configuration ++files are edited. However, if an optional configuration file is deleted, it is ++necessary to touch the associated non-optional file (that is, Local/Makefile or ++Local/eximon.conf) before rebuilding. ++ ++4.14 OS-specific header files ++ ++The OS directory contains a number of files with names of the form os.h- ++. These are system-specific C header files that should not normally ++need to be changed. There is a list of macro settings that are recognized in ++the file OS/os.configuring, which should be consulted if you are porting Exim ++to a new operating system. ++ ++4.15 Overriding build-time options for the monitor ++ ++A similar process is used for overriding things when building the Exim monitor, ++where the files that are involved are ++ ++OS/eximon.conf-Default ++OS/eximon.conf- ++Local/eximon.conf ++Local/eximon.conf- ++Local/eximon.conf- ++Local/eximon.conf-- ++ ++As with Exim itself, the final three files need not exist, and in this case the ++OS/eximon.conf- file is also optional. The default values in OS/ ++eximon.conf-Default can be overridden dynamically by setting environment ++variables of the same name, preceded by EXIMON_. For example, setting ++EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run ++time. ++ ++4.16 Installing Exim binaries and scripts ++ ++The command "make install" runs the exim_install script with no arguments. The ++script copies binaries and utility scripts into the directory whose name is ++specified by the BIN_DIRECTORY setting in Local/Makefile. The install script ++copies files only if they are newer than the files they are going to replace. ++The Exim binary is required to be owned by root and have the setuid bit set, ++for normal configurations. Therefore, you must run "make install" as root so ++that it can set up the Exim binary in this way. However, in some special ++situations (for example, if a host is doing no local deliveries) it may be ++possible to run Exim without making the binary setuid root (see chapter 52 for ++details). ++ ++Exim's run time configuration file is named by the CONFIGURE_FILE setting in ++Local/Makefile. If this names a single file, and the file does not exist, the ++default configuration file src/configure.default is copied there by the ++installation script. If a run time configuration file already exists, it is ++left alone. If CONFIGURE_FILE is a colon-separated list, naming several ++alternative files, no default is installed. ++ ++One change is made to the default configuration file when it is installed: the ++default configuration contains a router that references a system aliases file. ++The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in ++Local/Makefile (/etc/aliases by default). If the system aliases file does not ++exist, the installation script creates it, and outputs a comment to the user. ++ ++The created file contains no aliases, but it does contain comments about the ++aliases a site should normally have. Mail aliases have traditionally been kept ++in /etc/aliases. However, some operating systems are now using /etc/mail/ ++aliases. You should check if yours is one of these, and change Exim's ++configuration if necessary. ++ ++The default configuration uses the local host's name as the only local domain, ++and is set up to do local deliveries into the shared directory /var/mail, ++running as the local user. System aliases and .forward files in users' home ++directories are supported, but no NIS or NIS+ support is configured. Domains ++other than the name of the local host are routed using the DNS, with delivery ++over SMTP. ++ ++It is possible to install Exim for special purposes (such as building a binary ++distribution) in a private part of the file system. You can do this by a ++command such as ++ ++make DESTDIR=/some/directory/ install ++ ++This has the effect of pre-pending the specified directory to all the file ++paths, except the name of the system aliases file that appears in the default ++configuration. (If a default alias file is created, its name is modified.) For ++backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is ++deprecated. ++ ++Running make install does not copy the Exim 4 conversion script convert4r4. You ++will probably run this only once if you are upgrading from Exim 3. None of the ++documentation files in the doc directory are copied, except for the info files ++when you have set INFO_DIRECTORY, as described in section 4.17 below. ++ ++For the utility programs, old versions are renamed by adding the suffix .O to ++their names. The Exim binary itself, however, is handled differently. It is ++installed under a name that includes the version number and the compile number, ++for example exim-4.74-1. The script then arranges for a symbolic link called ++exim to point to the binary. If you are updating a previous version of Exim, ++the script takes care to ensure that the name exim is never absent from the ++directory (as seen by other processes). ++ ++If you want to see what the make install will do before running it for real, ++you can pass the -n option to the installation script by this command: ++ ++make INSTALL_ARG=-n install ++ ++The contents of the variable INSTALL_ARG are passed to the installation script. ++You do not need to be root to run this test. Alternatively, you can run the ++installation script directly, but this must be from within the build directory. ++For example, from the top-level Exim directory you could use this command: ++ ++(cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) ++ ++There are two other options that can be supplied to the installation script. ++ ++ * -no_chown bypasses the call to change the owner of the installed binary to ++ root, and the call to make it a setuid binary. ++ ++ * -no_symlink bypasses the setting up of the symbolic link exim to the ++ installed binary. ++ ++INSTALL_ARG can be used to pass these options to the script. For example: ++ ++make INSTALL_ARG=-no_symlink install ++ ++The installation script can also be given arguments specifying which files are ++to be copied. For example, to install just the Exim binary, and nothing else, ++without creating the symbolic link, you could use: ++ ++make INSTALL_ARG='-no_symlink exim' install ++ ++4.17 Installing info documentation ++ ++Not all systems use the GNU info system for documentation, and for this reason, ++the Texinfo source of Exim's documentation is not included in the main ++distribution. Instead it is available separately from the ftp site (see section ++1.6). ++ ++If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of ++the documentation is found in the source tree, running "make install" ++automatically builds the info files and installs them. ++ ++4.18 Setting up the spool directory ++ ++When it starts up, Exim tries to create its spool directory if it does not ++exist. The Exim uid and gid are used for the owner and group of the spool ++directory. Sub-directories are automatically created in the spool directory as ++necessary. ++ ++4.19 Testing ++ ++Having installed Exim, you can check that the run time configuration file is ++syntactically valid by running the following command, which assumes that the ++Exim binary directory is within your PATH environment variable: ++ ++exim -bV ++ ++If there are any errors in the configuration file, Exim outputs error messages. ++Otherwise it outputs the version number and build date, the DBM library that is ++being used, and information about which drivers and other optional code modules ++are included in the binary. Some simple routing tests can be done by using the ++address testing option. For example, ++ ++exim -bt ++ ++should verify that it recognizes a local mailbox, and ++ ++exim -bt ++ ++a remote one. Then try getting it to deliver mail, both locally and remotely. ++This can be done by passing messages directly to Exim, without going through a ++user agent. For example: ++ ++exim -v postmaster@your.domain.example ++From: user@your.domain.example ++To: postmaster@your.domain.example ++Subject: Testing Exim ++ ++This is a test message. ++^D ++ ++The -v option causes Exim to output some verification of what it is doing. In ++this case you should see copies of three log lines, one for the message's ++arrival, one for its delivery, and one containing "Completed". ++ ++If you encounter problems, look at Exim's log files (mainlog and paniclog) to ++see if there is any relevant information there. Another source of information ++is running Exim with debugging turned on, by specifying the -d option. If a ++message is stuck on Exim's spool, you can force a delivery with debugging ++turned on by a command of the form ++ ++exim -d -M ++ ++You must be root or an "admin user" in order to do this. The -d option produces ++rather a lot of output, but you can cut this down to specific areas. For ++example, if you use -d-all+route only the debugging information relevant to ++routing is included. (See the -d option in chapter 5 for more details.) ++ ++One specific problem that has shown up on some sites is the inability to do ++local deliveries into a shared mailbox directory, because it does not have the ++"sticky bit" set on it. By default, Exim tries to create a lock file before ++writing to a mailbox file, and if it cannot create the lock file, the delivery ++is deferred. You can get round this either by setting the "sticky bit" on the ++directory, or by setting a specific group for local deliveries and allowing ++that group to create files in the directory (see the comments above the ++local_delivery transport in the default configuration file). Another approach ++is to configure Exim not to use lock files, but just to rely on fcntl() locking ++instead. However, you should do this only if all user agents also use fcntl() ++locking. For further discussion of locking issues, see chapter 26. ++ ++One thing that cannot be tested on a system that is already running an MTA is ++the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX ++option can be used to run an Exim daemon that listens on some other port, or ++inetd can be used to do this. The -bh option and the exim_checkaccess utility ++can be used to check out policy controls on incoming SMTP mail. ++ ++Testing a new version on a system that is already running Exim can most easily ++be done by building a binary with a different CONFIGURE_FILE setting. From ++within the run time configuration, all other file and directory names that Exim ++uses can be altered, in order to keep it entirely clear of the production ++version. ++ ++4.20 Replacing another MTA with Exim ++ ++Building and installing Exim for the first time does not of itself put it in ++general use. The name by which the system's MTA is called by mail user agents ++is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating ++system), and it is necessary to make this name point to the exim binary in ++order to get the user agents to pass messages to Exim. This is normally done by ++renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a ++symbolic link to the exim binary. It is a good idea to remove any setuid ++privilege and executable status from the old MTA. It is then necessary to stop ++and restart the mailer daemon, if one is running. ++ ++Some operating systems have introduced alternative ways of switching MTAs. For ++example, if you are running FreeBSD, you need to edit the file /etc/mail/ ++mailer.conf instead of setting up a symbolic link as just described. A typical ++example of the contents of this file for running Exim is as follows: ++ ++sendmail /usr/exim/bin/exim ++send-mail /usr/exim/bin/exim ++mailq /usr/exim/bin/exim -bp ++newaliases /usr/bin/true ++ ++Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your ++Exim installation is "live". Check it by sending a message from your favourite ++user agent. ++ ++You should consider what to tell your users about the change of MTA. Exim may ++have different capabilities to what was previously running, and there are ++various operational differences such as the text of messages produced by ++command line options and in bounce messages. If you allow your users to make ++use of Exim's filtering capabilities, you should make the document entitled ++Exim's interface to mail filtering available to them. ++ ++4.21 Upgrading Exim ++ ++If you are already running Exim on your host, building and installing a new ++version automatically makes it available to MUAs, or any other programs that ++call the MTA directly. However, if you are running an Exim daemon, you do need ++to send it a HUP signal, to make it re-execute itself, and thereby pick up the ++new binary. You do not need to stop processing mail in order to install a new ++version of Exim. The install script does not modify an existing runtime ++configuration file. ++ ++4.22 Stopping the Exim daemon on Solaris ++ ++The standard command for stopping the mailer daemon on Solaris is ++ ++/etc/init.d/sendmail stop ++ ++If /usr/lib/sendmail has been turned into a symbolic link, this script fails to ++stop Exim because it uses the command ps -e and greps the output for the text ++"sendmail"; this is not present because the actual program name (that is, ++"exim") is given by the ps command with these options. A solution is to replace ++the line that finds the process id with something like ++ ++pid=`cat /var/spool/exim/exim-daemon.pid` ++ ++to obtain the daemon's pid directly from the file that Exim saves it in. ++ ++Note, however, that stopping the daemon does not "stop Exim". Messages can ++still be received from local processes, and if automatic delivery is configured ++(the normal case), deliveries will still occur. ++ ++5. The Exim command line ++ ++Exim's command line takes the standard Unix form of a sequence of options, each ++starting with a hyphen character, followed by a number of arguments. The ++options are compatible with the main options of Sendmail, and there are also ++some additional options, some of which are compatible with Smail 3. Certain ++combinations of options do not make sense, and provoke an error if used. The ++form of the arguments depends on which options are set. ++ ++5.1 Setting options by program name ++ ++If Exim is called under the name mailq, it behaves as if the option -bp were ++present before any other options. The -bp option requests a listing of the ++contents of the mail queue on the standard output. This feature is for ++compatibility with some systems that contain a command of that name in one of ++the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/ ++sendmail. ++ ++If Exim is called under the name rsmtp it behaves as if the option -bS were ++present before any other options, for compatibility with Smail. The -bS option ++is used for reading in a number of messages in batched SMTP format. ++ ++If Exim is called under the name rmail it behaves as if the -i and -oee options ++were present before any other options, for compatibility with Smail. The name ++rmail is used as an interface by some UUCP systems. ++ ++If Exim is called under the name runq it behaves as if the option -q were ++present before any other options, for compatibility with Smail. The -q option ++causes a single queue runner process to be started. ++ ++If Exim is called under the name newaliases it behaves as if the option -bi ++were present before any other options, for compatibility with Sendmail. This ++option is used for rebuilding Sendmail's alias file. Exim does not have the ++concept of a single alias file, but can be configured to run a given command if ++called with the -bi option. ++ ++5.2 Trusted and admin users ++ ++Some Exim options are available only to trusted users and others are available ++only to admin users. In the description below, the phrases "Exim user" and ++"Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in ++Local/Makefile or set by the exim_user and exim_group options. These do not ++necessarily have to use the name "exim". ++ ++ * The trusted users are root, the Exim user, any user listed in the ++ trusted_users configuration option, and any user whose current group or any ++ supplementary group is one of those listed in the trusted_groups ++ configuration option. Note that the Exim group is not automatically ++ trusted. ++ ++ Trusted users are always permitted to use the -f option or a leading ++ "From " line to specify the envelope sender of a message that is passed to ++ Exim through the local interface (see the -bm and -f options below). See ++ the untrusted_set_sender option for a way of permitting non-trusted users ++ to set envelope senders. ++ ++ For a trusted user, there is never any check on the contents of the From: ++ header line, and a Sender: line is never added. Furthermore, any existing ++ Sender: line in incoming local (non-TCP/IP) messages is not removed. ++ ++ Trusted users may also specify a host name, host address, interface ++ address, protocol name, ident value, and authentication data when ++ submitting a message locally. Thus, they are able to insert messages into ++ Exim's queue locally that have the characteristics of messages received ++ from a remote host. Untrusted users may in some circumstances use -f, but ++ can never set the other values that are available to trusted users. ++ ++ * The admin users are root, the Exim user, and any user that is a member of ++ the Exim group or of any group listed in the admin_groups configuration ++ option. The current group does not have to be one of these groups. ++ ++ Admin users are permitted to list the queue, and to carry out certain ++ operations on messages, for example, to force delivery failures. It is also ++ necessary to be an admin user in order to see the full information provided ++ by the Exim monitor, and full debugging output. ++ ++ By default, the use of the -M, -q, -R, and -S options to cause Exim to ++ attempt delivery of messages on its queue is restricted to admin users. ++ However, this restriction can be relaxed by setting the prod_requires_admin ++ option false (that is, specifying no_prod_requires_admin). ++ ++ Similarly, the use of the -bp option to list all the messages in the queue ++ is restricted to admin users unless queue_list_requires_admin is set false. ++ ++Warning: If you configure your system so that admin users are able to edit ++Exim's configuration file, you are giving those users an easy way of getting ++root. There is further discussion of this issue at the start of chapter 6. ++ ++5.3 Command line options ++ ++Exim's command line options are described in alphabetical order below. If none ++of the options that specifies a specific action (such as starting the daemon or ++a queue runner, or testing an address, or receiving a message in a specific ++format, or listing the queue) are present, and there is at least one argument ++on the command line, -bm (accept a local message on the standard input, with ++the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a ++brief message about itself and exits. ++ ++-- ++ ++ This is a pseudo-option whose only purpose is to terminate the options and ++ therefore to cause subsequent command line items to be treated as arguments ++ rather than options, even if they begin with hyphens. ++ ++--help ++ ++ This option causes Exim to output a few sentences stating what it is. The ++ same output is generated if the Exim binary is called with no options and ++ no arguments. ++ ++--version ++ ++ This option is an alias for -bV and causes version information to be ++ displayed. ++ ++-B ++ ++ This is a Sendmail option for selecting 7 or 8 bit processing. Exim is ++ 8-bit clean; it ignores this option. ++ ++-bd ++ ++ This option runs Exim as a daemon, awaiting incoming SMTP connections. ++ Usually the -bd option is combined with the -q