X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/ee8b809061baea861fc87c41bcb72a62d76b0047..f078f86ef3e6d0119845cdf8603b8174770cacc7:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 4e99e6c0d..84597da83 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,6 +1,6 @@ . ///////////////////////////////////////////////////////////////////////////// . 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. . @@ -35,7 +35,7 @@ .literal off . ///////////////////////////////////////////////////////////////////////////// -. This generate the outermost element that wraps then entire document. +. This generates the outermost element that wraps the entire document. . ///////////////////////////////////////////////////////////////////////////// .book @@ -45,14 +45,16 @@ . Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.91" +.set previousversion "4.98" .include ./local_params .set ACL "access control lists (ACLs)" .set I "    " +.set drivernamemax "64" + .macro copyyear -2018 +2024 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -60,12 +62,12 @@ . 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 &!? "‡" @@ -74,6 +76,16 @@ . --- table with four columns. For cases when the option name is given with . --- a space, so that it can be split, a fifth argument is used for the . --- index entry. +. --- Also one for multiple option def headings be grouped in a single +. --- table (but without the split capability). + +.macro otable +.itable all 0 0 4 8* left 6* center 6* center 6* right +.endmacro + +.macro orow +.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" +.endmacro .macro option .arg 5 @@ -82,19 +94,58 @@ .arg -5 .oindex "&%$1%&" .endarg -.itable all 0 0 4 8* left 6* center 6* center 6* right -.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" +.otable +.orow "$1" "$2" "$3" "$4" +.endtable +.endmacro + +.macro options +.eacharg +.oindex "&%$+1%&" +.endeach 4 +.otable +.eacharg +.orow "$+1" "$+2" "$+3" "$+4" +.endeach 4 .endtable .endmacro . --- 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 .endmacro + +. --- A macro for a plain variable, including the .vitem and .vindex +.macro var +.vitem $1 +.vindex $1 +.endmacro + +. --- A macro for a "tainted" marker, done as a one-element table +.macro tmark +.itable none 0 0 1 10pt left +.row &'Tainted'& +.endtable +.endmacro + +. --- A macro for a tainted variable, adding a taint-marker +.macro tvar +.var $1 +.tmark +.endmacro + +. --- A macro for a cmdline option, including a .oindex +. --- 1st arg is the option name, undecorated (we do that here). +. --- 2nd arg, optional, text (decorated as needed) to be appended to the name +.macro cmdopt +.vitem &%$1%&$=2+&~$2+ +.oindex &%$1%& +.endmacro + . --- A macro that generates .row, but puts &I; at the start of the first . --- argument, thus indenting it. Assume a minimum of two arguments, and . --- allow up to four arguments, which is as many as we'll ever need. @@ -117,6 +168,8 @@ . --- style of entry, use .scindex for the start and .ecindex for the end. The . --- first argument of .scindex and the only argument of .ecindex must be the . --- ID that ties them together. +. --- The index entry points to the most-recent chapter head, section or subsection +. --- head, or list-item. .macro cindex && @@ -149,6 +202,9 @@ && .endmacro +. --- The index entry points to the most-recent chapter head, section or subsection +. --- head, or varlist item. + .macro vindex && &&$1&& @@ -161,11 +217,18 @@ .macro index .echo "** Don't use .index; use .cindex or .oindex or .vindex" .endmacro + + +. use this for a concept-index entry for a header line +.macro chindex +.cindex "&'$1'& header line" +.cindex "header lines" $1 +.endmacro . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// -. The element is removed from the XML before processing for Ascii +. The element is removed from the XML before processing for ASCII . output formats. . //////////////////////////////////////////////////////////////////////////// @@ -184,142 +247,69 @@ .copyyear - University of Cambridge + The Exim Maintainers .literal off . ///////////////////////////////////////////////////////////////////////////// -. This chunk of literal XML implements index entries of the form "x, see y" and -. "x, see also y". However, the DocBook DTD doesn't allow entries +. These implement index entries of the form "x, see y" and "x, see also y". +. However, the DocBook DTD doesn't allow entries . at the top level, so we have to put the .chapter directive first. . ///////////////////////////////////////////////////////////////////////////// .chapter "Introduction" "CHID1" -.literal xml - - $1, $2, etc. - numerical variables - - - address - rewriting - rewriting - - - Bounce Address Tag Validation - BATV - - - Client SMTP Authorization - CSA - - - CR character - carriage return - - - CRL - certificate revocation list - - - delivery - failure report - bounce message - - - dialup - intermittently connected hosts - - - exiscan - content scanning - - - failover - fallback - - - fallover - fallback - - - filter - Sieve - Sieve filter - - - ident - RFC 1413 - - - LF character - linefeed - - - maximum - limit - - - monitor - Exim monitor - - - no_xxx - entry for xxx - - - NUL - binary zero - - - passwd file - /etc/passwd - - - process id - pid - - - RBL - DNS list - - - redirection - address redirection - - - return path - envelope sender - - - scanning - content scanning - - - SSL - TLS - - - string - expansion - expansion - - - top bit - 8-bit characters - - - variables - expansion, variables - - - zero, binary - binary zero +.macro seeother +.literal xml + + $3 +.arg 5 + $5 +.endarg + <$1>$4 - .literal off +.endmacro + +. NB: for the 4-arg variant the ordering is awkward +.macro see +.seeother see "$1" "$2" "$3" "$4" +.endmacro +.macro seealso +.seeother seealso "$1" "$2" "$3" "$4" +.endmacro + +.see variable "$1, $2, etc." "numerical variables" +.see concept address rewriting rewriting +.see concept "Bounce Address Tag Validation" BATV +.see concept "Client SMTP Authorization" CSA +.see concept "CR character" "carriage return" +.see concept CRL "certificate revocation list" +.seealso concept de-tainting "tainted data" +.see concept delivery "bounce message" "failure report" +.see concept dialup "intermittently connected hosts" +.see concept exiscan "content scanning" +.see concept fallover fallback +.see concept filter "Sieve filter" Sieve +.see concept headers "header lines" +.see concept ident "RFC 1413" +.see concept "LF character" "linefeed" +.seealso concept maximum limit +.see concept monitor "Exim monitor" +.see concept "no_xxx" "entry for xxx" +.see concept NUL "binary zero" +.see concept "passwd file" "/etc/passwd" +.see concept "process id" pid +.see concept RBL "DNS list" +.see concept redirection "address redirection" +.see concept "return path" "envelope sender" +.see concept scanning "content scanning" +.see concept SSL TLS +.see concept string expansion expansion +.see concept "top bit" "8-bit characters" +.see concept variables "expansion, variables" +.see concept "zero, binary" "binary zero" . ///////////////////////////////////////////////////////////////////////////// @@ -337,7 +327,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. @@ -349,8 +339,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. @@ -375,7 +365,7 @@ contributors. .cindex "documentation" 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 @@ -384,7 +374,7 @@ 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. @@ -394,7 +384,7 @@ introductory, and tutorial material can be found in a book entitled &'The Exim SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge (&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.) @@ -409,7 +399,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 @@ -420,7 +410,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_&" @@ -445,8 +435,8 @@ 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 the &%exim.org%& FTP site, available over HTTPS, HTTP and FTP. These services, and the &%exim.org%& @@ -454,7 +444,7 @@ 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(https://wiki.exim.org)), which contains what used to be a separate FAQ, as well as various other @@ -474,10 +464,11 @@ Please do not ask for configuration help in the bug-tracker. 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-cvs@exim.org'& "Automated commit messages from the VCS" +.row &'exim-announce@lists.exim.org'& "Moderated, low volume announcements list" +.row &'exim-users@lists.exim.org'& "General discussion list" +.row &'exim-users-de@lists.exim.org'& "General discussion list in German language" +.row &'exim-dev@lists.exim.org'& "Discussion of bugs, enhancements, etc." +.row &'exim-cvs@lists.exim.org'& "Automated commit messages from the VCS" .endtable You can subscribe to these lists, change your existing subscriptions, and view @@ -489,7 +480,7 @@ via this web page: .display &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 "Bug reports" "SECID5" @@ -505,7 +496,7 @@ message to the &'exim-dev'& mailing list and have it discussed. .section "Where to find the Exim distribution" "SECTavail" .cindex "FTP site" .cindex "HTTPS download site" -.cindex "distribution" "ftp site" +.cindex "distribution" "FTP site" .cindex "distribution" "https site" The master distribution site for the Exim distribution is .display @@ -547,12 +538,12 @@ 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 Nigel Metheringham's -PGP key, a version of which can be found in the release directory in the file -&_nigel-pubkey.asc_&. All keys used will be available in public keyserver pools, +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 time of last update, releases were being made by Jeremy Harris and signed +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'&. @@ -563,7 +554,7 @@ The signatures for the tar bundles are in: &_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. @@ -621,8 +612,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 @@ -636,13 +627,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. @@ -653,7 +644,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" @@ -698,7 +689,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'&. @@ -714,20 +705,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. @@ -743,17 +734,17 @@ the Exim documentation, &"spool"& is always used in the first sense. .chapter "Incorporated code" "CHID2" .cindex "incorporated code" .cindex "regular expressions" "library" -.cindex "PCRE" +.cindex "PCRE2" .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 PCRE is no longer shipped with -Exim, so you will need to use the version of PCRE shipped with your system, +Exim monitor using the freely-distributable PCRE2 library, copyright +© University of Cambridge. The source to PCRE2 is not longer shipped with +Exim, so you will need to use the version of PCRE2 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). +&url(https://github.com/PhilipHazel/pcre2/releases). .next .cindex "cdb" "acknowledgment" Support for the cdb (Constant DataBase) lookup method is provided by code @@ -879,7 +870,7 @@ 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 @@ -907,9 +898,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 @@ -979,13 +970,14 @@ User filters are run as part of the routing process, described below. .cindex "base36" .cindex "Darwin" .cindex "Cygwin" -Every message handled by Exim is given a &'message id'& which is sixteen +.cindex "exim_msgdate" +Every message handled by Exim is given a &'message id'& which is 23 characters long. It is divided into three parts, separated by hyphens, for -example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, +example &`16VDhn-000000001bo-D342`&. 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" @@ -1002,20 +994,24 @@ started to be received, to a granularity of one second. That is, this field contains the number of seconds since the start of the epoch (the normal Unix way of representing the date and time of day). .next -After the first hyphen, the next six characters are the id of the process that -received the message. +After the first hyphen, the next +eleven +characters are the id of the process that received the message. .next -There are two different possibilities for the final two characters: +There are two different possibilities for the final four characters: .olist .oindex "&%localhost_number%&" If &%localhost_number%& is not set, this value is the fractional part of the -time of reception, normally in units of 1/2000 of a second, but for systems +time of reception, normally in units of +microseconds. +but for systems that must use base 36 instead of base 62 (because of case-insensitive file -systems), the units are 1/1000 of a second. +systems), the units are +2 us. .next -If &%localhost_number%& is set, it is multiplied by 200 (100) and added to -the fractional part of the time, which in this case is in units of 1/200 -(1/100) of a second. +If &%localhost_number%& is set, it is multiplied by +500000 (250000) and added to +the fractional part of the time, which in this case is in units of 2 us (4 us). .endlist .endlist @@ -1025,6 +1021,10 @@ received by the same process, or by another process with the same (re-used) pid, it is guaranteed that the time will be different. In most cases, the clock will already have ticked while the message was being received. +The exim_msgdate utility (see section &<>&) can be +used to display the date, and optionally the process id, of an Exim +Message ID. + .section "Receiving mail" "SECID13" .cindex "receiving mail" @@ -1042,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 @@ -1066,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 @@ -1074,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. @@ -1102,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 @@ -1139,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. @@ -1154,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" @@ -1162,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 @@ -1179,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 @@ -1194,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 @@ -1233,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 @@ -1271,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. @@ -1291,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, @@ -1307,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). @@ -1349,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. @@ -1363,7 +1363,7 @@ The preconditions that are tested for each router are listed below, in the order in which they are tested. The individual configuration options are described in more detail in chapter &<>&. -.ilist +.olist .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 @@ -1394,21 +1394,47 @@ 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). + .next If the &%domains%& option is set, the domain of the address must be in the set of domains that it defines. +.cindex "tainted data" "de-tainting" +.cindex "de-tainting" "using router domains option" +A match verifies the variable &$domain$& (which carries tainted data) +and assigns an untainted value to the &$domain_data$& variable. +Such an untainted value is often needed in the transport. +For specifics of the matching operation and the resulting untainted value, +refer to section &<>&. + +When an untainted value is wanted, use this option +rather than the generic &%condition%& option. + .next .vindex "&$local_part_prefix$&" +.vindex "&$local_part_prefix_v$&" .vindex "&$local_part$&" .vindex "&$local_part_suffix$&" +.vindex "&$local_part_suffix_v$&" .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 +the set of local parts that it defines. +A match verifies the variable &$local_part$& (which carries tainted data) +and assigns an untainted value to the &$local_part_data$& variable. +Such an untainted value is often needed in the transport. +For specifics of the matching operation and the resulting untainted value, +refer to section &<>&. + +When an untainted value is wanted, use this option +rather than the generic &%condition%& option. + +If &%local_part_prefix%& or &%local_part_suffix%& is in use, the prefix or suffix is removed from the local part before this check. If you want to do precondition tests on local parts that include affixes, you can do so by using a &%condition%& option (see below) -that uses the variables &$local_part$&, &$local_part_prefix$&, and -&$local_part_suffix$& as necessary. +that uses the variables &$local_part$&, &$local_part_prefix$&, +&$local_part_prefix_v$&, &$local_part_suffix$& +and &$local_part_suffix_v$& as necessary. + .next .vindex "&$local_user_uid$&" .vindex "&$local_user_gid$&" @@ -1418,23 +1444,35 @@ an account on the local host. If this check succeeds, the uid and gid of the local user are placed in &$local_user_uid$& and &$local_user_gid$& and the user's home directory is placed in &$home$&; these values can be used in the remaining preconditions. + .next If the &%router_home_directory%& option is set, it is expanded at this point, because it overrides the value of &$home$&. If this expansion were left till later, the value of &$home$& as set by &%check_local_user%& would be used in subsequent tests. Having two different values of &$home$& in the same router could lead to confusion. + .next If the &%senders%& option is set, the envelope sender address must be in the set of addresses that it defines. + .next If the &%require_files%& option is set, the existence or non-existence of specified files is tested. + .next .cindex "customizing" "precondition" If the &%condition%& option is set, it is evaluated and tested. This option uses an expanded string to allow you to set up your own custom preconditions. Expanded strings are described in chapter &<>&. + +Note that while using +this option for address matching technically works, +it does not set any de-tainted values. +Such values are often needed, either for router-specific options or +for transport options. +Using the &%domains%& and &%local_parts%& options is usually the most +convenient way to obtain them. .endlist @@ -1452,7 +1490,7 @@ example, &_.procmailrc_&). .cindex "delivery" "in detail" When a message is to be delivered, the sequence of events is as follows: -.ilist +.olist If a system-wide filter file is specified, the message is passed to it. The filter may add recipients to the message, replace the recipients, discard the message, cause a new message to be generated, or cause the message delivery to @@ -1470,7 +1508,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 @@ -1547,9 +1585,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. @@ -1563,7 +1601,7 @@ as permanent. -.section "Temporary delivery failure" "SECID20" +.subsection "Temporary delivery failure" SECID20 .cindex "delivery" "temporary failure" There are many reasons why a message may not be immediately deliverable to a particular address. Failure to connect to a remote machine (because it, or the @@ -1587,7 +1625,7 @@ one connection. -.section "Permanent delivery failure" "SECID21" +.subsection "Permanent delivery failure" SECID21 .cindex "delivery" "permanent failure" .cindex "bounce message" "when generated" When a message cannot be delivered to some or all of its intended recipients, a @@ -1615,10 +1653,10 @@ of the list. -.section "Failures to deliver bounce messages" "SECID22" +.subsection "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 @@ -1663,7 +1701,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. @@ -1685,20 +1723,20 @@ overridden if necessary. A C99-capable compiler will be required for the build. -.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 -system. If your system has a normal PCRE installation the Exim build +.section "PCRE2 library" "SECTpcre" +.cindex "PCRE2 library" +Exim no longer has an embedded regular-expression library as the vast majority of +modern systems include PCRE2 as a system library, although you may need to +install the PCRE2 package or the PCRE2 development package for your operating +system. If your system has a normal PCRE2 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 either set the PCRE_LIBS +headers are in an unusual location you will need to either set the PCRE2_LIBS and INCLUDE directives appropriately, -or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command. +or set PCRE2_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/). +PCRE2 support then you will need to obtain and build the current PCRE2 +from &url(https://github.com/PhilipHazel/pcre2/releases). +More information on PCRE2 is available at &url(https://www.pcre.org/). .section "DBM libraries" "SECTdb" .cindex "DBM libraries" "discussion of" @@ -1726,6 +1764,12 @@ distributors have chosen to bundle different libraries with their packaged versions. However, the more recent releases seem to have standardized on the Berkeley DB library. +.new +Ownership of the Berkeley DB library has moved to a major corporation; +development seems to have stalled and documentation is not freely available. +This is probably not tenable for the long term use by Exim. +.wen + Different DBM libraries have different conventions for naming the files they use. When a program opens a file called &_dbmfile_&, there are several possibilities: @@ -1738,7 +1782,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, @@ -1751,9 +1795,11 @@ 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 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 +2.&'x'& and 3.&'x'& were current for a while, +but the latest versions when Exim last revamped support were numbered 5.&'x'&. +Maintenance of some of the earlier releases has ceased, +and Exim no longer supports versions before 3.&'x'&. +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 @@ -1764,6 +1810,9 @@ suited to Exim's usage model. Yet another DBM library, called &'tdb'&, is available from &url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also operates on a single file. +.next +It is possible to use sqlite3 (&url(https://www.sqlite.org/index.html)) +for the DBM library. .endlist .cindex "USE_DB" @@ -1775,8 +1824,10 @@ USE_DB in an appropriate configuration file (typically .code USE_DB=yes .endd -Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An -error is diagnosed if you set more than one of these. +Similarly, for gdbm you set USE_GDBM, for tdb you set USE_TDB, +and for sqlite3 you set USE_SQLITE. +An error is diagnosed if you set more than one of these. +You can set USE_NDBM if needed to override an operating system default. At the lowest level, the build-time configuration sets none of these options, thereby assuming an interface of type (1). However, some operating system @@ -1791,7 +1842,10 @@ in one of these lines: .code DBMLIB = -ldb DBMLIB = -ltdb +DBMLIB = -lsqlite3 +DBMLIB = -lgdbm -lgdbm_compat .endd +The last of those was for a Linux having GDBM provide emulated NDBM facilities. Settings like that will work if the DBM library is installed in the standard place. Sometimes it is not, and the library's header file may also not be in the default path. You may need to set INCLUDE to specify where the header @@ -1804,6 +1858,17 @@ DBMLIB=/usr/local/lib/db-4.1/libdb.a There is further detailed discussion about the various DBM libraries in the file &_doc/dbm.discuss.txt_& in the Exim distribution. +.new +When moving from one DBM library to another, +for the hints databases it suffices to just remove all the files in the +directory named &"db/"& under the spool directory. +This is because hints are only for optimisation and will be rebuilt +during normal operations. +Non-hints DBM databases (used by &"dbm"& lookups in the configuration) +will need individual rebuilds for the new DBM library. +This is not done automatically +.wen + .section "Pre-building configuration" "SECID25" @@ -1820,17 +1885,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. @@ -1856,7 +1921,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. @@ -1888,11 +1953,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). @@ -1901,35 +1965,39 @@ 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 -SUPPORT_TLS=yes +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 @@ -1937,7 +2005,6 @@ TLS_INCLUDE=-I/usr/gnu/include .cindex "pkg-config" "GnuTLS" If you have &'pkg-config'& available, then instead you can just use: .code -SUPPORT_TLS=yes USE_GNUTLS=yes USE_GNUTLS_PC=gnutls .endd @@ -2002,18 +2069,25 @@ withdrawn. -.section "Dynamically loaded lookup module support" "SECTdynamicmodules" +.section "Dynamically loaded module support" "SECTdynamicmodules" .cindex "lookup modules" +.cindex "router 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 +library dependencies without requiring all systems to install all of those dependencies. Most, but not all, lookup types can be built this way. +.new +Similarly, router drivers can be built as external modules. +This permits a smaller exim binary, growing only as needed for the +runtime cofiguration. +.wen + 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 @@ -2024,7 +2098,7 @@ 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: +only if each is installed: .code LOOKUP_LSEARCH=yes LOOKUP_SQLITE=2 @@ -2163,7 +2237,7 @@ 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" @@ -2266,7 +2340,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 @@ -2286,10 +2360,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. @@ -2337,7 +2411,7 @@ 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). @@ -2385,7 +2459,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 @@ -2406,7 +2480,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 @@ -2480,7 +2554,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. @@ -2525,11 +2599,32 @@ use of Exim's filtering capabilities, you should make the document entitled +.section "Running the daemon" SECTdaemonLaunch +The most common command line for launching the Exim daemon looks like +.code +exim -bd -q5m +.endd +This starts a daemon which +.ilist +listens for incoming smtp connections, launching handler processes for +each new one +.next +starts a queue-runner process every five minutes, to inspect queued messages +and run delivery attempts on any that have arrived at their retry time +.endlist +Should a queue run take longer than the time between queue-runner starts, +they will run in parallel. +Numbers of jobs of the various types are subject to policy controls +defined in the configuration. + + .section "Upgrading Exim" "SECID36" .cindex "upgrading Exim" If you are already running Exim on your host, building and installing a new version automatically makes it available to MUAs, or any other programs that call the MTA directly. However, if you are running an Exim daemon, you do need +.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 @@ -2628,6 +2723,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 @@ -2635,10 +2731,8 @@ Exim through the local interface (see the &%-bm%& and &%-f%& options below). See the &%untrusted_set_sender%& option for a way of permitting non-trusted users to set envelope senders. -.cindex "&'From:'& header line" -.cindex "&'Sender:'& header line" -.cindex "header lines" "From:" -.cindex "header lines" "Sender:" +.chindex From: +.chindex 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. @@ -2701,21 +2795,18 @@ outputs a brief message about itself and exits. .vlist -.vitem &%--%& -.oindex "--" +.cmdopt "--" "--" .cindex "options" "command line; terminating" This is a pseudo-option whose only purpose is to terminate the options and therefore to cause subsequent command line items to be treated as arguments rather than options, even if they begin with hyphens. -.vitem &%--help%& -.oindex "&%--help%&" +.cmdopt --help This option causes Exim to output a few sentences stating what it is. The same output is generated if the Exim binary is called with no options and no arguments. -.vitem &%--version%& -.oindex "&%--version%&" +.cmdopt --version This option is an alias for &%-bV%& and causes version information to be displayed. @@ -2726,15 +2817,14 @@ displayed. These options are used by Sendmail for selecting configuration files and are ignored by Exim. -.vitem &%-B%&<&'type'&> +.cmdopt -B <&'type'&> .oindex "&%-B%&" .cindex "8-bit characters" .cindex "Sendmail compatibility" "8-bit characters" This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit clean; it ignores this option. -.vitem &%-bd%& -.oindex "&%-bd%&" +.cmdopt -bd .cindex "daemon" .cindex "SMTP" "listener" .cindex "queue runner" @@ -2767,7 +2857,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 @@ -2775,13 +2870,17 @@ of Exim is installed. It is not necessary to do this when other files that are referenced from the configuration (for example, alias files) are changed, because these are reread each time they are used. -.vitem &%-bdf%& -.oindex "&%-bdf%&" +Either a SIGTERM or a SIGINT signal should be used to cause the daemon +to cleanly shut down. +Subprocesses handling recceiving or delivering messages, +or for scanning the queue, +will not be affected by the termination of the daemon process. + +.cmdopt -bdf This option has the same effect as &%-bd%& except that it never disconnects from the controlling terminal, even when no debugging is specified. -.vitem &%-be%& -.oindex "&%-be%&" +.cmdopt -be .cindex "testing" "string expansion" .cindex "expansion" "testing" Run Exim in expansion testing mode. Exim discards its root privilege, to @@ -2796,7 +2895,7 @@ 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 @@ -2813,8 +2912,14 @@ 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%&" +The word &"set"& at the start of a line, followed by a single space, +is recognised specially as defining a value for a variable. +.cindex "tainted data" "expansion testing" +If the sequence &",t"& is inserted before the space, +the value is marked as tainted. +The syntax is otherwise the same as the ACL modifier &"set ="&. + +.cmdopt -bem <&'filename'&> .cindex "testing" "string expansion" .cindex "expansion" "testing" This option operates like &%-be%& except that it must be followed by the name @@ -2831,16 +2936,14 @@ recipients are read from the headers in the normal way, and are shown in the line, because further arguments are taken as strings to expand (just like &%-be%&). -.vitem &%-bF%&&~<&'filename'&> -.oindex "&%-bF%&" +.cmdopt -bF <&'filename'&> .cindex "system filter" "testing" .cindex "testing" "system filter" This option is the same as &%-bf%& except that it assumes that the filter being tested is a system filter. The additional commands that are available only in system filters are recognized. -.vitem &%-bf%&&~<&'filename'&> -.oindex "&%-bf%&" +.cmdopt -bf <&'filename'&> .cindex "filter" "testing" .cindex "testing" "filter file" .cindex "forward file" "testing" @@ -2877,6 +2980,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, @@ -2885,37 +2989,32 @@ that would normally be taken from the envelope recipient address of the message can be set by means of additional command line options (see the next four options). -.vitem &%-bfd%&&~<&'domain'&> -.oindex "&%-bfd%&" +.cmdopt -bfd <&'domain'&> .vindex "&$qualify_domain$&" This sets the domain of the recipient address when a filter file is being tested by means of the &%-bf%& option. The default is the value of &$qualify_domain$&. -.vitem &%-bfl%&&~<&'local&~part'&> -.oindex "&%-bfl%&" +.cmdopt -bfl <&'local&~part'&> This sets the local part of the recipient address when a filter file is being tested by means of the &%-bf%& option. The default is the username of the process that calls Exim. A local part should be specified with any prefix or suffix stripped, because that is how it appears to the filter when a message is actually being delivered. -.vitem &%-bfp%&&~<&'prefix'&> -.oindex "&%-bfp%&" +.cmdopt -bfp <&'prefix'&> .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%&" +.cmdopt -bfs <&'suffix'&> .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. -.vitem &%-bh%&&~<&'IP&~address'&> -.oindex "&%-bh%&" +.cmdopt -bh <&'IP&~address'&> .cindex "testing" "incoming SMTP" .cindex "SMTP" "testing incoming" .cindex "testing" "relay control" @@ -2967,14 +3066,12 @@ plain text, cannot easily be tested with &%-bh%&. Instead, you should use a specialized SMTP test program such as &url(https://www.jetmore.org/john/code/swaks/,swaks). -.vitem &%-bhc%&&~<&'IP&~address'&> -.oindex "&%-bhc%&" +.cmdopt -bhc <&'IP&~address'&> This option operates in the same way as &%-bh%&, except that address verification callouts are performed if required. This includes consulting and updating the callout cache database. -.vitem &%-bi%& -.oindex "&%-bi%&" +.cmdopt -bi .cindex "alias file" "building" .cindex "building alias file" .cindex "Sendmail compatibility" "&%-bi%& option" @@ -2993,8 +3090,7 @@ 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%&" +.cmdopt -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 @@ -3002,14 +3098,12 @@ 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%&" +.cmdopt -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%&" +.cmdopt -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 @@ -3018,8 +3112,7 @@ useful for ManageSieve (RFC 5804) implementations, in providing that protocol's compile-time build options, which this option will adapt to, this is the only way to guarantee a correct response. -.vitem &%-bm%& -.oindex "&%-bm%&" +.cmdopt -bm .cindex "local message reception" This option runs an Exim receiving process that accepts an incoming, locally-generated message on the standard input. The recipients are given as the @@ -3034,7 +3127,7 @@ options, as appropriate. The &%-bnq%& option (see below) provides a way of suppressing this for special cases. Policy checks on the contents of local messages can be enforced by means of -the non-SMTP ACL. See chapter &<>& for details. +the non-SMTP ACL. See section &<>& for details. .cindex "return code" "for &%-bm%&" The return code is zero if the message is successfully accepted. Otherwise, the @@ -3064,8 +3157,7 @@ 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%&" +.cmdopt -bmalware <&'filename'&> .cindex "testing", "malware" .cindex "malware scan test" This debugging option causes Exim to scan the given file or directory @@ -3085,8 +3177,7 @@ 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%&" +.cmdopt -bnq .cindex "address qualification, suppressing" By default, Exim automatically qualifies unqualified addresses (those without domains) that appear in messages that are submitted locally (that @@ -3107,8 +3198,7 @@ addresses in the envelope provoke errors (causing message rejection) and unqualified addresses in header lines are left alone. -.vitem &%-bP%& -.oindex "&%-bP%&" +.cmdopt -bP .cindex "configuration options" "extracting" .cindex "options" "configuration &-- extracting" If this option is given with no arguments, it causes the values of all Exim's @@ -3130,7 +3220,7 @@ mysql_servers = 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 run time +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 @@ -3184,17 +3274,16 @@ 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" +.cmdopt -bp +.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 @@ -3202,7 +3291,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 @@ -3222,48 +3311,50 @@ displayed with a D only when deliveries for all of its child addresses are complete. -.vitem &%-bpa%& -.oindex "&%-bpa%&" +.cmdopt -bpa This option operates like &%-bp%&, but in addition it shows delivered addresses that were generated from the original top level address(es) in each message by alias or forwarding operations. These addresses are flagged with &"+D"& instead of just &"D"&. -.vitem &%-bpc%& -.oindex "&%-bpc%&" +.cmdopt -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. -.vitem &%-bpr%& -.oindex "&%-bpr%&" +.cmdopt -bpi +.cindex queue "list of message IDs" +This option operates like &%-bp%&, but only outputs message ids +(one per line). + + +.cmdopt -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%& -.oindex "&%-bpra%&" +.cmdopt -bpra This option is a combination of &%-bpr%& and &%-bpa%&. -.vitem &%-bpru%& -.oindex "&%-bpru%&" +.cmdopt -bpri +This option is a combination of &%-bpr%& and &%-bpi%&. + +.cmdopt -bpru This option is a combination of &%-bpr%& and &%-bpu%&. -.vitem &%-bpu%& -.oindex "&%-bpu%&" +.cmdopt -bpu This option operates like &%-bp%& but shows only undelivered top-level addresses for each message displayed. Addresses generated by aliasing or forwarding are not shown, unless the message was deferred after processing by a router with the &%one_time%& option set. -.vitem &%-brt%& -.oindex "&%-brt%&" +.cmdopt -brt .cindex "testing" "retry configuration" .cindex "retry" "configuration testing" This option is for testing retry rules, and it must be followed by up to three @@ -3287,8 +3378,7 @@ exim -brt haydn.comp.mus.example quota_3d Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m .endd -.vitem &%-brw%& -.oindex "&%-brw%&" +.cmdopt -brw .cindex "testing" "rewriting" .cindex "rewriting" "testing" This option is for testing address rewriting rules, and it must be followed by @@ -3297,8 +3387,7 @@ complete address with a fully qualified domain. Exim outputs how this address would be rewritten for each possible place it might appear. See chapter &<>& for further details. -.vitem &%-bS%& -.oindex "&%-bS%&" +.cmdopt -bS .cindex "SMTP" "batched incoming" .cindex "batched SMTP input" This option is used for batched SMTP input, which is an alternative interface @@ -3314,7 +3403,7 @@ dots doubled), terminated by a line containing just a single dot. An error is provoked if the terminating dot is missing. A further message may then follow. As for other local message submissions, the contents of incoming batch SMTP -messages can be checked using the non-SMTP ACL (see chapter &<>&). +messages can be checked using the non-SMTP ACL (see section &<>&). Unqualified addresses are automatically qualified using &%qualify_domain%& and &%qualify_recipient%&, as appropriate, unless the &%-bnq%& option is used. @@ -3331,8 +3420,7 @@ was detected; otherwise it is 2. More details of input using batched SMTP are given in section &<>&. -.vitem &%-bs%& -.oindex "&%-bs%&" +.cmdopt -bs .cindex "SMTP" "local input" .cindex "local SMTP input" This option causes Exim to accept one or more messages by reading SMTP commands @@ -3360,8 +3448,7 @@ above concerning senders and qualification do not apply. In this situation, Exim behaves in exactly the same way as it does when receiving a message via the listening daemon. -.vitem &%-bt%& -.oindex "&%-bt%&" +.cmdopt -bt .cindex "testing" "addresses" .cindex "address" "testing" This option runs Exim in address testing mode, in which each argument is taken @@ -3406,14 +3493,13 @@ whose behaviour depends on the contents of an incoming message, you cannot test those conditions using &%-bt%&. The &%-N%& option provides a possible way of doing such tests. -.vitem &%-bV%& -.oindex "&%-bV%&" +.cmdopt -bV .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 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 @@ -3423,8 +3509,7 @@ alone to discover (for example) all the typos in the configuration; some realistic testing is needed. The &%-bh%& and &%-N%& options provide more dynamic testing facilities. -.vitem &%-bv%& -.oindex "&%-bv%&" +.cmdopt -bv .cindex "verifying address" "using &%-bv%&" .cindex "address" "verification" This option runs Exim in address verification mode, in which each argument is @@ -3474,14 +3559,12 @@ address of a message, you should use the &%-f%& option to set an appropriate sender when running &%-bv%& tests. Without it, the sender is assumed to be the calling user at the default qualifying domain. -.vitem &%-bvs%& -.oindex "&%-bvs%&" +.cmdopt -bvs 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%&" +.cmdopt -bw .cindex "daemon" .cindex "inetd" .cindex "inetd" "wait mode" @@ -3497,15 +3580,14 @@ 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%&" +.cmdopt -C <&'filelist'&> .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. @@ -3525,15 +3607,15 @@ 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%&). +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 @@ -3601,41 +3683,41 @@ of debugging data, respectively. For example, &%-d+filter%& adds filter debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that no spaces are allowed in the debug setting. The available debugging categories are: -.display -&`acl `& ACL interpretation -&`auth `& authenticators -&`deliver `& general delivery logic -&`dns `& DNS lookups (see also resolver) -&`dnsbl `& DNS black list (aka RBL) code -&`exec `& arguments for &[execv()]& calls -&`expand `& detailed debugging for string expansions -&`filter `& filter handling -&`hints_lookup `& hints data lookups -&`host_lookup `& all types of name-to-IP address handling -&`ident `& ident lookup -&`interface `& lists of local interfaces -&`lists `& matching things in lists -&`load `& system load checks -&`local_scan `& can be used by &[local_scan()]& (see chapter &&& - &<>&) -&`lookup `& general lookup code and all lookups -&`memory `& memory handling -&`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 -&`resolver `& turn on the DNS resolver's debugging output -&`retry `& retry handling -&`rewrite `& address rewriting -&`route `& address routing -&`timestamp `& modifier: add timestamp to debug output lines -&`tls `& TLS logic -&`transport `& transports -&`uid `& changes of uid/gid and looking up uid/gid -&`verify `& address verification logic -&`all `& almost all of the above (see below), and also &%-v%& -.endd +.itable none 0 0 2 20* left 80* left +.irow acl "ACL interpretation" +.irow auth "authenticators" +.irow deliver "general delivery logic" +.irow dns "DNS lookups (see also resolver)" +.irow dnsbl "DNS black list (aka RBL) code" +.irow exec "arguments for &[execv()]& calls" +.irow expand "detailed debugging for string expansions" +.irow filter "filter handling" +.irow hints_lookup "hints data lookups" +.irow host_lookup "all types of name-to-IP address handling" +.irow ident "ident lookup" +.irow interface "lists of local interfaces" +.irow lists "matching things in lists" +.irow load "system load checks" +.irow local_scan "can be used by &[local_scan()]& (see chapter &&& + &<>&)" +.irow lookup "general lookup code and all lookups" +.irow memory "memory handling" +.irow noutf8 "modifier: avoid UTF-8 line-drawing" +.irow pid "modifier: add pid to debug output lines" +.irow process_info "setting info for the process log" +.irow queue_run "queue runs" +.irow receive "general message reception logic" +.irow resolver "turn on the DNS resolver's debugging output" +.irow retry "retry handling" +.irow rewrite "address rewriting"" +.irow route "address routing" +.irow timestamp "modifier: add timestamp to debug output lines" +.irow tls "TLS logic" +.irow transport "transports" +.irow uid "changes of uid/gid and looking up uid/gid" +.irow verify "address verification logic" +.irow all "almost all of the above (see below), and also &%-v%&" +.endtable The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it for &`-all`&. The reason for this is that &`+all`& is something that people tend to use when generating debug output for Exim maintainers. If &`+memory`& @@ -3661,14 +3743,12 @@ 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. -.new .cindex debugging "UTF-8 in" .cindex UTF-8 "in debug output" -The &`noutf8`& selector disables the use of +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, -.wen If the &%debug_print%& option is set in any driver, it produces output whenever any debugging is selected, or if &%-v%& is used. @@ -3680,14 +3760,12 @@ starts a daemon process. In that case, debugging is turned off for the subprocesses that the daemon creates. Thus, it is useful for monitoring the behaviour of the daemon without creating as much output as full debugging does. -.vitem &%-dropcr%& -.oindex "&%-dropcr%&" +.cmdopt -dropcr This is an obsolete option that is now a no-op. It used to affect the way Exim handled CR and LF characters in incoming messages. What happens now is described in section &<>&. -.vitem &%-E%& -.oindex "&%-E%&" +.cmdopt -E .cindex "bounce message" "generating" This option specifies that an incoming message is a locally-generated delivery failure report. It is used internally by Exim when handling delivery failures @@ -3704,8 +3782,7 @@ called by various programs without the leading &%o%& in the option. For example, the &%vacation%& program uses &%-eq%&. Exim treats all options of the form &%-e%&&'x'& as synonymous with the corresponding &%-oe%&&'x'& options. -.vitem &%-F%&&~<&'string'&> -.oindex "&%-F%&" +.cmdopt -F <&'string'&> .cindex "sender" "name" .cindex "name" "of sender" This option sets the sender's full name for use when a locally-generated @@ -3714,11 +3791,11 @@ entry from the password data is used. As users are generally permitted to alter their &'gecos'& entries, no security considerations are involved. White space between &%-F%& and the <&'string'&> is optional. -.vitem &%-f%&&~<&'address'&> -.oindex "&%-f%&" +.cmdopt -f <&'address'&> .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 @@ -3758,8 +3835,7 @@ locally-generated message can also be set (when permitted) by an initial &"From&~"& line in the message &-- see the description of &%-bm%& above &-- but if &%-f%& is also present, it overrides &"From&~"&. -.vitem &%-G%& -.oindex "&%-G%&" +.cmdopt -G .cindex "submission fixups, suppressing (command-line)" This option is equivalent to an ACL applying: .code @@ -3772,24 +3848,23 @@ in future. As this affects audit information, the caller must be a trusted user to use this option. -.vitem &%-h%&&~<&'number'&> -.oindex "&%-h%&" +.cmdopt -h <&'number'&> .cindex "Sendmail compatibility" "&%-h%& option ignored" This option is accepted for compatibility with Sendmail, but has no effect. (In Sendmail it overrides the &"hop count"& obtained by counting &'Received:'& headers.) -.vitem &%-i%& -.oindex "&%-i%&" +.cmdopt -i .cindex "Solaris" "&'mail'& command" .cindex "dot" "in incoming non-SMTP message" This option, which has the same effect as &%-oi%&, specifies that a dot on a -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%&. +line by itself should not terminate an incoming, non-SMTP message. +Solaris 2.4 (SunOS 5.4) Sendmail has a similar &%-i%& processing option +&url(https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf), +p. 1M-529), and therefore a &%-oi%& command line option, which both are used +by its &'mailx'& command. -.vitem &%-L%&&~<&'tag'&> -.oindex "&%-L%&" +.cmdopt -L <&'tag'&> .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`&. @@ -3799,8 +3874,7 @@ 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%&" +.cmdopt -M <&'message&~id'&>&~<&'message&~id'&>&~... .cindex "forcing delivery" .cindex "delivery" "forcing attempt" .cindex "frozen messages" "forcing delivery" @@ -3822,8 +3896,7 @@ not terminate until all the delivery attempts have finished. No output is produced unless there is a serious error. If you want to see what is happening, use the &%-v%& option as well, or inspect Exim's main log. -.vitem &%-Mar%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... -.oindex "&%-Mar%&" +.cmdopt -Mar <&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... .cindex "message" "adding recipients" .cindex "recipient" "adding" This option requests Exim to add the addresses to the list of recipients of the @@ -3832,7 +3905,9 @@ id, and the remaining ones must be email addresses. However, if the message is active (in the middle of a delivery attempt), it is not altered. This option can be used only by an admin user. -.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&& +.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&&& + &~<&'host&~IP'&>&&& + &~<&'sequence&~number'&>&&& &~<&'message&~id'&>" .oindex "&%-MC%&" .cindex "SMTP" "passed connection" @@ -3844,38 +3919,50 @@ an existing SMTP connection, which is passed as the standard input. Details are given in chapter &<>&. This must be the final option, and the caller must be root or the Exim user in order to use it. -.vitem &%-MCA%& -.oindex "&%-MCA%&" +.cmdopt -MCA 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%&" +.cmdopt -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%&" +.cmdopt -MCd +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-d%& option +to pass on an information string on the purpose of the process. + +.cmdopt -MCG <&'queue&~name'&> 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%&" +.cmdopt -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%&" +.cmdopt -MCL +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 server to +which Exim is connected advertised limits on numbers of mails, recipients or +recipient domains. +The limits are given by the following three arguments. + +.cmdopt -MCP 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 server to which Exim is connected supports pipelining. -.vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&> -.oindex "&%-MCQ%&" +.cmdopt -MCp +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 +t a remote server is via a SOCKS proxy, using addresses and ports given by +the following four arguments. + +.cmdopt -MCQ <&'process&~id'&>&~<&'pipe&~fd'&> This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option when the original delivery was started by a queue runner. It passes on the process id of the queue runner, @@ -3883,31 +3970,41 @@ together with the file descriptor number of an open pipe. Closure of the pipe signals the final completion of the sequence of processes that are passing messages through the same SMTP connection. -.vitem &%-MCS%& -.oindex "&%-MCS%&" +.cmdopt -MCq <&'recipient&~address'&>&~<&'size'&> +This option is not intended for use by external callers. It is used internally +by Exim to implement quota checking for local users. + +.cmdopt -MCS 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 -SMTP SIZE option should be used on messages delivered down the existing +ESMTP SIZE option should be used on messages delivered down the existing connection. -.vitem &%-MCT%& -.oindex "&%-MCT%&" +.cmdopt -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 host to which Exim is connected supports TLS encryption. -.vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>&~<&'cipher'&> -.oindex "&%-MCt%&" +.vitem &%-MCr%&&~<&'SNI'&> &&& + &%-MCs%&&~<&'SNI'&> +.oindex "&%-MCs%&" +.oindex "&%-MCr%&" +These options are not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MCt%& option, and passes on the fact that +a TLS Server Name Indication was sent as part of the channel establishment. +The argument gives the SNI string. +The "r" variant indicates a DANE-verified connection. + +.cmdopt -MCt <&'IP&~address'&>&~<&'port'&>&~<&'cipher'&> 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%&" +.cmdopt -Mc <&'message&~id'&>&~<&'message&~id'&>&~... .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 @@ -3919,8 +4016,7 @@ If you want to run a specific delivery as if in a queue run, you should use &%-q%& with a message id argument. A distinction between queue run deliveries and other deliveries is made in one or two places. -.vitem &%-Mes%&&~<&'message&~id'&>&~<&'address'&> -.oindex "&%-Mes%&" +.cmdopt -Mes <&'message&~id'&>&~<&'address'&> .cindex "message" "changing sender" .cindex "sender" "changing" This option requests Exim to change the sender address in the message to the @@ -3930,8 +4026,7 @@ be a message id, and the second one an email address. However, if the message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. -.vitem &%-Mf%&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-Mf%&" +.cmdopt -Mf <&'message&~id'&>&~<&'message&~id'&>&~... .cindex "freezing messages" .cindex "message" "manually freezing" This option requests Exim to mark each listed message as &"frozen"&. This @@ -3941,28 +4036,36 @@ However, if any of the messages are active (in the middle of a delivery attempt), their status is not altered. This option can be used only by an admin user. -.vitem &%-Mg%&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-Mg%&" +.cmdopt -Mg <&'message&~id'&>&~<&'message&~id'&>&~... .cindex "giving up on messages" .cindex "message" "abandoning delivery attempts" .cindex "delivery" "abandoning further attempts" This option requests Exim to give up trying to deliver the listed messages, including any that are frozen. However, if any of the messages are active, their status is not altered. For non-bounce messages, a delivery error message -is sent to the sender, containing the text &"cancelled by administrator"&. +is sent to the sender. Bounce messages are just discarded. This option can be used only by an admin user. -.vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-Mmad%&" +.cmdopt -MG <&'queue&~name'&>&~<&'message&~id'&>&~<&'message&~id'&>&~... +.cindex queue named +.cindex "named queues" "moving messages" +.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. + +.cmdopt -Mmad <&'message&~id'&>&~<&'message&~id'&>&~... .cindex "delivery" "cancelling all" This option requests Exim to mark all the recipient addresses in the messages as already delivered (&"mad"& for &"mark all delivered"&). However, if any message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. -.vitem &%-Mmd%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... -.oindex "&%-Mmd%&" +.cmdopt -Mmd <&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... .cindex "delivery" "cancelling by address" .cindex "recipient" "removing" .cindex "removing recipients" @@ -3973,8 +4076,7 @@ addresses in the message in a case-sensitive manner. If the message is active (in the middle of a delivery attempt), its status is not altered. This option can be used only by an admin user. -.vitem &%-Mrm%&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-Mrm%&" +.cmdopt -Mrm <&'message&~id'&>&~<&'message&~id'&>&~... .cindex "removing messages" .cindex "abandoning mail" .cindex "message" "manually discarding" @@ -3982,7 +4084,7 @@ 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%& @@ -3993,8 +4095,7 @@ placed on the queue. . a bounce message. . .wen -.vitem &%-Mset%&&~<&'message&~id'&> -.oindex "&%-Mset%&" +.cmdopt -Mset <&'message&~id'&> .cindex "testing" "string expansion" .cindex "expansion" "testing" This option is useful only in conjunction with &%-be%& (that is, when testing @@ -4005,8 +4106,7 @@ available. This feature is provided to make it easier to test expansions that make use of these variables. However, this option can be used only by an admin user. See also &%-bem%&. -.vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-Mt%&" +.cmdopt -Mt <&'message&~id'&>&~<&'message&~id'&>&~... .cindex "thawing messages" .cindex "unfreezing messages" .cindex "frozen messages" "thawing" @@ -4016,43 +4116,38 @@ This option requests Exim to &"thaw"& any of the listed messages that are messages are active, their status is not altered. This option can be used only by an admin user. -.vitem &%-Mvb%&&~<&'message&~id'&> -.oindex "&%-Mvb%&" +.cmdopt -Mvb <&'message&~id'&> .cindex "listing" "message body" .cindex "message" "listing body of" This option causes the contents of the message body (-D) spool file to be written to the standard output. This option can be used only by an admin user. -.vitem &%-Mvc%&&~<&'message&~id'&> -.oindex "&%-Mvc%&" +.cmdopt -Mvc <&'message&~id'&> .cindex "message" "listing in RFC 2822 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. -.vitem &%-Mvh%&&~<&'message&~id'&> -.oindex "&%-Mvh%&" +.cmdopt -Mvh <&'message&~id'&> .cindex "listing" "message headers" .cindex "header lines" "listing" .cindex "message" "listing header lines" This option causes the contents of the message headers (-H) spool file to be written to the standard output. This option can be used only by an admin user. -.vitem &%-Mvl%&&~<&'message&~id'&> -.oindex "&%-Mvl%&" +.cmdopt -Mvl <&'message&~id'&> .cindex "listing" "message log" .cindex "message" "listing message log" This option causes the contents of the message log spool file to be written to the standard output. This option can be used only by an admin user. -.vitem &%-m%& -.oindex "&%-m%&" -This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim -treats it that way too. +.cmdopt -m +This is a synonym for &%-om%& that is accepted by Sendmail +(&url(https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf) +p. 1M-258), so Exim treats it that way too. -.vitem &%-N%& -.oindex "&%-N%&" +.cmdopt -N .cindex "debugging" "&%-N%& option" .cindex "debugging" "suppressing delivery" This is a debugging option that inhibits delivery of a message at the transport @@ -4071,27 +4166,23 @@ routing problem. Once &%-N%& has been used for a delivery attempt, it sticks to the message, and applies to any subsequent delivery attempts that may happen for that message. -.vitem &%-n%& -.oindex "&%-n%&" +.cmdopt -n 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%&" +.cmdopt -O <&'data'&> This option is interpreted by Sendmail to mean &`set option`&. It is ignored by Exim. -.vitem &%-oA%&&~<&'file&~name'&> -.oindex "&%-oA%&" +.cmdopt -oA <&'file&~name'&> .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'&> -.oindex "&%-oB%&" +.cmdopt -oB <&'n'&> .cindex "SMTP" "passed connection" .cindex "SMTP" "multiple deliveries" .cindex "multiple SMTP deliveries" @@ -4099,8 +4190,7 @@ This is a debugging option which limits the maximum number of messages that can be delivered down one SMTP connection, overriding the value set in any &(smtp)& transport. If <&'n'&> is omitted, the limit is set to 1. -.vitem &%-odb%& -.oindex "&%-odb%&" +.cmdopt -odb .cindex "background delivery" .cindex "delivery" "in the background" This option applies to all modes in which Exim accepts incoming messages, @@ -4119,8 +4209,7 @@ If one of the queueing options in the configuration file overrides it if &%queue_only_override%& is set true, which is the default setting. If &%queue_only_override%& is set false, &%-odb%& has no effect. -.vitem &%-odf%& -.oindex "&%-odf%&" +.cmdopt -odf .cindex "foreground delivery" .cindex "delivery" "in the foreground" This option requests &"foreground"& (synchronous) delivery when Exim has @@ -4136,33 +4225,31 @@ 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. -.vitem &%-odi%& -.oindex "&%-odi%&" +.cmdopt -odi This option is synonymous with &%-odf%&. It is provided for compatibility with Sendmail. -.vitem &%-odq%& -.oindex "&%-odq%&" +.cmdopt -odq .cindex "non-immediate delivery" .cindex "delivery" "suppressing immediate" .cindex "queueing incoming messages" 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 forces queueing. -.vitem &%-odqs%& -.oindex "&%-odqs%&" +.cmdopt -odqs .cindex "SMTP" "delaying delivery" +.cindex "first pass routing" This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&. However, like &%-odb%& and &%-odi%&, this option has no effect if &%queue_only_override%& is false and one of the queueing options in the @@ -4172,15 +4259,14 @@ 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%& configuration option has the same effect for specific domains. See also the &%-qq%& option. -.vitem &%-oee%& -.oindex "&%-oee%&" +.cmdopt -oee .cindex "error" "reporting" If an error is detected while a non-SMTP message is being received (for example, a malformed address), the error is reported to the sender in a mail @@ -4193,36 +4279,31 @@ 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 for any other error. This is the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. -.vitem &%-oem%& -.oindex "&%-oem%&" +.cmdopt -oem .cindex "error" "reporting" .cindex "return code" "for &%-oem%&" This is the same as &%-oee%&, except that Exim always exits with a non-zero return code, whether or not the error message was successfully sent. This is the default &%-oe%&&'x'& option, unless Exim is called as &'rmail'&. -.vitem &%-oep%& -.oindex "&%-oep%&" +.cmdopt -oep .cindex "error" "reporting" If an error is detected while a non-SMTP message is being received, the error is reported by writing a message to the standard error file (stderr). .cindex "return code" "for &%-oep%&" The return code is 1 for all errors. -.vitem &%-oeq%& -.oindex "&%-oeq%&" +.cmdopt -oeq .cindex "error" "reporting" This option is supported for compatibility with Sendmail, but has the same effect as &%-oep%&. -.vitem &%-oew%& -.oindex "&%-oew%&" +.cmdopt -oew .cindex "error" "reporting" This option is supported for compatibility with Sendmail, but has the same effect as &%-oem%&. -.vitem &%-oi%& -.oindex "&%-oi%&" +.cmdopt -oi .cindex "dot" "in incoming non-SMTP message" This option, which has the same effect as &%-i%&, specifies that a dot on a line by itself should not terminate an incoming, non-SMTP message. Otherwise, a @@ -4230,12 +4311,10 @@ single dot does terminate, though Exim does no special processing for other lines that start with a dot. This option is set by default if Exim is called as &'rmail'&. See also &%-ti%&. -.vitem &%-oitrue%& -.oindex "&%-oitrue%&" +.cmdopt -oitrue This option is treated as synonymous with &%-oi%&. -.vitem &%-oMa%&&~<&'host&~address'&> -.oindex "&%-oMa%&" +.cmdopt -oMa <&'host&~address'&> .cindex "sender" "host address, specifying for local message" A number of options starting with &%-oM%& can be used to set values associated with remote hosts on locally-submitted messages (that is, messages not received @@ -4258,8 +4337,7 @@ port, if present, in &$sender_host_port$&. If both &%-oMa%& and &%-bh%& are present on the command line, the sender host IP address is taken from whichever one is last. -.vitem &%-oMaa%&&~<&'name'&> -.oindex "&%-oMaa%&" +.cmdopt -oMaa <&'name'&> .cindex "authentication" "name, specifying for local message" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%& option sets the value of &$sender_host_authenticated$& (the authenticator @@ -4267,8 +4345,7 @@ name). See chapter &<>& for a discussion of SMTP authentication. This option can be used with &%-bh%& and &%-bs%& to set up an authenticated SMTP session without actually using the SMTP AUTH command. -.vitem &%-oMai%&&~<&'string'&> -.oindex "&%-oMai%&" +.cmdopt -oMai <&'string'&> .cindex "authentication" "id, specifying for local message" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%& option sets the value of &$authenticated_id$& (the id that was authenticated). @@ -4276,8 +4353,7 @@ This overrides the default value (the caller's login id, except with &%-bh%&, where there is no default) for messages from local sources. See chapter &<>& for a discussion of authenticated ids. -.vitem &%-oMas%&&~<&'address'&> -.oindex "&%-oMas%&" +.cmdopt -oMas <&'address'&> .cindex "authentication" "sender, specifying for local message" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%& option sets the authenticated sender value in &$authenticated_sender$&. It @@ -4287,16 +4363,14 @@ default. For both &%-bh%& and &%-bs%&, an authenticated sender that is specified on a MAIL command overrides this value. See chapter &<>& for a discussion of authenticated senders. -.vitem &%-oMi%&&~<&'interface&~address'&> -.oindex "&%-oMi%&" +.cmdopt -oMi <&'interface&~address'&> .cindex "interface" "address, specifying for local message" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%& 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%&" +.cmdopt -oMm <&'message&~reference'&> .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 @@ -4309,8 +4383,7 @@ 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%&" +.cmdopt -oMr <&'protocol&~name'&> .cindex "protocol, specifying for local message" .vindex "&$received_protocol$&" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%& @@ -4322,37 +4395,32 @@ SMTP protocol names (see the description of &$received_protocol$& in section one of those same names. For &%-bS%& (batched SMTP) however, the protocol can be set by &%-oMr%&. Repeated use of this option is not supported. -.vitem &%-oMs%&&~<&'host&~name'&> -.oindex "&%-oMs%&" +.cmdopt -oMs <&'host&~name'&> .cindex "sender" "host name, specifying for local message" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMs%& option sets the sender host name in &$sender_host_name$&. When this option is present, Exim does not attempt to look up a host name from an IP address; it uses the name it is given. -.vitem &%-oMt%&&~<&'ident&~string'&> -.oindex "&%-oMt%&" +.cmdopt -oMt <&'ident&~string'&> .cindex "sender" "ident string, specifying for local message" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%& option sets the sender ident value in &$sender_ident$&. The default setting for local callers is the login id of the calling process, except when &%-bh%& is used, when there is no default. -.vitem &%-om%& -.oindex "&%-om%&" +.cmdopt -om .cindex "Sendmail compatibility" "&%-om%& option ignored" In Sendmail, this option means &"me too"&, indicating that the sender of a message should receive a copy of the message if the sender appears in an alias expansion. Exim always does this, so the option does nothing. -.vitem &%-oo%& -.oindex "&%-oo%&" +.cmdopt -oo .cindex "Sendmail compatibility" "&%-oo%& option ignored" This option is ignored. In Sendmail it specifies &"old style headers"&, whatever that means. -.vitem &%-oP%&&~<&'path'&> -.oindex "&%-oP%&" +.cmdopt -oP <&'path'&> .cindex "pid (process id)" "of daemon" .cindex "daemon" "process id (pid)" This option is useful only in conjunction with &%-bd%& or &%-q%& with a time @@ -4361,16 +4429,22 @@ 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. -.vitem &%-or%&&~<&'time'&> -.oindex "&%-or%&" +.cmdopt -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. + +.cmdopt -or <&'time'&> .cindex "timeout" "for non-SMTP input" This option sets a timeout value for incoming non-SMTP messages. If it is not set, Exim will wait forever for the standard input. The value can also be set by the &%receive_timeout%& option. The format used for specifying times is described in section &<>&. -.vitem &%-os%&&~<&'time'&> -.oindex "&%-os%&" +.cmdopt -os <&'time'&> .cindex "timeout" "for SMTP input" .cindex "SMTP" "input timeout" This option sets a timeout value for incoming SMTP messages. The timeout @@ -4378,12 +4452,10 @@ applies to each SMTP command and block of data. The value can also be set by the &%smtp_receive_timeout%& option; it defaults to 5 minutes. The format used for specifying times is described in section &<>&. -.vitem &%-ov%& -.oindex "&%-ov%&" +.cmdopt -ov This option has exactly the same effect as &%-v%&. -.vitem &%-oX%&&~<&'number&~or&~string'&> -.oindex "&%-oX%&" +.cmdopt -oX <&'number&~or&~string'&> .cindex "TCP/IP" "setting listening ports" .cindex "TCP/IP" "setting listening interfaces" .cindex "port" "receiving TCP/IP" @@ -4391,18 +4463,38 @@ 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%&" +.cmdopt -oY +.cindex "daemon notifier socket" +This option controls the creation of an inter-process communications endpoint +by the Exim daemon. +It is only relevant when the &%-bd%& (start listening daemon) option is also +given. +Normally the daemon creates this socket, unless a &%-oX%& and &*no*& &%-oP%& +option is also present. +If this option is given then the socket will not be created. This is required +if the system is running multiple daemons, in which case it should +be used on all. +The features supported by the socket will not be available in such cases. + +The socket is currently used for +.ilist +fast ramp-up of queue runner processes +.next +caching compiled regexes +.next +obtaining a current queue size +.endlist + +.cmdopt -pd .cindex "Perl" "starting the interpreter" This option applies when an embedded Perl interpreter is linked with Exim (see chapter &<>&). It overrides the setting of the &%perl_at_start%& option, forcing the starting of the interpreter to be delayed until it is needed. -.vitem &%-ps%& -.oindex "&%-ps%&" +.cmdopt -ps .cindex "Perl" "starting the interpreter" This option applies when an embedded Perl interpreter is linked with Exim (see chapter &<>&). It overrides the setting of the &%perl_at_start%& @@ -4422,8 +4514,7 @@ 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%&" +.cmdopt -q .cindex "queue runner" "starting manually" This option is normally restricted to admin users. However, there is a configuration option called &%prod_requires_admin%& which can be set false to @@ -4470,22 +4561,38 @@ appear in the correct order. Each flag is described in a separate item below. .cindex "queue" "double scanning" .cindex "queue" "routing" .cindex "routing" "whole queue before delivery" +.cindex "first pass routing" +.cindex "queue runner" "two phase" An option starting with &%-qq%& requests a two-stage queue run. In the first stage, the queue is scanned as if the &%queue_smtp_domains%& option matched every domain. Addresses are routed, local deliveries happen, but no remote transports are run. +Performance will be best if the &%queue_run_in_order%& option is false. +If that is so and +the &%queue_fast_ramp%& option is true +and a daemon-notifier socket is available +then in the first phase of the run, +once a threshold number of messages are routed for a given host, +a delivery process is forked in parallel with the rest of the scan. + .cindex "hints database" "remembering routing" The hints database that remembers which messages are waiting for specific hosts -is updated, as if delivery to those hosts had been deferred. After this is -complete, a second, normal queue scan happens, with routing and delivery taking -place as normal. Messages that are routed to the same host should mostly be +is updated, as if delivery to those hosts had been deferred. + +After the first queue scan complete, +a second, normal queue scan is done, with routing and delivery taking +place as normal. +Messages that are routed to the same host should mostly be delivered down a single SMTP .cindex "SMTP" "passed connection" .cindex "SMTP" "multiple deliveries" .cindex "multiple SMTP deliveries" connection because of the hints that were set up during the first queue scan. -This option may be useful for hosts that are connected to the Internet + +Two-phase queue runs should be used on systems which, even intermittently, +have a large queue (such as mailing-list operators). +They may also be useful for hosts that are connected to the Internet intermittently. .vitem &%-q[q]i...%& @@ -4493,7 +4600,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...%& @@ -4514,13 +4621,13 @@ 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[q][i][f[f]][l][G[/