From 980bb6b778928aeb9401bafc9e1a00c184fb5ff0 Mon Sep 17 00:00:00 2001 From: Jeremy Harris Date: Sat, 1 Aug 2020 17:22:48 +0100 Subject: [PATCH] Testsuite: add EAI local-part testcase --- doc/doc-docbook/spec.xfpt | 3 + doc/doc-docbook/spec.xfpt.readsock | 41682 +++++++++++++++++++++++++++ test/confs/0024 | 9 + test/log/0024 | 1 + test/scripts/0000-Basic/0024 | 2 + test/stdout/0024 | 1 + 6 files changed, 41698 insertions(+) create mode 100644 doc/doc-docbook/spec.xfpt.readsock diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 73420473f..37bfeb3f3 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -9451,6 +9451,9 @@ become case-sensitive after &"+caseful"& has been seen. .section "Local part lists" "SECTlocparlis" .cindex "list" "local part list" .cindex "local part" "list" +These behave in the same way as domain and host lists, with the following +changes: + Case-sensitivity in local part lists is handled in the same way as for address lists, as just described. The &"+caseful"& item can be used if required. In a setting of the &%local_parts%& option in a router with &%caseful_local_part%& diff --git a/doc/doc-docbook/spec.xfpt.readsock b/doc/doc-docbook/spec.xfpt.readsock new file mode 100644 index 000000000..2f7dad340 --- /dev/null +++ b/doc/doc-docbook/spec.xfpt.readsock @@ -0,0 +1,41682 @@ +. ///////////////////////////////////////////////////////////////////////////// +. This is the primary source of the Exim Manual. It is an xfpt document that is +. converted into DocBook XML for subsequent conversion into printable and online +. 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 generates the outermost element that wraps the entire document. +. ///////////////////////////////////////////////////////////////////////////// + +.book + +. ///////////////////////////////////////////////////////////////////////////// +. These definitions set some parameters and save some typing. +. Update the Copyright year (only) when changing content. +. ///////////////////////////////////////////////////////////////////////////// + +.set previousversion "4.93" +.include ./local_params + +.set ACL "access control lists (ACLs)" +.set I "    " + +.macro copyyear +2019 +.endmacro + +. ///////////////////////////////////////////////////////////////////////////// +. Additional xfpt markup used by this document, over and above the default +. provided in the xfpt library. +. ///////////////////////////////////////////////////////////////////////////// + +. --- Override the &$ flag to automatically insert a $ with the variable name. + +.flag &$ $& "$" "" + +. --- Short flags for daggers in option headings. They will always be inside +. --- an italic string, but we want the daggers to be in Roman. + +.flag &!! "†" +.flag &!? "‡" + +. --- A macro for an Exim option definition heading, generating a one-line +. --- 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 +.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 + +. --- A macro for the common 2-column tables. The width of the first column +. --- is suitable for the many tables at the start of the main options chapter; +. --- a small number of other 2-column tables override it. + +.macro table2 196pt 254pt +.itable none 0 0 2 $1 left $2 left +.endmacro + +. --- A macro 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 +&& +&&$1&& +.arg 2 +&&$2&& +.endarg +&& +.endmacro + +.macro scindex +&& +&&$2&& +.arg 3 +&&$3&& +.endarg +&& +.endmacro + +.macro ecindex +&& +.endmacro + +.macro oindex +&& +&&$1&& +.arg 2 +&&$2&& +.endarg +&& +.endmacro + +.macro vindex +&& +&&$1&& +.arg 2 +&&$2&& +.endarg +&& +.endmacro + +.macro index +.echo "** Don't use .index; use .cindex or .oindex or .vindex" +.endmacro +. //////////////////////////////////////////////////////////////////////////// + + +. //////////////////////////////////////////////////////////////////////////// +. The element is removed from the XML before processing for ASCII +. output formats. +. //////////////////////////////////////////////////////////////////////////// + +.literal xml + +Specification of the Exim Mail Transfer Agent +The Exim MTA + +.fulldate + +EximMaintainers +EM + +.versiondatexml + EM + + +.copyyear + University of Cambridge + +.literal off + + +. ///////////////////////////////////////////////////////////////////////////// +. This chunk of literal XML implements index entries of the form "x, see y" and +. "x, see also y". However, the DocBook DTD doesn't allow entries +. at the top level, so we have to put the .chapter directive first. +. ///////////////////////////////////////////////////////////////////////////// + +.chapter "Introduction" "CHID1" +.literal xml + + + $1, $2, etc. + numerical variables + + + address + rewriting + rewriting + + + Bounce Address Tag Validation + BATV + + + Client SMTP Authorization + CSA + + + CR character + carriage return + + + CRL + certificate revocation list + + + delivery + failure report + bounce message + + + dialup + intermittently connected hosts + + + exiscan + content scanning + + + failover + fallback + + + fallover + fallback + + + filter + Sieve + Sieve filter + + + ident + RFC 1413 + + + LF character + linefeed + + + maximum + limit + + + monitor + Exim monitor + + + no_xxx + entry for xxx + + + NUL + binary zero + + + passwd file + /etc/passwd + + + process id + pid + + + RBL + DNS list + + + redirection + address redirection + + + return path + envelope sender + + + scanning + content scanning + + + SSL + TLS + + + string + expansion + expansion + + + top bit + 8-bit characters + + + variables + expansion, variables + + + zero, binary + binary zero + + +.literal off + + +. ///////////////////////////////////////////////////////////////////////////// +. This is the real start of the first chapter. See the comment above as to why +. we can't have the .chapter line here. +. chapter "Introduction" +. ///////////////////////////////////////////////////////////////////////////// + +Exim is a mail transfer agent (MTA) for hosts that are running Unix or +Unix-like operating systems. It was designed on the assumption that it would be +run on hosts that are permanently connected to the Internet. However, it can be +used on intermittently connected hosts with suitable configuration adjustments. + +Configuration files currently exist for the following operating systems: AIX, +BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, +GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, +OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, +Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare. +Some of these operating systems are no longer current and cannot easily be +tested, so the configuration files may no longer work in practice. + +There are also configuration files for compiling Exim in the Cygwin environment +that can be installed on systems running Windows. However, this document does +not contain any information about running Exim in the Cygwin environment. + +The terms and conditions for the use and distribution of Exim are contained in +the file &_NOTICE_&. Exim is distributed under the terms of the GNU General +Public Licence, a copy of which may be found in the file &_LICENCE_&. + +The use, supply, or promotion of Exim for the purpose of sending bulk, +unsolicited electronic mail is incompatible with the basic aims of Exim, +which revolve around the free provision of a service that enhances the quality +of personal communications. The author of Exim regards indiscriminate +mass-mailing as an antisocial, irresponsible abuse of the Internet. + +Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the +experience of running and working on the Smail 3 code, I could never have +contemplated starting to write a new MTA. Many of the ideas and user interfaces +were originally taken from Smail 3, though the actual code of Exim is entirely +new, and has developed far beyond the initial concept. + +Many people, both in Cambridge and around the world, have contributed to the +development and the testing of Exim, and to porting it to various operating +systems. I am grateful to them all. The distribution now contains a file called +&_ACKNOWLEDGMENTS_&, in which I have started recording the names of +contributors. + + +.section "Exim documentation" "SECID1" +. Keep this example change bar when updating the documentation! + +.new +.cindex "documentation" +This edition of the Exim specification applies to version &version() of Exim. +Substantive changes from the &previousversion; edition are marked in some +renditions of this document; this paragraph is so marked if the rendition is +capable of showing a change indicator. +.wen + +This document is very much a reference manual; it is not a tutorial. The reader +is expected to have some familiarity with the SMTP mail transfer protocol and +with general Unix system administration. Although there are some discussions +and examples in places, the information is mostly organized in a way that makes +it easy to look up, rather than in a natural order for sequential reading. +Furthermore, this manual aims to cover every aspect of Exim in detail, including +a number of rarely-used, special-purpose features that are unlikely to be of +very wide interest. + +.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'& (second edition, 2007), published by UIT Cambridge +(&url(https://www.uit.co.uk/exim-book/)). + +The book also contains a chapter that gives a general introduction to SMTP and +Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date +with the latest release of Exim. (Note that the earlier book about Exim, +published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) + +.cindex "Debian" "information sources" +If you are using a Debian distribution of Exim, you will find information about +Debian-specific features in the file +&_/usr/share/doc/exim4-base/README.Debian_&. +The command &(man update-exim.conf)& is another source of Debian-specific +information. + +.cindex "&_doc/NewStuff_&" +.cindex "&_doc/ChangeLog_&" +.cindex "change log" +As Exim develops, there may be features in newer versions that have not +yet made it into this document, which is updated only when the most significant +digit of the fractional part of the version number changes. Specifications of +new features that are not yet in this manual are placed in the file +&_doc/NewStuff_& in the Exim distribution. + +Some features may be classified as &"experimental"&. These may change +incompatibly while they are developing, or even be withdrawn. For this reason, +they are not documented in this manual. Information about experimental features +can be found in the file &_doc/experimental.txt_&. + +All changes to Exim (whether new features, bug fixes, or other kinds of +change) are noted briefly in the file called &_doc/ChangeLog_&. + +.cindex "&_doc/spec.txt_&" +This specification itself is available as an ASCII file in &_doc/spec.txt_& so +that it can easily be searched with a text editor. Other files in the &_doc_& +directory are: + +.table2 100pt +.row &_OptionLists.txt_& "list of all options in alphabetical order" +.row &_dbm.discuss.txt_& "discussion about DBM libraries" +.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 &_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 +available in other formats (HTML, PostScript, PDF, and Texinfo). Section +&<>& below tells you how to get hold of these. + + + +.section "FTP site and websites" "SECID2" +.cindex "website" +.cindex "FTP site" +The primary site for Exim source distributions is the &%exim.org%& FTP site, +available over HTTPS, HTTP and FTP. These services, and the &%exim.org%& +website, are hosted at the University of Cambridge. + +.cindex "wiki" +.cindex "FAQ" +As well as Exim distribution tar files, the Exim website contains a number of +differently formatted versions of the documentation. A recent addition to the +online information is the Exim wiki (&url(https://wiki.exim.org)), +which contains what used to be a separate FAQ, as well as various other +examples, tips, and know-how that have been contributed by Exim users. +The wiki site should always redirect to the correct place, which is currently +provided by GitHub, and is open to editing by anyone with a GitHub account. + +.cindex Bugzilla +An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use +this to report bugs, and also to add items to the wish list. Please search +first to check that you are not duplicating a previous entry. +Please do not ask for configuration help in the bug-tracker. + + +.section "Mailing lists" "SECID3" +.cindex "mailing lists" "for Exim users" +The following Exim mailing lists exist: + +.table2 140pt +.row &'exim-announce@exim.org'& "Moderated, low volume announcements list" +.row &'exim-users@exim.org'& "General discussion list" +.row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc." +.row &'exim-cvs@exim.org'& "Automated commit messages from the VCS" +.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'& +via this web page: +.display +&url(https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users) +.endd +Please ask Debian-specific questions on that list and not on the general Exim +lists. + +.section "Bug reports" "SECID5" +.cindex "bug reports" +.cindex "reporting bugs" +Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported +via the Bugzilla (&url(https://bugs.exim.org)). However, if you are unsure +whether some behaviour is a bug or not, the best thing to do is to post a +message to the &'exim-dev'& mailing list and have it discussed. + + + +.section "Where to find the Exim distribution" "SECTavail" +.cindex "FTP site" +.cindex "HTTPS download site" +.cindex "distribution" "FTP site" +.cindex "distribution" "https site" +The master distribution site for the Exim distribution is +.display +&url(https://downloads.exim.org/) +.endd +The service is available over HTTPS, HTTP and FTP. +We encourage people to migrate to HTTPS. + +The content served at &url(https://downloads.exim.org/) is identical to the +content served at &url(https://ftp.exim.org/pub/exim) and +&url(ftp://ftp.exim.org/pub/exim). + +If accessing via a hostname containing &'ftp'&, then the file references that +follow are relative to the &_exim_& directories at these sites. +If accessing via the hostname &'downloads'& then the subdirectories described +here are top-level directories. + +There are now quite a number of independent mirror sites around +the world. Those that I know about are listed in the file called &_Mirrors_&. + +Within the top exim directory there are subdirectories called &_exim3_& (for +previous Exim 3 distributions), &_exim4_& (for the latest Exim 4 +distributions), and &_Testing_& for testing versions. In the &_exim4_& +subdirectory, the current release can always be found in files called +.display +&_exim-n.nn.tar.xz_& +&_exim-n.nn.tar.gz_& +&_exim-n.nn.tar.bz2_& +.endd +where &'n.nn'& is the highest such version number in the directory. The three +files contain identical data; the only difference is the type of compression. +The &_.xz_& file is usually the smallest, while the &_.gz_& file is the +most portable to old systems. + +.cindex "distribution" "signing details" +.cindex "distribution" "public key" +.cindex "public key for signed distribution" +The distributions will be PGP signed by an individual key of the Release +Coordinator. This key will have a uid containing an email address in the +&'exim.org'& domain and will have signatures from other people, including +other Exim maintainers. We expect that the key will be in the "strong set" of +PGP keys. There should be a trust path to that key from the Exim Maintainer's +PGP keys, a version of which can be found in the release directory in the file +&_Exim-Maintainers-Keyring.asc_&. All keys used will be available in public keyserver pools, +such as &'pool.sks-keyservers.net'&. + +At the time of the last update, releases were being made by Jeremy Harris and signed +with key &'0xBCE58C8CE41F32DF'&. Other recent keys used for signing are those +of Heiko Schlittermann, &'0x26101B62F69376CE'&, +and of Phil Pennock, &'0x4D1E900E14C1CC04'&. + +The signatures for the tar bundles are in: +.display +&_exim-n.nn.tar.xz.asc_& +&_exim-n.nn.tar.gz.asc_& +&_exim-n.nn.tar.bz2.asc_& +.endd +For each released version, the log of changes is made available in a +separate file in the directory &_ChangeLogs_& so that it is possible to +find out what has changed without having to download the entire distribution. + +.cindex "documentation" "available formats" +The main distribution contains ASCII versions of this specification and other +documentation; other formats of the documents are available in separate files +inside the &_exim4_& directory of the FTP site: +.display +&_exim-html-n.nn.tar.gz_& +&_exim-pdf-n.nn.tar.gz_& +&_exim-postscript-n.nn.tar.gz_& +&_exim-texinfo-n.nn.tar.gz_& +.endd +These tar files contain only the &_doc_& directory, not the complete +distribution, and are also available in &_.bz2_& and &_.xz_& forms. + + +.section "Limitations" "SECID6" +.ilist +.cindex "limitations of Exim" +.cindex "bang paths" "not handled by Exim" +Exim is designed for use as an Internet MTA, and therefore handles addresses in +RFC 2822 domain format only. It cannot handle UUCP &"bang paths"&, though +simple two-component bang paths can be converted by a straightforward rewriting +configuration. This restriction does not prevent Exim from being interfaced to +UUCP as a transport mechanism, provided that domain addresses are used. +.next +.cindex "domainless addresses" +.cindex "address" "without domain" +Exim insists that every address it handles has a domain attached. For incoming +local messages, domainless addresses are automatically qualified with a +configured domain value. Configuration options specify from which remote +systems unqualified addresses are acceptable. These are then qualified on +arrival. +.next +.cindex "transport" "external" +.cindex "external transports" +The only external transport mechanisms that are currently implemented are SMTP +and LMTP over a TCP/IP network (including support for IPv6). However, a pipe +transport is available, and there are facilities for writing messages to files +and pipes, optionally in &'batched SMTP'& format; these facilities can be used +to send messages to other transport mechanisms such as UUCP, provided they can +handle domain-style addresses. Batched SMTP input is also catered for. +.next +Exim is not designed for storing mail for dial-in hosts. When the volumes of +such mail are large, it is better to get the messages &"delivered"& into files +(that is, off Exim's queue) and subsequently passed on to the dial-in hosts by +other means. +.next +Although Exim does have basic facilities for scanning incoming messages, these +are not comprehensive enough to do full virus or spam scanning. Such operations +are best carried out using additional specialized software packages. If you +compile Exim with the content-scanning extension, straightforward interfaces to +a number of common scanners are provided. +.endlist + + +.section "Runtime configuration" "SECID7" +Exim's runtime configuration is held in a single text file that is divided +into a number of sections. The entries in this file consist of keywords and +values, in the style of Smail 3 configuration files. A default configuration +file which is suitable for simple online installations is provided in the +distribution, and is described in chapter &<>& below. + + +.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 +&_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything +about Sendmail in order to run Exim. For actions other than sending messages, +Sendmail-compatible options also exist, but those that produce output (for +example, &%-bp%&, which lists the messages in the queue) do so in Exim's own +format. There are also some additional options that are compatible with Smail +3, and some further options that are new to Exim. Chapter &<>& +documents all Exim's command line options. This information is automatically +made into the man page that forms part of the Exim distribution. + +Control of messages in the queue can be done via certain privileged command +line options. There is also an optional monitor program called &'eximon'&, +which displays current information in an X window, and which contains a menu +interface to Exim's command line administration options. + + + +.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. +It is the last part of a message and is separated from the &'header'& (see +below) by a blank line. + +.cindex "bounce message" "definition of" +When a message cannot be delivered, it is normally returned to the sender in a +delivery failure message or a &"non-delivery report"& (NDR). The term +&'bounce'& is commonly used for this action, and the error reports are often +called &'bounce messages'&. This is a convenient shorthand for &"delivery +failure error report"&. Such messages have an empty sender address in the +message's &'envelope'& (see below) to ensure that they cannot themselves give +rise to further bounce messages. + +The term &'default'& appears frequently in this manual. It is used to qualify a +value which is used in the absence of any setting in the configuration. It may +also qualify an action which is taken unless a configuration setting specifies +otherwise. + +The term &'defer'& is used when the delivery of a message to a specific +destination cannot immediately take place for some reason (a remote host may be +down, or a user's local mailbox may be full). Such deliveries are &'deferred'& +until a later time. + +The word &'domain'& is sometimes used to mean all but the first component of a +host's name. It is &'not'& used in that sense here, where it normally refers to +the part of an email address following the @ sign. + +.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 +be delivered), and any number of recipient addresses. References to the +sender or the recipients of a message usually mean the addresses in the +envelope. An MTA uses these addresses for delivery, and for returning bounce +messages, not the addresses that appear in the header lines. + +.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:'&, +&'Subject:'&, etc. Long header lines can be split over several text lines by +indenting the continuations. The header is separated from the body by a blank +line. + +.cindex "local part" "definition of" +.cindex "domain" "definition of" +The term &'local part'&, which is taken from RFC 2822, is used to refer to the +part of an email address that precedes the @ sign. The part that follows the +@ sign is called the &'domain'& or &'mail domain'&. + +.cindex "local 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 +host it is running on are &'remote'&. + +.cindex "return path" "definition of" +&'Return path'& is another name that is used for the sender address in a +message's envelope. + +.cindex "queue" "definition of" +The term &'queue'& is used to refer to the set of messages awaiting delivery +because this term is in widespread use in the context of MTAs. However, in +Exim's case, the reality is more like a pool than a queue, because there is +normally no ordering of waiting messages. + +.cindex "queue runner" "definition of" +The term &'queue runner'& is used to describe a process that scans the queue +and attempts to deliver those messages whose retry times have come. This term +is used by other MTAs and also relates to the command &%runq%&, but in Exim +the waiting messages are normally processed in an unpredictable order. + +.cindex "spool directory" "definition of" +The term &'spool directory'& is used for a directory in which Exim keeps the +messages in its queue &-- that is, those that it is in the process of +delivering. This should not be confused with the directory in which local +mailboxes are stored, which is called a &"spool directory"& by some people. In +the Exim documentation, &"spool"& is always used in the first sense. + + + + + + +. //////////////////////////////////////////////////////////////////////////// +. //////////////////////////////////////////////////////////////////////////// + +.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 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. +It does not link against an external cdb library. The code contains the +following statements: + +.blockquote +Copyright © 1998 Nigel Metheringham, Planet Online Ltd + +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. +This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, +the spec and sample code for cdb can be obtained from +&url(https://cr.yp.to/cdb.html). This implementation borrows +some code from Dan Bernstein's implementation (which has no license +restrictions applied to it). +.endblockquote +.next +.cindex "SPA authentication" +.cindex "Samba project" +.cindex "Microsoft Secure Password Authentication" +Client support for Microsoft's &'Secure Password Authentication'& is provided +by code contributed by Marc Prud'hommeaux. Server support was contributed by +Tom Kistner. This includes code taken from the Samba project, which is released +under the Gnu GPL. +.next +.cindex "Cyrus" +.cindex "&'pwcheck'& daemon" +.cindex "&'pwauthd'& daemon" +Support for calling the Cyrus &'pwcheck'& and &'saslauthd'& daemons is provided +by code taken from the Cyrus-SASL library and adapted by Alexander S. +Sabourenkov. The permission notice appears below, in accordance with the +conditions expressed therein. + +.blockquote +Copyright © 2001 Carnegie Mellon University. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +.olist +Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. +.next +Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in +the documentation and/or other materials provided with the +distribution. +.next +The name &"Carnegie Mellon University"& must not be used to +endorse or promote products derived from this software without +prior written permission. For permission or any other legal +details, please contact +.display + Office of Technology Transfer + Carnegie Mellon University + 5000 Forbes Avenue + Pittsburgh, PA 15213-3890 + (412) 268-4387, fax: (412) 268-7395 + tech-transfer@andrew.cmu.edu +.endd +.next +Redistributions of any form whatsoever must retain the following +acknowledgment: + +&"This product includes software developed by Computing Services +at Carnegie Mellon University (&url(https://www.cmu.edu/computing/)."& + +CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO +THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE +FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN +AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING +OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.endlist +.endblockquote + +.next +.cindex "Exim monitor" "acknowledgment" +.cindex "X-windows" +.cindex "Athena" +The Exim Monitor program, which is an X-Window application, includes +modified versions of the Athena StripChart and TextPop widgets. +This code is copyright by DEC and MIT, and their permission notice appears +below, in accordance with the conditions expressed therein. + +.blockquote +Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, +and the Massachusetts Institute of Technology, Cambridge, Massachusetts. + +All Rights Reserved + +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the names of Digital or MIT not be +used in advertising or publicity pertaining to distribution of the +software without specific, written prior permission. + +DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +SOFTWARE. +.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 license requirements. It is assumed that the +contributors are happy to see their code incorporated into Exim under the GPL. +.endlist + + + + + +. //////////////////////////////////////////////////////////////////////////// +. //////////////////////////////////////////////////////////////////////////// + +.chapter "How Exim receives and delivers mail" "CHID11" &&& + "Receiving and delivering mail" + + +.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, +most messages can be delivered immediately. Consequently, Exim does not +maintain independent queues of messages for specific domains or hosts, though +it does try to send several messages in a single SMTP connection after a host +has been down, and it also maintains per-host retry information. + + +.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 from being abused as +&"open relays"& by misguided individuals who send out vast amounts of +unsolicited junk and want to disguise its source. Exim provides flexible +facilities for specifying policy controls on incoming mail: + +.ilist +.cindex "&ACL;" "introduction" +Exim 4 (unlike previous versions of Exim) implements policy controls on +incoming mail by means of &'Access Control Lists'& (ACLs). Each list is a +series of statements that may either grant or deny access. ACLs can be used at +several places in the SMTP dialogue while receiving a message from a remote +host. However, the most common places are after each RCPT command, and at the +very end of the message. The sysadmin can specify conditions for accepting or +rejecting individual recipients or the entire message, respectively, at these +two points (see chapter &<>&). Denial of access results in an SMTP +error code. +.next +An ACL is also available for locally generated, non-SMTP messages. In this +case, the only available actions are to accept or deny the entire message. +.next +When Exim is compiled with the content-scanning extension, facilities are +provided in the ACL mechanism for passing the message to external virus and/or +spam scanning software. The result of such a scan is passed back to the ACL, +which can then use it to decide what to do with the message. +.next +When a message has been received, either from a remote host or from the local +host, but before the final acknowledgment has been sent, a locally supplied C +function called &[local_scan()]& can be run to inspect the message and decide +whether to accept it or not (see chapter &<>&). If the message +is accepted, the list of recipients can be modified by the function. +.next +Using the &[local_scan()]& mechanism is another way of calling external scanner +software. The &%SA-Exim%& add-on package works this way. It does not require +Exim to be compiled with the content-scanning extension. +.next +After a message has been accepted, a further checking mechanism is available in +the form of the &'system filter'& (see chapter &<>&). This +runs at the start of every delivery process. +.endlist + + + +.section "User filters" "SECID12" +.cindex "filter" "introduction" +.cindex "Sieve filter" +In a conventional Exim configuration, users are able to run private filters by +setting up appropriate &_.forward_& files in their home directories. See +chapter &<>& (about the &(redirect)& router) for the +configuration needed to support this, and the separate document entitled +&'Exim's interfaces to mail filtering'& for user details. Two different kinds +of filtering are available: + +.ilist +Sieve filters are written in the standard filtering language that is defined +by RFC 3028. +.next +Exim filters are written in a syntax that is unique to Exim, but which is more +powerful than Sieve, which it pre-dates. +.endlist + +User filters are run as part of the routing process, described below. + + + +.section "Message identification" "SECTmessiden" +.cindex "message ids" "details of format" +.cindex "format" "of message id" +.cindex "id of message" +.cindex "base62" +.cindex "base36" +.cindex "Darwin" +.cindex "Cygwin" +Every message handled by Exim is given a &'message id'& which is sixteen +characters long. It is divided into three parts, separated by hyphens, for +example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, +normally encoding numbers in base 62. However, in the Darwin operating +system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 +(avoiding the use of lower case letters) is used instead, because the message +id is used to construct filenames, and the names of files in those systems are +not always case-sensitive. + +.cindex "pid (process id)" "re-use of" +The detail of the contents of the message id have changed as Exim has evolved. +Earlier versions relied on the operating system not re-using a process id (pid) +within one second. On modern operating systems, this assumption can no longer +be made, so the algorithm had to be changed. To retain backward compatibility, +the format of the message id was retained, which is why the following rules are +somewhat eccentric: + +.ilist +The first six characters of the message id are the time at which the message +started to be received, to a granularity of one second. That is, this field +contains the number of seconds since the start of the epoch (the normal Unix +way of representing the date and time of day). +.next +After the first hyphen, the next six characters are the id of the process that +received the message. +.next +There are two different possibilities for the final two characters: +.olist +.oindex "&%localhost_number%&" +If &%localhost_number%& is not set, this value is the fractional part of the +time of reception, normally in units of 1/2000 of a second, but for systems +that must use base 36 instead of base 62 (because of case-insensitive file +systems), the units are 1/1000 of a second. +.next +If &%localhost_number%& is set, it is multiplied by 200 (100) and added to +the fractional part of the time, which in this case is in units of 1/200 +(1/100) of a second. +.endlist +.endlist + +After a message has been received, Exim waits for the clock to tick at the +appropriate resolution before proceeding, so that if another message is +received by the same process, or by another process with the same (re-used) +pid, it is guaranteed that the time will be different. In most cases, the clock +will already have ticked while the message was being received. + + +.section "Receiving mail" "SECID13" +.cindex "receiving mail" +.cindex "message" "reception" +The only way Exim can receive mail from another host is using SMTP over +TCP/IP, in which case the sender and recipient addresses are transferred using +SMTP commands. However, from a locally running process (such as a user's MUA), +there are several possibilities: + +.ilist +If the process runs Exim with the &%-bm%& option, the message is read +non-interactively (usually via a pipe), with the recipients taken from the +command line, or from the body of the message if &%-t%& is also used. +.next +If the process runs Exim with the &%-bS%& option, the message is also read +non-interactively, but in this case the recipients are listed at the start of +the message in a series of SMTP RCPT commands, terminated by a DATA +command. This is called &"batch SMTP"& format, +but it isn't really SMTP. The SMTP commands are just another way of passing +envelope addresses in a non-interactive submission. +.next +If the process runs Exim with the &%-bs%& option, the message is read +interactively, using the SMTP protocol. A two-way pipe is normally used for +passing data between the local process and the Exim process. +This is &"real"& SMTP and is handled in the same way as SMTP over TCP/IP. For +example, the ACLs for SMTP commands are used for this form of submission. +.next +A local process may also make a TCP/IP call to the host's loopback address +(127.0.0.1) or any other of its IP addresses. When receiving messages, Exim +does not treat the loopback address specially. It treats all such connections +in the same way as connections from other hosts. +.endlist + + +.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 +qualification domain (which can be set by the &%qualify_domain%& configuration +option). For local or batch SMTP, a sender address that is passed using the +SMTP MAIL command is ignored. However, the system administrator may allow +certain users (&"trusted users"&) to specify a different sender addresses +unconditionally, or all users to specify certain forms of different sender +address. The &%-f%& option or the SMTP MAIL command is used to specify these +different addresses. See section &<>& for details of trusted +users, and the &%untrusted_set_sender%& option for a way of allowing untrusted +users to change sender addresses. + +Messages received by either of the non-interactive mechanisms are subject to +checking by the non-SMTP ACL if one is defined. Messages received using SMTP +(either over TCP/IP or interacting with a local process) can be checked by a +number of ACLs that operate at different times during the SMTP session. Either +individual recipients or the entire message can be rejected if local policy +requirements are not met. The &[local_scan()]& function (see chapter +&<>&) is run for all incoming messages. + +Exim can be configured not to start a delivery process when a message is +received; this can be unconditional, or depend on the number of incoming SMTP +connections or the system load. In these situations, new messages wait on the +queue until a queue runner process picks them up. However, in standard +configurations under normal conditions, delivery is started as soon as a +message is received. + + + + + +.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 +first contains the envelope information, the current status of the message, and +the header lines, and the second contains the body of the message. The names of +the two spool files consist of the message id, followed by &`-H`& for the +file containing the envelope and header, and &`-D`& for the data file. + +.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 large; to +improve performance in such cases, the &%split_spool_directory%& option can be +used. This causes Exim to split up the input files into 62 sub-directories +whose names are single letters or digits. When this is done, the queue is +processed one sub-directory at a time instead of all at once, which can improve +overall performance even when there are not enough files in each directory to +affect file system performance. + +The envelope information consists of the address of the message's sender and +the addresses of the recipients. This information is entirely separate from +any addresses contained in the header lines. The status of the message includes +a list of recipients who have already received the message. The format of the +first spool file is described in chapter &<>&. + +.cindex "rewriting" "addresses" +Address rewriting that is specified in the rewrite section of the configuration +(see chapter &<>&) is done once and for all on incoming addresses, +both in the header lines and the envelope, at the time the message is accepted. +If during the course of delivery additional addresses are generated (for +example, via aliasing), these new addresses are rewritten as soon as they are +generated. At the time a message is actually delivered (transported) further +rewriting can take place; because this is a transport option, it can be +different for different forms of delivery. It is also possible to specify the +addition or removal of certain header lines at the time the message is +delivered (see chapters &<>& and +&<>&). + + + +.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 +its recipients or to an error address, or until it is deleted by an +administrator or by the user who originally created it. In cases when delivery +cannot proceed &-- for example when a message can neither be delivered to its +recipients nor returned to its sender, the message is marked &"frozen"& on the +spool, and no more deliveries are attempted. + +.cindex "frozen messages" "thawing" +.cindex "message" "thawing frozen" +An administrator can &"thaw"& such messages when the problem has been +corrected, and can also freeze individual messages by hand if necessary. In +addition, an administrator can force a delivery error, causing a bounce message +to be sent. + +.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 all frozen messages. + +.cindex "message" "log file for" +.cindex "log" "file for each message" +While Exim is working on a message, it writes information about each delivery +attempt to its main log file. This includes successful, unsuccessful, and +delayed deliveries for each recipient (see chapter &<>&). The log +lines are also written to a separate &'message log'& file for each message. +These logs are solely for the benefit of the administrator and are normally +deleted along with the spool files when processing of a message is complete. +The use of individual message logs can be disabled by setting +&%no_message_logs%&; this might give an improvement in performance on very busy +systems. + +.cindex "journal file" +.cindex "file" "journal" +All the information Exim itself needs to set up a delivery is kept in the first +spool file, along with the header lines. When a successful delivery occurs, the +address is immediately written at the end of a journal file, whose name is the +message id followed by &`-J`&. At the end of a delivery run, if there are some +addresses left to be tried again later, the first spool file (the &`-H`& file) +is updated to indicate which these are, and the journal file is then deleted. +Updating the spool file is done by writing a new file and renaming it, to +minimize the possibility of data loss. + +Should the system or Exim crash after a successful delivery but before +the spool file has been updated, the journal is left lying around. The next +time Exim attempts to deliver the message, it reads the journal file and +updates the spool file before proceeding. This minimizes the chances of double +deliveries caused by crashes. + + + +.section "Processing an address for delivery" "SECTprocaddress" +.cindex "drivers" "definition of" +.cindex "router" "definition of" +.cindex "transport" "definition of" +The main delivery processing elements of Exim are called &'routers'& and +&'transports'&, and collectively these are known as &'drivers'&. Code for a +number of them is provided in the source distribution, and compile-time options +specify which ones are included in the binary. Runtime options specify which +ones are actually used for delivering messages. + +.cindex "drivers" "instance definition" +Each driver that is specified in the runtime configuration is an &'instance'& +of that particular driver type. Multiple instances are allowed; for example, +you can set up several different &(smtp)& transports, each with different +option values that might specify different ports or different timeouts. Each +instance has its own identifying name. In what follows we will normally use the +instance name when discussing one particular instance (that is, one specific +configuration of the driver), and the generic driver name when discussing +the driver's features in general. + +A &'router'& is a driver that operates on an address, either determining how +its delivery should happen, by assigning it to a specific transport, or +converting the address into one or more new addresses (for example, via an +alias file). A router may also explicitly choose to fail an address, causing it +to be bounced. + +A &'transport'& is a driver that transmits a copy of the message from Exim's +spool to some destination. There are two kinds of transport: for a &'local'& +transport, the destination is a file or a pipe on the local host, whereas for a +&'remote'& transport the destination is some other host. A message is passed +to a specific transport as a result of successful routing. If a message has +several recipients, it may be passed to a number of different transports. + +.cindex "preconditions" "definition of" +An address is processed by passing it to each configured router instance in +turn, subject to certain preconditions, until a router accepts the address or +specifies that it should be bounced. We will describe this process in more +detail shortly. First, as a simple example, we consider how each recipient +address in a message is processed in a small configuration of three routers. + +To make this a more concrete example, it is described in terms of some actual +routers, but remember, this is only an example. You can configure Exim's +routers in many different ways, and there may be any number of routers in a +configuration. + +The first router that is specified in a configuration is often one that handles +addresses in domains that are not recognized specifically by the local host. +Typically these are addresses for arbitrary domains on the Internet. A precondition +is set up which looks for the special domains known to the host (for example, +its own domain name), and the router is run for addresses that do &'not'& +match. Typically, this is a router that looks up domains in the DNS in order to +find the hosts to which this address routes. If it succeeds, the address is +assigned to a suitable SMTP transport; if it does not succeed, the router is +configured to fail the address. + +The second router is reached only when the domain is recognized as one that +&"belongs"& to the local host. This router does redirection &-- also known as +aliasing and forwarding. When it generates one or more new addresses from the +original, each of them is routed independently from the start. Otherwise, the +router may cause an address to fail, or it may simply decline to handle the +address, in which case the address is passed to the next router. + +The final router in many configurations is one that checks to see if the +address belongs to a local mailbox. The precondition may involve a check to +see if the local part is the name of a login account, or it may look up the +local part in a file or a database. If its preconditions are not met, or if +the router declines, we have reached the end of the routers. When this happens, +the address is bounced. + + + +.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 +are also used for &'address verification'&. Verification can be requested as +one of the checks to be performed in an ACL for incoming messages, on both +sender and recipient addresses, and it can be tested using the &%-bv%& and +&%-bvs%& command line options. + +When an address is being verified, the routers are run in &"verify mode"&. This +does not affect the way the routers work, but it is a state that can be +detected. By this means, a router can be skipped or made to behave differently +when verifying. A common example is a configuration in which the first router +sends all messages to a message-scanning program unless they have been +previously scanned. Thus, the first router accepts all addresses without any +checking, making it useless for verifying. Normally, the &%no_verify%& option +would be set for such a router, causing it to be skipped in verify mode. + + + + +.section "Running an individual router" "SECTrunindrou" +.cindex "router" "running details" +.cindex "preconditions" "checking" +.cindex "router" "result of running" +As explained in the example above, a number of preconditions are checked before +running a router. If any are not met, the router is skipped, and the address is +passed to the next router. When all the preconditions on a router &'are'& met, +the router is run. What happens next depends on the outcome, which is one of +the following: + +.ilist +&'accept'&: The router accepts the address, and either assigns it to a +transport or generates one or more &"child"& addresses. Processing the +original address ceases +.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 +passed to the next router. Normally, however, an &'accept'& return marks the +end of routing. + +Any child addresses generated by the router are processed independently, +starting with the first router by default. It is possible to change this by +setting the &%redirect_router%& option to specify which router to start at for +child addresses. Unlike &%pass_router%& (see below) the router specified by +&%redirect_router%& may be anywhere in the router configuration. +.next +&'pass'&: The router recognizes the address, but cannot handle it itself. It +requests that the address be passed to another router. By default, the address +is passed to the next router, but this can be changed by setting the +&%pass_router%& option. However, (unlike &%redirect_router%&) the named router +must be below the current router (to avoid loops). +.next +&'decline'&: The router declines to accept the address because it does not +recognize it at all. By default, the address is passed to the next router, but +this can be prevented by setting the &%no_more%& option. When &%no_more%& is +set, all the remaining routers are skipped. In effect, &%no_more%& converts +&'decline'& into &'fail'&. +.next +&'fail'&: The router determines that the address should fail, and queues it for +the generation of a bounce message. There is no further processing of the +original address unless &%unseen%& is set on the router. +.next +&'defer'&: The router cannot handle the address at the present time. (A +database may be offline, or a DNS lookup may have timed out.) No further +processing of the address happens in this delivery attempt. It is tried again +next time the message is considered for delivery. +.next +&'error'&: There is some error in the router (for example, a syntax error in +its configuration). The action is as for defer. +.endlist + +If an address reaches the end of the routers without having been accepted by +any of them, it is bounced as unrouteable. The default error message in this +situation is &"unrouteable address"&, but you can set your own message by +making use of the &%cannot_route_message%& option. This can be set for any +router; the value from the last router that &"saw"& the address is used. + +Sometimes while routing you want to fail a delivery when some conditions are +met but others are not, instead of passing the address on for further routing. +You can do this by having a second router that explicitly fails the delivery +when the relevant conditions are met. The &(redirect)& router has a &"fail"& +facility for this purpose. + + +.section "Duplicate addresses" "SECID17" +.cindex "case of local parts" +.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 case-sensitively. 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 "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 +described in more detail in chapter &<>&. + +.ilist +.cindex affix "router precondition" +The &%local_part_prefix%& and &%local_part_suffix%& options can specify that +the local parts handled by the router may or must have certain prefixes and/or +suffixes. If a mandatory affix (prefix or suffix) is not present, the router is +skipped. These conditions are tested first. When an affix is present, it is +removed from the local part before further processing, including the evaluation +of any other conditions. +.next +Routers can be designated for use only when not verifying an address, that is, +only when routing it for delivery (or testing its delivery routing). If the +&%verify%& option is set false, the router is skipped when Exim is verifying an +address. +Setting the &%verify%& option actually sets two options, &%verify_sender%& and +&%verify_recipient%&, which independently control the use of the router for +sender and recipient verification. You can set these options directly if +you want a router to be used for only one type of verification. +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 +when the first router sends all new messages to a scanner of some sort; it +makes it possible to use &%-bt%& to test subsequent delivery routing without +having to simulate the effect of the scanner. +.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). +.next +If the &%domains%& option is set, the domain of the address must be in the set +of domains that it defines. +.next +.vindex "&$local_part_prefix$&" +.vindex "&$local_part_prefix_v$&" +.vindex "&$local_part$&" +.vindex "&$local_part_suffix$&" +.vindex "&$local_part_suffix_v$&" +.cindex affix "router precondition" +If the &%local_parts%& option is set, the local part of the address must be in +the set of local parts that it defines. If &%local_part_prefix%& or +&%local_part_suffix%& is in use, the prefix or suffix is removed from the local +part before this check. If you want to do precondition tests on local parts +that include affixes, you can do so by using a &%condition%& option (see below) +.new +that uses the variables &$local_part$&, &$local_part_prefix$&, +&$local_part_prefix_v$&, &$local_part_suffix$& +and &$local_part_suffix_v$& as necessary. +.wen +.next +.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 +user's home directory is placed in &$home$&; these values can be used in the +remaining preconditions. +.next +If the &%router_home_directory%& option is set, it is expanded at this point, +because it overrides the value of &$home$&. If this expansion were left till +later, the value of &$home$& as set by &%check_local_user%& would be used in +subsequent tests. Having two different values of &$home$& in the same router +could lead to confusion. +.next +If the &%senders%& option is set, the envelope sender address must be in the +set of addresses that it defines. +.next +If the &%require_files%& option is set, the existence or non-existence of +specified files is tested. +.next +.cindex "customizing" "precondition" +If the &%condition%& option is set, it is evaluated and tested. This option +uses an expanded string to allow you to set up your own custom preconditions. +Expanded strings are described in chapter &<>&. +.endlist + + +Note that &%require_files%& comes near the end of the list, so you cannot use +it to check for the existence of a file in which to lookup up a domain, local +part, or sender. However, as these options are all expanded, you can use the +&%exists%& expansion condition to make such tests within each condition. The +&%require_files%& option is intended for checking files that the router may be +going to use internally, or which are needed by a specific transport (for +example, &_.procmailrc_&). + + + +.section "Delivery in detail" "SECID18" +.cindex "delivery" "in detail" +When a message is to be delivered, the sequence of events is as follows: + +.ilist +If a system-wide filter file is specified, the message is passed to it. The +filter may add recipients to the message, replace the recipients, discard the +message, cause a new message to be generated, or cause the message delivery to +fail. The format of the system filter file is the same as for Exim user filter +files, described in the separate document entitled &'Exim's interfaces to mail +filtering'&. +.cindex "Sieve filter" "not available for system filter" +(&*Note*&: Sieve cannot be used for system filter files.) + +Some additional features are available in system filters &-- see chapter +&<>& for details. Note that a message is passed to the system +filter only once per delivery attempt, however many recipients it has. However, +if there are several delivery attempts because one or more addresses could not +be immediately delivered, the system filter is run each time. The filter +condition &%first_delivery%& can be used to detect the first run of the system +filter. +.next +Each recipient address is offered to each configured router, in turn, subject to +its preconditions, until one is able to handle it. If no router can handle the +address, that is, if they all decline, the address is failed. Because routers +can be targeted at particular domains, several locally handled domains can be +processed entirely independently of each other. +.next +.cindex "routing" "loops in" +.cindex "loop" "while routing" +A router that accepts an address may assign it to a local or a remote +transport. However, the transport is not run at this time. Instead, the address +is placed on a list for the particular transport, which will be run later. +Alternatively, the router may generate one or more new addresses (typically +from alias, forward, or filter files). New addresses are fed back into this +process from the top, but in order to avoid loops, a router ignores any address +which has an identically-named ancestor that was processed by itself. +.next +When all the routing has been done, addresses that have been successfully +handled are passed to their assigned transports. When local transports are +doing real local deliveries, they handle only one address at a time, but if a +local transport is being used as a pseudo-remote transport (for example, to +collect batched SMTP messages for transmission by some other means) multiple +addresses can be handled. Remote transports can always handle more than one +address at a time, but can be configured not to do so, or to restrict multiple +addresses to the same domain. +.next +Each local delivery to a file or a pipe runs in a separate process under a +non-privileged uid, and these deliveries are run one at a time. Remote +deliveries also run in separate processes, normally under a uid that is private +to Exim (&"the Exim user"&), but in this case, several remote deliveries can be +run in parallel. The maximum number of simultaneous remote deliveries for any +one message is set by the &%remote_max_parallel%& option. +The order in which deliveries are done is not defined, except that all local +deliveries happen before any remote deliveries. +.next +.cindex "queue runner" +When it encounters a local delivery during a queue run, Exim checks its retry +database to see if there has been a previous temporary delivery failure for the +address before running the local transport. If there was a previous failure, +Exim does not attempt a new delivery until the retry time for the address is +reached. However, this happens only for delivery attempts that are part of a +queue run. Local deliveries are always attempted when delivery immediately +follows message reception, even if retry times are set for them. This makes for +better behaviour if one particular message is causing problems (for example, +causing quota overflow, or provoking an error in a filter file). +.next +.cindex "delivery" "retry in remote transports" +Remote transports do their own retry handling, since an address may be +deliverable to one of a number of hosts, each of which may have a different +retry time. If there have been previous temporary failures and no host has +reached its retry time, no delivery is attempted, whether in a queue run or +not. See chapter &<>& for details of retry strategies. +.next +If there were any permanent errors, a bounce message is returned to an +appropriate address (the sender in the common case), with details of the error +for each failing address. Exim can be configured to send copies of bounce +messages to other addresses. +.next +.cindex "delivery" "deferral" +If one or more addresses suffered a temporary failure, the message is left on +the queue, to be tried again later. Delivery of these addresses is said to be +&'deferred'&. +.next +When all the recipient addresses have either been delivered or bounced, +handling of the message is complete. The spool files and message log are +deleted, though the message log can optionally be preserved if required. +.endlist + + + + +.section "Retry mechanism" "SECID19" +.cindex "delivery" "retry mechanism" +.cindex "retry" "description of mechanism" +.cindex "queue runner" +Exim's mechanism for retrying messages that fail to get delivered at the first +attempt is the queue runner process. You must either run an Exim daemon that +uses the &%-q%& option with a time interval to start queue runners at regular +intervals or use some other means (such as &'cron'&) to start them. If you do +not arrange for queue runners to be run, messages that fail temporarily at the +first attempt will remain in your queue forever. A queue runner process works +its way through the queue, one message at a time, trying each delivery that has +passed its retry time. +You can run several queue runners at once. + +Exim uses a set of configured rules to determine when next to retry the failing +address (see chapter &<>&). These rules also specify when Exim +should give up trying to deliver to the address, at which point it generates a +bounce message. If no retry rules are set for a particular host, address, and +error combination, no retries are attempted, and temporary errors are treated +as permanent. + + + +.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 +connection to it, is down) is one of the most common. Temporary failures may be +detected during routing as well as during the transport stage of delivery. +Local deliveries may be delayed if NFS files are unavailable, or if a mailbox +is on a file system where the user is over quota. Exim can be configured to +impose its own quotas on local mailboxes; where system quotas are set they will +also apply. + +If a host is unreachable for a period of time, a number of messages may be +waiting for it by the time it recovers, and sending them in a single SMTP +connection is clearly beneficial. Whenever a delivery to a remote host is +deferred, +.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 +connection, subject to a configuration limit as to the maximum number in any +one connection. + + + +.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 +bounce message is generated. Temporary delivery failures turn into permanent +errors when their timeout expires. All the addresses that fail in a given +delivery attempt are listed in a single message. If the original message has +many recipients, it is possible for some addresses to fail in one delivery +attempt and others to fail subsequently, giving rise to more than one bounce +message. The wording of bounce messages can be customized by the administrator. +See chapter &<>& for details. + +.cindex "&'X-Failed-Recipients:'& header line" +Bounce messages contain an &'X-Failed-Recipients:'& header line that lists the +failed addresses, for the benefit of programs that try to analyse such messages +automatically. + +.cindex "bounce message" "recipient of" +A bounce message is normally sent to the sender of the original message, as +obtained from the message's envelope. For incoming SMTP messages, this is the +address given in the MAIL command. However, when an address is expanded via a +forward or alias file, an alternative address can be specified for delivery +failures of the generated addresses. For a mailing list expansion (see section +&<>&) it is common to direct bounce messages to the manager +of the list. + + + +.section "Failures to deliver bounce messages" "SECID22" +.cindex "bounce message" "failure to deliver" +If a bounce message (either locally generated or received from a remote host) +itself suffers a permanent delivery failure, the message is left in the queue, +but it is frozen, awaiting the attention of an administrator. There are options +that can be used to make Exim discard such failed messages, or to keep them +for only a short time (see &%timeout_frozen_after%& and +&%ignore_bounce_errors_after%&). + + + + + +. //////////////////////////////////////////////////////////////////////////// +. //////////////////////////////////////////////////////////////////////////// + +.chapter "Building and installing Exim" "CHID3" +.scindex IIDbuex "building Exim" + +.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: + +.table2 140pt +.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 +.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 +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" "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 +source files. Compilation does not take place in the &_src_& directory. +Instead, a &'build directory'& is created for each architecture and operating +system. +.cindex "symbolic link" "to build directory" +Symbolic links to the sources are installed in this directory, which is where +the actual building takes place. In most cases, Exim can discover the machine +architecture and operating system for itself, but the defaults can be +overridden if necessary. +.cindex compiler requirements +.cindex compiler version +A C99-capable compiler will be required for the build. + + +.section "PCRE library" "SECTpcre" +.cindex "PCRE library" +Exim no longer has an embedded PCRE library as the vast majority of +modern systems include PCRE as a system library, although you may need to +install the PCRE package or the PCRE development package for your operating +system. If your system has a normal PCRE installation the Exim build +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(https://www.pcre.org/). + +.section "DBM libraries" "SECTdb" +.cindex "DBM libraries" "discussion of" +.cindex "hints database" "DBM files used for" +Even if you do not use any DBM files in your configuration, Exim still needs a +DBM library in order to operate, because it uses indexed files for its hints +databases. Unfortunately, there are a number of DBM libraries in existence, and +different operating systems often have different ones installed. + +.cindex "Solaris" "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 +you would like about DBM libraries from what follows. + +.cindex "&'ndbm'& DBM library" +Licensed versions of Unix normally contain a library of DBM functions operating +via the &'ndbm'& interface, and this is what Exim expects by default. Free +versions of Unix seem to vary in what they contain as standard. In particular, +some early versions of Linux have no default DBM library, and different +distributors have chosen to bundle different libraries with their packaged +versions. However, the more recent releases seem to have standardized on the +Berkeley DB library. + +Different DBM libraries have different conventions for naming the files they +use. When a program opens a file called &_dbmfile_&, there are several +possibilities: + +.olist +A traditional &'ndbm'& implementation, such as that supplied as part of +Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&. +.next +.cindex "&'gdbm'& DBM library" +The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'& +compatibility interface it makes two different hard links to it with names +&_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the +filename is used unmodified. +.next +.cindex "Berkeley DB library" +The Berkeley DB package, if called via its &'ndbm'& compatibility interface, +operates on a single file called &_dbmfile.db_&, but otherwise looks to the +programmer exactly the same as the traditional &'ndbm'& implementation. +.next +If the Berkeley package is used in its native mode, it operates on a single +file called &_dbmfile_&; the programmer's interface is somewhat different to +the traditional &'ndbm'& interface. +.next +To complicate things further, there are several very different versions of the +Berkeley DB package. Version 1.85 was stable for a very long time, releases +2.&'x'& and 3.&'x'& were current for a while, but the latest versions when Exim last revamped support were numbered 4.&'x'&. +Maintenance of some of the earlier releases has ceased. All versions of +Berkeley DB could be obtained from +&url(http://www.sleepycat.com/), which is now a redirect to their new owner's +page with far newer versions listed. +It is probably wise to plan to move your storage configurations away from +Berkeley DB format, as today there are smaller and simpler alternatives more +suited to Exim's usage model. +.next +.cindex "&'tdb'& DBM library" +Yet another DBM library, called &'tdb'&, is available from +&url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also +operates on a single file. +.endlist + +.cindex "USE_DB" +.cindex "DBM libraries" "configuration for building" +Exim and its utilities can be compiled to use any of these interfaces. In order +to use any version of the Berkeley DB package in native mode, you must set +USE_DB in an appropriate configuration file (typically +&_Local/Makefile_&). For example: +.code +USE_DB=yes +.endd +Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An +error is diagnosed if you set more than one of these. + +At the lowest level, the build-time configuration sets none of these options, +thereby assuming an interface of type (1). However, some operating system +configuration files (for example, those for the BSD operating systems and +Linux) assume type (4) by setting USE_DB as their default, and the +configuration files for Cygwin set USE_GDBM. Anything you set in +&_Local/Makefile_&, however, overrides these system defaults. + +As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be +necessary to set DBMLIB, to cause inclusion of the appropriate library, as +in one of these lines: +.code +DBMLIB = -ldb +DBMLIB = -ltdb +.endd +Settings like that will work if the DBM library is installed in the standard +place. Sometimes it is not, and the library's header file may also not be in +the default path. You may need to set INCLUDE to specify where the header +file is, and to specify the path to the library more fully in DBMLIB, as in +this example: +.code +INCLUDE=-I/usr/local/include/db-4.1 +DBMLIB=/usr/local/lib/db-4.1/libdb.a +.endd +There is further detailed discussion about the various DBM libraries in the +file &_doc/dbm.discuss.txt_& in the Exim distribution. + + + +.section "Pre-building configuration" "SECID25" +.cindex "building Exim" "pre-building configuration" +.cindex "configuration for building Exim" +.cindex "&_Local/Makefile_&" +.cindex "&_src/EDITME_&" +Before building Exim, a local configuration file that specifies options +independent of any operating system has to be created with the name +&_Local/Makefile_&. A template for this file is supplied as the file +&_src/EDITME_&, and it contains full descriptions of all the option settings +therein. These descriptions are therefore not repeated here. If you are +building Exim for the first time, the simplest thing to do is to copy +&_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately. + +There are three settings that you must supply, because Exim will not build +without them. They are the location of the runtime configuration file +(CONFIGURE_FILE), the directory in which Exim binaries will be installed +(BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and +maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be +a colon-separated list of filenames; Exim uses the first of them that exists. + +There are a few other parameters that can be specified either at build time or +at runtime, to enable the same binary to be used on a number of different +machines. However, if the locations of Exim's spool directory and log file +directory (if not within the spool directory) are fixed, it is recommended that +you specify them in &_Local/Makefile_& instead of at runtime, so that errors +detected early in Exim's execution (such as a malformed configuration file) can +be logged. + +.cindex "content scanning" "specifying at build time" +Exim's interfaces for calling virus and spam scanning software directly from +access control lists are not compiled by default. If you want to include these +facilities, you need to set +.code +WITH_CONTENT_SCAN=yes +.endd +in your &_Local/Makefile_&. For details of the facilities themselves, see +chapter &<>&. + + +.cindex "&_Local/eximon.conf_&" +.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 +happy with the default settings described in &_exim_monitor/EDITME_&, +&_Local/eximon.conf_& can be empty, but it must exist. + +This is all the configuration that is needed in straightforward cases for known +operating systems. However, the building process is set up so that it is easy +to override options that are set by default or by operating-system-specific +configuration files, for example, to change the C compiler, which +defaults to &%gcc%&. See section &<>& below for details of how to +do this. + + + +.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 +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 is set at build time). The translation is possible only if the operating system +supports the &[iconv()]& function. + +However, some of the operating systems that supply &[iconv()]& do not support +very many conversions. The GNU &%libiconv%& library (available from +&url(https://www.gnu.org/software/libiconv/)) can be installed on such +systems to remedy this deficiency, as well as on systems that do not supply +&[iconv()]& at all. After installing &%libiconv%&, you should add +.code +HAVE_ICONV=yes +.endd +to your &_Local/Makefile_& and rebuild Exim. + + + +.section "Including TLS/SSL encryption support" "SECTinctlsssl" +.cindex "TLS" "including support for TLS" +.cindex "encryption" "including support for" +.cindex "OpenSSL" "building Exim with" +.cindex "GnuTLS" "building Exim with" +Exim is usually built to support encrypted SMTP connections, using the STARTTLS +command as per RFC 2487. It can also support clients that expect to +start a TLS session immediately on connection to a non-standard port (see the +&%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command +line option). + +If you want to build Exim with TLS support, you must first install either the +OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for +implementing SSL. + +If you do not want TLS support you should set +.code +DISABLE_TLS=yes +.endd +in &_Local/Makefile_&. + +If OpenSSL is installed, you should set +.code +USE_OPENSL=yes +TLS_LIBS=-lssl -lcrypto +.endd +in &_Local/Makefile_&. You may also need to specify the locations of the +OpenSSL library and include files. For example: +.code +USE_OPENSSL=yes +TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto +TLS_INCLUDE=-I/usr/local/openssl/include/ +.endd +.cindex "pkg-config" "OpenSSL" +If you have &'pkg-config'& available, then instead you can just use: +.code +USE_OPENSSL=yes +USE_OPENSSL_PC=openssl +.endd +.cindex "USE_GNUTLS" +If GnuTLS is installed, you should set +.code +USE_GNUTLS=yes +TLS_LIBS=-lgnutls -ltasn1 -lgcrypt +.endd +in &_Local/Makefile_&, and again you may need to specify the locations of the +library and include files. For example: +.code +USE_GNUTLS=yes +TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt +TLS_INCLUDE=-I/usr/gnu/include +.endd +.cindex "pkg-config" "GnuTLS" +If you have &'pkg-config'& available, then instead you can just use: +.code +USE_GNUTLS=yes +USE_GNUTLS_PC=gnutls +.endd + +You do not need to set TLS_INCLUDE if the relevant directory is already +specified in INCLUDE. Details of how to configure Exim to make use of TLS are +given in chapter &<>&. + + + + +.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 +already making use of &'tcpwrappers'& for other purposes. To do this, you +should set USE_TCP_WRAPPERS in &_Local/Makefile_&, arrange for the file +&_tcpd.h_& to be available at compile time, and also ensure that the library +&_libwrap.a_& is available at link time, typically by including &%-lwrap%& in +EXTRALIBS_EXIM. For example, if &'tcpwrappers'& is installed in &_/usr/local_&, +you might have +.code +USE_TCP_WRAPPERS=yes +CFLAGS=-O -I/usr/local/include +EXTRALIBS_EXIM=-L/usr/local/lib -lwrap +.endd +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. The daemon name used by &'tcpwrappers'& +can be changed at build time by setting TCP_WRAPPERS_DAEMON_NAME in +&_Local/Makefile_&, or by setting tcp_wrappers_daemon_name in the +configure file. Consult the &'tcpwrappers'& documentation for +further details. + + +.section "Including support for IPv6" "SECID28" +.cindex "IPv6" "including support for" +Exim contains code for use on systems that have IPv6 support. Setting +&`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included; +it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems +where the IPv6 support is not fully integrated into the normal include and +library files. + +Two different types of DNS record for handling IPv6 addresses have been +defined. AAAA records (analogous to A records for IPv4) are in use, and are +currently seen as the mainstream. Another record type called A6 was proposed +as better than AAAA because it had more flexibility. However, it was felt to be +over-complex, and its status was reduced to &"experimental"&. +Exim used to +have a compile option for including A6 record support but this has now been +withdrawn. + + + +.section "Dynamically loaded lookup module support" "SECTdynamicmodules" +.cindex "lookup modules" +.cindex "dynamic modules" +.cindex ".so building" +On some platforms, Exim supports not compiling all lookup types directly into +the main binary, instead putting some into external modules which can be loaded +on demand. +This permits packagers to build Exim with support for lookups with extensive +library dependencies without requiring all users to install all of those +dependencies. +Most, but not all, lookup types can be built this way. + +Set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be +installed; Exim will only load modules from that directory, as a security +measure. You will need to set &`CFLAGS_DYNAMIC`& if not already defined +for your OS; see &_OS/Makefile-Linux_& for an example. +Some other requirements for adjusting &`EXTRALIBS`& may also be necessary, +see &_src/EDITME_& for details. + +Then, for each module to be loaded dynamically, define the relevant +&`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes". +For example, this will build in lsearch but load sqlite and mysql support +on demand: +.code +LOOKUP_LSEARCH=yes +LOOKUP_SQLITE=2 +LOOKUP_MYSQL=2 +.endd + + +.section "The building process" "SECID29" +.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 +operating system types, and creates a build directory if one does not exist. +For example, on a Sun system running Solaris 8, the directory +&_build-SunOS5-5.8-sparc_& is created. +.cindex "symbolic link" "to source files" +Symbolic links to relevant source files are installed in the build directory. + +If this is the first time &'make'& has been run, it calls a script that builds +a make file inside the build directory, using the configuration files from the +&_Local_& directory. The new make file is then passed to another instance of +&'make'&. This does the real work, building a number of utility scripts, and +then compiling and linking the binaries for the Exim monitor (if configured), a +number of utility programs, and finally Exim itself. The command &`make +makefile`& can be used to force a rebuild of the make file in the build +directory, should this ever be necessary. + +If you have problems building Exim, check for any comments there may be in the +&_README_& file concerning your operating system, and also take a look at the +FAQ, where some common problems are covered. + + + +.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 +appears when compiling the 2.6 Linux kernel is generated: just a short line for +each module that is being compiled or linked. However, it is still possible to +get the full output, by calling &'make'& like this: +.code +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 short output. + + + +.section "Overriding build-time options for Exim" "SECToverride" +.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 +more than once, the last setting overrides any previous ones. This provides a +convenient way of overriding defaults. The files that are concatenated are, in +order: +.display +&_OS/Makefile-Default_& +&_OS/Makefile-_&<&'ostype'&> +&_Local/Makefile_& +&_Local/Makefile-_&<&'ostype'&> +&_Local/Makefile-_&<&'archtype'&> +&_Local/Makefile-_&<&'ostype'&>-<&'archtype'&> +&_OS/Makefile-Base_& +.endd +.cindex "&_Local/Makefile_&" +.cindex "building Exim" "operating system type" +.cindex "building Exim" "architecture type" +where <&'ostype'&> is the operating system type and <&'archtype'&> is the +architecture type. &_Local/Makefile_& is required to exist, and the building +process fails if it is absent. The other three &_Local_& files are optional, +and are often not needed. + +The values used for <&'ostype'&> and <&'archtype'&> are obtained from scripts +called &_scripts/os-type_& and &_scripts/arch-type_& respectively. If either of +the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their +values are used, thereby providing a means of forcing particular settings. +Otherwise, the scripts try to get values from the &%uname%& command. If this +fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number +of &'ad hoc'& transformations are then applied, to produce the standard names +that Exim expects. You can run these scripts directly from the shell in order +to find out what values are being used on your system. + + +&_OS/Makefile-Default_& contains comments about the variables that are set +therein. Some (but not all) are mentioned below. If there is something that +needs changing, review the contents of this file and the contents of the make +file for your operating system (&_OS/Makefile-_&) to see what the +default values are. + + +.cindex "building Exim" "overriding default settings" +If you need to change any of the values that are set in &_OS/Makefile-Default_& +or in &_OS/Makefile-_&, or to add any new definitions, you do not +need to change the original files. Instead, you should make the changes by +putting the new values in an appropriate &_Local_& file. For example, +.cindex "Tru64-Unix build-time settings" +when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, +formerly DEC-OSF1) operating system, it is necessary to specify that the C +compiler is called &'cc'& rather than &'gcc'&. Also, the compiler must be +called with the option &%-std1%&, to make it recognize some of the features of +Standard C that Exim uses. (Most other compilers recognize Standard C by +default.) To do this, you should create a file called &_Local/Makefile-OSF1_& +containing the lines +.code +CC=cc +CFLAGS=-std1 +.endd +If you are compiling for just one operating system, it may be easier to put +these lines directly into &_Local/Makefile_&. + +Keeping all your local configuration settings separate from the distributed +files makes it easy to transfer them to new versions of Exim simply by copying +the contents of the &_Local_& directory. + + +.cindex "NIS lookup type" "including support for" +.cindex "NIS+ lookup type" "including support for" +.cindex "LDAP" "including support for" +.cindex "lookup" "inclusion in binary" +Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file +lookup, but not all systems have these components installed, so the default is +not to include the relevant code in the binary. All the different kinds of file +and database lookup that Exim supports are implemented as separate code modules +which are included only if the relevant compile-time options are set. In the +case of LDAP, NIS, and NIS+, the settings for &_Local/Makefile_& are: +.code +LOOKUP_LDAP=yes +LOOKUP_NIS=yes +LOOKUP_NISPLUS=yes +.endd +and similar settings apply to the other lookup types. They are all listed in +&_src/EDITME_&. In many cases the relevant include files and interface +libraries need to be installed before compiling Exim. +.cindex "cdb" "including support for" +However, there are some optional lookup types (such as cdb) for which +the code is entirely contained within Exim, and no external include +files or libraries are required. When a lookup type is not included in the +binary, attempts to configure Exim to use it cause runtime configuration +errors. + +.cindex "pkg-config" "lookups" +.cindex "pkg-config" "authenticators" +Many systems now use a tool called &'pkg-config'& to encapsulate information +about how to compile against a library; Exim has some initial support for +being able to use pkg-config for lookups and authenticators. For any given +makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new +variable with the &`_PC`& suffix in the name and assign as the value the +name of the package to be queried. The results of querying via the +&'pkg-config'& command will be added to the appropriate Makefile variables +with &`+=`& directives, so your version of &'make'& will need to support that +syntax. For instance: +.code +LOOKUP_SQLITE=yes +LOOKUP_SQLITE_PC=sqlite3 +AUTH_GSASL=yes +AUTH_GSASL_PC=libgsasl +AUTH_HEIMDAL_GSSAPI=yes +AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi +.endd + +.cindex "Perl" "including support for" +Exim can be linked with an embedded Perl interpreter, allowing Perl +subroutines to be called during string expansion. To enable this facility, +.code +EXIM_PERL=perl.o +.endd +must be defined in &_Local/Makefile_&. Details of this facility are given in +chapter &<>&. + +.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 +monitor, the X11 libraries must be available. +The following three variables are set in &_OS/Makefile-Default_&: +.code +X11=/usr/X11R6 +XINCLUDE=-I$(X11)/include +XLFLAGS=-L$(X11)/lib +.endd +These are overridden in some of the operating-system configuration files. For +example, in &_OS/Makefile-SunOS5_& there is +.code +X11=/usr/openwin +XINCLUDE=-I$(X11)/include +XLFLAGS=-L$(X11)/lib -R$(X11)/lib +.endd +If you need to override the default setting for your operating system, place a +definition of all three of these variables into your +&_Local/Makefile-_& file. + +.cindex "EXTRALIBS" +If you need to add any extra libraries to the link steps, these can be put in a +variable called EXTRALIBS, which appears in all the link commands, but by +default is not defined. In contrast, EXTRALIBS_EXIM is used only on the +command for linking the main Exim binary, and not for any associated utilities. + +.cindex "DBM libraries" "configuration for building" +There is also DBMLIB, which appears in the link commands for binaries that +use DBM functions (see also section &<>&). Finally, there is +EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor +binary, and which can be used, for example, to include additional X11 +libraries. + +.cindex "configuration file" "editing" +The make file copes with rebuilding Exim correctly if any of the configuration +files are edited. However, if an optional configuration file is deleted, it is +necessary to touch the associated non-optional file (that is, +&_Local/Makefile_& or &_Local/eximon.conf_&) before rebuilding. + + +.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 +&_os.h-_&. These are system-specific C header files that should not +normally need to be changed. There is a list of macro settings that are +recognized in the file &_OS/os.configuring_&, which should be consulted if you +are porting Exim to a new operating system. + + + +.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 +&_OS/eximon.conf-Default_& +&_OS/eximon.conf-_&<&'ostype'&> +&_Local/eximon.conf_& +&_Local/eximon.conf-_&<&'ostype'&> +&_Local/eximon.conf-_&<&'archtype'&> +&_Local/eximon.conf-_&<&'ostype'&>-<&'archtype'&> +.endd +.cindex "&_Local/eximon.conf_&" +As with Exim itself, the final three files need not exist, and in this case the +&_OS/eximon.conf-_& file is also optional. The default values in +&_OS/eximon.conf-Default_& can be overridden dynamically by setting environment +variables of the same name, preceded by EXIMON_. For example, setting +EXIMON_LOG_DEPTH in the environment overrides the value of +LOG_DEPTH at runtime. +.ecindex IIDbuex + + +.section "Installing Exim binaries and scripts" "SECID32" +.cindex "installing Exim" +.cindex "BIN_DIRECTORY" +The command &`make install`& runs the &(exim_install)& script with no +arguments. The script copies binaries and utility scripts into the directory +whose name is specified by the BIN_DIRECTORY setting in &_Local/Makefile_&. +.cindex "setuid" "installing Exim with" +The install script copies files only if they are newer than the files they are +going to replace. The Exim binary is required to be owned by root and have the +&'setuid'& bit set, for normal configurations. Therefore, you must run &`make +install`& as root so that it can set up the Exim binary in this way. However, in +some special situations (for example, if a host is doing no local deliveries) +it may be possible to run Exim without making the binary setuid root (see +chapter &<>& for details). + +.cindex "CONFIGURE_FILE" +Exim's runtime configuration file is named by the CONFIGURE_FILE setting +in &_Local/Makefile_&. If this names a single file, and the file does not +exist, the default configuration file &_src/configure.default_& is copied there +by the installation script. If a runtime configuration file already exists, it +is left alone. If CONFIGURE_FILE is a colon-separated list, naming several +alternative files, no default is installed. + +.cindex "system aliases file" +.cindex "&_/etc/aliases_&" +One change is made to the default configuration file when it is installed: the +default configuration contains a router that references a system aliases file. +The path to this file is set to the value specified by +SYSTEM_ALIASES_FILE in &_Local/Makefile_& (&_/etc/aliases_& by default). +If the system aliases file does not exist, the installation script creates it, +and outputs a comment to the user. + +The created file contains no aliases, but it does contain comments about the +aliases a site should normally have. Mail aliases have traditionally been +kept in &_/etc/aliases_&. However, some operating systems are now using +&_/etc/mail/aliases_&. You should check if yours is one of these, and change +Exim's configuration if necessary. + +The default configuration uses the local host's name as the only local domain, +and is set up to do local deliveries into the shared directory &_/var/mail_&, +running as the local user. System aliases and &_.forward_& files in users' home +directories are supported, but no NIS or NIS+ support is configured. Domains +other than the name of the local host are routed using the DNS, with delivery +over SMTP. + +It is possible to install Exim for special purposes (such as building a binary +distribution) in a private part of the file system. You can do this by a +command such as +.code +make DESTDIR=/some/directory/ install +.endd +This has the effect of pre-pending the specified directory to all the file +paths, except the name of the system aliases file that appears in the default +configuration. (If a default alias file is created, its name &'is'& modified.) +For backwards compatibility, ROOT is used if DESTDIR is not set, +but this usage is deprecated. + +.cindex "installing Exim" "what is not installed" +Running &'make install'& does not copy the Exim 4 conversion script +&'convert4r4'&. You will probably run this only once if you are +upgrading from Exim 3. None of the documentation files in the &_doc_& +directory are copied, except for the info files when you have set +INFO_DIRECTORY, as described in section &<>& 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 +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). + +.cindex "installing Exim" "testing the script" +If you want to see what the &'make install'& will do before running it for +real, you can pass the &%-n%& option to the installation script by this +command: +.code +make INSTALL_ARG=-n install +.endd +The contents of the variable INSTALL_ARG are passed to the installation +script. You do not need to be root to run this test. Alternatively, you can run +the installation script directly, but this must be from within the build +directory. For example, from the top-level Exim directory you could use this +command: +.code +(cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) +.endd +.cindex "installing Exim" "install script options" +There are two other options that can be supplied to the installation script. + +.ilist +&%-no_chown%& bypasses the call to change the owner of the installed binary +to root, and the call to make it a setuid binary. +.next +&%-no_symlink%& bypasses the setting up of the symbolic link &_exim_& to the +installed binary. +.endlist + +INSTALL_ARG can be used to pass these options to the script. For example: +.code +make INSTALL_ARG=-no_symlink install +.endd +The installation script can also be given arguments specifying which files are +to be copied. For example, to install just the Exim binary, and nothing else, +without creating the symbolic link, you could use: +.code +make INSTALL_ARG='-no_symlink exim' install +.endd + + + +.section "Installing info documentation" "SECTinsinfdoc" +.cindex "installing Exim" "&'info'& documentation" +Not all systems use the GNU &'info'& system for documentation, and for this +reason, the Texinfo source of Exim's documentation is not included in the main +distribution. Instead it is available separately from the FTP site (see section +&<>&). + +If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo +source of the documentation is found in the source tree, running &`make +install`& automatically builds the info files and installs them. + + + +.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 +directory. Sub-directories are automatically created in the spool directory as +necessary. + + + + +.section "Testing" "SECID34" +.cindex "testing" "installation" +Having installed Exim, you can check that the runtime configuration file is +syntactically valid by running the following command, which assumes that the +Exim binary directory is within your PATH environment variable: +.code +exim -bV +.endd +If there are any errors in the configuration file, Exim outputs error messages. +Otherwise it outputs the version number and build date, +the DBM library that is being used, and information about which drivers and +other optional code modules are included in the binary. +Some simple routing tests can be done by using the address testing option. For +example, +.display +&`exim -bt`& <&'local username'&> +.endd +should verify that it recognizes a local mailbox, and +.display +&`exim -bt`& <&'remote address'&> +.endd +a remote one. Then try getting it to deliver mail, both locally and remotely. +This can be done by passing messages directly to Exim, without going through a +user agent. For example: +.code +exim -v postmaster@your.domain.example +From: user@your.domain.example +To: postmaster@your.domain.example +Subject: Testing Exim + +This is a test message. +^D +.endd +The &%-v%& option causes Exim to output some verification of what it is doing. +In this case you should see copies of three log lines, one for the message's +arrival, one for its delivery, and one containing &"Completed"&. + +.cindex "delivery" "problems with" +If you encounter problems, look at Exim's log files (&'mainlog'& and +&'paniclog'&) to see if there is any relevant information there. Another source +of information is running Exim with debugging turned on, by specifying the +&%-d%& option. If a message is stuck on Exim's spool, you can force a delivery +with debugging turned on by a command of the form +.display +&`exim -d -M`& <&'exim-message-id'&> +.endd +You must be root or an &"admin user"& in order to do this. The &%-d%& option +produces rather a lot of output, but you can cut this down to specific areas. +For example, if you use &%-d-all+route%& only the debugging information +relevant to routing is included. (See the &%-d%& option in chapter +&<>& for more details.) + +.cindex '&"sticky"& bit' +.cindex "lock files" +One specific problem that has shown up on some sites is the inability to do +local deliveries into a shared mailbox directory, because it does not have the +&"sticky bit"& set on it. By default, Exim tries to create a lock file before +writing to a mailbox file, and if it cannot create the lock file, the delivery +is deferred. You can get round this either by setting the &"sticky bit"& on the +directory, or by setting a specific group for local deliveries and allowing +that group to create files in the directory (see the comments above the +&(local_delivery)& transport in the default configuration file). Another +approach is to configure Exim not to use lock files, but just to rely on +&[fcntl()]& locking instead. However, you should do this only if all user +agents also use &[fcntl()]& locking. For further discussion of locking issues, +see chapter &<>&. + +One thing that cannot be tested on a system that is already running an MTA is +the receipt of incoming SMTP mail on the standard SMTP port. However, the +&%-oX%& option can be used to run an Exim daemon that listens on some other +port, or &'inetd'& can be used to do this. The &%-bh%& option and the +&'exim_checkaccess'& utility can be used to check out policy controls on +incoming SMTP mail. + +Testing a new version on a system that is already running Exim can most easily +be done by building a binary with a different CONFIGURE_FILE setting. From +within the runtime configuration, all other file and directory names +that Exim uses can be altered, in order to keep it entirely clear of the +production version. + + +.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 +is either &_/usr/sbin/sendmail_&, or &_/usr/lib/sendmail_& (depending on the +operating system), and it is necessary to make this name point to the &'exim'& +binary in order to get the user agents to pass messages to Exim. This is +normally done by renaming any existing file and making &_/usr/sbin/sendmail_& +or &_/usr/lib/sendmail_& +.cindex "symbolic link" "to &'exim'& binary" +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 "&_/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 +&_/etc/mail/mailer.conf_& instead of setting up a symbolic link as just +described. A typical example of the contents of this file for running Exim is +as follows: +.code +sendmail /usr/exim/bin/exim +send-mail /usr/exim/bin/exim +mailq /usr/exim/bin/exim -bp +newaliases /usr/bin/true +.endd +Once you have set up the symbolic link, or edited &_/etc/mail/mailer.conf_&, +your Exim installation is &"live"&. Check it by sending a message from your +favourite user agent. + +You should consider what to tell your users about the change of MTA. Exim may +have different capabilities to what was previously running, and there are +various operational differences such as the text of messages produced by +command line options and in bounce messages. If you allow your users to make +use of Exim's filtering capabilities, you should make the document entitled +&'Exim's interface to mail filtering'& available to them. + + + +.section "Upgrading Exim" "SECID36" +.cindex "upgrading Exim" +If you are already running Exim on your host, building and installing a new +version automatically makes it available to MUAs, or any other programs that +call the MTA directly. However, if you are running an Exim daemon, you do need +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" +to send it a HUP signal, to make it re-execute itself, and thereby pick up the +new binary. You do not need to stop processing mail in order to install a new +version of Exim. The install script does not modify an existing runtime +configuration file. + + + + +.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 +/etc/init.d/sendmail stop +.endd +If &_/usr/lib/sendmail_& has been turned into a symbolic link, this script +fails to stop Exim because it uses the command &'ps -e'& and greps the output +for the text &"sendmail"&; this is not present because the actual program name +(that is, &"exim"&) is given by the &'ps'& command with these options. A +solution is to replace the line that finds the process id with something like +.code +pid=`cat /var/spool/exim/exim-daemon.pid` +.endd +to obtain the daemon's pid directly from the file that Exim saves it in. + +Note, however, that stopping the daemon does not &"stop Exim"&. Messages can +still be received from local processes, and if automatic delivery is configured +(the normal case), deliveries will still occur. + + + + +. //////////////////////////////////////////////////////////////////////////// +. //////////////////////////////////////////////////////////////////////////// + +.chapter "The Exim command line" "CHAPcommandline" +.scindex IIDclo1 "command line" "options" +.scindex IIDclo2 "options" "command line" +Exim's command line takes the standard Unix form of a sequence of options, +each starting with a hyphen character, followed by a number of arguments. The +options are compatible with the main options of Sendmail, and there are also +some additional options, some of which are compatible with Smail 3. Certain +combinations of options do not make sense, and provoke an error if used. +The form of the arguments depends on which options are set. + + +.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. +The &%-bp%& option requests a listing of the contents of the mail queue on the +standard output. +This feature is for compatibility with some systems that contain a command of +that name in one of the standard libraries, symbolically linked to +&_/usr/sbin/sendmail_& or &_/usr/lib/sendmail_&. + +.cindex "&'rsmtp'&" +If Exim is called under the name &'rsmtp'& it behaves as if the option &%-bS%& +were present before any other options, for compatibility with Smail. The +&%-bS%& option is used for reading in a number of messages in batched SMTP +format. + +.cindex "&'rmail'&" +If Exim is called under the name &'rmail'& it behaves as if the &%-i%& and +&%-oee%& options were present before any other options, for compatibility with +Smail. The name &'rmail'& is used as an interface by some UUCP systems. + +.cindex "&'runq'&" +.cindex "queue runner" +If Exim is called under the name &'runq'& it behaves as if the option &%-q%& +were present before any other options, for compatibility with Smail. The &%-q%& +option causes a single queue runner process to be started. + +.cindex "&'newaliases'&" +.cindex "alias file" "building" +.cindex "Sendmail compatibility" "calling Exim as &'newaliases'&" +If Exim is called under the name &'newaliases'& it behaves as if the option +&%-bi%& were present before any other options, for compatibility with Sendmail. +This option is used for rebuilding Sendmail's alias file. Exim does not have +the concept of a single alias file, but can be configured to run a given +command if called with the &%-bi%& option. + + +.section "Trusted and admin users" "SECTtrustedadmin" +Some Exim options are available only to &'trusted users'& and others are +available only to &'admin users'&. In the description below, the phrases &"Exim +user"& and &"Exim group"& mean the user and group defined by EXIM_USER and +EXIM_GROUP in &_Local/Makefile_& or set by the &%exim_user%& and +&%exim_group%& options. These do not necessarily have to use the name &"exim"&. + +.ilist +.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 +supplementary group is one of those listed in the &%trusted_groups%& +configuration option. Note that the Exim group is not automatically trusted. + +.cindex '&"From"& line' +.cindex "envelope from" +.cindex "envelope sender" +Trusted users are always permitted to use the &%-f%& option or a leading +&"From&~"& line to specify the envelope sender of a message that is passed to +Exim through the local interface (see the &%-bm%& and &%-f%& options below). +See the &%untrusted_set_sender%& option for a way of permitting non-trusted +users to set envelope senders. + +.cindex "&'From:'& header line" +.cindex "&'Sender:'& header line" +.cindex "header lines" "From:" +.cindex "header lines" "Sender:" +For a trusted user, there is never any check on the contents of the &'From:'& +header line, and a &'Sender:'& line is never added. Furthermore, any existing +&'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. + +Trusted users may also specify a host name, host address, interface address, +protocol name, ident value, and authentication data when submitting a message +locally. Thus, they are able to insert messages into Exim's queue locally that +have the characteristics of messages received from a remote host. Untrusted +users may in some circumstances use &%-f%&, but can never set the other values +that are available to trusted users. +.next +.cindex "user" "admin definition of" +.cindex "admin user" "definition of" +The admin users are root, the Exim user, and any user that is a member of the +Exim group or of any group listed in the &%admin_groups%& configuration option. +The current group does not have to be one of these groups. + +Admin users are permitted to list the queue, and to carry out certain +operations on messages, for example, to force delivery failures. It is also +necessary to be an admin user in order to see the full information provided by +the Exim monitor, and full debugging output. + +By default, the use of the &%-M%&, &%-q%&, &%-R%&, and &%-S%& options to cause +Exim to attempt delivery of messages on its queue is restricted to admin users. +However, this restriction can be relaxed by setting the &%prod_requires_admin%& +option false (that is, specifying &%no_prod_requires_admin%&). + +Similarly, the use of the &%-bp%& option to list all the messages in the queue +is restricted to admin users unless &%queue_list_requires_admin%& is set +false. +.endlist + + +&*Warning*&: If you configure your system so that admin users are able to +edit Exim's configuration file, you are giving those users an easy way of +getting root. There is further discussion of this issue at the start of chapter +&<>&. + + + + +.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 +. options. This is for the benefit of the Perl script that automatically +. creates a man page for the options. +. //////////////////////////////////////////////////////////////////////////// + +.literal xml + +.literal off + + +.vlist +.vitem &%--%& +.oindex "--" +.cindex "options" "command line; terminating" +This is a pseudo-option whose only purpose is to terminate the options and +therefore to cause subsequent command line items to be treated as arguments +rather than options, even if they begin with hyphens. + +.vitem &%--help%& +.oindex "&%--help%&" +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" +.cindex "Sendmail compatibility" "8-bit characters" +This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit +clean; it ignores this option. + +.vitem &%-bd%& +.oindex "&%-bd%&" +.cindex "daemon" +.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 +that the daemon should also initiate periodic queue runs. + +The &%-bd%& option can be used only by an admin user. If either of the &%-d%& +(debugging) or &%-v%& (verifying) options are set, the daemon does not +disconnect from the controlling terminal. When running this way, it can be +stopped by pressing ctrl-C. + +By default, Exim listens for incoming connections to the standard SMTP port on +all the host's running interfaces. However, it is possible to listen on other +ports, on multiple ports, and only on specific interfaces. Chapter +&<>& contains a description of the options that control this. + +When a listening daemon +.cindex "daemon" "process id (pid)" +.cindex "pid (process id)" "of daemon" +is started without the use of &%-oX%& (that is, without overriding the normal +configuration), it writes its process id to a file called &_exim-daemon.pid_& +in Exim's spool directory. This location can be overridden by setting +PID_FILE_PATH in &_Local/Makefile_&. The file is written while Exim is still +running as root. + +When &%-oX%& is used on the command line to start a listening daemon, the +process id is not written to the normal pid file path. However, &%-oP%& can be +used to specify a path on the command line if a pid file is required. + +The SIGHUP signal +.cindex "SIGHUP" +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" +.cindex "daemon" "restarting" +.cindex signal "to reload configuration" +.cindex daemon "reload configuration" +.cindex reload configuration +can be used to cause the daemon to re-execute itself. This should be done +whenever Exim's configuration file, or any file that is incorporated into it by +means of the &%.include%& facility, is changed, and also whenever a new version +of Exim is installed. It is not necessary to do this when other files that are +referenced from the configuration (for example, alias files) are changed, +because these are reread each time they are used. + +.vitem &%-bdf%& +.oindex "&%-bdf%&" +This option has the same effect as &%-bd%& except that it never disconnects +from the controlling terminal, even when no debugging is specified. + +.vitem &%-be%& +.oindex "&%-be%&" +.cindex "testing" "string expansion" +.cindex "expansion" "testing" +Run Exim in expansion testing mode. Exim discards its root privilege, to +prevent ordinary users from using this mode to read otherwise inaccessible +files. If no arguments are given, Exim runs interactively, prompting for lines +of data. Otherwise, it processes each argument in turn. + +If Exim was built with USE_READLINE=yes in &_Local/Makefile_&, it tries +to load the &%libreadline%& library dynamically whenever the &%-be%& option is +used without command line arguments. If successful, it uses the &[readline()]& +function, which provides extensive line-editing facilities, for reading the +test data. A line history is supported. + +Long expansion expressions can be split over several lines by using backslash +continuations. As in Exim's runtime configuration, white space at the start of +continuation lines is ignored. Each argument or data line is passed through the +string expansion mechanism, and the result is output. Variable values from the +configuration file (for example, &$qualify_domain$&) are available, but no +message-specific values (such as &$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. + +Macro processing is done on lines before string-expansion: new macros can be +defined and macros will be expanded. +Because macros in the config file are often used for secrets, those are only +available to admin users. + +.vitem &%-bem%&&~<&'filename'&> +.oindex "&%-bem%&" +.cindex "testing" "string expansion" +.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" +.cindex "testing" "system filter" +This option is the same as &%-bf%& except that it assumes that the filter being +tested is a system filter. The additional commands that are available only in +system filters are recognized. + +.vitem &%-bf%&&~<&'filename'&> +.oindex "&%-bf%&" +.cindex "filter" "testing" +.cindex "testing" "filter file" +.cindex "forward file" "testing" +.cindex "testing" "forward file" +.cindex "Sieve filter" "testing" +This option runs Exim in user filter testing mode; the file is the filter file +to be tested, and a test message must be supplied on the standard input. If +there are no message-dependent tests in the filter, an empty file can be +supplied. + +If you want to test a system filter file, use &%-bF%& instead of &%-bf%&. You +can use both &%-bF%& and &%-bf%& on the same command, in order to test a system +filter and a user filter in the same run. For example: +.code +exim -bF /system/filter -bf /user/filter >& to +&<>& for a description of the possible contents of non-filter +redirection lists. + +The result of an Exim command that uses &%-bf%&, provided no errors are +detected, is a list of the actions that Exim would try to take if presented +with the message for real. More details of filter testing are given in the +separate document entitled &'Exim's interfaces to mail filtering'&. + +When testing a filter file, +.cindex "&""From""& line" +.cindex "envelope from" +.cindex "envelope sender" +.oindex "&%-f%&" "for filter testing" +the envelope sender can be set by the &%-f%& option, +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 +can be set by means of additional command line options (see the next four +options). + +.vitem &%-bfd%&&~<&'domain'&> +.oindex "&%-bfd%&" +.vindex "&$qualify_domain$&" +This sets the domain of the recipient address when a filter file is being +tested by means of the &%-bf%& option. The default is the value of +&$qualify_domain$&. + +.vitem &%-bfl%&&~<&'local&~part'&> +.oindex "&%-bfl%&" +This sets the local part of the recipient address when a filter file is being +tested by means of the &%-bf%& option. The default is the username of the +process that calls Exim. A local part should be specified with any prefix or +suffix stripped, because that is how it appears to the filter when a message is +actually being delivered. + +.vitem &%-bfp%&&~<&'prefix'&> +.oindex "&%-bfp%&" +.cindex affix "filter testing" +This sets the prefix of the local part of the recipient address when a filter +file is being tested by means of the &%-bf%& option. The default is an empty +prefix. + +.vitem &%-bfs%&&~<&'suffix'&> +.oindex "&%-bfs%&" +.cindex affix "filter testing" +This sets the suffix of the local part of the recipient address when a filter +file is being tested by means of the &%-bf%& option. The default is an empty +suffix. + +.vitem &%-bh%&&~<&'IP&~address'&> +.oindex "&%-bh%&" +.cindex "testing" "incoming SMTP" +.cindex "SMTP" "testing incoming" +.cindex "testing" "relay control" +.cindex "relaying" "testing configuration" +.cindex "policy control" "testing" +.cindex "debugging" "&%-bh%& option" +This option runs a fake SMTP session as if from the given IP address, using the +standard input and output. The IP address may include a port number at the end, +after a full stop. For example: +.code +exim -bh 10.9.8.7.1234 +exim -bh fe80::a00:20ff:fe86:a061.5678 +.endd +When an IPv6 address is given, it is converted into canonical form. In the case +of the second example above, the value of &$sender_host_address$& after +conversion to the canonical form is +&`fe80:0000:0000:0a00:20ff:fe86:a061.5678`&. + +Comments as to what is going on are written to the standard error file. These +include lines beginning with &"LOG"& for anything that would have been logged. +This facility is provided for testing configuration options for incoming +messages, to make sure they implement the required policy. For example, you can +test your relay controls using &%-bh%&. + +&*Warning 1*&: +.cindex "RFC 1413" +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 +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, +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(https://www.jetmore.org/john/code/swaks/,swaks). + +.vitem &%-bhc%&&~<&'IP&~address'&> +.oindex "&%-bhc%&" +This option operates in the same way as &%-bh%&, except that address +verification callouts are performed if required. This includes consulting and +updating the callout cache database. + +.vitem &%-bi%& +.oindex "&%-bi%&" +.cindex "alias file" "building" +.cindex "building alias file" +.cindex "Sendmail compatibility" "&%-bi%& option" +Sendmail interprets the &%-bi%& option as a request to rebuild its alias file. +Exim does not have the concept of a single alias file, and so it cannot mimic +this behaviour. However, calls to &_/usr/lib/sendmail_& with the &%-bi%& option +tend to appear in various scripts such as NIS make files, so the option must be +recognized. + +If &%-bi%& is encountered, the command specified by the &%bi_command%& +configuration option is run, under the uid and gid of the caller of Exim. If +the &%-oA%& option is used, its value is passed to the command as an argument. +The command set by &%bi_command%& may not contain arguments. The command can +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 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 +if no other conflicting option is present. + +If any addresses in the message are unqualified (have no domain), they are +qualified by the values of the &%qualify_domain%& or &%qualify_recipient%& +options, as appropriate. The &%-bnq%& option (see below) provides a way of +suppressing this for special cases. + +Policy checks on the contents of local messages can be enforced by means of +the non-SMTP ACL. See chapter &<>& for details. + +.cindex "return code" "for &%-bm%&" +The return code is zero if the message is successfully accepted. Otherwise, the +action is controlled by the &%-oe%&&'x'& option setting &-- see below. + +The format +.cindex "message" "format" +.cindex "format" "message" +.cindex "&""From""& line" +.cindex "UUCP" "&""From""& line" +.cindex "Sendmail compatibility" "&""From""& line" +of the message must be as defined in RFC 2822, except that, for +compatibility with Sendmail and Smail, a line in one of the forms +.code +From sender Fri Jan 5 12:55 GMT 1997 +From sender Fri, 5 Jan 97 12:55:01 +.endd +(with the weekday optional, and possibly with additional text after the date) +is permitted to appear at the start of the message. There appears to be no +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. + +.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" +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 +envelopes, and addresses in header lines. Sender addresses are qualified using +&%qualify_domain%&, and recipient addresses using &%qualify_recipient%& (which +defaults to the value of &%qualify_domain%&). + +Sometimes, qualification is not wanted. For example, if &%-bS%& (batch SMTP) is +being used to re-submit messages that originally came from remote hosts after +content scanning, you probably do not want to qualify unqualified addresses in +header lines. (Such lines will be present only if you have not enabled a header +syntax check in the appropriate ACL.) + +The &%-bnq%& option suppresses all qualification of unqualified addresses in +messages that originate on the local host. When this is used, unqualified +addresses in the envelope provoke errors (causing message rejection) and +unqualified addresses in header lines are left alone. + + +.vitem &%-bP%& +.oindex "&%-bP%&" +.cindex "configuration options" "extracting" +.cindex "options" "configuration &-- extracting" +If this option is given with no arguments, it causes the values of all Exim's +main configuration options to be written to the standard output. The values +of one or more specific options can be requested by giving their names as +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 &%config%& is given as an argument, the config is +output, as it was parsed, any include file resolved, any comment removed. + +If &%config_file%& is given as an argument, the name of the runtime +configuration file is output. (&%configure_file%& works too, for +backward compatibility.) +If a list of configuration files was supplied, the value that is output here +is the name of the file that was actually used. + +.cindex "options" "hiding name of" +If the &%-n%& flag is given, then for most modes of &%-bP%& operation the +name will not be output. + +.cindex "daemon" "process id (pid)" +.cindex "pid (process id)" "of daemon" +If &%log_file_path%& or &%pid_file_path%& are given, the names of the +directories where log files and daemon pid files are written are output, +respectively. If these values are unset, log files are written in a +sub-directory of the spool directory called &%log%&, and the pid file is +written directly into the spool directory. + +If &%-bP%& is followed by a name preceded by &`+`&, for example, +.code +exim -bP +local_domains +.endd +it searches for a matching named list of any type (domain, host, address, or +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: +.code +exim -bP transport local_delivery +.endd +The generic driver options are output first, followed by the driver's private +options. A list of the names of drivers of a particular type can be obtained by +using one of the words &%router_list%&, &%transport_list%&, or +&%authenticator_list%&, and a complete list of all drivers with their option +settings can be obtained by using &%routers%&, &%transports%&, or +&%authenticators%&. + +.cindex "environment" +If &%environment%& is given as an argument, the set of environment +variables is output, line by line. Using the &%-n%& flag suppresses the value of the +variables. + +.cindex "options" "macro &-- extracting" +If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& +are available, similarly to the drivers. Because macros are sometimes used +for storing passwords, this option is restricted. +The output format is one item per line. +For the "-bP macro " form, if no such macro is found +the exit status will be nonzero. + +.vitem &%-bp%& +.oindex "&%-bp%&" +.cindex "queue" "listing messages in" +.cindex "listing" "messages in the queue" +This option requests a listing of the contents of the mail queue on the +standard output. If the &%-bp%& option is followed by a list of message ids, +just those messages are listed. By default, this option can be used only by an +admin user. However, the &%queue_list_requires_admin%& option can be set false +to allow any user to see the queue. + +Each message in the queue is displayed as in the following example: +.code +25m 2.9K 0t5C6f-0000c8-00 + red.king@looking-glass.fict.example + +.endd +.cindex "message" "size in queue listing" +.cindex "size" "of message" +The first line contains the length of time the message has been in the queue +(in this case 25 minutes), the size of the message (2.9K), the unique local +identifier for the message, and the message sender, as contained in the +envelope. For bounce messages, the sender address is empty, and appears as +&"<>"&. If the message was submitted locally by an untrusted user who overrode +the default sender address, the user's login name is shown in parentheses +before the sender address. + +.cindex "frozen messages" "in queue listing" +If the message is frozen (attempts to deliver it are suspended) then the text +&"*** frozen ***"& is displayed at the end of this line. + +The recipients of the message (taken from the envelope, not the headers) are +displayed on subsequent lines. Those addresses to which the message has already +been delivered are marked with the letter D. If an original address gets +expanded into several addresses via an alias or forward file, the original is +displayed with a D only when deliveries for all of its child addresses are +complete. + + +.vitem &%-bpa%& +.oindex "&%-bpa%&" +This option operates like &%-bp%&, but in addition it shows delivered addresses +that were generated from the original top level address(es) in each message by +alias or forwarding operations. These addresses are flagged with &"+D"& instead +of just &"D"&. + + +.vitem &%-bpc%& +.oindex "&%-bpc%&" +.cindex "queue" "count of messages on" +This option counts the number of messages in the queue, and writes the total +to the standard output. It is restricted to admin users, unless +&%queue_list_requires_admin%& is set false. + + +.vitem &%-bpr%& +.oindex "&%-bpr%&" +This option operates like &%-bp%&, but the output is not sorted into +chronological order of message arrival. This can speed it up when there are +lots of messages in the queue, and is particularly useful if the output is +going to be post-processed in a way that doesn't need the sorting. + +.vitem &%-bpra%& +.oindex "&%-bpra%&" +This option is a combination of &%-bpr%& and &%-bpa%&. + +.vitem &%-bpru%& +.oindex "&%-bpru%&" +This option is a combination of &%-bpr%& and &%-bpu%&. + + +.vitem &%-bpu%& +.oindex "&%-bpu%&" +This option operates like &%-bp%& but shows only undelivered top-level +addresses for each message displayed. Addresses generated by aliasing or +forwarding are not shown, unless the message was deferred after processing by a +router with the &%one_time%& option set. + + +.vitem &%-brt%& +.oindex "&%-brt%&" +.cindex "testing" "retry configuration" +.cindex "retry" "configuration testing" +This option is for testing retry rules, and it must be followed by up to three +arguments. It causes Exim to look for a retry rule that matches the values +and to write it to the standard output. For example: +.code +exim -brt bach.comp.mus.example +Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; +.endd +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 +contains a dot, it is interpreted as an optional second domain name; if no +retry rule is found for the first argument, the second is tried. This ties in +with Exim's behaviour when looking for retry rules for remote hosts &-- if no +rule is found that matches the host, one that matches the mail domain is +sought. Finally, an argument that is the name of a specific delivery error, as +used in setting up retry rules, can be given. For example: +.code +exim -brt haydn.comp.mus.example quota_3d +Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m +.endd + +.vitem &%-brw%& +.oindex "&%-brw%&" +.cindex "testing" "rewriting" +.cindex "rewriting" "testing" +This option is for testing address rewriting rules, and it must be followed by +a single argument, consisting of either a local part without a domain, or a +complete address with a fully qualified domain. Exim outputs how this address +would be rewritten for each possible place it might appear. See chapter +&<>& for further details. + +.vitem &%-bS%& +.oindex "&%-bS%&" +.cindex "SMTP" "batched incoming" +.cindex "batched SMTP input" +This option is used for batched SMTP input, which is an alternative interface +for non-interactive local message submission. A number of messages can be +submitted in a single run. However, despite its name, this is not really SMTP +input. Exim reads each message's envelope from SMTP commands on the standard +input, but generates no responses. If the caller is trusted, or +&%untrusted_set_sender%& is set, the senders in the SMTP MAIL commands are +believed; otherwise the sender is always the caller of Exim. + +The message itself is read from the standard input, in SMTP format (leading +dots doubled), terminated by a line containing just a single dot. An error is +provoked if the terminating dot is missing. A further message may then follow. + +As for other local message submissions, the contents of incoming batch SMTP +messages can be checked using the non-SMTP ACL (see chapter &<>&). +Unqualified addresses are automatically qualified using &%qualify_domain%& and +&%qualify_recipient%&, as appropriate, unless the &%-bnq%& option is used. + +Some other SMTP commands are recognized in the input. HELO and EHLO act +as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; +QUIT quits, ignoring the rest of the standard input. + +.cindex "return code" "for &%-bS%&" +If any error is encountered, reports are written to the standard output and +error streams, and Exim gives up immediately. The return code is 0 if no error +was detected; it is 1 if one or more messages were accepted before the error +was detected; otherwise it is 2. + +More details of input using batched SMTP are given in section +&<>&. + +.vitem &%-bs%& +.oindex "&%-bs%&" +.cindex "SMTP" "local input" +.cindex "local SMTP input" +This option causes Exim to accept one or more messages by reading SMTP commands +on the standard input, and producing SMTP replies on the standard output. SMTP +policy controls, as defined in ACLs (see chapter &<>&) are applied. +Some user agents use this interface as a way of passing locally-generated +messages to the MTA. + +In +.cindex "sender" "source of" +this usage, if the caller of Exim is trusted, or &%untrusted_set_sender%& is +set, the senders of messages are taken from the SMTP MAIL commands. +Otherwise the content of these commands is ignored and the sender is set up as +the calling user. Unqualified addresses are automatically qualified using +&%qualify_domain%& and &%qualify_recipient%&, as appropriate, unless the +&%-bnq%& option is used. + +.cindex "inetd" +The +&%-bs%& option is also used to run Exim from &'inetd'&, as an alternative to +using a listening daemon. Exim can distinguish the two cases by checking +whether the standard input is a TCP/IP socket. When Exim is called from +&'inetd'&, the source of the mail is assumed to be remote, and the comments +above concerning senders and qualification do not apply. In this situation, +Exim behaves in exactly the same way as it does when receiving a message via +the listening daemon. + +.vitem &%-bt%& +.oindex "&%-bt%&" +.cindex "testing" "addresses" +.cindex "address" "testing" +This option runs Exim in address testing mode, in which each argument is taken +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. + +Unlike the &%-be%& test option, you cannot arrange for Exim to use the +&[readline()]& function, because it is running as &'root'& and there are +security issues. + +Each address is handled as if it were the recipient address of a message +(compare the &%-bv%& option). It is passed to the routers and the result is +written to the standard output. However, any router that has +&%no_address_test%& set is bypassed. This can make &%-bt%& easier to use for +genuine routing tests if your first router passes everything to a scanner +program. + +.cindex "return code" "for &%-bt%&" +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, +.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 +whose behaviour depends on the contents of an incoming message, you cannot test +those conditions using &%-bt%&. The &%-N%& option provides a possible way of +doing such tests. + +.vitem &%-bV%& +.oindex "&%-bV%&" +.cindex "version number of Exim" +This option causes Exim to write the current version number, compilation +number, and compilation date of the &'exim'& binary to the standard output. +It also lists the DBM library that is being used, the optional modules (such as +specific lookup types), the drivers that are included in the binary, and the +name of the runtime configuration file that is in use. + +As part of its operation, &%-bV%& causes Exim to read and syntax check its +configuration file. However, this is a static check only. It cannot check +values that are to be expanded. For example, although a misspelt ACL verb is +detected, an error in the verb's arguments is not. You cannot rely on &%-bV%& +alone to discover (for example) all the typos in the configuration; some +realistic testing is needed. The &%-bh%& and &%-N%& options provide more +dynamic testing facilities. + +.vitem &%-bv%& +.oindex "&%-bv%&" +.cindex "verifying address" "using &%-bv%&" +.cindex "address" "verification" +This option runs Exim in address verification mode, in which each argument is +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, 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 +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 verified. + +Unlike the &%-be%& test option, you cannot arrange for Exim to use the +&[readline()]& function, because it is running as &'exim'& and there are +security issues. + +Verification differs from address testing (the &%-bt%& option) in that routers +that have &%no_verify%& set are skipped, and if the address is accepted by a +router that has &%fail_verify%& set, verification fails. The address is +verified as a recipient if &%-bv%& is used; to test verification for a sender +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. 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%&" +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. + +If any of the routers in the configuration makes any tests on the sender +address of a message, you should use the &%-f%& option to set an appropriate +sender when running &%-bv%& tests. Without it, the sender is assumed to be the +calling user at the default qualifying domain. + +.vitem &%-bvs%& +.oindex "&%-bvs%&" +This option acts like &%-bv%&, but verifies the address as a sender rather +than a recipient address. This affects any rewriting and qualification that +might happen. + +.vitem &%-bw%& +.oindex "&%-bw%&" +.cindex "daemon" +.cindex "inetd" +.cindex "inetd" "wait mode" +This option runs Exim as a daemon, awaiting incoming SMTP connections, +similarly to the &%-bd%& option. All port specifications on the command-line +and in the configuration file are ignored. Queue-running may not be specified. + +In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is +listening for connections. This permits the system to start up and have +inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for +each port only when the first connection is received. + +If the option is given as &%-bw%&<&'time'&> then the time is a timeout, after +which the daemon will exit, which should cause inetd to listen once more. + +.vitem &%-C%&&~<&'filelist'&> +.oindex "&%-C%&" +.cindex "configuration file" "alternate" +.cindex "CONFIGURE_FILE" +.cindex "alternate configuration file" +This option causes Exim to find the runtime configuration file from the given +list instead of from the list specified by the CONFIGURE_FILE +compile-time setting. Usually, the list will consist of just a single filename, +but it can be a colon-separated list of names. In this case, the first +file that exists is used. Failure to open an existing file stops Exim from +proceeding any further along the list, and an error is generated. + +When this option is used by a caller other than root, and the list is different +from the compiled-in list, Exim gives up its root privilege immediately, and +runs with the real and effective uid and gid set to those of the caller. +However, if a TRUSTED_CONFIG_LIST file is defined in &_Local/Makefile_&, that +file contains a list of full pathnames, one per line, for configuration files +which are trusted. Root privilege is retained for any configuration file so +listed, as long as the caller is the Exim user (or the user specified in the +CONFIGURE_OWNER option, if any), and as long as the configuration file is +not writeable by inappropriate users or groups. + +Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a +configuration using &%-C%& right through message reception and delivery, +even if the caller is root. The reception works, but by that time, Exim is +running as the Exim user, so when it re-executes to regain privilege for the +delivery, the use of &%-C%& causes privilege to be lost. However, root can +test reception and delivery using two separate commands (one to put a message +in the queue, using &%-odq%&, and another to do the delivery, using &%-M%&). + +If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a +prefix string with which any file named in a &%-C%& command line option +must start. In addition, the filename must not contain the sequence &`/../`&. +However, if the value of the &%-C%& option is identical to the value of +CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as +usual. There is no default setting for ALT_CONFIG_PREFIX; when it is +unset, any filename can be used with &%-C%&. + +ALT_CONFIG_PREFIX can be used to confine alternative configuration files +to a directory to which only root has access. This prevents someone who has +broken into the Exim account from running a privileged Exim with an arbitrary +configuration file. + +The &%-C%& facility is useful for ensuring that configuration files are +syntactically correct, but cannot be used for test deliveries, unless the +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" +This option can be used to override macro definitions in the configuration file +(see section &<>&). However, like &%-C%&, if it is used by an +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 +synonymous: +.code +exim -DABC ... +exim -DABC= ... +.endd +To include spaces in a macro definition item, quotes must be used. If you use +quotes, spaces are permitted around the macro name and the equals sign. For +example: +.code +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%&" +.cindex "debugging" "list of selectors" +.cindex "debugging" "&%-d%& option" +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. 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 +&`deliver `& general delivery logic +&`dns `& DNS lookups (see also resolver) +&`dnsbl `& DNS black list (aka RBL) code +&`exec `& arguments for &[execv()]& calls +&`expand `& detailed debugging for string expansions +&`filter `& filter handling +&`hints_lookup `& hints data lookups +&`host_lookup `& all types of name-to-IP address handling +&`ident `& ident lookup +&`interface `& lists of local interfaces +&`lists `& matching things in lists +&`load `& system load checks +&`local_scan `& can be used by &[local_scan()]& (see chapter &&& + &<>&) +&`lookup `& general lookup code and all lookups +&`memory `& memory handling +&`noutf8 `& modifier: avoid UTF-8 line-drawing +&`pid `& modifier: add pid to debug output lines +&`process_info `& setting info for the process log +&`queue_run `& queue runs +&`receive `& general message reception logic +&`resolver `& turn on the DNS resolver's debugging output +&`retry `& retry handling +&`rewrite `& address rewriting +&`route `& address routing +&`timestamp `& modifier: add timestamp to debug output lines +&`tls `& TLS logic +&`transport `& transports +&`uid `& changes of uid/gid and looking up uid/gid +&`verify `& address verification logic +&`all `& almost all of the above (see below), and also &%-v%& +.endd +The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it +for &`-all`&. The reason for this is that &`+all`& is something that people +tend to use when generating debug output for Exim maintainers. If &`+memory`& +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" +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 +rather than stderr. + +The default (&%-d%& with no argument) omits &`expand`&, &`filter`&, +&`interface`&, &`load`&, &`memory`&, &`pid`&, &`resolver`&, and &`timestamp`&. +However, the &`pid`& selector is forced when debugging is turned on for a +daemon, which then passes it on to any re-executed Exims. Exim also +automatically adds the pid to debug lines when several remote deliveries are +run in parallel. + +The &`timestamp`& selector causes the current time to be inserted at the start +of all debug output lines. This can be useful when trying to track down delays +in processing. + +.cindex debugging "UTF-8 in" +.cindex UTF-8 "in debug output" +The &`noutf8`& selector disables the use of +UTF-8 line-drawing characters to group related information. +When disabled. ascii-art is used instead. +Using the &`+all`& option does not set this modifier, + +If the &%debug_print%& option is set in any driver, it produces output whenever +any debugging is selected, or if &%-v%& is used. + +.vitem &%-dd%&<&'debug&~options'&> +.oindex "&%-dd%&" +This option behaves exactly like &%-d%& except when used on a command that +starts a daemon process. In that case, debugging is turned off for the +subprocesses that the daemon creates. Thus, it is useful for monitoring the +behaviour of the daemon without creating as much output as full debugging does. + +.vitem &%-dropcr%& +.oindex "&%-dropcr%&" +This is an obsolete option that is now a no-op. It used to affect the way Exim +handled CR and LF characters in incoming messages. What happens now is +described in section &<>&. + +.vitem &%-E%& +.oindex "&%-E%&" +.cindex "bounce message" "generating" +This option specifies that an incoming message is a locally-generated delivery +failure report. It is used internally by Exim when handling delivery failures +and is not intended for external use. Its only effect is to stop Exim +generating certain messages to the postmaster, as otherwise message cascades +could occur in some situations. As part of the same option, a message id may +follow the characters &%-E%&. If it does, the log entry for the receipt of the +new message contains the id, following &"R="&, as a cross-reference. + +.vitem &%-e%&&'x'& +.oindex "&%-e%&&'x'&" +There are a number of Sendmail options starting with &%-oe%& which seem to be +called by various programs without the leading &%o%& in the option. For +example, the &%vacation%& program uses &%-eq%&. Exim treats all options of the +form &%-e%&&'x'& as synonymous with the corresponding &%-oe%&&'x'& options. + +.vitem &%-F%&&~<&'string'&> +.oindex "&%-F%&" +.cindex "sender" "name" +.cindex "name" "of sender" +This option sets the sender's full name for use when a locally-generated +message is being accepted. In the absence of this option, the user's &'gecos'& +entry from the password data is used. As users are generally permitted to alter +their &'gecos'& entries, no security considerations are involved. White space +between &%-F%& and the <&'string'&> is optional. + +.vitem &%-f%&&~<&'address'&> +.oindex "&%-f%&" +.cindex "sender" "address" +.cindex "address" "sender" +.cindex "trusted users" +.cindex "envelope from" +.cindex "envelope sender" +.cindex "user" "trusted" +This option sets the address of the envelope sender of a locally-generated +message (also known as the return path). The option can normally be used only +by a trusted user, but &%untrusted_set_sender%& can be set to allow untrusted +users to use it. + +Processes running as root or the Exim user are always trusted. Other +trusted users are defined by the &%trusted_users%& or &%trusted_groups%& +options. In the absence of &%-f%&, or if the caller is not trusted, the sender +of a local message is set to the caller's login name at the default qualify +domain. + +There is one exception to the restriction on the use of &%-f%&: an empty sender +can be specified by any user, trusted or not, to create a message that can +never provoke a bounce. An empty sender can be specified either as an empty +string, or as a pair of angle brackets with nothing between them, as in these +examples of shell commands: +.code +exim -f '<>' user@domain +exim -f "" user@domain +.endd +In addition, the use of &%-f%& is not restricted when testing a filter file +with &%-bf%& or when testing or verifying addresses using the &%-bt%& or +&%-bv%& options. + +Allowing untrusted users to change the sender address does not of itself make +it possible to send anonymous mail. Exim still checks that the &'From:'& header +refers to the local user, and if it does not, it adds a &'Sender:'& header, +though this can be overridden by setting &%no_local_from_check%&. + +White +.cindex "&""From""& line" +space between &%-f%& and the <&'address'&> is optional (that is, they can be +given as two arguments or one combined argument). The sender of a +locally-generated message can also be set (when permitted) by an initial +&"From&~"& line in the message &-- see the description of &%-bm%& above &-- but +if &%-f%& is also present, it overrides &"From&~"&. + +.vitem &%-G%& +.oindex "&%-G%&" +.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%&" +.cindex "Sendmail compatibility" "&%-h%& option ignored" +This option is accepted for compatibility with Sendmail, but has no effect. (In +Sendmail it overrides the &"hop count"& obtained by counting &'Received:'& +headers.) + +.vitem &%-i%& +.oindex "&%-i%&" +.cindex "Solaris" "&'mail'& command" +.cindex "dot" "in incoming non-SMTP message" +This option, which has the same effect as &%-oi%&, specifies that a dot on a +line by itself should not terminate an incoming, non-SMTP message. I can find +no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'& +command in Solaris 2.4 uses it. See also &%-ti%&. + +.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" +.cindex "delivery" "forcing attempt" +.cindex "frozen messages" "forcing delivery" +This option requests Exim to run a delivery attempt on each message in turn. If +any of the messages are frozen, they are automatically thawed before the +delivery attempt. The settings of &%queue_domains%&, &%queue_smtp_domains%&, +and &%hold_domains%& are ignored. + +Retry +.cindex "hints database" "overriding retry hints" +hints for any of the addresses are overridden &-- Exim tries to deliver even if +the normal retry time has not yet been reached. This option requires the caller +to be an admin user. However, there is an option called &%prod_requires_admin%& +which can be set false to relax this restriction (and also the same requirement +for the &%-q%&, &%-R%&, and &%-S%& options). + +The deliveries happen synchronously, that is, the original Exim process does +not terminate until all the delivery attempts have finished. No output is +produced unless there is a serious error. If you want to see what is happening, +use the &%-v%& option as well, or inspect Exim's main log. + +.vitem &%-Mar%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... +.oindex "&%-Mar%&" +.cindex "message" "adding recipients" +.cindex "recipient" "adding" +This option requests Exim to add the addresses to the list of recipients of the +message (&"ar"& for &"add recipients"&). The first argument must be a message +id, and the remaining ones must be email addresses. However, if the message is +active (in the middle of a delivery attempt), it is not altered. This option +can be used only by an admin user. + +.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&& + &~<&'message&~id'&>" +.oindex "&%-MC%&" +.cindex "SMTP" "passed connection" +.cindex "SMTP" "multiple deliveries" +.cindex "multiple SMTP deliveries" +This option is not intended for use by external callers. It is used internally +by Exim to invoke another instance of itself to deliver a waiting message using +an existing SMTP connection, which is passed as the standard input. Details are +given in chapter &<>&. This must be the final option, and the caller +must be root or the Exim user in order to use it. + +.vitem &%-MCA%& +.oindex "&%-MCA%&" +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. + +.new +.vitem &%-MCd%& +.oindex "&%-MCd%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-d%& option +to pass on an information string on the purpose of the process. +.wen + +.vitem &%-MCG%&&~<&'queue&~name'&> +.oindex "&%-MCG%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that an +alternate queue is used, named by the following argument. + +.vitem &%-MCK%& +.oindex "&%-MCK%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that a +remote host supports the ESMTP &_CHUNKING_& extension. + +.vitem &%-MCP%& +.oindex "&%-MCP%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that the server to +which Exim is connected supports pipelining. + +.vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&> +.oindex "&%-MCQ%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option when the original delivery was +started by a queue runner. It passes on the process id of the queue runner, +together with the file descriptor number of an open pipe. Closure of the pipe +signals the final completion of the sequence of processes that are passing +messages through the same SMTP connection. + +.vitem &%-MCS%& +.oindex "&%-MCS%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option, and passes on the fact that the +SMTP SIZE option should be used on messages delivered down the existing +connection. + +.vitem &%-MCT%& +.oindex "&%-MCT%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option, and passes on the fact that the +host to which Exim is connected supports TLS encryption. + +.vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>&~<&'cipher'&> +.oindex "&%-MCt%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option, and passes on the fact that the +connection is being proxied by a parent process for handling TLS encryption. +The arguments give the local address and port being proxied, and the TLS cipher. + +.vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-Mc%&" +.cindex "hints database" "not overridden by &%-Mc%&" +.cindex "delivery" "manually started &-- not forced" +This option requests Exim to run a delivery attempt on each message, in turn, +but unlike the &%-M%& option, it does check for retry hints, and respects any +that are found. This option is not very useful to external callers. It is +provided mainly for internal use by Exim when it needs to re-invoke itself in +order to regain root privilege for a delivery (see chapter &<>&). +However, &%-Mc%& can be useful when testing, in order to run a delivery that +respects retry times and other options such as &%hold_domains%& that are +overridden when &%-M%& is used. Such a delivery does not count as a queue run. +If you want to run a specific delivery as if in a queue run, you should use +&%-q%& with a message id argument. A distinction between queue run deliveries +and other deliveries is made in one or two places. + +.vitem &%-Mes%&&~<&'message&~id'&>&~<&'address'&> +.oindex "&%-Mes%&" +.cindex "message" "changing sender" +.cindex "sender" "changing" +This option requests Exim to change the sender address in the message to the +given address, which must be a fully qualified address or &"<>"& (&"es"& for +&"edit sender"&). There must be exactly two arguments. The first argument must +be a message id, and the second one an email address. However, if the message +is active (in the middle of a delivery attempt), its status is not altered. +This option can be used only by an admin user. + +.vitem &%-Mf%&&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-Mf%&" +.cindex "freezing messages" +.cindex "message" "manually freezing" +This option requests Exim to mark each listed message as &"frozen"&. This +prevents any delivery attempts taking place until the message is &"thawed"&, +either manually or as a result of the &%auto_thaw%& configuration option. +However, if any of the messages are active (in the middle of a delivery +attempt), their status is not altered. This option can be used only by an admin +user. + +.vitem &%-Mg%&&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-Mg%&" +.cindex "giving up on messages" +.cindex "message" "abandoning delivery attempts" +.cindex "delivery" "abandoning further attempts" +This option requests Exim to give up trying to deliver the listed messages, +including any that are frozen. However, if any of the messages are active, +their status is not altered. For non-bounce messages, a delivery error message +is sent to the sender, containing the text &"cancelled by administrator"&. +Bounce messages are just discarded. This option can be used only by an admin +user. + +.vitem &%-MG%&&~<&'queue&~name'&>&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-MG%&" +.cindex queue named +.cindex "named queues" "moving messages" +.cindex "queue" "moving messages" +This option requests that each listed message be moved from its current +queue to the given named queue. +The destination queue name argument is required, but can be an empty +string to define the default queue. +If the messages are not currently located in the default queue, +a &%-qG%& option will be required to define the source queue. + +.vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-Mmad%&" +.cindex "delivery" "cancelling all" +This option requests Exim to mark all the recipient addresses in the messages +as already delivered (&"mad"& for &"mark all delivered"&). However, if any +message is active (in the middle of a delivery attempt), its status is not +altered. This option can be used only by an admin user. + +.vitem &%-Mmd%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... +.oindex "&%-Mmd%&" +.cindex "delivery" "cancelling by address" +.cindex "recipient" "removing" +.cindex "removing recipients" +This option requests Exim to mark the given addresses as already delivered +(&"md"& for &"mark delivered"&). The first argument must be a message id, and +the remaining ones must be email addresses. These are matched to recipient +addresses in the message in a case-sensitive manner. If the message is active +(in the middle of a delivery attempt), its status is not altered. This option +can be used only by an admin user. + +.vitem &%-Mrm%&&~<&'message&~id'&>&~<&'message&~id'&>&~... +.oindex "&%-Mrm%&" +.cindex "removing messages" +.cindex "abandoning mail" +.cindex "message" "manually discarding" +This option requests Exim to remove the given messages from the queue. No +bounce messages are sent; each message is simply forgotten. However, if any of +the messages are active, their status is not altered. This option can be used +only by an admin user or by the user who originally caused the message to be +placed in the queue. + +. .new +. .vitem &%-MS%& +. .oindex "&%-MS%&" +. .cindex REQUIRETLS +. This option is used to request REQUIRETLS processing on the message. +. It is used internally by Exim in conjunction with -E when generating +. a bounce message. +. .wen + +.vitem &%-Mset%&&~<&'message&~id'&> +.oindex "&%-Mset%&" +.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" +.cindex "unfreezing messages" +.cindex "frozen messages" "thawing" +.cindex "message" "thawing frozen" +This option requests Exim to &"thaw"& any of the listed messages that are +&"frozen"&, so that delivery attempts can resume. However, if any of the +messages are active, their status is not altered. This option can be used only +by an admin user. + +.vitem &%-Mvb%&&~<&'message&~id'&> +.oindex "&%-Mvb%&" +.cindex "listing" "message body" +.cindex "message" "listing body of" +This option causes the contents of the message body (-D) spool file to be +written to the standard output. This option can be used only by an admin user. + +.vitem &%-Mvc%&&~<&'message&~id'&> +.oindex "&%-Mvc%&" +.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" +.cindex "header lines" "listing" +.cindex "message" "listing header lines" +This option causes the contents of the message headers (-H) spool file to be +written to the standard output. This option can be used only by an admin user. + +.vitem &%-Mvl%&&~<&'message&~id'&> +.oindex "&%-Mvl%&" +.cindex "listing" "message log" +.cindex "message" "listing message log" +This option causes the contents of the message log spool file to be written to +the standard output. This option can be used only by an admin user. + +.vitem &%-m%& +.oindex "&%-m%&" +This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim +treats it that way too. + +.vitem &%-N%& +.oindex "&%-N%&" +.cindex "debugging" "&%-N%& option" +.cindex "debugging" "suppressing delivery" +This is a debugging option that inhibits delivery of a message at the transport +level. It implies &%-v%&. Exim goes through many of the motions of delivery &-- +it just doesn't actually transport the message, but instead behaves as if it +had successfully done so. However, it does not make any updates to the retry +database, and the log entries for deliveries are flagged with &"*>"& rather +than &"=>"&. + +Because &%-N%& discards any message to which it applies, only root or the Exim +user are allowed to use it with &%-bd%&, &%-q%&, &%-R%& or &%-M%&. In other +words, an ordinary user can use it only when supplying an incoming message to +which it will apply. Although transportation never fails when &%-N%& is set, an +address may be deferred because of a configuration problem on a transport, or a +routing problem. Once &%-N%& has been used for a delivery attempt, it sticks to +the message, and applies to any subsequent delivery attempts that may happen +for that message. + +.vitem &%-n%& +.oindex "&%-n%&" +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%&" +This option is interpreted by Sendmail to mean &`set option`&. It is ignored by +Exim. + +.vitem &%-oA%&&~<&'file&~name'&> +.oindex "&%-oA%&" +.cindex "Sendmail compatibility" "&%-oA%& option" +This option is used by Sendmail in conjunction with &%-bi%& to specify an +alternative alias filename. Exim handles &%-bi%& differently; see the +description above. + +.vitem &%-oB%&&~<&'n'&> +.oindex "&%-oB%&" +.cindex "SMTP" "passed connection" +.cindex "SMTP" "multiple deliveries" +.cindex "multiple SMTP deliveries" +This is a debugging option which limits the maximum number of messages that can +be delivered down one SMTP connection, overriding the value set in any &(smtp)& +transport. If <&'n'&> is omitted, the limit is set to 1. + +.vitem &%-odb%& +.oindex "&%-odb%&" +.cindex "background delivery" +.cindex "delivery" "in the background" +This option applies to all modes in which Exim accepts incoming messages, +including the listening daemon. It requests &"background"& delivery of such +messages, which means that the accepting process automatically starts a +delivery process for each message received, but does not wait for the delivery +processes to finish. + +When all the messages have been received, the reception process exits, +leaving the delivery processes to finish in their own time. The standard output +and error streams are closed at the start of each delivery process. +This is the default action if none of the &%-od%& options are present. + +If one of the queueing options in the configuration file +(&%queue_only%& or &%queue_only_file%&, for example) is in effect, &%-odb%& +overrides it if &%queue_only_override%& is set true, which is the default +setting. If &%queue_only_override%& is set false, &%-odb%& has no effect. + +.vitem &%-odf%& +.oindex "&%-odf%&" +.cindex "foreground delivery" +.cindex "delivery" "in the foreground" +This option requests &"foreground"& (synchronous) delivery when Exim has +accepted a locally-generated message. (For the daemon it is exactly the same as +&%-odb%&.) A delivery process is automatically started to deliver the message, +and Exim waits for it to complete before proceeding. + +The original Exim reception process does not finish until the delivery +process for the final message has ended. The standard error stream is left open +during deliveries. + +However, like &%-odb%&, this option has no effect if &%queue_only_override%& is +false and one of the queueing options in the configuration file is in effect. + +If there is a temporary delivery error during foreground delivery, the +message is left in the queue for later delivery, and the original reception +process exits. See chapter &<>& for a way of setting up a +restricted configuration that never queues messages. + + +.vitem &%-odi%& +.oindex "&%-odi%&" +This option is synonymous with &%-odf%&. It is provided for compatibility with +Sendmail. + +.vitem &%-odq%& +.oindex "&%-odq%&" +.cindex "non-immediate delivery" +.cindex "delivery" "suppressing immediate" +.cindex "queueing incoming messages" +This option applies to all modes in which Exim accepts incoming messages, +including the listening daemon. It specifies that the accepting process should +not automatically start a delivery process for each message received. Messages +are placed in the queue, and remain there until a subsequent queue runner +process encounters them. There are several configuration options (such as +&%queue_only%&) that can be used to queue incoming messages under certain +conditions. This option overrides all of them and also &%-odqs%&. It always +forces queueing. + +.vitem &%-odqs%& +.oindex "&%-odqs%&" +.cindex "SMTP" "delaying delivery" +.cindex "first pass routing" +This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&. +However, like &%-odb%& and &%-odi%&, this option has no effect if +&%queue_only_override%& is false and one of the queueing options in the +configuration file is in effect. + +When &%-odqs%& does operate, a delivery process is started for each incoming +message, in the background by default, but in the foreground if &%-odi%& is +also present. The recipient addresses are routed, and local deliveries are done +in the normal way. However, if any SMTP deliveries are required, they are not +done at this time, so the message remains in the queue until a subsequent queue +runner process encounters it. Because routing was done, Exim knows which +messages are waiting for which hosts, and so a number of messages for the same +host can be sent in a single SMTP connection. The &%queue_smtp_domains%& +configuration option has the same effect for specific domains. See also the +&%-qq%& option. + +.vitem &%-oee%& +.oindex "&%-oee%&" +.cindex "error" "reporting" +If an error is detected while a non-SMTP message is being received (for +example, a malformed address), the error is reported to the sender in a mail +message. + +.cindex "return code" "for &%-oee%&" +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 for any other error. +This is the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. + +.vitem &%-oem%& +.oindex "&%-oem%&" +.cindex "error" "reporting" +.cindex "return code" "for &%-oem%&" +This is the same as &%-oee%&, except that Exim always exits with a non-zero +return code, whether or not the error message was successfully sent. +This is the default &%-oe%&&'x'& option, unless Exim is called as &'rmail'&. + +.vitem &%-oep%& +.oindex "&%-oep%&" +.cindex "error" "reporting" +If an error is detected while a non-SMTP message is being received, the +error is reported by writing a message to the standard error file (stderr). +.cindex "return code" "for &%-oep%&" +The return code is 1 for all errors. + +.vitem &%-oeq%& +.oindex "&%-oeq%&" +.cindex "error" "reporting" +This option is supported for compatibility with Sendmail, but has the same +effect as &%-oep%&. + +.vitem &%-oew%& +.oindex "&%-oew%&" +.cindex "error" "reporting" +This option is supported for compatibility with Sendmail, but has the same +effect as &%-oem%&. + +.vitem &%-oi%& +.oindex "&%-oi%&" +.cindex "dot" "in incoming non-SMTP message" +This option, which has the same effect as &%-i%&, specifies that a dot on a +line by itself should not terminate an incoming, non-SMTP message. Otherwise, a +single dot does terminate, though Exim does no special processing for other +lines that start with a dot. This option is set by default if Exim is called as +&'rmail'&. See also &%-ti%&. + +.vitem &%-oitrue%& +.oindex "&%-oitrue%&" +This option is treated as synonymous with &%-oi%&. + +.vitem &%-oMa%&&~<&'host&~address'&> +.oindex "&%-oMa%&" +.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 +&%-bh%&, &%-be%&, &%-bf%&, &%-bF%&, &%-bt%&, or &%-bv%& testing options. In +other circumstances, they are ignored unless the caller is trusted. + +The &%-oMa%& option sets the sender host address. This may include a port +number at the end, after a full stop (period). For example: +.code +exim -bs -oMa 10.9.8.7.1234 +.endd +An alternative syntax is to enclose the IP address in square brackets, +followed by a colon and the port number: +.code +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$&. 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" +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" +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, 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" +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, 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" +See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%& +option sets the IP interface address value. A port number may be included, +using the same syntax as for &%-oMa%&. The interface address is placed in +&$received_ip_address$& and the port number, if present, in &$received_port$&. + +.vitem &%-oMm%&&~<&'message&~reference'&> +.oindex "&%-oMm%&" +.cindex "message reference" "message reference, specifying for local message" +See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMm%& +option sets the message reference, e.g. message-id, and is logged during +delivery. This is useful when some kind of audit trail is required to tie +messages together. The format of the message reference is checked and will +abort if the format is invalid. The option will only be accepted if exim is +running in trusted mode, not as any regular user. + +The best example of a message reference is when Exim sends a bounce message. +The message reference is the message-id of the original message for which Exim +is sending the bounce. + +.vitem &%-oMr%&&~<&'protocol&~name'&> +.oindex "&%-oMr%&" +.cindex "protocol, specifying for local message" +.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, 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%&. Repeated use of this option is not supported. + +.vitem &%-oMs%&&~<&'host&~name'&> +.oindex "&%-oMs%&" +.cindex "sender" "host name, specifying for local message" +See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMs%& +option sets the sender host name in &$sender_host_name$&. When this option is +present, Exim does not attempt to look up a host name from an IP address; it +uses the name it is given. + +.vitem &%-oMt%&&~<&'ident&~string'&> +.oindex "&%-oMt%&" +.cindex "sender" "ident string, specifying for local message" +See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%& +option sets the sender ident value in &$sender_ident$&. The default setting for +local callers is the login id of the calling process, except when &%-bh%& is +used, when there is no default. + +.vitem &%-om%& +.oindex "&%-om%&" +.cindex "Sendmail compatibility" "&%-om%& option ignored" +In Sendmail, this option means &"me too"&, indicating that the sender of a +message should receive a copy of the message if the sender appears in an alias +expansion. Exim always does this, so the option does nothing. + +.vitem &%-oo%& +.oindex "&%-oo%&" +.cindex "Sendmail compatibility" "&%-oo%& option ignored" +This option is ignored. In Sendmail it specifies &"old style headers"&, +whatever that means. + +.vitem &%-oP%&&~<&'path'&> +.oindex "&%-oP%&" +.cindex "pid (process id)" "of daemon" +.cindex "daemon" "process id (pid)" +This option is useful only in conjunction with &%-bd%& or &%-q%& with a time +value. The option specifies the file to which the process id of the daemon is +written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used +without &%-bd%&, this is the only way of causing Exim to write a pid file, +because in those cases, the normal pid file is not used. + +.new +.vitem &%-oPX%& +.oindex "&%-oPX%&" +.cindex "pid (process id)" "of daemon" +.cindex "daemon" "process id (pid)" +This option is not intended for general use. +The daemon uses it when terminating due to a SIGTEM, possibly in +combination with &%-oP%&&~<&'path'&>. +It causes the pid file to be removed. +.wen + +.vitem &%-or%&&~<&'time'&> +.oindex "&%-or%&" +.cindex "timeout" "for non-SMTP input" +This option sets a timeout value for incoming non-SMTP messages. If it is not +set, Exim will wait forever for the standard input. The value can also be set +by the &%receive_timeout%& option. The format used for specifying times is +described in section &<>&. + +.vitem &%-os%&&~<&'time'&> +.oindex "&%-os%&" +.cindex "timeout" "for SMTP 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 +for specifying times is described in section &<>&. + +.vitem &%-ov%& +.oindex "&%-ov%&" +This option has exactly the same effect as &%-v%&. + +.vitem &%-oX%&&~<&'number&~or&~string'&> +.oindex "&%-oX%&" +.cindex "TCP/IP" "setting listening ports" +.cindex "TCP/IP" "setting listening interfaces" +.cindex "port" "receiving TCP/IP" +This option is relevant only when the &%-bd%& (start listening daemon) option +is also given. It controls which ports and interfaces the daemon uses. Details +of the syntax, and how it interacts with configuration file options, are given +in chapter &<>&. When &%-oX%& is used to start a daemon, no pid +file is written unless &%-oP%& is also present to specify a pid filename. + +.vitem &%-pd%& +.oindex "&%-pd%&" +.cindex "Perl" "starting the interpreter" +This option applies when an embedded Perl interpreter is linked with Exim (see +chapter &<>&). It overrides the setting of the &%perl_at_start%& +option, forcing the starting of the interpreter to be delayed until it is +needed. + +.vitem &%-ps%& +.oindex "&%-ps%&" +.cindex "Perl" "starting the interpreter" +This option applies when an embedded Perl interpreter is linked with Exim (see +chapter &<>&). It overrides the setting of the &%perl_at_start%& +option, forcing the starting of the interpreter to occur as soon as Exim is +started. + +.vitem &%-p%&<&'rval'&>:<&'sval'&> +.oindex "&%-p%&" +For compatibility with Sendmail, this option is equivalent to +.display +&`-oMr`& <&'rval'&> &`-oMs`& <&'sval'&> +.endd +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 &`d`& +or &`s`& using this option (but that does not seem a real limitation). +Repeated use of this option is not supported. + +.vitem &%-q%& +.oindex "&%-q%&" +.cindex "queue runner" "starting manually" +This option is normally restricted to admin users. However, there is a +configuration option called &%prod_requires_admin%& which can be set false to +relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, +and &%-S%& options). + +.cindex "queue runner" "description of operation" +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 +have not been reached. Use &%-qf%& (see below) if you want to override this. + +If +.cindex "SMTP" "passed connection" +.cindex "SMTP" "multiple deliveries" +.cindex "multiple SMTP deliveries" +the delivery process spawns other processes to deliver other messages down +passed SMTP connections, the queue runner waits for these to finish before +proceeding. + +When all the queued messages have been considered, the original queue runner +process terminates. In other words, a single pass is made over the waiting +mail, one message at a time. Use &%-q%& with a time (see below) if you want +this to be repeated periodically. + +Exim processes the waiting messages in an unpredictable order. It isn't very +random, but it is likely to be different each time, which is all that matters. +If one particular message screws up a remote MTA, other messages to the same +MTA have a chance of getting through if they get tried first. + +It is possible to cause the messages to be processed in lexical message id +order, which is essentially the order in which they arrived, by setting the +&%queue_run_in_order%& option, but this is not recommended for normal use. + +.vitem &%-q%&<&'qflags'&> +The &%-q%& option may be followed by one or more flag letters that change its +behaviour. They are all optional, but if more than one is present, they must +appear in the correct order. Each flag is described in a separate item below. + +.vitem &%-qq...%& +.oindex "&%-qq%&" +.cindex "queue" "double scanning" +.cindex "queue" "routing" +.cindex "routing" "whole queue before delivery" +.cindex "first pass routing" +An option starting with &%-qq%& requests a two-stage queue run. In the first +stage, the queue is scanned as if the &%queue_smtp_domains%& option matched +every domain. Addresses are routed, local deliveries happen, but no remote +transports are run. + +.new +Performance will be best if the &%queue_run_in_order%& option is false. +.wen + +.cindex "hints database" "remembering routing" +The hints database that remembers which messages are waiting for specific hosts +is updated, as if delivery to those hosts had been deferred. After this is +complete, a second, normal queue scan happens, with routing and delivery taking +place as normal. Messages that are routed to the same host should mostly be +delivered down a single SMTP +.cindex "SMTP" "passed connection" +.cindex "SMTP" "multiple deliveries" +.cindex "multiple SMTP deliveries" +connection because of the hints that were set up during the first queue scan. +This option may be useful for hosts that are connected to the Internet +intermittently. + +.vitem &%-q[q]i...%& +.oindex "&%-qi%&" +.cindex "queue" "initial delivery" +If the &'i'& flag is present, the queue runner runs delivery processes only for +those messages that haven't previously been tried. (&'i'& stands for &"initial +delivery"&.) This can be helpful if you are putting messages in the queue using +&%-odq%& and want a queue runner just to process the new messages. + +.vitem &%-q[q][i]f...%& +.oindex "&%-qf%&" +.cindex "queue" "forcing delivery" +.cindex "delivery" "forcing in queue run" +If one &'f'& flag is present, a delivery attempt is forced for each non-frozen +message, whereas without &'f'& only those non-frozen addresses that have passed +their retry times are tried. + +.vitem &%-q[q][i]ff...%& +.oindex "&%-qff%&" +.cindex "frozen messages" "forcing delivery" +If &'ff'& is present, a delivery attempt is forced for every message, whether +frozen or not. + +.vitem &%-q[q][i][f[f]]l%& +.oindex "&%-ql%&" +.cindex "queue" "local deliveries only" +The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to +be done. If a message requires any remote deliveries, it remains in the queue +for later delivery. + +.vitem &%-q[q][i][f[f]][l][G[/