diff -r 525826c63eba -r 399967a8bbf1 doc.maildir_tag --- a/doc.maildir_tag Sun Feb 13 22:42:33 2011 +0100 +++ b/doc.maildir_tag Sun Feb 13 23:07:24 2011 +0100 @@ -1,18809 +1,22 @@ # HG changeset patch -# Parent 0000000000000000000000000000000000000000 +# Parent 4acd755ecda3351741f615164fd0e3c972d9578f diff --git a/doc/spec.txt b/doc/spec.txt -new file mode 100644 ---- /dev/null +--- a/doc/spec.txt +++ 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