X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/4f5788623ab3e8456ad254883b6cc018079aab96..1d2e086378c87cfc0fc437ab7cb7d170526ce46d:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index a23aab3de..4eb1dcb7a 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,26 +1,59 @@ -. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.2 2006/04/04 14:03:49 ph10 Exp $ -. . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is . converted into DocBook XML for subsequent conversion into printing and online . formats. The markup used herein is "standard" xfpt markup, with some extras. . The markup is summarized in a file called Markup.txt. +. +. WARNING: When you use the .new macro, make sure it appears *before* any +. adjacent index items; otherwise you get an empty "paragraph" which causes +. unwanted vertical space. . ///////////////////////////////////////////////////////////////////////////// .include stdflags .include stdmacs + +. ///////////////////////////////////////////////////////////////////////////// +. This outputs the standard DocBook boilerplate. +. ///////////////////////////////////////////////////////////////////////////// + .docbook + +. ///////////////////////////////////////////////////////////////////////////// +. These lines are processing instructions for the Simple DocBook Processor that +. Philip Hazel has developed as a less cumbersome way of making PostScript and +. PDFs than using xmlto and fop. They will be ignored by all other XML +. processors. +. ///////////////////////////////////////////////////////////////////////////// + +.literal xml + +.literal off + +. ///////////////////////////////////////////////////////////////////////////// +. This generate the outermost element that wraps then entire document. +. ///////////////////////////////////////////////////////////////////////////// + .book . ///////////////////////////////////////////////////////////////////////////// -. These definitions set some parameters and save some typing. Remember that -. the element must also be updated for each new edition. +. These definitions set some parameters and save some typing. +. Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// +.set previousversion "4.88" +.include ./local_params + .set ACL "access control lists (ACLs)" -.set previousversion "4.60" -.set version "4.61" +.set I "    " +.macro copyyear +2017 +.endmacro . ///////////////////////////////////////////////////////////////////////////// . Additional xfpt markup used by this document, over and above the default @@ -38,11 +71,18 @@ .flag &!? "‡" . --- A macro for an Exim option definition heading, generating a one-line -. --- table with four columns. +. --- 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. .macro option -.oindex "$1" -.itable all 0 0 4 8* left 5* center 5* center 6* right +.arg 5 +.oindex "&%$5%&" +.endarg +.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'&" .endtable .endmacro @@ -51,14 +91,32 @@ . --- is suitable for the many tables at the start of the main options chapter; . --- the small number of other 2-column tables override it. -.macro table2 190pt 260pt +.macro table2 196pt 254pt .itable none 0 0 2 $1 left $2 left .endmacro -. --- Macros for the concept and option index entries. For a "range" 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. +. --- 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. + +.macro irow +.arg 4 +.row "&I;$1" "$2" "$3" "$4" +.endarg +.arg -4 +.arg 3 +.row "&I;$1" "$2" "$3" +.endarg +.arg -3 +.row "&I;$1" "$2" +.endarg +.endarg +.endmacro + +. --- Macros for option, variable, and concept index entries. For a "range" +. --- 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. .macro cindex && @@ -91,8 +149,17 @@ && .endmacro +.macro vindex +&& +&&$1&& +.arg 2 +&&$2&& +.endarg +&& +.endmacro + .macro index -.echo "** Don't use .index; use .cindex or .oindex" +.echo "** Don't use .index; use .cindex or .oindex or .vindex" .endmacro . //////////////////////////////////////////////////////////////////////////// @@ -106,17 +173,18 @@ Specification of the Exim Mail Transfer Agent The Exim MTA -22 March 2006 -PhilipHazel -PH -University of Cambridge Computing Service -
New Museums Site, Pembroke Street, Cambridge CB2 3QH, England
+ +.fulldate + +EximMaintainers +EM - 4.61 - 22 March 2006 - PH +.versiondatexml + EM -2006University of Cambridge + +.copyyear + University of Cambridge .literal off @@ -127,10 +195,10 @@ . at the top level, so we have to put the .chapter directive first. . ///////////////////////////////////////////////////////////////////////////// -.chapter "Introduction" +.chapter "Introduction" "CHID1" .literal xml - + $1, $2, etc. numerical variables @@ -191,7 +259,7 @@ maximum - limit + limit monitor @@ -300,14 +368,14 @@ systems. I am grateful to them all. The distribution now contains a file called contributors. -.section "Exim documentation" -.new +.section "Exim documentation" "SECID1" +. Keep this example change bar when updating the documentation! + .cindex "documentation" -This edition of the Exim specification applies to version &version; of Exim. +This edition of the Exim specification applies to version &version() of Exim. Substantive changes from the &previousversion; edition are marked in some renditions of the document; this paragraph is so marked if the rendition is 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 @@ -321,7 +389,7 @@ very wide interest. .cindex "books about Exim" An &"easier"& discussion of Exim which provides more in-depth explanatory, introductory, and tutorial material can be found in a book entitled &'The Exim -SMTP Mail Server'&, published by UIT Cambridge +SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge (&url(http://www.uit.co.uk/exim-book/)). This book also contains a chapter that gives a general introduction to SMTP and @@ -332,9 +400,7 @@ published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) .cindex "Debian" "information sources" If you are using a Debian distribution of Exim, you will find information about Debian-specific features in the file -.display -&_/usr/share/doc/exim4-base/README.Debian_& -.endd +&_/usr/share/doc/exim4-base/README.Debian_&. The command &(man update-exim.conf)& is another source of Debian-specific information. @@ -366,10 +432,9 @@ directory are: .row &_exim.8_& "a man page of Exim's command line options" .row &_experimental.txt_& "documentation of experimental features" .row &_filter.txt_& "specification of the filter language" -.row &_pcrepattern.txt_& "specification of PCRE regular expressions" -.row &_pcretest.txt_& "specification of the PCRE testing program" .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" +.row &_openssl.txt_& "installing a current OpenSSL release" .endtable The main specification and the specification of the filtering language are also @@ -378,7 +443,7 @@ available in other formats (HTML, PostScript, PDF, and Texinfo). Section -.section "FTP and web sites" +.section "FTP and web sites" "SECID2" .cindex "web site" .cindex "FTP site" The primary site for Exim source distributions is currently the University of @@ -391,45 +456,55 @@ Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. .cindex "wiki" .cindex "FAQ" As well as Exim distribution tar files, the Exim web site contains a number of -differently formatted versions of the documentation, including the FAQ in both -text and HTML formats. The HTML version comes with a keyword-in-context index. -A recent addition to the online information is the Exim wiki -(&url(http://www.exim.org/eximwiki/)). We hope that this will make it easier -for Exim users to contribute examples, tips, and know-how for the benefit of -others. +differently formatted versions of the documentation. A recent addition to the +online information is the Exim wiki (&url(http://wiki.exim.org)), +which contains what used to be a separate FAQ, as well as various other +examples, tips, and know-how that have been contributed by Exim users. + +.cindex Bugzilla +An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use +this to report bugs, and also to add items to the wish list. Please search +first to check that you are not duplicating a previous entry. -.section "Mailing lists" +.section "Mailing lists" "SECID3" .cindex "mailing lists" "for Exim users" -The following are the three main Exim mailing lists: +The following Exim mailing lists exist: .table2 140pt -.row &'exim-users@exim.org'& "general discussion list" -.row &'exim-dev@exim.org'& "discussion of bugs, enhancements, etc." -.row &'exim-announce@exim.org'& "moderated, low volume announcements list" +.row &'exim-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" .endtable You can subscribe to these lists, change your existing subscriptions, and view or search the archives via the mailing lists link on the Exim home page. .cindex "Debian" "mailing list for" If you are using a Debian distribution of Exim, you may wish to subscribe to -the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'&. +the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'& +via this web page: +.display +&url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users) +.endd +Please ask Debian-specific questions on this list and not on the general Exim +lists. -.section "Exim training" +.section "Exim training" "SECID4" .cindex "training courses" -From time to time (approximately annually at the time of writing), training -courses are run by the author of Exim in Cambridge, UK. Details of any -forthcoming courses can be found on the web site -&url(http://www-tus.csx.cam.ac.uk/courses/exim/). +Training courses in Cambridge (UK) used to be run annually by the author of +Exim, before he retired. At the time of writing, there are no plans to run +further Exim courses in Cambridge. However, if that changes, relevant +information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/). - -.section "Bug reports" +.section "Bug reports" "SECID5" .cindex "bug reports" .cindex "reporting bugs" -Reports of obvious bugs should be emailed to &'bugs@exim.org'&. However, if you -are unsure whether some behaviour is a bug or not, the best thing to do is to -post a message to the &'exim-dev'& mailing list and have it discussed. +Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported +via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure +whether some behaviour is a bug or not, the best thing to do is to post a +message to the &'exim-dev'& mailing list and have it discussed. @@ -463,13 +538,28 @@ The &_.bz2_& file is usually a lot smaller than the &_.gz_& file. .cindex "distribution" "signing details" .cindex "distribution" "public key" .cindex "public key for signed distribution" -The distributions are currently signed with Philip Hazel's GPG key. The -corresponding public key is available from a number of keyservers, and there is -also a copy in the file &_Public-Key_&. The signatures for the tar bundles are -in: +The distributions will be PGP signed by an individual key of the Release +Coordinator. This key will have a uid containing an email address in the +&'exim.org'& domain and will have signatures from other people, including +other Exim maintainers. We expect that the key will be in the "strong set" of +PGP keys. There should be a trust path to that key from 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, +such as &'pool.sks-keyservers.net'&. + +At time of last update, releases were being made by Phil Pennock and signed with +key &'0x403043153903637F'&, although that key is expected to be replaced in 2013. +A trust path from Nigel's key to Phil's can be observed at +&url(https://www.security.spodhuis.org/exim-trustpath). + +Releases have also been authorized to be performed by Todd Lyons who signs with +key &'0xC4F4F94804D29EBA'&. A direct trust path exists between previous RE Phil +Pennock and Todd Lyons through a common associate. + +The signatures for the tar bundles are in: .display -&_exim-n.nn.tar.gz.sig_& -&_exim-n.nn.tar.bz2.sig_& +&_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 separate file in the directory &_ChangeLogs_& so that it is possible to @@ -487,37 +577,9 @@ inside the &_exim4_& directory of the FTP site: .endd These tar files contain only the &_doc_& directory, not the complete distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. -.cindex "FAQ" -The FAQ is available for downloading in two different formats in these files: -.display -&_exim4/FAQ.txt.gz_& -&_exim4/FAQ.html.tar.gz_& -.endd -The first of these is a single ASCII file that can be searched with a text -editor. The second is a directory of HTML files, normally accessed by starting -at &_index.html_&. The HTML version of the FAQ (which is also included in the -HTML documentation tarbundle) includes a keyword-in-context index, which is -often the most convenient way of finding your way around. -.section "Wish list" -.cindex "wish list" -A wish list is maintained, containing ideas for new features that have been -submitted. From time to time the file is exported to the ftp site into the file -&_exim4/WishList_&. Items are removed from the list if they get implemented. - - - -.section "Contributed material" -.cindex "contributed material" -At the ftp site, there is a directory called &_Contrib_& that contains -miscellaneous files contributed to the Exim community by Exim users. There is -also a collection of contributed configuration examples in -&_exim4/config.samples.tar.gz_&. These samples are referenced from the FAQ. - - - -.section "Limitations" +.section "Limitations" "SECID6" .ilist .cindex "limitations of Exim" .cindex "bang paths" "not handled by Exim" @@ -557,7 +619,7 @@ a number of common scanners are provided. .endlist -.section "Run time configuration" +.section "Run time configuration" "SECID7" Exim's run time configuration is held in a single text file that is divided into a number of sections. The entries in this file consist of keywords and values, in the style of Smail 3 configuration files. A default configuration @@ -565,7 +627,7 @@ file which is suitable for simple online installations is provided in the distribution, and is described in chapter &<>& below. -.section "Calling interface" +.section "Calling interface" "SECID8" .cindex "Sendmail compatibility" "command line interface" Like many MTAs, Exim has adopted the Sendmail command line interface so that it can be a straight replacement for &_/usr/lib/sendmail_& or @@ -585,7 +647,7 @@ interface to Exim's command line administration options. -.section "Terminology" +.section "Terminology" "SECID9" .cindex "terminology definitions" .cindex "body of message" "definition of" The &'body'& of a message is the actual data that the sender wants to transmit. @@ -615,7 +677,7 @@ The word &'domain'& is sometimes used to mean all but the first component of a host's name. It is &'not'& used in that sense here, where it normally refers to the part of an email address following the @ sign. -.cindex "envelope" "definition of" +.cindex "envelope, definition of" .cindex "sender" "definition of" A message in transit has an associated &'envelope'&, as well as a header and a body. The envelope contains a sender address (to which bounce messages should @@ -624,7 +686,7 @@ sender or the recipients of a message usually mean the addresses in the envelope. An MTA uses these addresses for delivery, and for returning bounce messages, not the addresses that appear in the header lines. -.cindex "message header" "definition of" +.cindex "message" "header, definition of" .cindex "header section" "definition of" The &'header'& of a message is the first part of a message's text, consisting of a number of lines, each of which has a name such as &'From:'&, &'To:'&, @@ -639,7 +701,7 @@ part of an email address that precedes the @ sign. The part that follows the @ sign is called the &'domain'& or &'mail domain'&. .cindex "local delivery" "definition of" -.cindex "remote delivery" "definition of" +.cindex "remote delivery, definition of" The terms &'local delivery'& and &'remote delivery'& are used to distinguish delivery to a file or a pipe on the local host from delivery by SMTP over TCP/IP to another host. As far as Exim is concerned, all hosts other than the @@ -676,21 +738,22 @@ the Exim documentation, &"spool"& is always used in the first sense. . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// -.chapter "Incorporated code" +.chapter "Incorporated code" "CHID2" .cindex "incorporated code" .cindex "regular expressions" "library" .cindex "PCRE" +.cindex "OpenDMARC" A number of pieces of external code are included in the Exim distribution. .ilist -Regular expressions are supported in the main Exim program and in the Exim -monitor using the freely-distributable PCRE library, copyright © -University of Cambridge. The source is distributed in the directory -&_src/pcre_&. However, this is a cut-down version of PCRE. If you want to use -the PCRE library in other programs, you should obtain and install the full -version from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre). -.next -.cindex "cdb" "acknowledgement" +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, +or obtain and install the full version of the library from +&url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre). +.next +.cindex "cdb" "acknowledgment" Support for the cdb (Constant DataBase) lookup method is provided by code contributed by Nigel Metheringham of (at the time he contributed it) Planet Online Ltd. The implementation is completely contained within the code of Exim. @@ -704,12 +767,11 @@ This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, the spec and sample code for cdb can be obtained from -&url(http://www.pobox.com/~djb/cdb.html). This implementation borrows some -code from Dan Bernstein's implementation (which has no license restrictions -applied to it). +&url(http://www.pobox.com/~djb/cdb.html). This implementation borrows +some code from Dan Bernstein's implementation (which has no license +restrictions applied to it). .endblockquote .next .cindex "SPA authentication" @@ -774,7 +836,7 @@ OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .endblockquote .next -.cindex "Exim monitor" "acknowledgement" +.cindex "Exim monitor" "acknowledgment" .cindex "X-windows" .cindex "Athena" The Exim Monitor program, which is an X-Window application, includes @@ -805,10 +867,18 @@ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .endblockquote +.next +.cindex "opendmarc" "acknowledgment" +The DMARC implementation uses the OpenDMARC library which is Copyrighted by +The Trusted Domain Project. Portions of Exim source which use OpenDMARC +derived code are indicated in the respective source files. The full OpenDMARC +license is provided in the LICENSE.opendmarc file contained in the distributed +source code. + .next Many people have contributed code fragments, some large, some small, that were not covered by any specific licence requirements. It is assumed that the -contributors are happy to see their code incoporated into Exim under the GPL. +contributors are happy to see their code incorporated into Exim under the GPL. .endlist @@ -818,11 +888,11 @@ contributors are happy to see their code incoporated into Exim under the GPL. . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// -.chapter "How Exim receives and delivers mail" "" &&& +.chapter "How Exim receives and delivers mail" "CHID11" &&& "Receiving and delivering mail" -.section "Overall philosophy" +.section "Overall philosophy" "SECID10" .cindex "design philosophy" Exim is designed to work efficiently on systems that are permanently connected to the Internet and are handling a general mix of mail. In such circumstances, @@ -832,7 +902,7 @@ it does try to send several messages in a single SMTP connection after a host has been down, and it also maintains per-host retry information. -.section "Policy control" +.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 @@ -861,7 +931,7 @@ spam scanning software. The result of such a scan is passed back to the ACL, which can then use it to decide what to do with the message. .next When a message has been received, either from a remote host or from the local -host, but before the final acknowledgement has been sent, a locally supplied C +host, but before the final acknowledgment has been sent, a locally supplied C function called &[local_scan()]& can be run to inspect the message and decide whether to accept it or not (see chapter &<>&). If the message is accepted, the list of recipients can be modified by the function. @@ -877,7 +947,7 @@ runs at the start of every delivery process. -.section "User filters" +.section "User filters" "SECID12" .cindex "filter" "introduction" .cindex "Sieve filter" In a conventional Exim configuration, users are able to run private filters by @@ -935,7 +1005,7 @@ received the message. .next There are two different possibilities for the final two characters: .olist -.cindex "&%localhost_number%&" +.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 that must use base 36 instead of base 62 (because of case-insensitive file @@ -954,7 +1024,7 @@ 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. -.section "Receiving mail" +.section "Receiving mail" "SECID13" .cindex "receiving mail" .cindex "message" "reception" The only way Exim can receive mail from another host is using SMTP over @@ -987,7 +1057,7 @@ in the same way as connections from other hosts. .endlist -.cindex "message sender" "constructed by Exim" +.cindex "message sender, constructed by Exim" .cindex "sender" "constructed by Exim" In the three cases that do not involve TCP/IP, the sender address is constructed from the login name of the user that called Exim and a default @@ -1020,7 +1090,7 @@ message is received. -.section "Handling an incoming message" +.section "Handling an incoming message" "SECID14" .cindex "spool directory" "files that hold a message" .cindex "file" "how a message is held" When Exim accepts a message, it writes two files in its spool directory. The @@ -1032,10 +1102,13 @@ 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 &_input_& inside the general Exim spool directory. Some operating systems do -not perform very well if the number of files in a directory gets very large; to +not perform very well if the number of files in a directory gets large; to improve performance in such cases, the &%split_spool_directory%& option can be used. This causes Exim to split up the input files into 62 sub-directories -whose names are single letters or digits. +whose names are single letters or digits. When this is done, the queue is +processed one sub-directory at a time instead of all at once, which can improve +overall performance even when there are not enough files in each directory to +affect file system performance. The envelope information consists of the address of the message's sender and the addresses of the recipients. This information is entirely separate from @@ -1058,7 +1131,7 @@ delivered (see chapters &<>& and -.section "Life of a message" +.section "Life of a message" "SECID15" .cindex "message" "life of" .cindex "message" "frozen" A message remains in the spool directory until it is completely delivered to @@ -1075,8 +1148,8 @@ corrected, and can also freeze individual messages by hand if necessary. In addition, an administrator can force a delivery error, causing a bounce message to be sent. -.cindex "&%timeout_frozen_after%&" -.cindex "&%ignore_bounce_errors_after%&" +.oindex "&%timeout_frozen_after%&" +.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. @@ -1183,7 +1256,7 @@ the address is bounced. -.section "Processing an address for verification" +.section "Processing an address for verification" "SECID16" .cindex "router" "for verification" .cindex "verifying address" "overview" As well as being used to decide how to deliver to an address, Exim's routers @@ -1218,7 +1291,7 @@ the following: &'accept'&: The router accepts the address, and either assigns it to a transport, or generates one or more &"child"& addresses. Processing the original address ceases, -.cindex "&%unseen%& option" +.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, for keeping archive copies of messages). When &%unseen%& is set, the address is @@ -1269,16 +1342,20 @@ when the relevant conditions are met. The &(redirect)& router has a &"fail"& facility for this purpose. -.section "Duplicate addresses" +.section "Duplicate addresses" "SECID17" .cindex "case of local parts" -.cindex "address duplicate" "discarding" +.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. +check, local parts are treated as case-sensitive. This happens only when +actually delivering a message; when testing routers with &%-bt%&, all the +routed addresses are shown. + .section "Router preconditions" "SECTrouprecon" -.cindex "router preconditions" "order of processing" +.cindex "router" "preconditions, order of processing" .cindex "preconditions" "order of processing" The preconditions that are tested for each router are listed below, in the order in which they are tested. The individual configuration options are @@ -1300,6 +1377,7 @@ Setting the &%verify%& option actually sets two options, &%verify_sender%& and &%verify_recipient%&, which independently control the use of the router for sender and recipient verification. You can set these options directly if you want a router to be used for only one type of verification. +Note that cutthrough delivery is classed as a recipient verification for this purpose. .next If the &%address_test%& option is set false, the router is skipped when Exim is run with the &%-bt%& option to test an address routing. This can be helpful @@ -1309,6 +1387,7 @@ having to simulate the effect of the scanner. .next Routers can be designated for use only when verifying an address, as opposed to routing it for delivery. The &%verify_only%& option controls this. +Again, cutthrough delivery counts as a verification. .next Individual routers can be explicitly skipped when running the routers to check an address given in the SMTP EXPN command (see the &%expn%& option). @@ -1316,9 +1395,9 @@ check an address given in the SMTP EXPN command (see the &%expn%& option). If the &%domains%& option is set, the domain of the address must be in the set of domains that it defines. .next -.cindex "&$local_part_prefix$&" -.cindex "&$local_part$&" -.cindex "&$local_part_suffix$&" +.vindex "&$local_part_prefix$&" +.vindex "&$local_part$&" +.vindex "&$local_part_suffix$&" If the &%local_parts%& option is set, the local part of the address must be in the set of local parts that it defines. If &%local_part_prefix%& or &%local_part_suffix%& is in use, the prefix or suffix is removed from the local @@ -1327,9 +1406,9 @@ 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. .next -.cindex "&$local_user_uid$&" -.cindex "&$local_user_gid$&" -.cindex "&$home$&" +.vindex "&$local_user_uid$&" +.vindex "&$local_user_gid$&" +.vindex "&$home$&" If the &%check_local_user%& option is set, the local part must be the name of an account on the local host. If this check succeeds, the uid and gid of the local user are placed in &$local_user_uid$& and &$local_user_gid$& and the @@ -1365,7 +1444,7 @@ example, &_.procmailrc_&). -.section "Delivery in detail" +.section "Delivery in detail" "SECID18" .cindex "delivery" "in detail" When a message is to be delivered, the sequence of events is as follows: @@ -1457,7 +1536,7 @@ deleted, though the message log can optionally be preserved if required. -.section "Retry mechanism" +.section "Retry mechanism" "SECID19" .cindex "delivery" "retry mechanism" .cindex "retry" "description of mechanism" .cindex "queue runner" @@ -1480,7 +1559,7 @@ as permanent. -.section "Temporary delivery failure" +.section "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 @@ -1495,8 +1574,7 @@ If a host is unreachable for a period of time, a number of messages may be waiting for it by the time it recovers, and sending them in a single SMTP connection is clearly beneficial. Whenever a delivery to a remote host is deferred, - -.cindex "hints database" +.cindex "hints database" "deferred deliveries" Exim makes a note in its hints database, and whenever a successful SMTP delivery has happened, it looks to see if any other messages are waiting for the same host. If any are found, they are sent over the same SMTP @@ -1505,8 +1583,7 @@ one connection. - -.section "Permanent delivery failure" +.section "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 @@ -1534,7 +1611,7 @@ of the list. -.section "Failures to deliver bounce messages" +.section "Failures to deliver bounce messages" "SECID22" .cindex "bounce message" "failure to deliver" If a bounce message (either locally generated or received from a remote host) itself suffers a permanent delivery failure, the message is left on the queue, @@ -1550,35 +1627,36 @@ for only a short time (see &%timeout_frozen_after%& and . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// -.chapter "Building and installing Exim" +.chapter "Building and installing Exim" "CHID3" .scindex IIDbuex "building Exim" -.section "Unpacking" -Exim is distributed as a gzipped or bzipped tar file which, when upacked, +.section "Unpacking" "SECID23" +Exim is distributed as a gzipped or bzipped tar file which, when unpacked, creates a directory with the name of the current release (for example, -&_exim-&version;_&) into which the following files are placed: +&_exim-&version()_&) into which the following files are placed: .table2 140pt -.row &_ACKNOWLEDGMENTS_& "contains some acknowledgments" -.row &_CHANGES_& "contains a reference to where changes are documented" -.row &_LICENCE_& "the GNU General Public Licence" -.row &_Makefile_& "top-level make file" -.row &_NOTICE_& "conditions for the use of Exim" -.row &_README_& "list of files, directories and simple build &&& - instructions" +.irow &_ACKNOWLEDGMENTS_& "contains some acknowledgments" +.irow &_CHANGES_& "contains a reference to where changes are &&& + documented" +.irow &_LICENCE_& "the GNU General Public Licence" +.irow &_Makefile_& "top-level make file" +.irow &_NOTICE_& "conditions for the use of Exim" +.irow &_README_& "list of files, directories and simple build &&& + instructions" .endtable Other files whose names begin with &_README_& may also be present. The following subdirectories are created: .table2 140pt -.row &_Local_& "an empty directory for local configuration files" -.row &_OS_& "OS-specific files" -.row &_doc_& "documentation files" -.row &_exim_monitor_& "source files for the Exim monitor" -.row &_scripts_& "scripts used in the build process" -.row &_src_& "remaining source files" -.row &_util_& "independent utilities" +.irow &_Local_& "an empty directory for local configuration files" +.irow &_OS_& "OS-specific files" +.irow &_doc_& "documentation files" +.irow &_exim_monitor_& "source files for the Exim monitor" +.irow &_scripts_& "scripts used in the build process" +.irow &_src_& "remaining source files" +.irow &_util_& "independent utilities" .endtable The main utility programs are contained in the &_src_& directory, and are built @@ -1586,7 +1664,7 @@ with the Exim binary. The &_util_& directory contains a few optional scripts that may be useful to some sites. -.section "Multiple machine architectures and operating systems" +.section "Multiple machine architectures and operating systems" "SECID24" .cindex "building Exim" "multiple OS/architectures" The building process for Exim is arranged to make it easy to build binaries for a number of different architectures and operating systems from the same set of @@ -1600,6 +1678,21 @@ architecture and operating system for itself, but the defaults can be overridden if necessary. +.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 +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 +and INCLUDE directives appropriately, +or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command. +If your operating system has no +PCRE support then you will need to obtain and build the current PCRE +from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). +More information on PCRE is available at &url(http://www.pcre.org/). + .section "DBM libraries" "SECTdb" .cindex "DBM libraries" "discussion of" .cindex "hints database" "DBM files used for" @@ -1609,9 +1702,9 @@ databases. Unfortunately, there are a number of DBM libraries in existence, and different operating systems often have different ones installed. .cindex "Solaris" "DBM library for" -.cindex "IRIX" "DBM library for" -.cindex "BSD" "DBM library for" -.cindex "Linux" "DBM library for" +.cindex "IRIX, DBM library for" +.cindex "BSD, DBM library for" +.cindex "Linux, DBM library for" If you are using Solaris, IRIX, one of the modern BSD systems, or a modern Linux distribution, the DBM configuration should happen automatically, and you may be able to ignore this section. Otherwise, you may have to learn more than @@ -1623,7 +1716,7 @@ via the &'ndbm'& interface, and this is what Exim expects by default. Free versions of Unix seem to vary in what they contain as standard. In particular, some early versions of Linux have no default DBM library, and different distributors have chosen to bundle different libraries with their packaged -versions. However, the more recent releases seem to have standardised on the +versions. However, the more recent releases seem to have standardized on the Berkeley DB library. Different DBM libraries have different conventions for naming the files they @@ -1702,7 +1795,7 @@ file &_doc/dbm.discuss.txt_& in the Exim distribution. -.section "Pre-building configuration" +.section "Pre-building configuration" "SECID25" .cindex "building Exim" "pre-building configuration" .cindex "configuration for building Exim" .cindex "&_Local/Makefile_&" @@ -1742,7 +1835,7 @@ chapter &<>&. .cindex "&_Local/eximon.conf_&" -.cindex "_exim_monitor/EDITME_" +.cindex "&_exim_monitor/EDITME_&" If you are going to build the Exim monitor, a similar configuration process is required. The file &_exim_monitor/EDITME_& must be edited appropriately for your installation and saved under the name &_Local/eximon.conf_&. If you are @@ -1758,7 +1851,7 @@ do this. -.section "Support for iconv()" +.section "Support for iconv()" "SECID26" .cindex "&[iconv()]& support" .cindex "RFC 2047" The contents of header lines in messages may be encoded according to the rules @@ -1766,7 +1859,7 @@ described RFC 2047. This makes it possible to transmit characters that are not in the ASCII character set, and to label them as being in a particular character set. When Exim is inspecting header lines by means of the &%$h_%& mechanism, it decodes them, and translates them into a specified character set -(default ISO-8859-1). The translation is possible only if the operating system +(default is set at build time). The translation is possible only if the operating system supports the &[iconv()]& function. However, some of the operating systems that supply &[iconv()]& do not support @@ -1809,6 +1902,12 @@ SUPPORT_TLS=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_PC=openssl +.endd .cindex "USE_GNUTLS" If GnuTLS is installed, you should set .code @@ -1824,6 +1923,14 @@ USE_GNUTLS=yes TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt TLS_INCLUDE=-I/usr/gnu/include .endd +.cindex "pkg-config" "GnuTLS" +If you have &'pkg-config'& available, then instead you can just use: +.code +SUPPORT_TLS=yes +USE_GNUTLS=yes +USE_GNUTLS_PC=gnutls +.endd + You do not need to set TLS_INCLUDE if the relevant directory is already specified in INCLUDE. Details of how to configure Exim to make use of TLS are given in chapter &<>&. @@ -1831,9 +1938,12 @@ given in chapter &<>&. -.section "Use of tcpwrappers" -.cindex "tcpwrappers" "building Exim to support" +.section "Use of tcpwrappers" "SECID27" + +.cindex "tcpwrappers, building Exim to support" .cindex "USE_TCP_WRAPPERS" +.cindex "TCP_WRAPPERS_DAEMON_NAME" +.cindex "tcp_wrappers_daemon_name" Exim can be linked with the &'tcpwrappers'& library in order to check incoming SMTP calls using the &'tcpwrappers'& control files. This may be a convenient alternative to Exim's own checking facilities for installations that are @@ -1848,19 +1958,21 @@ USE_TCP_WRAPPERS=yes CFLAGS=-O -I/usr/local/include EXTRALIBS_EXIM=-L/usr/local/lib -lwrap .endd -in &_Local/Makefile_&. The name to use in the &'tcpwrappers'& control files is -&"exim"&. For example, the line +in &_Local/Makefile_&. The daemon name to use in the &'tcpwrappers'& control +files is &"exim"&. For example, the line .code exim : LOCAL 192.168.1. .friendly.domain.example .endd in your &_/etc/hosts.allow_& file allows connections from the local host, from the subnet 192.168.1.0/24, and from all hosts in &'friendly.domain.example'&. -All other connections are denied. Consult the &'tcpwrappers'& documentation for +All other connections are denied. The daemon name used by &'tcpwrappers'& +can be changed at build time by setting TCP_WRAPPERS_DAEMON_NAME in +&_Local/Makefile_&, or by setting tcp_wrappers_daemon_name in the +configure file. Consult the &'tcpwrappers'& documentation for further details. - -.section "Including support for IPv6" +.section "Including support for IPv6" "SECID28" .cindex "IPv6" "including support for" Exim contains code for use on systems that have IPv6 support. Setting &`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included; @@ -1869,17 +1981,47 @@ where the IPv6 support is not fully integrated into the normal include and library files. Two different types of DNS record for handling IPv6 addresses have been -defined. AAAA records (analagous to A records for IPv4) are in use, and are +defined. AAAA records (analogous to A records for IPv4) are in use, and are currently seen as the mainstream. Another record type called A6 was proposed as better than AAAA because it had more flexibility. However, it was felt to be -over-complex, and its status was reduced to &"experimental"&. It is not known -if anyone is actually using A6 records. Exim has support for A6 records, but -this is included only if you set &`SUPPORT_A6=YES`& in &_Local/Makefile_&. The -support has not been tested for some time. - +over-complex, and its status was reduced to &"experimental"&. +Exim used to +have a compile option for including A6 record support but this has now been +withdrawn. + + + +.section "Dynamically loaded lookup module support" "SECTdynamicmodules" +.cindex "lookup modules" +.cindex "dynamic modules" +.cindex ".so building" +On some platforms, Exim supports not compiling all lookup types directly into +the main binary, instead putting some into external modules which can be loaded +on demand. +This permits packagers to build Exim with support for lookups with extensive +library dependencies without requiring all users to install all of those +dependencies. +Most, but not all, lookup types can be built this way. + +Set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be +installed; Exim will only load modules from that directory, as a security +measure. You will need to set &`CFLAGS_DYNAMIC`& if not already defined +for your OS; see &_OS/Makefile-Linux_& for an example. +Some other requirements for adjusting &`EXTRALIBS`& may also be necessary, +see &_src/EDITME_& for details. + +Then, for each module to be loaded dynamically, define the relevant +&`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes". +For example, this will build in lsearch but load sqlite and mysql support +on demand: +.code +LOOKUP_LSEARCH=yes +LOOKUP_SQLITE=2 +LOOKUP_MYSQL=2 +.endd -.section "The building process" +.section "The building process" "SECID29" .cindex "build directory" Once &_Local/Makefile_& (and &_Local/eximon.conf_&, if required) have been created, run &'make'& at the top level. It determines the architecture and @@ -1889,9 +2031,6 @@ For example, on a Sun system running Solaris 8, the directory .cindex "symbolic link" "to source files" Symbolic links to relevant source files are installed in the build directory. -&*Warning*&: The &%-j%& (parallel) flag must not be used with &'make'&; the -building process fails if it is set. - If this is the first time &'make'& has been run, it calls a script that builds a make file inside the build directory, using the configuration files from the &_Local_& directory. The new make file is then passed to another instance of @@ -1907,7 +2046,7 @@ FAQ, where some common problems are covered. -.section 'Output from &"make"&' +.section 'Output from &"make"&' "SECID283" The output produced by the &'make'& process for compile lines is often very unreadable, because these lines can be very long. For this reason, the normal output is suppressed by default, and instead output similar to that which @@ -1919,12 +2058,12 @@ FULLECHO='' make -e .endd The value of FULLECHO defaults to &"@"&, the flag character that suppresses command reflection in &'make'&. When you ask for the full output, it is -given in addition to the the short output. +given in addition to the short output. .section "Overriding build-time options for Exim" "SECToverride" -.cindex "build-time options" "overriding" +.cindex "build-time options, overriding" The main make file that is created at the beginning of the building process consists of the concatenation of a number of files which set configuration values, followed by a fixed set of &'make'& instructions. If a value is set @@ -2016,6 +2155,26 @@ files or libraries are required. When a lookup type is not included in the binary, attempts to configure Exim to use it cause run time configuration errors. +.cindex "pkg-config" "lookups" +.cindex "pkg-config" "authenticators" +Many systems now use a tool called &'pkg-config'& to encapsulate information +about how to compile against a library; Exim has some initial support for +being able to use pkg-config for lookups and authenticators. For any given +makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new +variable with the &`_PC`& suffix in the name and assign as the value the +name of the package to be queried. The results of querying via the +&'pkg-config'& command will be added to the appropriate Makefile variables +with &`+=`& directives, so your version of &'make'& will need to support that +syntax. For instance: +.code +LOOKUP_SQLITE=yes +LOOKUP_SQLITE_PC=sqlite3 +AUTH_GSASL=yes +AUTH_GSASL_PC=libgsasl +AUTH_HEIMDAL_GSSAPI=yes +AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi +.endd + .cindex "Perl" "including support for" Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines to be called during string expansion. To enable this facility, @@ -2025,7 +2184,7 @@ EXIM_PERL=perl.o must be defined in &_Local/Makefile_&. Details of this facility are given in chapter &<>&. -.cindex "X11 libraries" "location of" +.cindex "X11 libraries, location of" The location of the X11 libraries is something that varies a lot between operating systems, and there may be different versions of X11 to cope with. Exim itself makes no use of X11, but if you are compiling the Exim @@ -2067,7 +2226,7 @@ necessary to touch the associated non-optional file (that is, &_Local/Makefile_& or &_Local/eximon.conf_&) before rebuilding. -.section "OS-specific header files" +.section "OS-specific header files" "SECID30" .cindex "&_os.h_&" .cindex "building Exim" "OS-specific C header files" The &_OS_& directory contains a number of files with names of the form @@ -2078,8 +2237,8 @@ are porting Exim to a new operating system. -.section "Overriding build-time options for the monitor" -.cindex "building Eximon" "overriding default options" +.section "Overriding build-time options for the monitor" "SECID31" +.cindex "building Eximon" A similar process is used for overriding things when building the Exim monitor, where the files that are involved are .display @@ -2100,7 +2259,7 @@ LOG_DEPTH at run time. .ecindex IIDbuex -.section "Installing Exim binaries and scripts" +.section "Installing Exim binaries and scripts" "SECID32" .cindex "installing Exim" .cindex "BIN_DIRECTORY" The command &`make install`& runs the &(exim_install)& script with no @@ -2159,16 +2318,15 @@ but this usage is deprecated. .cindex "installing Exim" "what is not installed" Running &'make install'& does not copy the Exim 4 conversion script -&'convert4r4'&, or the &'pcretest'& test program. You will probably run the -first of these only once (if you are upgrading from Exim 3), and the second -isn't really part of Exim. None of the documentation files in the &_doc_& +&'convert4r4'&. You will probably run this only once if you are +upgrading from Exim 3. None of the documentation files in the &_doc_& directory are copied, except for the info files when you have set INFO_DIRECTORY, as described in section &<>& below. For the utility programs, old versions are renamed by adding the suffix &_.O_& to their names. The Exim binary itself, however, is handled differently. It is installed under a name that includes the version number and the compile number, -for example &_exim-&version;-1_&. The script then arranges for a symbolic link +for example &_exim-&version()-1_&. The script then arranges for a symbolic link called &_exim_& to point to the binary. If you are updating a previous version of Exim, the script takes care to ensure that the name &_exim_& is never absent from the directory (as seen by other processes). @@ -2225,7 +2383,7 @@ install`& automatically builds the info files and installs them. -.section "Setting up the spool directory" +.section "Setting up the spool directory" "SECID33" .cindex "spool directory" "creating" When it starts up, Exim tries to create its spool directory if it does not exist. The Exim uid and gid are used for the owner and group of the spool @@ -2235,7 +2393,7 @@ necessary. -.section "Testing" +.section "Testing" "SECID34" .cindex "testing" "installation" Having installed Exim, you can check that the run time configuration file is syntactically valid by running the following command, which assumes that the @@ -2316,7 +2474,7 @@ that Exim uses can be altered, in order to keep it entirely clear of the production version. -.section "Replacing another MTA with Exim" +.section "Replacing another MTA with Exim" "SECID35" .cindex "replacing another MTA" Building and installing Exim for the first time does not of itself put it in general use. The name by which the system's MTA is called by mail user agents @@ -2330,7 +2488,7 @@ a symbolic link to the &'exim'& binary. It is a good idea to remove any setuid privilege and executable status from the old MTA. It is then necessary to stop and restart the mailer daemon, if one is running. -.cindex "FreeBSD" "MTA indirection" +.cindex "FreeBSD, MTA indirection" .cindex "&_/etc/mail/mailer.conf_&" Some operating systems have introduced alternative ways of switching MTAs. For example, if you are running FreeBSD, you need to edit the file @@ -2356,7 +2514,7 @@ use of Exim's filtering capabilities, you should make the document entitled -.section "Upgrading Exim" +.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 @@ -2369,7 +2527,7 @@ configuration file. -.section "Stopping the Exim daemon on Solaris" +.section "Stopping the Exim daemon on Solaris" "SECID37" .cindex "Solaris" "stopping Exim on" The standard command for stopping the mailer daemon on Solaris is .code @@ -2406,7 +2564,7 @@ combinations of options do not make sense, and provoke an error if used. The form of the arguments depends on which options are set. -.section "Setting options by program name" +.section "Setting options by program name" "SECID38" .cindex "&'mailq'&" If Exim is called under the name &'mailq'&, it behaves as if the option &%-bp%& were present before any other options. @@ -2451,7 +2609,7 @@ EXIM_GROUP in &_Local/Makefile_& or set by the &%exim_user%& and &%exim_group%& options. These do not necessarily have to use the name &"exim"&. .ilist -.cindex "trusted user" "definition of" +.cindex "trusted users" "definition of" .cindex "user" "trusted definition of" The trusted users are root, the Exim user, any user listed in the &%trusted_users%& configuration option, and any user whose current group or any @@ -2468,6 +2626,8 @@ users to set envelope senders. .cindex "&'From:'& header line" .cindex "&'Sender:'& header line" +.cindex "header lines" "From:" +.cindex "header lines" "Sender:" For a trusted user, there is never any check on the contents of the &'From:'& header line, and a &'Sender:'& line is never added. Furthermore, any existing &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. @@ -2509,8 +2669,14 @@ getting root. There is further discussion of this issue at the start of chapter -.section "Command line options" -The command options are described in alphabetical order below. +.section "Command line options" "SECID39" +Exim's command line options are described in alphabetical order below. If none +of the options that specifies a specific action (such as starting the daemon or +a queue runner, or testing an address, or receiving a message in a specific +format, or listing the queue) are present, and there is at least one argument +on the command line, &%-bm%& (accept a local message on the standard input, +with the arguments specifying the recipients) is assumed. Otherwise, Exim +outputs a brief message about itself and exits. . //////////////////////////////////////////////////////////////////////////// . Insert a stylized XML comment here, to identify the start of the command line @@ -2537,6 +2703,18 @@ This option causes Exim to output a few sentences stating what it is. The same output is generated if the Exim binary is called with no options and no arguments. +.vitem &%--version%& +.oindex "&%--version%&" +This option is an alias for &%-bV%& and causes version information to be +displayed. + +.vitem &%-Ac%& &&& + &%-Am%& +.oindex "&%-Ac%&" +.oindex "&%-Am%&" +These options are used by Sendmail for selecting configuration files and are +ignored by Exim. + .vitem &%-B%&<&'type'&> .oindex "&%-B%&" .cindex "8-bit characters" @@ -2547,7 +2725,7 @@ clean; it ignores this option. .vitem &%-bd%& .oindex "&%-bd%&" .cindex "daemon" -.cindex "SMTP listener" +.cindex "SMTP" "listener" .cindex "queue runner" This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually the &%-bd%& option is combined with the &%-q%&<&'time'&> option, to specify @@ -2578,10 +2756,11 @@ used to specify a path on the command line if a pid file is required. The SIGHUP signal .cindex "SIGHUP" -can be used to cause the daemon to re-exec 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 of Exim -is installed. It is not necessary to do this when other files that are +.cindex "daemon" "restarting" +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 +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. @@ -2610,14 +2789,32 @@ continuations. As in Exim's run time configuration, white space at the start of continuation lines is ignored. Each argument or data line is passed through the string expansion mechanism, and the result is output. Variable values from the configuration file (for example, &$qualify_domain$&) are available, but no -message-specific values (such as &$domain$&) are set, because no message is -being processed. +message-specific values (such as &$message_exim_id$&) are set, because no message +is being processed (but see &%-bem%& and &%-Mset%&). &*Note*&: If you use this mechanism to test lookups, and you change the data files or databases you are using, you must exit and restart Exim before trying the same lookup again. Otherwise, because each Exim process caches the results of lookups, you will just get the same result as before. +.vitem &%-bem%&&~<&'filename'&> +.oindex "&%-bem%&" +.cindex "testing" "string expansion" +.cindex "expansion" "testing" +This option operates like &%-be%& except that it must be followed by the name +of a file. For example: +.code +exim -bem /tmp/testmessage +.endd +The file is read as a message (as if receiving a locally-submitted non-SMTP +message) before any of the test expansions are done. Thus, message-specific +variables such as &$message_size$& and &$header_from:$& are available. However, +no &'Received:'& header is added to the message. If the &%-t%& option is set, +recipients are read from the headers in the normal way, and are shown in the +&$recipients$& variable. Note that recipients cannot be given on the command +line, because further arguments are taken as strings to expand (just like +&%-be%&). + .vitem &%-bF%&&~<&'filename'&> .oindex "&%-bF%&" .cindex "system filter" "testing" @@ -2665,7 +2862,7 @@ separate document entitled &'Exim's interfaces to mail filtering'&. When testing a filter file, .cindex "&""From""& line" .cindex "envelope sender" -.cindex "&%-f%& option" "for filter testing" +.oindex "&%-f%&" "for filter testing" the envelope sender can be set by the &%-f%& option, or by a &"From&~"& line at the start of the test message. Various parameters that would normally be taken from the envelope recipient address of the message @@ -2674,7 +2871,7 @@ options). .vitem &%-bfd%&&~<&'domain'&> .oindex "&%-bfd%&" -.cindex "&$qualify_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$&. @@ -2727,9 +2924,10 @@ test your relay controls using &%-bh%&. &*Warning 1*&: .cindex "RFC 1413" -You cannot test features of the configuration that rely on -ident (RFC 1413) callouts. These cannot be done when testing using -&%-bh%& because there is no incoming SMTP connection. +You can test features of the configuration that rely on ident (RFC 1413) +information by using the &%-oMt%& option. However, Exim cannot actually perform +an ident callout when testing using &%-bh%& because there is no incoming SMTP +connection. &*Warning 2*&: Address verification callouts (see section &<>&) are also skipped when testing using &%-bh%&. If you want these callouts to @@ -2738,12 +2936,19 @@ occur, use &%-bhc%& instead. Messages supplied during the testing session are discarded, and nothing is written to any of the real log files. There may be pauses when DNS (and other) lookups are taking place, and of course these may time out. The &%-oMi%& option -can be used to specify a specific IP interface and port if this is important. +can be used to specify a specific IP interface and port if this is important, +and &%-oMaa%& and &%-oMai%& can be used to set parameters as if the SMTP +session were authenticated. The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose output just states whether a given recipient address from a given host is acceptable or not. See section &<>&. +Features such as authentication and encryption, where the client input is not +plain text, cannot easily be tested with &%-bh%&. Instead, you should use a +specialized SMTP test program such as +&url(http://jetmore.org/john/code/#swaks,swaks). + .vitem &%-bhc%&&~<&'IP&~address'&> .oindex "&%-bhc%&" This option operates in the same way as &%-bh%&, except that address @@ -2769,11 +2974,37 @@ use the &'exim_dbmbuild'& utility, or some other means, to rebuild alias files if this is required. If the &%bi_command%& option is not set, calling Exim with &%-bi%& is a no-op. +. // Keep :help first, then the rest in alphabetical order +.vitem &%-bI:help%& +.oindex "&%-bI:help%&" +.cindex "querying exim information" +We shall provide various options starting &`-bI:`& for querying Exim for +information. The output of many of these will be intended for machine +consumption. This one is not. The &%-bI:help%& option asks Exim for a +synopsis of supported options beginning &`-bI:`&. Use of any of these +options shall cause Exim to exit after producing the requested output. + +.vitem &%-bI:dscp%& +.oindex "&%-bI:dscp%&" +.cindex "DSCP" "values" +This option causes Exim to emit an alphabetically sorted list of all +recognised DSCP names. + +.vitem &%-bI:sieve%& +.oindex "&%-bI:sieve%&" +.cindex "Sieve filter" "capabilities" +This option causes Exim to emit an alphabetically sorted list of all supported +Sieve protocol extensions on stdout, one per line. This is anticipated to be +useful for ManageSieve (RFC 5804) implementations, in providing that protocol's +&`SIEVE`& capability response line. As the precise list may depend upon +compile-time build options, which this option will adapt to, this is the only +way to guarantee a correct response. + .vitem &%-bm%& .oindex "&%-bm%&" .cindex "local message reception" This option runs an Exim receiving process that accepts an incoming, -locally-generated message on the current input. The recipients are given as the +locally-generated message on the standard input. The recipients are given as the command arguments (except when &%-t%& is also present &-- see below). Each argument can be a comma-separated list of RFC 2822 addresses. This is the default option for selecting the overall action of an Exim call; it is assumed @@ -2809,16 +3040,36 @@ authoritative specification of the format of this line. Exim recognizes it by matching against the regular expression defined by the &%uucp_from_pattern%& option, which can be changed if necessary. -The -.cindex "&%-f%& option" "overriding &""From""& line" -specified sender is treated as if it were given as the argument to the +.oindex "&%-f%&" "overriding &""From""& line" +The specified sender is treated as if it were given as the argument to the &%-f%& option, but if a &%-f%& option is also present, its argument is used in preference to the address taken from the message. The caller of Exim must be a trusted user for the sender of a message to be set in this way. +.vitem &%-bmalware%&&~<&'filename'&> +.oindex "&%-bmalware%&" +.cindex "testing", "malware" +.cindex "malware scan test" +This debugging option causes Exim to scan the given file or directory +(depending on the used scanner interface), +using the malware scanning framework. The option of &%av_scanner%& influences +this option, so if &%av_scanner%&'s value is dependent upon an expansion then +the expansion should have defaults which apply to this invocation. ACLs are +not invoked, so if &%av_scanner%& references an ACL variable then that variable +will never be populated and &%-bmalware%& will fail. + +Exim will have changed working directory before resolving the filename, so +using fully qualified pathnames is advisable. Exim will be running as the Exim +user when it tries to open the file, rather than as the invoking user. +This option requires admin privileges. + +The &%-bmalware%& option will not be extended to be more generally useful, +there are better tools for file-scanning. This option exists to help +administrators verify their Exim and AV scanner configuration. + .vitem &%-bnq%& .oindex "&%-bnq%&" -.cindex "address qualification" "suppressing" +.cindex "address qualification, suppressing" By default, Exim automatically qualifies unqualified addresses (those without domains) that appear in messages that are submitted locally (that is, not over TCP/IP). This qualification applies both to addresses in @@ -2849,17 +3100,28 @@ arguments, for example: .code exim -bP qualify_domain hold_domains .endd +.cindex "hiding configuration option values" +.cindex "configuration options" "hiding value of" +.cindex "options" "hiding value of" However, any option setting that is preceded by the word &"hide"& in the configuration file is not shown in full, except to an admin user. For other users, the output is as in this example: .code mysql_servers = .endd -If &%configure_file%& is given as an argument, the name of the run time -configuration file is output. +If &%config%& is given as an argument, the config is +output, as it was parsed, any include file resolved, any comment removed. + +If &%config_file%& is given as an argument, the name of the run time +configuration file is output. (&%configure_file%& works too, for +backward compatibility.) If a list of configuration files was supplied, the value that is output here is the name of the file that was actually used. +.cindex "options" "hiding name of" +If the &%-n%& flag is given, then for most modes of &%-bP%& operation the +name will not be output. + .cindex "daemon" "process id (pid)" .cindex "pid (process id)" "of daemon" If &%log_file_path%& or &%pid_file_path%& are given, the names of the @@ -2877,6 +3139,7 @@ local part) and outputs what it finds. .cindex "options" "router &-- extracting" .cindex "options" "transport &-- extracting" +.cindex "options" "authenticator &-- extracting" If one of the words &%router%&, &%transport%&, or &%authenticator%& is given, followed by the name of an appropriate driver instance, the option settings for that driver are output. For example: @@ -2890,6 +3153,16 @@ using one of the words &%router_list%&, &%transport_list%&, or settings can be obtained by using &%routers%&, &%transports%&, or &%authenticators%&. +.cindex "environment" +If &%environment%& is given as an argument, the set of environment +variables is output, line by line. Using the &%-n%& flag suppresses the value of the +variables. + +.cindex "options" "macro &-- extracting" +If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& +are available, similarly to the drivers. Because macros are sometimes used +for storing passwords, this option is restricted. +The output format is one item per line. .vitem &%-bp%& .oindex "&%-bp%&" @@ -2980,7 +3253,6 @@ and to write it to the standard output. For example: exim -brt bach.comp.mus.example Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; .endd -.new See chapter &<>& for a description of Exim's retry rules. The first argument, which is required, can be a complete address in the form &'local_part@domain'&, or it can be just a domain name. If the second argument @@ -2994,7 +3266,6 @@ used in setting up retry rules, can be given. For example: exim -brt haydn.comp.mus.example quota_3d Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m .endd -.wen .vitem &%-brw%& .oindex "&%-brw%&" @@ -3074,10 +3345,10 @@ the listening daemon. .cindex "testing" "addresses" .cindex "address" "testing" This option runs Exim in address testing mode, in which each argument is taken -as an address to be tested for deliverability. The results are written to the -standard output. If a test fails, and the caller is not an admin user, no -details of the failure are output, because these might contain sensitive -information such as usernames and passwords for database lookups. +as a recipient address to be tested for deliverability. The results are +written to the standard output. If a test fails, and the caller is not an admin +user, no details of the failure are output, because these might contain +sensitive information such as usernames and passwords for database lookups. If no arguments are given, Exim runs in an interactive manner, prompting with a right angle bracket for addresses to be tested. @@ -3093,16 +3364,21 @@ written to the standard output. However, any router that has genuine routing tests if your first router passes everything to a scanner program. -The .cindex "return code" "for &%-bt%&" -return code is 2 if any address failed outright; it is 1 if no address +The return code is 2 if any address failed outright; it is 1 if no address failed outright but at least one could not be resolved for some reason. Return code 0 is given only when all addresses succeed. +.cindex "duplicate addresses" +&*Note*&: When actually delivering a message, Exim removes duplicate recipient +addresses after routing is complete, so that only one delivery takes place. +This does not happen when testing with &%-bt%&; the full results of routing are +always shown. + &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the routers in the configuration makes any tests on the sender address of a message, -.cindex "&%-f%& option" "for address testing" +.oindex "&%-f%&" "for address testing" you can use the &%-f%& option to set an appropriate sender when running &%-bt%& tests. Without it, the sender is assumed to be the calling user at the default qualifying domain. However, if you have set up (for example) routers @@ -3112,10 +3388,10 @@ doing such tests. .vitem &%-bV%& .oindex "&%-bV%&" -.cindex "version number of Exim" "verifying" +.cindex "version number of Exim" This option causes Exim to write the current version number, compilation number, and compilation date of the &'exim'& binary to the standard output. -It also lists the DBM library this is being used, the optional modules (such as +It also lists the DBM library that is being used, the optional modules (such as specific lookup types), the drivers that are included in the binary, and the name of the run time configuration file that is in use. @@ -3132,10 +3408,11 @@ dynamic testing facilities. .cindex "verifying address" "using &%-bv%&" .cindex "address" "verification" This option runs Exim in address verification mode, in which each argument is -taken as an address to be verified. During normal operation, verification +taken as a recipient address to be verified by the routers. (This does +not involve any verification callouts). During normal operation, verification happens mostly as a consequence processing a &%verify%& condition in an ACL -(see chapter &<>&). If you want to test an entire ACL, see the &%-bh%& -option. +(see chapter &<>&). If you want to test an entire ACL, possibly +including callouts, see the &%-bh%& and &%-bhc%& options. If verification fails, and the caller is not an admin user, no details of the failure are output, because these might contain sensitive information such as @@ -3156,10 +3433,15 @@ address, &%-bvs%& should be used. If the &%-v%& option is not set, the output consists of a single line for each address, stating whether it was verified or not, and giving a reason in the -latter case. Otherwise, more details are given of how the address has been -handled, and in the case of address redirection, all the generated addresses -are also considered. Without &%-v%&, generating more than one address by -redirection causes verification to end successfully. +latter case. Without &%-v%&, generating more than one address by redirection +causes verification to end successfully, without considering the generated +addresses. However, if just one address is generated, processing continues, +and the generated address must verify successfully for the overall verification +to succeed. + +When &%-v%& is set, more details are given of how the address has been handled, +and in the case of address redirection, all the generated addresses are also +considered. Verification may succeed for some and fail for others. The .cindex "return code" "for &%-bv%&" @@ -3178,6 +3460,23 @@ This option acts like &%-bv%&, but verifies the address as a sender rather than a recipient address. This affects any rewriting and qualification that might happen. +.vitem &%-bw%& +.oindex "&%-bw%&" +.cindex "daemon" +.cindex "inetd" +.cindex "inetd" "wait mode" +This option runs Exim as a daemon, awaiting incoming SMTP connections, +similarly to the &%-bd%& option. All port specifications on the command-line +and in the configuration file are ignored. Queue-running may not be specified. + +In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is +listening for connections. This permits the system to start up and have +inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for +each port only when the first connection is received. + +If the option is given as &%-bw%&<&'time'&> then the time is a timeout, after +which the daemon will exit, which should cause inetd to listen once more. + .vitem &%-C%&&~<&'filelist'&> .oindex "&%-C%&" .cindex "configuration file" "alternate" @@ -3190,25 +3489,23 @@ name, but it can be a colon-separated list of names. In this case, the first file that exists is used. Failure to open an existing file stops Exim from proceeding any further along the list, and an error is generated. -When this option is used by a caller other than root or the Exim user, and the -list is different from the compiled-in list, Exim gives up its root privilege -immediately, and runs with the real and effective uid and gid set to those of -the caller. However, if ALT_CONFIG_ROOT_ONLY is defined in -&_Local/Makefile_&, root privilege is retained for &%-C%& only if the caller of -Exim is root. - -That is, the Exim user is no longer privileged in this regard. This build-time -option is not set by default in the Exim source distribution tarbundle. -However, if you are using a &"packaged"& version of Exim (source or binary), -the packagers might have enabled it. - -Setting ALT_CONFIG_ROOT_ONLY locks out the possibility of testing a -configuration using &%-C%& right through message reception and delivery, even -if the caller is root. The reception works, but by that time, Exim is running -as the Exim user, so when it re-executes to regain privilege for the delivery, -the use of &%-C%& causes privilege to be lost. However, root can test reception -and delivery using two separate commands (one to put a message on the queue, -using &%-odq%&, and another to do the delivery, using &%-M%&). +When this option is used by a caller other than root, and the list is different +from the compiled-in list, Exim gives up its root privilege immediately, and +runs with the real and effective uid and gid set to those of the caller. +However, if a TRUSTED_CONFIG_LIST file is defined in &_Local/Makefile_&, that +file contains a list of full pathnames, one per line, for configuration files +which are trusted. Root privilege is retained for any configuration file so +listed, as long as the caller is the Exim user (or the user specified in the +CONFIGURE_OWNER option, if any), and as long as the configuration file is +not writeable by inappropriate users or groups. + +Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a +configuration using &%-C%& right through message reception and delivery, +even if the caller is root. The reception works, but by that time, Exim is +running as the Exim user, so when it re-executes to regain privilege for the +delivery, the use of &%-C%& causes privilege to be lost. However, root can +test reception and delivery using two separate commands (one to put a message +on 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 @@ -3229,6 +3526,7 @@ caller is privileged, or unless it is an exotic configuration that does not require privilege. No check is made on the owner or group of the files specified by this option. + .vitem &%-D%&<&'macro'&>=<&'value'&> .oindex "&%-D%&" .cindex "macro" "setting on command line" @@ -3238,6 +3536,14 @@ unprivileged caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is completely disabled, and its use causes an immediate error exit. +If WHITELIST_D_MACROS is defined in &_Local/Makefile_& then it should be a +colon-separated list of macros which are considered safe and, if &%-D%& only +supplies macros from this list, and the values are acceptable, then Exim will +not give up root privilege if the caller is root, the Exim run-time user, or +the CONFIGURE_OWNER, if set. This is a transition mechanism and is expected +to be removed in the future. Acceptable values for the macros satisfy the +regexp: &`^[A-Za-z0-9_/.-]*$`& + The entire option (including equals sign if present) must all be within one command line item. &%-D%& can be used to set the value of a macro to the empty string, in which case the equals sign is optional. These two commands are @@ -3253,6 +3559,8 @@ example: exim '-D ABC = something' ... .endd &%-D%& may be repeated up to 10 times on a command line. +Only macro names up to 22 letters long can be set. + .vitem &%-d%&<&'debug&~options'&> .oindex "&%-d%&" @@ -3261,14 +3569,18 @@ exim '-D ABC = something' ... This option causes debugging information to be written to the standard error stream. It is restricted to admin users because debugging output may show database queries that contain password information. Also, the details of users' -filter files should be protected. When &%-d%& is used, &%-v%& is assumed. If -&%-d%& is given on its own, a lot of standard debugging data is output. This -can be reduced, or increased to include some more rarely needed information, by -directly following &%-d%& with a string made up of names preceded by plus or -minus characters. These add or remove sets 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: +filter files should be protected. If a non-admin user uses &%-d%&, Exim +writes an error message to the standard error stream and exits with a non-zero +return code. + +When &%-d%& is used, &%-v%& is assumed. If &%-d%& is given on its own, a lot of +standard debugging data is output. This can be reduced, or increased to include +some more rarely needed information, by directly following &%-d%& with a string +made up of names preceded by plus or minus characters. These add or remove sets +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 @@ -3310,8 +3622,8 @@ is included, an awful lot of output that is very rarely of interest is generated, so it now has to be explicitly requested. However, &`-all`& does turn everything off. -.cindex "resolver" "debugging output" -.cindex "DNS resolver" "debugging output" +.cindex "resolver, debugging output" +.cindex "DNS resolver, debugging output" The &`resolver`& option produces output only if the DNS resolver was compiled with DEBUG enabled. This is not the case in some operating systems. Also, unfortunately, debugging output from the DNS resolver is written to stdout @@ -3376,7 +3688,7 @@ between &%-F%& and the <&'string'&> is optional. .oindex "&%-f%&" .cindex "sender" "address" .cindex "address" "sender" -.cindex "trusted user" +.cindex "trusted users" .cindex "envelope sender" .cindex "user" "trusted" This option sets the address of the envelope sender of a locally-generated @@ -3418,8 +3730,17 @@ if &%-f%& is also present, it overrides &"From&~"&. .vitem &%-G%& .oindex "&%-G%&" -.cindex "Sendmail compatibility" "&%-G%& option ignored" -This is a Sendmail option which is ignored by Exim. +.cindex "submission fixups, suppressing (command-line)" +This option is equivalent to an ACL applying: +.code +control = suppress_local_fixups +.endd +for every message received. Note that Sendmail will complain about such +bad formatting, where Exim silently just does not fix it up. This may change +in future. + +As this affects audit information, the caller must be a trusted user to use +this option. .vitem &%-h%&&~<&'number'&> .oindex "&%-h%&" @@ -3431,12 +3752,23 @@ headers.) .vitem &%-i%& .oindex "&%-i%&" .cindex "Solaris" "&'mail'& command" -.cindex "dot in incoming" "non-SMTP message" +.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%&. +.vitem &%-L%&&~<&'tag'&> +.oindex "&%-L%&" +.cindex "syslog" "process name; set with flag" +This option is equivalent to setting &%syslog_processname%& in the config +file and setting &%log_file_path%& to &`syslog`&. +Its use is restricted to administrators. The configuration file has to be +read and parsed, to determine access rights, before this is set and takes +effect, so early configuration file errors will not honour this flag. + +The tag should not be longer than 32 characters. + .vitem &%-M%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-M%&" .cindex "forcing delivery" @@ -3488,6 +3820,18 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option. It signifies that the connection to the remote host has been authenticated. +.vitem &%-MCD%& +.oindex "&%-MCD%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that the +remote host supports the ESMTP &_DSN_& extension. + +.vitem &%-MCG%& +.oindex "&%-MCG%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that an +alternate queue is used, named by the following option. + .vitem &%-MCP%& .oindex "&%-MCP%&" This option is not intended for use by external callers. It is used internally @@ -3597,6 +3941,18 @@ 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. +.vitem &%-Mset%&&~<&'message&~id'&> +.oindex "&%-Mset%& +.cindex "testing" "string expansion" +.cindex "expansion" "testing" +This option is useful only in conjunction with &%-be%& (that is, when testing +string expansions). Exim loads the given message from its spool before doing +the test expansions, thus setting message-specific variables such as +&$message_size$& and the header variables. The &$recipients$& variable is made +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%&" .cindex "thawing messages" @@ -3615,6 +3971,14 @@ by an admin user. 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%&" +.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%&" .cindex "listing" "message headers" @@ -3657,9 +4021,10 @@ for that message. .vitem &%-n%& .oindex "&%-n%&" -.cindex "Sendmail compatibility" "&%-n%& option ignored" -This option is interpreted by Sendmail to mean &"no aliasing"&. It is ignored -by Exim. +This option is interpreted by Sendmail to mean &"no aliasing"&. +For normal modes of operation, it is ignored by Exim. +When combined with &%-bP%& it makes the output more terse (suppresses +option names, environment values and config pretty printing). .vitem &%-O%&&~<&'data'&> .oindex "&%-O%&" @@ -3773,8 +4138,8 @@ message. Provided this error message is successfully sent, the Exim receiving process exits with a return code of zero. If not, the return code is 2 if the problem -is that the original message has no recipients, or 1 any other error. This is -the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. +is that the original message has no recipients, or 1 for any other error. +This is the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. .vitem &%-oem%& .oindex "&%-oem%&" @@ -3806,7 +4171,7 @@ effect as &%-oem%&. .vitem &%-oi%& .oindex "&%-oi%&" -.cindex "dot in incoming" "non-SMTP message" +.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 single dot does terminate, though Exim does no special processing for other @@ -3819,7 +4184,7 @@ This option is treated as synonymous with &%-oi%&. .vitem &%-oMa%&&~<&'host&~address'&> .oindex "&%-oMa%&" -.cindex "sender host address" "specifying for local message" +.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 over TCP/IP). These options can be used by any caller in conjunction with the @@ -3837,56 +4202,77 @@ followed by a colon and the port number: exim -bs -oMa [10.9.8.7]:1234 .endd The IP address is placed in the &$sender_host_address$& variable, and the -port, if present, in &$sender_host_port$&. +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%&" -.cindex "authentication name" "specifying for local message" +.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 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%&" -.cindex "authentication id" "specifying for local message" +.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). -This overrides the default value (the caller's login id) for messages from -local sources. See chapter &<>& for a discussion of authenticated -ids. +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%&" -.cindex "authentication sender" "specifying for local message" +.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 overrides the sender address that is created from the caller's login id for -messages from local sources. See chapter &<>& for a discussion of -authenticated senders. +messages from local sources, except when &%-bh%& is used, when there is no +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%&" -.cindex "interface address" "specifying for local message" +.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 -&$interface_address$& and the port number, if present, in &$interface_port$&. +&$received_ip_address$& and the port number, if present, in &$received_port$&. + +.vitem &%-oMm%&&~<&'message&~reference'&> +.oindex "&%-oMm%&" +.cindex "message reference" "message reference, specifying for local message" +See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMm%& +option sets the message reference, e.g. message-id, and is logged during +delivery. This is useful when some kind of audit trail is required to tie +messages together. The format of the message reference is checked and will +abort if the format is invalid. The option will only be accepted if exim is +running in trusted mode, not as any regular user. + +The best example of a message reference is when Exim sends a bounce message. +The message reference is the message-id of the original message for which Exim +is sending the bounce. .vitem &%-oMr%&&~<&'protocol&~name'&> .oindex "&%-oMr%&" -.cindex "protocol" "incoming &-- specifying for local message" -.cindex "&$received_protocol$&" +.cindex "protocol, specifying for local message" +.vindex "&$received_protocol$&" See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%& option sets the received protocol value that is stored in -&$received_protocol$&. However, this applies only when &%-bs%& is not used. For -interactive SMTP input (&%-bs%&), the protocol is always &"local-"& followed by -one of the standard SMTP protocol names (see the description of -&$received_protocol$& in section &<>&). For &%-bS%& (batch SMTP) -however, the protocol can be set by &%-oMr%&. +&$received_protocol$&. However, it does not apply (and is ignored) when &%-bh%& +or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard +SMTP protocol names (see the description of &$received_protocol$& in section +&<>&). For &%-bs%&, the protocol is always &"local-"& followed by +one of those same names. For &%-bS%& (batched SMTP) however, the protocol can +be set by &%-oMr%&. .vitem &%-oMs%&&~<&'host&~name'&> .oindex "&%-oMs%&" -.cindex "sender host name" "specifying for local message" +.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 @@ -3894,10 +4280,11 @@ uses the name it is given. .vitem &%-oMt%&&~<&'ident&~string'&> .oindex "&%-oMt%&" -.cindex "sender ident string" "specifying for local message" +.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. +local callers is the login id of the calling process, except when &%-bh%& is +used, when there is no default. .vitem &%-om%& .oindex "&%-om%&" @@ -3933,7 +4320,7 @@ described in section &<>&. .vitem &%-os%&&~<&'time'&> .oindex "&%-os%&" .cindex "timeout" "for SMTP input" -.cindex "SMTP timeout" "input" +.cindex "SMTP" "input timeout" This option sets a timeout value for incoming SMTP messages. The timeout 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 @@ -3979,7 +4366,7 @@ For compatibility with Sendmail, this option is equivalent to It sets the incoming protocol and host name (for trusted callers). The host name and its colon can be omitted when only the protocol is to be set. Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer -to embedded Perl. It is therefore impossible to set a protocol value of &`p`& +to embedded Perl. It is therefore impossible to set a protocol value of &`d`& or &`s`& using this option (but that does not seem a real limitation). .vitem &%-q%& @@ -3991,7 +4378,8 @@ relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, and &%-S%& options). .cindex "queue runner" "description of operation" -The &%-q%& option starts one queue runner process. This scans the queue of +If other commandline options do not specify an action, +the &%-q%& option starts one queue runner process. This scans the queue of waiting messages, and runs a delivery process for each one in turn. It waits for each delivery process to finish before starting the next one. A delivery process may not actually do any deliveries if the retry times for the addresses @@ -4076,8 +4464,27 @@ 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 for later delivery. -.vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&> +.vitem &%-q[q][i][f[f]][l][G[/