From 32451e8a6e14b740eed61b95f334a38957f7ee35 Mon Sep 17 00:00:00 2001 From: Jeremy Harris Date: Tue, 20 Jul 2021 11:00:03 +0100 Subject: [PATCH] Docs: remove extraneous file copy --- doc/doc-docbook/spec.xfpt.readsock | 41682 --------------------------- 1 file changed, 41682 deletions(-) delete mode 100644 doc/doc-docbook/spec.xfpt.readsock diff --git a/doc/doc-docbook/spec.xfpt.readsock b/doc/doc-docbook/spec.xfpt.readsock deleted file mode 100644 index 2f7dad340..000000000 --- a/doc/doc-docbook/spec.xfpt.readsock +++ /dev/null @@ -1,41682 +0,0 @@ -. ///////////////////////////////////////////////////////////////////////////// -. 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[/