X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/83d18f011e399f82d9583abe20d9c5dc850778c2..b0e63c7efdc2133c61545b051042d3617ecd2bbd:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 7d9281e40..dc8f5cc4d 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,3 +1,4 @@ + . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is . converted into DocBook XML for subsequent conversion into printable and online @@ -45,14 +46,16 @@ . Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.92" +.set previousversion "4.97" .include ./local_params .set ACL "access control lists (ACLs)" .set I "    " +.set drivernamemax "64" + .macro copyyear -2018, 2019 +2023 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -74,6 +77,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,8 +95,19 @@ .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 @@ -95,6 +119,34 @@ .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 +169,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 +203,9 @@ && .endmacro +. --- The index entry points to the most-recent chapter head, section or subsection +. --- head, or varlist item. + .macro vindex && &&$1&& @@ -161,6 +218,13 @@ .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 . //////////////////////////////////////////////////////////////////////////// @@ -184,142 +248,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" . ///////////////////////////////////////////////////////////////////////////// @@ -371,11 +362,13 @@ contributors. .section "Exim documentation" "SECID1" . Keep this example change bar when updating the documentation! +.new .cindex "documentation" This edition of the Exim specification applies to version &version() of Exim. Substantive changes from the &previousversion; edition are marked in some renditions of this document; this paragraph is so marked if the rendition is capable of showing a change indicator. +.wen This document is very much a reference manual; it is not a tutorial. The reader is expected to have some familiarity with the SMTP mail transfer protocol and @@ -472,10 +465,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 @@ -741,17 +735,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 @@ -977,9 +971,10 @@ 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 @@ -1000,20 +995,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 @@ -1023,6 +1022,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" @@ -1361,7 +1364,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 @@ -1392,21 +1395,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$&" @@ -1416,23 +1445,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 @@ -1450,7 +1491,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 @@ -1561,7 +1602,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 @@ -1585,7 +1626,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 @@ -1613,7 +1654,7 @@ 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 in the queue, @@ -1683,20 +1724,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 package or the 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" @@ -1749,9 +1790,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 @@ -1775,6 +1818,7 @@ 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. +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 @@ -1789,7 +1833,9 @@ in one of these lines: .code DBMLIB = -ldb DBMLIB = -ltdb +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 @@ -1898,13 +1944,11 @@ 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. -.new If you do not want TLS support you should set .code DISABLE_TLS=yes .endd in &_Local/Makefile_&. -.wen If OpenSSL is installed, you should set .code @@ -1914,14 +1958,14 @@ TLS_LIBS=-lssl -lcrypto in &_Local/Makefile_&. You may also need to specify the locations of the OpenSSL library and include files. For example: .code -USE_OPENSL=yes +USE_OPENSSL=yes TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto TLS_INCLUDE=-I/usr/local/openssl/include/ .endd .cindex "pkg-config" "OpenSSL" If you have &'pkg-config'& available, then instead you can just use: .code -USE_OPENSL=yes +USE_OPENSSL=yes USE_OPENSSL_PC=openssl .endd .cindex "USE_GNUTLS" @@ -2527,6 +2571,25 @@ 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 @@ -2640,10 +2703,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. @@ -2706,21 +2767,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. @@ -2731,15 +2789,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" @@ -2785,13 +2842,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 @@ -2823,8 +2884,11 @@ 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. +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 @@ -2841,16 +2905,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" @@ -2896,37 +2958,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" @@ -2978,14 +3035,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" @@ -3004,8 +3059,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 @@ -3013,14 +3067,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 @@ -3029,8 +3081,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 @@ -3075,8 +3126,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 @@ -3096,8 +3146,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 @@ -3118,8 +3167,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 @@ -3195,8 +3243,7 @@ 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%&" +.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 @@ -3233,48 +3280,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 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 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 @@ -3298,8 +3347,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 @@ -3308,8 +3356,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 @@ -3342,8 +3389,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 @@ -3371,8 +3417,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 @@ -3417,8 +3462,7 @@ 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. @@ -3434,8 +3478,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 @@ -3485,14 +3528,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" @@ -3508,8 +3549,7 @@ 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" @@ -3612,41 +3652,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`& @@ -3689,14 +3729,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 @@ -3713,8 +3751,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 @@ -3723,8 +3760,7 @@ 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" @@ -3768,8 +3804,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 @@ -3782,24 +3817,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`&. @@ -3809,8 +3843,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" @@ -3832,8 +3865,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 @@ -3842,7 +3874,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" @@ -3854,38 +3888,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, @@ -3893,28 +3939,38 @@ 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, @@ -3929,8 +3985,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 @@ -3940,8 +3995,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 @@ -3951,23 +4005,20 @@ 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. -.new -.vitem &%-MG%&&~<&'queue&~name'&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-MG%&" +.cmdopt -MG <&'queue&~name'&>&~<&'message&~id'&>&~<&'message&~id'&>&~... .cindex queue named -.cindex "named queues" +.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. @@ -3975,18 +4026,15 @@ 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. -.wen -.vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... -.oindex "&%-Mmad%&" +.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" @@ -3997,8 +4045,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" @@ -4017,8 +4064,7 @@ placed in 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 @@ -4029,8 +4075,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" @@ -4040,43 +4085,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 @@ -4095,27 +4135,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 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" @@ -4123,8 +4159,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, @@ -4143,8 +4178,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 @@ -4165,13 +4199,11 @@ 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" @@ -4184,9 +4216,9 @@ process encounters them. There are several configuration options (such as 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 @@ -4203,8 +4235,7 @@ 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 @@ -4217,36 +4248,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 @@ -4254,12 +4280,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 @@ -4282,8 +4306,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 @@ -4291,8 +4314,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). @@ -4300,8 +4322,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 @@ -4311,16 +4332,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 @@ -4333,8 +4352,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%& @@ -4346,37 +4364,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 @@ -4385,16 +4398,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 @@ -4402,12 +4421,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" @@ -4417,16 +4434,36 @@ 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 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%& @@ -4446,8 +4483,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 @@ -4494,22 +4530,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...%& @@ -4544,7 +4596,7 @@ for later delivery. .vitem &%-q[q][i][f[f]][l][G[/