X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/7d0ab55cbe2498a27fc54a779d82b5240e440517..c275c1f151f3cb893edcb725ee8728560b9408d9:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 41c977589..42a393558 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,8 +1,6 @@ -. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.32 2008/01/29 17:14:47 fanf2 Exp $ -. . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is -. converted into DocBook XML for subsequent conversion into printing and online +. converted into DocBook XML for subsequent conversion into printable and online . formats. The markup used herein is "standard" xfpt markup, with some extras. . The markup is summarized in a file called Markup.txt. . @@ -37,34 +35,37 @@ .literal off . ///////////////////////////////////////////////////////////////////////////// -. This generate the outermost element that wraps then entire document. +. This generates the outermost element that wraps the entire document. . ///////////////////////////////////////////////////////////////////////////// .book . ///////////////////////////////////////////////////////////////////////////// -. These definitions set some parameters and save some typing. Remember that -. the element must also be updated for each new edition. +. These definitions set some parameters and save some typing. +. Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.69" -.set version "4.70" +.set previousversion "4.93" +.include ./local_params .set ACL "access control lists (ACLs)" .set I "    " +.macro copyyear +2019 +.endmacro . ///////////////////////////////////////////////////////////////////////////// . Additional xfpt markup used by this document, over and above the default . provided in the xfpt library. . ///////////////////////////////////////////////////////////////////////////// -. --- Override the &$ flag to automatically insert a $ with the variable name +. --- Override the &$ flag to automatically insert a $ with the variable name. .flag &$ $& "$" "" . --- Short flags for daggers in option headings. They will always be inside -. --- an italic string, but we want the daggers to be roman. +. --- an italic string, but we want the daggers to be in Roman. .flag &!! "†" .flag &!? "‡" @@ -88,7 +89,7 @@ . --- A macro for the common 2-column tables. The width of the first column . --- is suitable for the many tables at the start of the main options chapter; -. --- the small number of other 2-column tables override it. +. --- a small number of other 2-column tables override it. .macro table2 196pt 254pt .itable none 0 0 2 $1 left $2 left @@ -164,7 +165,7 @@ . //////////////////////////////////////////////////////////////////////////// -. The element is removed from the XML before processing for Ascii +. The element is removed from the XML before processing for ASCII . output formats. . //////////////////////////////////////////////////////////////////////////// @@ -172,17 +173,18 @@ Specification of the Exim Mail Transfer Agent The Exim MTA -23 August 2007 -PhilipHazel -PH -University of Cambridge Computing Service -
New Museums Site, Pembroke Street, Cambridge CB2 3QH, England
+ +.fulldate + +EximMaintainers +EM - 4.68 - 23 August 2007 - PH +.versiondatexml + EM -2007University of Cambridge + +.copyyear + University of Cambridge .literal off @@ -335,7 +337,7 @@ 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. +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. @@ -347,8 +349,8 @@ 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, +The use, supply, or promotion of Exim for the purpose of sending bulk, +unsolicited electronic mail is incompatible with the basic aims of Exim, 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. @@ -367,18 +369,22 @@ contributors. .section "Exim documentation" "SECID1" +. Keep this example change bar when updating the documentation! + +.new .cindex "documentation" -This edition of the Exim specification applies to version &version; of Exim. +This edition of the Exim specification applies to version &version() of Exim. Substantive changes from the &previousversion; edition are marked in some -renditions of the document; this paragraph is so marked if the rendition is +renditions of this document; this paragraph is so marked if the rendition is capable of showing a change indicator. +.wen 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 +Furthermore, this 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. @@ -386,9 +392,9 @@ 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 -(&url(http://www.uit.co.uk/exim-book/)). +(&url(https://www.uit.co.uk/exim-book/)). -This book also contains a chapter that gives a general introduction to SMTP and +The 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.) @@ -403,7 +409,7 @@ information. .cindex "&_doc/NewStuff_&" .cindex "&_doc/ChangeLog_&" .cindex "change log" -As the program develops, there may be features in newer versions that have not +As Exim 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 @@ -414,7 +420,7 @@ 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 +All changes to Exim (whether new features, bug fixes, or other kinds of change) are noted briefly in the file called &_doc/ChangeLog_&. .cindex "&_doc/spec.txt_&" @@ -428,10 +434,9 @@ directory are: .row &_exim.8_& "a man page of Exim's command line options" .row &_experimental.txt_& "documentation of experimental features" .row &_filter.txt_& "specification of the filter language" -.row &_pcrepattern.txt_& "specification of PCRE regular expressions" -.row &_pcretest.txt_& "specification of the PCRE testing program" .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" +.row &_openssl.txt_& "installing a current OpenSSL release" .endtable The main specification and the specification of the filtering language are also @@ -440,29 +445,28 @@ available in other formats (HTML, PostScript, PDF, and Texinfo). Section -.section "FTP and web sites" "SECID2" -.cindex "web site" +.section "FTP site and websites" "SECID2" +.cindex "website" .cindex "FTP site" -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. +The primary site for Exim source distributions is the &%exim.org%& FTP site, +available over HTTPS, HTTP and FTP. These services, and the &%exim.org%& +website, are hosted at the University of Cambridge. .cindex "wiki" .cindex "FAQ" -As well as Exim distribution tar files, the Exim web site contains a number of +As well as Exim distribution tar files, the Exim website contains a number of differently formatted versions of the documentation. A recent addition to the -online information is the Exim wiki (&url(http://wiki.exim.org)), +online information is the Exim wiki (&url(https://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. +The wiki site should always redirect to the correct place, which is currently +provided by GitHub, and is open to editing by anyone with a GitHub account. .cindex Bugzilla -An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use +An Exim Bugzilla exists at &url(https://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. - +Please do not ask for configuration help in the bug-tracker. .section "Mailing lists" "SECID3" @@ -470,10 +474,10 @@ first to check that you are not duplicating a previous entry. The following Exim mailing lists exist: .table2 140pt +.row &'exim-announce@exim.org'& "Moderated, low volume announcements list" .row &'exim-users@exim.org'& "General discussion list" .row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc." -.row &'exim-announce@exim.org'& "Moderated, low volume announcements list" -.row &'exim-future@exim.org'& "Discussion of long-term development" +.row &'exim-cvs@exim.org'& "Automated commit messages from the VCS" .endtable You can subscribe to these lists, change your existing subscriptions, and view @@ -483,23 +487,16 @@ 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: .display -&url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users) +&url(https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users) .endd -Please ask Debian-specific questions on this list and not on the general Exim +Please ask Debian-specific questions on that list and not on the general Exim lists. -.section "Exim training" "SECID4" -.cindex "training courses" -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 &url(http://www-tus.csx.cam.ac.uk/courses/exim/). - .section "Bug reports" "SECID5" .cindex "bug reports" .cindex "reporting bugs" Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported -via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure +via the Bugzilla (&url(https://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. @@ -507,43 +504,66 @@ message to the &'exim-dev'& mailing list and have it discussed. .section "Where to find the Exim distribution" "SECTavail" .cindex "FTP site" -.cindex "distribution" "ftp site" -The master ftp site for the Exim distribution is -.display -&*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim*& -.endd -This is mirrored by +.cindex "HTTPS download site" +.cindex "distribution" "FTP site" +.cindex "distribution" "https site" +The master distribution site for the Exim distribution is .display -&*ftp://ftp.exim.org/pub/exim*& +&url(https://downloads.exim.org/) .endd -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 service is available over HTTPS, HTTP and FTP. +We encourage people to migrate to HTTPS. + +The content served at &url(https://downloads.exim.org/) is identical to the +content served at &url(https://ftp.exim.org/pub/exim) and +&url(ftp://ftp.exim.org/pub/exim). + +If accessing via a hostname containing &'ftp'&, then the file references that +follow are relative to the &_exim_& directories at these sites. +If accessing via the hostname &'downloads'& then the subdirectories described +here are top-level directories. + +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 +Within the top 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 .display +&_exim-n.nn.tar.xz_& &_exim-n.nn.tar.gz_& &_exim-n.nn.tar.bz2_& .endd -where &'n.nn'& is the highest such version number in the directory. The two +where &'n.nn'& is the highest such version number in the directory. The three 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 &_.xz_& file is usually the smallest, while the &_.gz_& file is the +most portable to old systems. .cindex "distribution" "signing details" .cindex "distribution" "public key" .cindex "public key for signed distribution" -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: +The distributions will be PGP signed by an individual key of the Release +Coordinator. This key will have a uid containing an email address in the +&'exim.org'& domain and will have signatures from other people, including +other Exim maintainers. We expect that the key will be in the "strong set" of +PGP keys. There should be a trust path to that key from the Exim Maintainer's +PGP keys, a version of which can be found in the release directory in the file +&_Exim-Maintainers-Keyring.asc_&. All keys used will be available in public keyserver pools, +such as &'pool.sks-keyservers.net'&. + +At the time of the last update, releases were being made by Jeremy Harris and signed +with key &'0xBCE58C8CE41F32DF'&. Other recent keys used for signing are those +of Heiko Schlittermann, &'0x26101B62F69376CE'&, +and of Phil Pennock, &'0x4D1E900E14C1CC04'&. + +The signatures for the tar bundles are in: .display +&_exim-n.nn.tar.xz.asc_& &_exim-n.nn.tar.gz.asc_& &_exim-n.nn.tar.bz2.asc_& .endd -For each released version, the log of changes is made separately available in a +For each released version, the log of changes is made 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. @@ -558,7 +578,7 @@ inside the &_exim4_& directory of the FTP site: &_exim-texinfo-n.nn.tar.gz_& .endd These tar files contain only the &_doc_& directory, not the complete -distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. +distribution, and are also available in &_.bz2_& and &_.xz_& forms. .section "Limitations" "SECID6" @@ -601,8 +621,8 @@ a number of common scanners are provided. .endlist -.section "Run time configuration" "SECID7" -Exim's run time configuration is held in a single text file that is divided +.section "Runtime configuration" "SECID7" +Exim's runtime 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 @@ -616,13 +636,13 @@ 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 +example, &%-bp%&, which lists the messages in 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 &<>& 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 +Control of messages in 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. @@ -633,7 +653,7 @@ interface to Exim's command line administration options. .cindex "terminology definitions" .cindex "body of message" "definition of" 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 +It is the last part of a message and is separated from the &'header'& (see below) by a blank line. .cindex "bounce message" "definition of" @@ -678,7 +698,7 @@ line. .cindex "local part" "definition of" .cindex "domain" "definition of" -The term &'local part'&, which is taken from RFC 2822, is used to refer to that +The term &'local part'&, which is taken from RFC 2822, is used to refer to the part of an email address that precedes the @ sign. The part that follows the @ sign is called the &'domain'& or &'mail domain'&. @@ -694,20 +714,20 @@ host it is running on are &'remote'&. message's envelope. .cindex "queue" "definition of" -The term &'queue'& is used to refer to the set of messages awaiting delivery, +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 +Exim's case, the reality is more like a pool than a queue, because there is normally no ordering of waiting messages. .cindex "queue runner" "definition of" 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 +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. .cindex "spool directory" "definition of" 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 +messages in 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. @@ -724,15 +744,15 @@ the Exim documentation, &"spool"& is always used in the first sense. .cindex "incorporated code" .cindex "regular expressions" "library" .cindex "PCRE" +.cindex "OpenDMARC" A number of pieces of external code are included in the Exim distribution. .ilist Regular expressions are supported in the main Exim program and in the Exim monitor using the freely-distributable PCRE library, copyright -© University of Cambridge. The source to a cut down version of PCRE -used to be distributed in the directory &_src/pcre_&. However, this is -no longer the case and you will need to use a system PCRE library or -obtain and install the full version of the library from +© 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 &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre). .next .cindex "cdb" "acknowledgment" @@ -751,7 +771,7 @@ 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 -&url(http://www.pobox.com/~djb/cdb.html). This implementation borrows +&url(https://cr.yp.to/cdb.html). This implementation borrows some code from Dan Bernstein's implementation (which has no license restrictions applied to it). .endblockquote @@ -805,7 +825,7 @@ Redistributions of any form whatsoever must retain the following acknowledgment: &"This product includes software developed by Computing Services -at Carnegie Mellon University (&url(http://www.cmu.edu/computing/)."& +at Carnegie Mellon University (&url(https://www.cmu.edu/computing/)."& CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY @@ -849,9 +869,17 @@ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .endblockquote +.next +.cindex "opendmarc" "acknowledgment" +The DMARC implementation uses the OpenDMARC library which is Copyrighted by +The Trusted Domain Project. Portions of Exim source which use OpenDMARC +derived code are indicated in the respective source files. The full OpenDMARC +license is provided in the LICENSE.opendmarc file contained in the distributed +source code. + .next Many people have contributed code fragments, some large, some small, that were -not covered by any specific licence requirements. It is assumed that the +not covered by any specific license requirements. It is assumed that the contributors are happy to see their code incorporated into Exim under the GPL. .endlist @@ -879,9 +907,9 @@ has been down, and it also maintains per-host retry information. .section "Policy control" "SECID11" .cindex "policy control" "overview" 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 +Internet. Perhaps their most important job is to stop MTAs from 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 +unsolicited junk and want to disguise its source. Exim provides flexible facilities for specifying policy controls on incoming mail: .ilist @@ -957,7 +985,7 @@ 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 +id is used to construct filenames, and the names of files in those systems are not always case-sensitive. .cindex "pid (process id)" "re-use of" @@ -1014,7 +1042,7 @@ 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, +command. This is 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. .next @@ -1038,7 +1066,7 @@ 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 +certain users (&"trusted users"&) to specify a different sender addresses 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 &<>& for details of trusted @@ -1046,10 +1074,10 @@ 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 +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 +individual recipients or the entire message can be rejected if local policy requirements are not met. The &[local_scan()]& function (see chapter &<>&) is run for all incoming messages. @@ -1074,7 +1102,7 @@ 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. .cindex "spool directory" "&_input_& sub-directory" -By default all these message files are held in a single directory called +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 @@ -1111,7 +1139,7 @@ delivered (see chapters &<>& and 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 +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. @@ -1126,7 +1154,7 @@ to be sent. .oindex "&%ignore_bounce_errors_after%&" 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. +The first applies only to frozen bounces, the second to all frozen messages. .cindex "message" "log file for" .cindex "log" "file for each message" @@ -1134,7 +1162,7 @@ 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 &<>&). 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 +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 @@ -1151,7 +1179,7 @@ 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 +Should the system or Exim 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 @@ -1166,11 +1194,11 @@ deliveries caused by crashes. 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 +specify which ones are included in the binary. Runtime options specify which ones are actually used for delivering messages. .cindex "drivers" "instance definition" -Each driver that is specified in the run time configuration is an &'instance'& +Each driver that is specified in the runtime 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 @@ -1205,8 +1233,8 @@ 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 +addresses in domains that are not recognized specifically by the local host. +Typically these are 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 @@ -1243,7 +1271,7 @@ 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 +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. @@ -1263,8 +1291,8 @@ the following: .ilist &'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, +transport or generates one or more &"child"& addresses. Processing the +original address ceases .oindex "&%unseen%&" unless the &%unseen%& option is set on the router. This option can be used to set up multiple deliveries with different routing (for example, @@ -1279,7 +1307,7 @@ child addresses. Unlike &%pass_router%& (see below) the router specified by &%redirect_router%& may be anywhere in the router configuration. .next &'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 +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). @@ -1321,8 +1349,8 @@ facility for this purpose. .cindex "address duplicate, discarding" .cindex "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 +and remote transports and discards any duplicates that it finds. During this +check, local parts are treated case-sensitively. This happens only when actually delivering a message; when testing routers with &%-bt%&, all the routed addresses are shown. @@ -1336,6 +1364,7 @@ order in which they are tested. The individual configuration options are described in more detail in chapter &<>&. .ilist +.cindex affix "router precondition" 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 @@ -1351,6 +1380,7 @@ 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. +Note that cutthrough delivery is classed as a recipient verification for this purpose. .next 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 @@ -1360,6 +1390,7 @@ having to simulate the effect of the scanner. .next Routers can be designated for use only when verifying an address, as opposed to routing it for delivery. The &%verify_only%& option controls this. +Again, cutthrough delivery counts as a verification. .next Individual routers can be explicitly skipped when running the routers to check an address given in the SMTP EXPN command (see the &%expn%& option). @@ -1370,6 +1401,7 @@ of domains that it defines. .vindex "&$local_part_prefix$&" .vindex "&$local_part$&" .vindex "&$local_part_suffix$&" +.cindex affix "router precondition" 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 @@ -1438,7 +1470,7 @@ 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. .next -Each recipient address is offered to each configured router in turn, subject to +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 @@ -1515,9 +1547,9 @@ deleted, though the message log can optionally be preserved if required. 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 +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 +first attempt will remain in your queue forever. 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. @@ -1546,8 +1578,7 @@ 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, - -.cindex "hints database" +.cindex "hints database" "deferred deliveries" 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 @@ -1556,7 +1587,6 @@ one connection. - .section "Permanent delivery failure" "SECID21" .cindex "delivery" "permanent failure" .cindex "bounce message" "when generated" @@ -1588,7 +1618,7 @@ of the list. .section "Failures to deliver bounce messages" "SECID22" .cindex "bounce message" "failure to deliver" 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, +itself suffers a permanent delivery failure, the message is left in 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 @@ -1607,7 +1637,7 @@ for only a short time (see &%timeout_frozen_after%& and .section "Unpacking" "SECID23" 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-&version;_&) into which the following files are placed: +&_exim-&version()_&) into which the following files are placed: .table2 140pt .irow &_ACKNOWLEDGMENTS_& "contains some acknowledgments" @@ -1633,7 +1663,7 @@ following subdirectories are created: .irow &_util_& "independent utilities" .endtable -The main utility programs are contained in the &_src_& directory, and are built +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. @@ -1650,19 +1680,25 @@ 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. +.cindex compiler requirements +.cindex compiler version +A C99-capable compiler will be required for the build. -.section "PCRE library" "SECTdb" +.section "PCRE library" "SECTpcre" .cindex "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 +modern systems include PCRE as a system library, although you may need to +install the PCRE package or the 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 +headers are in an unusual location you will need to either set the PCRE_LIBS +and INCLUDE directives appropriately, +or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command. +If your operating system has no PCRE support then you will need to obtain and build the current PCRE from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). +More information on PCRE is available at &url(https://www.pcre.org/). .section "DBM libraries" "SECTdb" .cindex "DBM libraries" "discussion of" @@ -1702,7 +1738,7 @@ Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&. 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. +filename is used unmodified. .next .cindex "Berkeley DB library" The Berkeley DB package, if called via its &'ndbm'& compatibility interface, @@ -1715,14 +1751,18 @@ the traditional &'ndbm'& interface. .next 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 -&url(http://www.sleepycat.com/). +2.&'x'& and 3.&'x'& were current for a while, but the latest versions when Exim last revamped support were numbered 4.&'x'&. +Maintenance of some of the earlier releases has ceased. All versions of +Berkeley DB could be obtained from +&url(http://www.sleepycat.com/), which is now a redirect to their new owner's +page with far newer versions listed. +It is probably wise to plan to move your storage configurations away from +Berkeley DB format, as today there are smaller and simpler alternatives more +suited to Exim's usage model. .next .cindex "&'tdb'& DBM library" Yet another DBM library, called &'tdb'&, is available from -&url(http://download.sourceforge.net/tdb). It has its own interface, and also +&url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also operates on a single file. .endlist @@ -1780,17 +1820,17 @@ 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 +without them. They are the location of the runtime 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. +a colon-separated list of filenames; 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 +at runtime, 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 +you specify them in &_Local/Makefile_& instead of at runtime, so that errors detected early in Exim's execution (such as a malformed configuration file) can be logged. @@ -1816,7 +1856,7 @@ happy with the default settings described in &_exim_monitor/EDITME_&, 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 +configuration files, for example, to change the C compiler, which defaults to &%gcc%&. See section &<>& below for details of how to do this. @@ -1830,12 +1870,12 @@ 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 +(default is set at build time). 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 -&url(http://www.gnu.org/software/libiconv/)) can be installed on such +&url(https://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 .code @@ -1848,11 +1888,10 @@ to your &_Local/Makefile_& and rebuild Exim. .section "Including TLS/SSL encryption support" "SECTinctlsssl" .cindex "TLS" "including support for TLS" .cindex "encryption" "including support for" -.cindex "SUPPORT_TLS" .cindex "OpenSSL" "building Exim with" .cindex "GnuTLS" "building Exim with" -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 +Exim is usually built to support encrypted SMTP connections, using the STARTTLS +command as per RFC 2487. It can also support 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). @@ -1861,33 +1900,50 @@ 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 you do not want TLS support you should set +.code +DISABLE_TLS=yes +.endd +in &_Local/Makefile_&. + If OpenSSL is installed, you should set .code -SUPPORT_TLS=yes +USE_OPENSL=yes TLS_LIBS=-lssl -lcrypto .endd in &_Local/Makefile_&. You may also need to specify the locations of the OpenSSL library and include files. For example: .code -SUPPORT_TLS=yes +USE_OPENSSL=yes TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto TLS_INCLUDE=-I/usr/local/openssl/include/ .endd +.cindex "pkg-config" "OpenSSL" +If you have &'pkg-config'& available, then instead you can just use: +.code +USE_OPENSSL=yes +USE_OPENSSL_PC=openssl +.endd .cindex "USE_GNUTLS" If GnuTLS is installed, you should set .code -SUPPORT_TLS=yes USE_GNUTLS=yes TLS_LIBS=-lgnutls -ltasn1 -lgcrypt .endd in &_Local/Makefile_&, and again you may need to specify the locations of the library and include files. For example: .code -SUPPORT_TLS=yes USE_GNUTLS=yes TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt TLS_INCLUDE=-I/usr/gnu/include .endd +.cindex "pkg-config" "GnuTLS" +If you have &'pkg-config'& available, then instead you can just use: +.code +USE_GNUTLS=yes +USE_GNUTLS_PC=gnutls +.endd + 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 &<>&. @@ -1896,8 +1952,11 @@ given in chapter &<>&. .section "Use of tcpwrappers" "SECID27" + .cindex "tcpwrappers, building Exim to support" .cindex "USE_TCP_WRAPPERS" +.cindex "TCP_WRAPPERS_DAEMON_NAME" +.cindex "tcp_wrappers_daemon_name" 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 @@ -1912,18 +1971,20 @@ USE_TCP_WRAPPERS=yes CFLAGS=-O -I/usr/local/include EXTRALIBS_EXIM=-L/usr/local/lib -lwrap .endd -in &_Local/Makefile_&. The name to use in the &'tcpwrappers'& control files is -&"exim"&. For example, the line +in &_Local/Makefile_&. The daemon name to use in the &'tcpwrappers'& control +files is &"exim"&. For example, the line .code exim : LOCAL 192.168.1. .friendly.domain.example .endd 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. Consult the &'tcpwrappers'& documentation for +All other connections are denied. The daemon name used by &'tcpwrappers'& +can be changed at build time by setting TCP_WRAPPERS_DAEMON_NAME in +&_Local/Makefile_&, or by setting tcp_wrappers_daemon_name in the +configure file. Consult the &'tcpwrappers'& documentation for further details. - .section "Including support for IPv6" "SECID28" .cindex "IPv6" "including support for" Exim contains code for use on systems that have IPv6 support. Setting @@ -1936,11 +1997,41 @@ 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. - +over-complex, and its status was reduced to &"experimental"&. +Exim used to +have a compile option for including A6 record support but this has now been +withdrawn. + + + +.section "Dynamically loaded lookup module support" "SECTdynamicmodules" +.cindex "lookup modules" +.cindex "dynamic modules" +.cindex ".so building" +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: +.code +LOOKUP_LSEARCH=yes +LOOKUP_SQLITE=2 +LOOKUP_MYSQL=2 +.endd .section "The building process" "SECID29" @@ -1953,9 +2044,6 @@ For example, on a Sun system running Solaris 8, the directory .cindex "symbolic link" "to source files" 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 @@ -2077,9 +2165,29 @@ 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 +binary, attempts to configure Exim to use it cause runtime configuration errors. +.cindex "pkg-config" "lookups" +.cindex "pkg-config" "authenticators" +Many systems now use a tool called &'pkg-config'& to encapsulate information +about how to compile against a library; Exim has some initial support for +being able to use pkg-config for lookups and authenticators. For any given +makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new +variable with the &`_PC`& suffix in the name and assign as the value the +name of the package to be queried. The results of querying via the +&'pkg-config'& command will be added to the appropriate Makefile variables +with &`+=`& directives, so your version of &'make'& will need to support that +syntax. For instance: +.code +LOOKUP_SQLITE=yes +LOOKUP_SQLITE_PC=sqlite3 +AUTH_GSASL=yes +AUTH_GSASL_PC=libgsasl +AUTH_HEIMDAL_GSSAPI=yes +AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi +.endd + .cindex "Perl" "including support for" Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines to be called during string expansion. To enable this facility, @@ -2160,7 +2268,7 @@ As with Exim itself, the final three files need not exist, and in this case the &_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. +LOG_DEPTH at runtime. .ecindex IIDbuex @@ -2180,10 +2288,10 @@ it may be possible to run Exim without making the binary setuid root (see chapter &<>& for details). .cindex "CONFIGURE_FILE" -Exim's run time configuration file is named by the CONFIGURE_FILE setting +Exim's runtime 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 +by the installation script. If a runtime configuration file already exists, it is left alone. If CONFIGURE_FILE is a colon-separated list, naming several alternative files, no default is installed. @@ -2223,16 +2331,15 @@ but this usage is deprecated. .cindex "installing Exim" "what is not installed" Running &'make install'& does not copy the Exim 4 conversion script -&'convert4r4'&, or the &'pcretest'& test program. You will probably run the -first of these only once (if you are upgrading from Exim 3), and the second -isn't really part of Exim. None of the documentation files in the &_doc_& +&'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 &<>& 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-&version;-1_&. The script then arranges for a symbolic link +for example, &_exim-&version()-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). @@ -2280,7 +2387,7 @@ make INSTALL_ARG='-no_symlink exim' install .cindex "installing Exim" "&'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 +distribution. Instead it is available separately from the FTP site (see section &<>&). If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo @@ -2301,7 +2408,7 @@ necessary. .section "Testing" "SECID34" .cindex "testing" "installation" -Having installed Exim, you can check that the run time configuration file is +Having installed Exim, you can check that the runtime configuration file is syntactically valid by running the following command, which assumes that the Exim binary directory is within your PATH environment variable: .code @@ -2375,7 +2482,7 @@ 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 +within the runtime configuration, all other file and directory names that Exim uses can be altered, in order to keep it entirely clear of the production version. @@ -2425,6 +2532,8 @@ use of Exim's filtering capabilities, you should make the document entitled 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 +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" 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 @@ -2523,6 +2632,7 @@ supplementary group is one of those listed in the &%trusted_groups%& configuration option. Note that the Exim group is not automatically trusted. .cindex '&"From"& line' +.cindex "envelope from" .cindex "envelope sender" 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 @@ -2532,6 +2642,8 @@ users to set envelope senders. .cindex "&'From:'& header line" .cindex "&'Sender:'& header line" +.cindex "header lines" "From:" +.cindex "header lines" "Sender:" 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. @@ -2607,6 +2719,18 @@ 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. +.vitem &%--version%& +.oindex "&%--version%&" +This option is an alias for &%-bV%& and causes version information to be +displayed. + +.vitem &%-Ac%& &&& + &%-Am%& +.oindex "&%-Ac%&" +.oindex "&%-Am%&" +These options are used by Sendmail for selecting configuration files and are +ignored by Exim. + .vitem &%-B%&<&'type'&> .oindex "&%-B%&" .cindex "8-bit characters" @@ -2648,7 +2772,12 @@ used to specify a path on the command line if a pid file is required. The SIGHUP signal .cindex "SIGHUP" +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" .cindex "daemon" "restarting" +.cindex signal "to reload configuration" +.cindex daemon "reload configuration" +.cindex reload configuration can be used to cause the daemon to re-execute itself. This should be done whenever Exim's configuration file, or any file that is incorporated into it by means of the &%.include%& facility, is changed, and also whenever a new version @@ -2677,11 +2806,11 @@ function, which provides extensive line-editing facilities, for reading the test data. A line history is supported. Long expansion expressions can be split over several lines by using backslash -continuations. As in Exim's run time configuration, white space at the start of +continuations. As in Exim's runtime configuration, white space at the start of continuation lines is ignored. Each argument or data line is passed through the string expansion mechanism, and the result is output. Variable values from the configuration file (for example, &$qualify_domain$&) are available, but no -message-specific values (such as &$sender_domain$&) are set, because no message +message-specific values (such as &$message_exim_id$&) are set, because no message is being processed (but see &%-bem%& and &%-Mset%&). &*Note*&: If you use this mechanism to test lookups, and you change the data @@ -2689,6 +2818,11 @@ files or databases you are using, you must exit and restart Exim before trying the same lookup again. Otherwise, because each Exim process caches the results of lookups, you will just get the same result as before. +Macro processing is done on lines before string-expansion: new macros can be +defined and macros will be expanded. +Because macros in the config file are often used for secrets, those are only +available to admin users. + .vitem &%-bem%&&~<&'filename'&> .oindex "&%-bem%&" .cindex "testing" "string expansion" @@ -2753,6 +2887,7 @@ separate document entitled &'Exim's interfaces to mail filtering'&. When testing a filter file, .cindex "&""From""& line" +.cindex "envelope from" .cindex "envelope sender" .oindex "&%-f%&" "for filter testing" the envelope sender can be set by the &%-f%& option, @@ -2778,12 +2913,14 @@ actually being delivered. .vitem &%-bfp%&&~<&'prefix'&> .oindex "&%-bfp%&" +.cindex affix "filter testing" This sets the prefix of the local part of the recipient address when a filter file is being tested by means of the &%-bf%& option. The default is an empty prefix. .vitem &%-bfs%&&~<&'suffix'&> .oindex "&%-bfs%&" +.cindex affix "filter testing" This sets the suffix of the local part of the recipient address when a filter file is being tested by means of the &%-bf%& option. The default is an empty suffix. @@ -2839,7 +2976,7 @@ acceptable or not. See section &<>&. Features such as authentication and encryption, where the client input is not plain text, cannot easily be tested with &%-bh%&. Instead, you should use a specialized SMTP test program such as -&url(http://jetmore.org/john/code/#swaks,swaks). +&url(https://www.jetmore.org/john/code/swaks/,swaks). .vitem &%-bhc%&&~<&'IP&~address'&> .oindex "&%-bhc%&" @@ -2866,11 +3003,37 @@ use the &'exim_dbmbuild'& utility, or some other means, to rebuild alias files if this is required. If the &%bi_command%& option is not set, calling Exim with &%-bi%& is a no-op. +. // Keep :help first, then the rest in alphabetical order +.vitem &%-bI:help%& +.oindex "&%-bI:help%&" +.cindex "querying exim information" +We shall provide various options starting &`-bI:`& for querying Exim for +information. The output of many of these will be intended for machine +consumption. This one is not. The &%-bI:help%& option asks Exim for a +synopsis of supported options beginning &`-bI:`&. Use of any of these +options shall cause Exim to exit after producing the requested output. + +.vitem &%-bI:dscp%& +.oindex "&%-bI:dscp%&" +.cindex "DSCP" "values" +This option causes Exim to emit an alphabetically sorted list of all +recognised DSCP names. + +.vitem &%-bI:sieve%& +.oindex "&%-bI:sieve%&" +.cindex "Sieve filter" "capabilities" +This option causes Exim to emit an alphabetically sorted list of all supported +Sieve protocol extensions on stdout, one per line. This is anticipated to be +useful for ManageSieve (RFC 5804) implementations, in providing that protocol's +&`SIEVE`& capability response line. As the precise list may depend upon +compile-time build options, which this option will adapt to, this is the only +way to guarantee a correct response. + .vitem &%-bm%& .oindex "&%-bm%&" .cindex "local message reception" This option runs an Exim receiving process that accepts an incoming, -locally-generated message on the current input. The recipients are given as the +locally-generated message on the standard input. The recipients are given as the command arguments (except when &%-t%& is also present &-- see below). Each argument can be a comma-separated list of RFC 2822 addresses. This is the default option for selecting the overall action of an Exim call; it is assumed @@ -2912,6 +3075,27 @@ The specified sender is treated as if it were given as the argument to the preference to the address taken from the message. The caller of Exim must be a trusted user for the sender of a message to be set in this way. +.vitem &%-bmalware%&&~<&'filename'&> +.oindex "&%-bmalware%&" +.cindex "testing", "malware" +.cindex "malware scan test" +This debugging option causes Exim to scan the given file or directory +(depending on the used scanner interface), +using the malware scanning framework. The option of &%av_scanner%& influences +this option, so if &%av_scanner%&'s value is dependent upon an expansion then +the expansion should have defaults which apply to this invocation. ACLs are +not invoked, so if &%av_scanner%& references an ACL variable then that variable +will never be populated and &%-bmalware%& will fail. + +Exim will have changed working directory before resolving the filename, so +using fully qualified pathnames is advisable. Exim will be running as the Exim +user when it tries to open the file, rather than as the invoking user. +This option requires admin privileges. + +The &%-bmalware%& option will not be extended to be more generally useful, +there are better tools for file-scanning. This option exists to help +administrators verify their Exim and AV scanner configuration. + .vitem &%-bnq%& .oindex "&%-bnq%&" .cindex "address qualification, suppressing" @@ -2954,11 +3138,19 @@ users, the output is as in this example: .code mysql_servers = .endd -If &%configure_file%& is given as an argument, the name of the run time -configuration file is output. +If &%config%& is given as an argument, the config is +output, as it was parsed, any include file resolved, any comment removed. + +If &%config_file%& is given as an argument, the name of the runtime +configuration file is output. (&%configure_file%& works too, for +backward compatibility.) If a list of configuration files was supplied, the value that is output here is the name of the file that was actually used. +.cindex "options" "hiding name of" +If the &%-n%& flag is given, then for most modes of &%-bP%& operation the +name will not be output. + .cindex "daemon" "process id (pid)" .cindex "pid (process id)" "of daemon" If &%log_file_path%& or &%pid_file_path%& are given, the names of the @@ -2976,6 +3168,7 @@ local part) and outputs what it finds. .cindex "options" "router &-- extracting" .cindex "options" "transport &-- extracting" +.cindex "options" "authenticator &-- extracting" If one of the words &%router%&, &%transport%&, or &%authenticator%& is given, followed by the name of an appropriate driver instance, the option settings for that driver are output. For example: @@ -2989,18 +3182,30 @@ using one of the words &%router_list%&, &%transport_list%&, or settings can be obtained by using &%routers%&, &%transports%&, or &%authenticators%&. +.cindex "environment" +If &%environment%& is given as an argument, the set of environment +variables is output, line by line. Using the &%-n%& flag suppresses the value of the +variables. + +.cindex "options" "macro &-- extracting" +If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& +are available, similarly to the drivers. Because macros are sometimes used +for storing passwords, this option is restricted. +The output format is one item per line. +For the "-bP macro " form, if no such macro is found +the exit status will be nonzero. .vitem &%-bp%& .oindex "&%-bp%&" -.cindex "queue" "listing messages on" -.cindex "listing" "messages on the queue" +.cindex "queue" "listing messages in" +.cindex "listing" "messages in the queue" This option requests a listing of the contents of the mail queue on the standard output. If the &%-bp%& option is followed by a list of message ids, just those messages are listed. By default, this option can be used only by an admin user. However, the &%queue_list_requires_admin%& option can be set false to allow any user to see the queue. -Each message on the queue is displayed as in the following example: +Each message in the queue is displayed as in the following example: .code 25m 2.9K 0t5C6f-0000c8-00 red.king@looking-glass.fict.example @@ -3008,7 +3213,7 @@ Each message on the queue is displayed as in the following example: .endd .cindex "message" "size in queue listing" .cindex "size" "of message" -The first line contains the length of time the message has been on the queue +The first line contains the length of time the message has been in the queue (in this case 25 minutes), the size of the message (2.9K), the unique local identifier for the message, and the message sender, as contained in the envelope. For bounce messages, the sender address is empty, and appears as @@ -3039,7 +3244,7 @@ of just &"D"&. .vitem &%-bpc%& .oindex "&%-bpc%&" .cindex "queue" "count of messages on" -This option counts the number of messages on the queue, and writes the total +This option counts the number of messages in the queue, and writes the total to the standard output. It is restricted to admin users, unless &%queue_list_requires_admin%& is set false. @@ -3048,7 +3253,7 @@ to the standard output. It is restricted to admin users, unless .oindex "&%-bpr%&" This option operates like &%-bp%&, but the output is not sorted into chronological order of message arrival. This can speed it up when there are -lots of messages on the queue, and is particularly useful if the output is +lots of messages in the queue, and is particularly useful if the output is going to be post-processed in a way that doesn't need the sorting. .vitem &%-bpra%& @@ -3217,9 +3422,9 @@ doing such tests. .cindex "version number of Exim" This option causes Exim to write the current version number, compilation number, and compilation date of the &'exim'& binary to the standard output. -It also lists the DBM library this is being used, the optional modules (such as +It also lists the DBM library that is being used, the optional modules (such as specific lookup types), the drivers that are included in the binary, and the -name of the run time configuration file that is in use. +name of the runtime configuration file that is in use. As part of its operation, &%-bV%& causes Exim to read and syntax check its configuration file. However, this is a static check only. It cannot check @@ -3286,45 +3491,60 @@ This option acts like &%-bv%&, but verifies the address as a sender rather than a recipient address. This affects any rewriting and qualification that might happen. +.vitem &%-bw%& +.oindex "&%-bw%&" +.cindex "daemon" +.cindex "inetd" +.cindex "inetd" "wait mode" +This option runs Exim as a daemon, awaiting incoming SMTP connections, +similarly to the &%-bd%& option. All port specifications on the command-line +and in the configuration file are ignored. Queue-running may not be specified. + +In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is +listening for connections. This permits the system to start up and have +inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for +each port only when the first connection is received. + +If the option is given as &%-bw%&<&'time'&> then the time is a timeout, after +which the daemon will exit, which should cause inetd to listen once more. + .vitem &%-C%&&~<&'filelist'&> .oindex "&%-C%&" .cindex "configuration file" "alternate" .cindex "CONFIGURE_FILE" .cindex "alternate configuration file" -This option causes Exim to find the run time configuration file from the given +This option causes Exim to find the runtime configuration file from the given list instead of from the list specified by the CONFIGURE_FILE -compile-time setting. Usually, the list will consist of just a single file -name, but it can be a colon-separated list of names. In this case, the first +compile-time setting. Usually, the list will consist of just a single filename, +but it can be a colon-separated list of names. In this case, the first file that exists is used. Failure to open an existing file stops Exim from proceeding any further along the list, and an error is generated. -When this option is used by a caller other than root or the Exim user, and the -list is different from the compiled-in list, Exim gives up its root privilege -immediately, and runs with the real and effective uid and gid set to those of -the caller. However, if ALT_CONFIG_ROOT_ONLY is defined in -&_Local/Makefile_&, root privilege is retained for &%-C%& only if the caller of -Exim is root. - -That is, the Exim user is no longer privileged in this regard. This build-time -option is not set by default in the Exim source distribution tarbundle. -However, if you are using a &"packaged"& version of Exim (source or binary), -the packagers might have enabled it. - -Setting ALT_CONFIG_ROOT_ONLY locks out the possibility of testing a -configuration using &%-C%& right through message reception and delivery, even -if the caller is root. The reception works, but by that time, Exim is running -as the Exim user, so when it re-executes to regain privilege for the delivery, -the use of &%-C%& causes privilege to be lost. However, root can test reception -and delivery using two separate commands (one to put a message on the queue, -using &%-odq%&, and another to do the delivery, using &%-M%&). +When this option is used by a caller other than root, and the list is different +from the compiled-in list, Exim gives up its root privilege immediately, and +runs with the real and effective uid and gid set to those of the caller. +However, if a TRUSTED_CONFIG_LIST file is defined in &_Local/Makefile_&, that +file contains a list of full pathnames, one per line, for configuration files +which are trusted. Root privilege is retained for any configuration file so +listed, as long as the caller is the Exim user (or the user specified in the +CONFIGURE_OWNER option, if any), and as long as the configuration file is +not writeable by inappropriate users or groups. + +Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a +configuration using &%-C%& right through message reception and delivery, +even if the caller is root. The reception works, but by that time, Exim is +running as the Exim user, so when it re-executes to regain privilege for the +delivery, the use of &%-C%& causes privilege to be lost. However, root can +test reception and delivery using two separate commands (one to put a message +in the queue, using &%-odq%&, and another to do the delivery, using &%-M%&). If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a prefix string with which any file named in a &%-C%& command line option -must start. In addition, the file name must not contain the sequence &`/../`&. +must start. In addition, the filename must not contain the sequence &`/../`&. However, if the value of the &%-C%& option is identical to the value of CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as usual. There is no default setting for ALT_CONFIG_PREFIX; when it is -unset, any file name can be used with &%-C%&. +unset, any filename can be used with &%-C%&. ALT_CONFIG_PREFIX can be used to confine alternative configuration files to a directory to which only root has access. This prevents someone who has @@ -3337,6 +3557,7 @@ caller is privileged, or unless it is an exotic configuration that does not require privilege. No check is made on the owner or group of the files specified by this option. + .vitem &%-D%&<&'macro'&>=<&'value'&> .oindex "&%-D%&" .cindex "macro" "setting on command line" @@ -3346,6 +3567,14 @@ unprivileged caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is completely disabled, and its use causes an immediate error exit. +If WHITELIST_D_MACROS is defined in &_Local/Makefile_& then it should be a +colon-separated list of macros which are considered safe and, if &%-D%& only +supplies macros from this list, and the values are acceptable, then Exim will +not give up root privilege if the caller is root, the Exim run-time user, or +the CONFIGURE_OWNER, if set. This is a transition mechanism and is expected +to be removed in the future. Acceptable values for the macros satisfy the +regexp: &`^[A-Za-z0-9_/.-]*$`& + The entire option (including equals sign if present) must all be within one command line item. &%-D%& can be used to set the value of a macro to the empty string, in which case the equals sign is optional. These two commands are @@ -3361,6 +3590,8 @@ example: exim '-D ABC = something' ... .endd &%-D%& may be repeated up to 10 times on a command line. +Only macro names up to 22 letters long can be set. + .vitem &%-d%&<&'debug&~options'&> .oindex "&%-d%&" @@ -3400,7 +3631,8 @@ are: &<>&) &`lookup `& general lookup code and all lookups &`memory `& memory handling -&`pid `& add pid to debug output lines +&`noutf8 `& modifier: avoid UTF-8 line-drawing +&`pid `& modifier: add pid to debug output lines &`process_info `& setting info for the process log &`queue_run `& queue runs &`receive `& general message reception logic @@ -3408,7 +3640,7 @@ are: &`retry `& retry handling &`rewrite `& address rewriting &`route `& address routing -&`timestamp `& add timestamp to debug output lines +&`timestamp `& modifier: add timestamp to debug output lines &`tls `& TLS logic &`transport `& transports &`uid `& changes of uid/gid and looking up uid/gid @@ -3440,6 +3672,13 @@ The &`timestamp`& selector causes the current time to be inserted at the start of all debug output lines. This can be useful when trying to track down delays in processing. +.cindex debugging "UTF-8 in" +.cindex UTF-8 "in debug output" +The &`noutf8`& selector disables the use of +UTF-8 line-drawing characters to group related information. +When disabled. ascii-art is used instead. +Using the &`+all`& option does not set this modifier, + If the &%debug_print%& option is set in any driver, it produces output whenever any debugging is selected, or if &%-v%& is used. @@ -3489,6 +3728,7 @@ between &%-F%& and the <&'string'&> is optional. .cindex "sender" "address" .cindex "address" "sender" .cindex "trusted users" +.cindex "envelope from" .cindex "envelope sender" .cindex "user" "trusted" This option sets the address of the envelope sender of a locally-generated @@ -3530,8 +3770,17 @@ if &%-f%& is also present, it overrides &"From&~"&. .vitem &%-G%& .oindex "&%-G%&" -.cindex "Sendmail compatibility" "&%-G%& option ignored" -This is a Sendmail option which is ignored by Exim. +.cindex "submission fixups, suppressing (command-line)" +This option is equivalent to an ACL applying: +.code +control = suppress_local_fixups +.endd +for every message received. Note that Sendmail will complain about such +bad formatting, where Exim silently just does not fix it up. This may change +in future. + +As this affects audit information, the caller must be a trusted user to use +this option. .vitem &%-h%&&~<&'number'&> .oindex "&%-h%&" @@ -3549,6 +3798,17 @@ line by itself should not terminate an incoming, non-SMTP message. I can find no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'& command in Solaris 2.4 uses it. See also &%-ti%&. +.vitem &%-L%&&~<&'tag'&> +.oindex "&%-L%&" +.cindex "syslog" "process name; set with flag" +This option is equivalent to setting &%syslog_processname%& in the config +file and setting &%log_file_path%& to &`syslog`&. +Its use is restricted to administrators. The configuration file has to be +read and parsed, to determine access rights, before this is set and takes +effect, so early configuration file errors will not honour this flag. + +The tag should not be longer than 32 characters. + .vitem &%-M%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-M%&" .cindex "forcing delivery" @@ -3600,6 +3860,24 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option. It signifies that the connection to the remote host has been authenticated. +.vitem &%-MCD%& +.oindex "&%-MCD%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that the +remote host supports the ESMTP &_DSN_& extension. + +.vitem &%-MCG%&&~<&'queue&~name'&> +.oindex "&%-MCG%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that an +alternate queue is used, named by the following argument. + +.vitem &%-MCK%& +.oindex "&%-MCK%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that a +remote host supports the ESMTP &_CHUNKING_& extension. + .vitem &%-MCP%& .oindex "&%-MCP%&" This option is not intended for use by external callers. It is used internally @@ -3628,11 +3906,18 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option, and passes on the fact that the host to which Exim is connected supports TLS encryption. +.vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>&~<&'cipher'&> +.oindex "&%-MCt%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option, and passes on the fact that the +connection is being proxied by a parent process for handling TLS encryption. +The arguments give the local address and port being proxied, and the TLS cipher. + .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-Mc%&" .cindex "hints database" "not overridden by &%-Mc%&" .cindex "delivery" "manually started &-- not forced" -This option requests Exim to run a delivery attempt on each message in turn, +This option requests Exim to run a delivery attempt on each message, in turn, but unlike the &%-M%& option, it does check for retry hints, and respects any that are found. This option is not very useful to external callers. It is provided mainly for internal use by Exim when it needs to re-invoke itself in @@ -3678,6 +3963,18 @@ is sent to the sender, containing the text &"cancelled by administrator"&. Bounce messages are just discarded. This option can be used only by an admin user. +.vitem &%-MG%&&~<&'queue&~name'&>&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-MG%&" +.cindex queue named +.cindex "named queues" +.cindex "queue" "moving messages" +This option requests that each listed message be moved from its current +queue to the given named queue. +The destination queue name argument is required, but can be an empty +string to define the default queue. +If the messages are not currently located in the default queue, +a &%-qG%& option will be required to define the source queue. + .vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-Mmad%&" .cindex "delivery" "cancelling all" @@ -3707,10 +4004,19 @@ This option requests Exim to remove the given messages from the queue. No bounce messages are sent; each message is simply forgotten. However, if any of the messages are active, their status is not altered. This option can be used only by an admin user or by the user who originally caused the message to be -placed on the queue. +placed in the queue. + +. .new +. .vitem &%-MS%& +. .oindex "&%-MS%&" +. .cindex REQUIRETLS +. This option is used to request REQUIRETLS processing on the message. +. It is used internally by Exim in conjunction with -E when generating +. a bounce message. +. .wen .vitem &%-Mset%&&~<&'message&~id'&> -.oindex "&%-Mset%& +.oindex "&%-Mset%&" .cindex "testing" "string expansion" .cindex "expansion" "testing" This option is useful only in conjunction with &%-be%& (that is, when testing @@ -3742,7 +4048,7 @@ written to the standard output. This option can be used only by an admin user. .vitem &%-Mvc%&&~<&'message&~id'&> .oindex "&%-Mvc%&" .cindex "message" "listing in RFC 2822 format" -.cindex "listing" "message in RFC 2922 format" +.cindex "listing" "message in RFC 2822 format" This option causes a copy of the complete message (header lines plus body) to be written to the standard output in RFC 2822 format. This option can be used only by an admin user. @@ -3789,9 +4095,10 @@ for that message. .vitem &%-n%& .oindex "&%-n%&" -.cindex "Sendmail compatibility" "&%-n%& option ignored" -This option is interpreted by Sendmail to mean &"no aliasing"&. It is ignored -by Exim. +This option is interpreted by Sendmail to mean &"no aliasing"&. +For normal modes of operation, it is ignored by Exim. +When combined with &%-bP%& it makes the output more terse (suppresses +option names, environment values and config pretty printing). .vitem &%-O%&&~<&'data'&> .oindex "&%-O%&" @@ -3802,7 +4109,7 @@ Exim. .oindex "&%-oA%&" .cindex "Sendmail compatibility" "&%-oA%& option" This option is used by Sendmail in conjunction with &%-bi%& to specify an -alternative alias file name. Exim handles &%-bi%& differently; see the +alternative alias filename. Exim handles &%-bi%& differently; see the description above. .vitem &%-oB%&&~<&'n'&> @@ -3851,7 +4158,7 @@ However, like &%-odb%&, this option has no effect if &%queue_only_override%& is false and one of the queueing options in the configuration file is in effect. If there is a temporary delivery error during foreground delivery, the -message is left on the queue for later delivery, and the original reception +message is left in the queue for later delivery, and the original reception process exits. See chapter &<>& for a way of setting up a restricted configuration that never queues messages. @@ -3869,7 +4176,7 @@ Sendmail. This option applies to all modes in which Exim accepts incoming messages, including the listening daemon. It specifies that the accepting process should not automatically start a delivery process for each message received. Messages -are placed on the queue, and remain there until a subsequent queue runner +are placed in the queue, and remain there until a subsequent queue runner process encounters them. There are several configuration options (such as &%queue_only%&) that can be used to queue incoming messages under certain conditions. This option overrides all of them and also &%-odqs%&. It always @@ -3887,7 +4194,7 @@ When &%-odqs%& does operate, a delivery process is started for each incoming message, in the background by default, but in the foreground if &%-odi%& is also present. The recipient addresses are routed, and local deliveries are done in the normal way. However, if any SMTP deliveries are required, they are not -done at this time, so the message remains on the queue until a subsequent queue +done at this time, so the message remains in the queue until a subsequent queue runner process encounters it. Because routing was done, Exim knows which messages are waiting for which hosts, and so a number of messages for the same host can be sent in a single SMTP connection. The &%queue_smtp_domains%& @@ -3905,8 +4212,8 @@ message. Provided this error message is successfully sent, the Exim receiving process exits with a return code of zero. If not, the return code is 2 if the problem -is that the original message has no recipients, or 1 any other error. This is -the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. +is that the original message has no recipients, or 1 for any other error. +This is the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. .vitem &%-oem%& .oindex "&%-oem%&" @@ -4010,6 +4317,20 @@ option sets the IP interface address value. A port number may be included, using the same syntax as for &%-oMa%&. The interface address is placed in &$received_ip_address$& and the port number, if present, in &$received_port$&. +.vitem &%-oMm%&&~<&'message&~reference'&> +.oindex "&%-oMm%&" +.cindex "message reference" "message reference, specifying for local message" +See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMm%& +option sets the message reference, e.g. message-id, and is logged during +delivery. This is useful when some kind of audit trail is required to tie +messages together. The format of the message reference is checked and will +abort if the format is invalid. The option will only be accepted if exim is +running in trusted mode, not as any regular user. + +The best example of a message reference is when Exim sends a bounce message. +The message reference is the message-id of the original message for which Exim +is sending the bounce. + .vitem &%-oMr%&&~<&'protocol&~name'&> .oindex "&%-oMr%&" .cindex "protocol, specifying for local message" @@ -4021,7 +4342,7 @@ or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard SMTP protocol names (see the description of &$received_protocol$& in section &<>&). For &%-bs%&, the protocol is always &"local-"& followed by one of those same names. For &%-bS%& (batched SMTP) however, the protocol can -be set by &%-oMr%&. +be set by &%-oMr%&. Repeated use of this option is not supported. .vitem &%-oMs%&&~<&'host&~name'&> .oindex "&%-oMs%&" @@ -4062,6 +4383,17 @@ written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used without &%-bd%&, this is the only way of causing Exim to write a pid file, because in those cases, the normal pid file is not used. +.new +.vitem &%-oPX%& +.oindex "&%-oPX%&" +.cindex "pid (process id)" "of daemon" +.cindex "daemon" "process id (pid)" +This option is not intended for general use. +The daemon uses it when terminating due to a SIGTEM, possibly in +combination with &%-oP%&&~<&'path'&>. +It causes the pid file to be removed. +.wen + .vitem &%-or%&&~<&'time'&> .oindex "&%-or%&" .cindex "timeout" "for non-SMTP input" @@ -4092,7 +4424,7 @@ This option is relevant only when the &%-bd%& (start listening daemon) option is also given. It controls which ports and interfaces the daemon uses. Details of the syntax, and how it interacts with configuration file options, are given in chapter &<>&. When &%-oX%& is used to start a daemon, no pid -file is written unless &%-oP%& is also present to specify a pid file name. +file is written unless &%-oP%& is also present to specify a pid filename. .vitem &%-pd%& .oindex "&%-pd%&" @@ -4119,8 +4451,9 @@ For compatibility with Sendmail, this option is equivalent to It sets the incoming protocol and host name (for trusted callers). The host name and its colon can be omitted when only the protocol is to be set. Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer -to embedded Perl. It is therefore impossible to set a protocol value of &`p`& +to embedded Perl. It is therefore impossible to set a protocol value of &`d`& or &`s`& using this option (but that does not seem a real limitation). +Repeated use of this option is not supported. .vitem &%-q%& .oindex "&%-q%&" @@ -4131,7 +4464,8 @@ relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, and &%-S%& options). .cindex "queue runner" "description of operation" -The &%-q%& option starts one queue runner process. This scans the queue of +If other commandline options do not specify an action, +the &%-q%& option starts one queue runner process. This scans the queue of waiting messages, and runs a delivery process for each one in turn. It waits for each delivery process to finish before starting the next one. A delivery process may not actually do any deliveries if the retry times for the addresses @@ -4192,7 +4526,7 @@ intermittently. .cindex "queue" "initial delivery" If the &'i'& flag is present, the queue runner runs delivery processes only for those messages that haven't previously been tried. (&'i'& stands for &"initial -delivery"&.) This can be helpful if you are putting messages on the queue using +delivery"&.) This can be helpful if you are putting messages in the queue using &%-odq%& and want a queue runner just to process the new messages. .vitem &%-q[q][i]f...%& @@ -4213,11 +4547,30 @@ frozen or not. .oindex "&%-ql%&" .cindex "queue" "local deliveries only" The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to -be done. If a message requires any remote deliveries, it remains on the queue +be done. If a message requires any remote deliveries, it remains in the queue for later delivery. -.vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&> +.vitem &%-q[q][i][f[f]][l][G[/