X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/0756eb3cb50d73a77b486e47528f7cb1bffdb299..495ae4b01f36d0d8bb0e34a1d7263c2b8224aa4a:/doc/doc-src/spec.src diff --git a/doc/doc-src/spec.src b/doc/doc-src/spec.src new file mode 100644 index 000000000..41a2ba13b --- /dev/null +++ b/doc/doc-src/spec.src @@ -0,0 +1,27935 @@ +. $Cambridge: exim/doc/doc-src/spec.src,v 1.1 2004/10/07 15:04:35 ph10 Exp $ +. +.set version "4.40" +.set previousversion "4.30" +.set versionmonth "July" +.set versionyear "2004" +.set ACL "ACL" + +. The last of those is to make ACL index entries easier to type. It is put +. up here so that it gets picked up by the HTML converter, which otherwise +. skips to the first chapter. A longer version is set below for use in the +. printed index. + +.set sgcal true +.set html false +.set texinfo false + +.if !set style +.library "a4ps" +.linelength ~~sys.linelength + 0.2in +.set newlinelength ~~sys.linelength +.emphasis ~~sys.linelength + 0.1in +.pagedepth ~~sys.pagedepth - 0.2in +.bindfont 51 "atl/Times-Bold" 9 +.bindfont 52 "atl/Times-Roman" 9 +.bindfont 53 "atl/Times-Roman" 7 +.bindfont 54 "atl/Courier" 9 +.bindfont 55 "atl/Courier-Bold" ~~maintypesize +.bindfont 56 "atl/Times-Italic" 7 +.bindfont 57 "atl/Times-Bold" 7 +.bindfont 58 "atl/Symbol" 7 +.set ssspaceb 1.50 + +.if ~~sgcal +. Used for the "small print" incorporated code stuff. Only rm, it, bf, sp are +. actually used at present. +. rm it sl bf bi ss tt sp sc +.fontgroup 9 = 53 56 0 57 0 0 0 58 0 +.fi +.fi + +.if !~~sys.fancy +.fontgroup 9 = 0 0 0 0 0 0 0 0 0 +.fi + +.include "markup.sg" + +.if ~~sys.fancy +.flag $smc{ "$push$g0$f54" +.flag $sm{ "$push$g0$f53" +.flag $smi{ "$push$g0$f56" +.flag $as{ "$push$g0$f52" +.flag $ab{ "$push$g0$f51" +.flag $cb{ "$push$g0$f55" +. +.else +.flag $smc{ "$push" +.flag $sm{ "$push" +.flag $smi{ "$push" +.flag $cb{ "$push" +.fi + +.macro isunderscore "string" +.set string "~~1" +.set length length "~~1" +.undrec 1 +.endm + +.macro undrec "offset" +.if ~~1 > ~~length +.set underscore false +.else +.set sub "~~string"(1,~~1) +.if "~~sub" == "_" +.set underscore true +.else +.set next ~~1 + 1 +.undrec ~~next +.fi +.fi +.endm + +.macro testunderscore "string" +.isunderscore "~~1" +.newline +.endm + +.macro tabs 6 +.if ~~sys.fancy +.tabset ~~1em +.else +.set temp (~~1 * 5)/4 +.tabset ~~temp em +.fi +.endm + +.macro startoptions +.newline +.push +.if ~~sys.fancy +.indent 6em +.else +.indent 7em +.fi +.endm + +.macro endoptions +.newline +.pop +.endm + +.macro option "option" "" +.newpar +.index \-~~1-\ option +.tempindent 0 +\-~~1-\~~2#$i +.nosep +.endm + +.macro startitems +.newline +.push +.indent 3em +.endm + +.macro enditems +.newline +.pop +.endm + +.macro item "item" "6" +.newpar +.if ~~sys.leftonpage < ~~2ld +.newpage +.fi +.tempindent 0 +\**~~1**\ +.blank +.endm + +.macro startconf +.newline +.push +.if ~~sys.fancy +.indent 2em +.tabset 9em +.else +.indent 4em +.tabset 13em +.fi +.endm + +.macro endconf +.newline +.pop +.endm + +.macro conf "option" "type" "default" "6" +.newpar +.if ~~sys.leftonpage < ~~4ld +.newpage +.fi +.testunderscore "~~1" +.if ~~underscore +.index \~~1\ +.else +.index \~~1\ option +.fi +.tempindent 0 +\**~~1**\ $c $rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3} +.blank +.endm + +.set contents true +.set figurenumber -1 +.set displayindent 2em + +.index @$1, @$2, etc. $it{see numerical variables} +.index address||rewriting $it{see rewriting} +.index CR character $it{see carriage return} +.index CRL $it{see certificate revocation list} +.index delivery||failure report $it{see bounce message} +.index dialup $it{see intermittently connected hosts} +.index failover $it{see fallback} +.index fallover $it{see fallback} +.index filter||Sieve $it{see Sieve filter} +.index ident $it{see RFC 1413} +.index LF character $it{see linefeed} +.index maximum $it{see limit} +.index NUL $it{see binary zero} +.index process id $it{see pid} +.index RBL $it{see DNS list} +.index redirection $it{see address redirection} +.index return path||$it{see also envelope sender} +.index SSL $it{see TLS} +.index string||expansion $it{see expansion} +.index top bit $it{see 8-bit characters} +.index variables $it{see expansion, variables} +.index zero, binary $it{see binary zero} + +. This is used for the printed index. See setting above for +. the HTML index value. + +.set ACL "access control lists (ACLs)" + +. ====================================================== + +.push +.disable filling +.justify centre +.nofoot +.space 8ld +$chead{University of Cambridge Computing Service} +.space 2ld +$chead{Specification of the Exim Mail Transfer Agent} +.space 3ld +by +.space 1ld +Philip Hazel +.space ~~sys.leftonpage - 15*~~sys.linedepth +.justify left +University Computing Service +New Museums Site +Pembroke Street +Cambridge CB2 3QH +United Kingdom +.blank +.tabs 6 +$it{phone:} $t +44 1223 334600 +$it{fax:} $t +44 1223 334679 +$it{email:} $t ph10 $it{at} cus.cam.ac.uk +.blank +Edition for Exim ~~version, ~~versionmonth ~~versionyear +.space 2ld +.if ~~sgcal +.fontgroup 1 +.fi +$c$rm{Copyright (c) University of Cambridge ~~versionyear} + + +.if ~~sgcal +.fontgroup 0 +.font 0 +.fi + +.pop +.newpage + +. Blank verso for title page +.space 1ld +.newpage + + +. Set up for actual text pages +.page 1 +. The first one to prevent a warning from sgfr +. set runningfoot "~~chapter" +.set runningfoot "" + +.if ~~sys.fancy +.footdepth 2ld +.foot +.if "~~runningfoot" == "" +.set rhs "" +.else +.set rhs "~~runningfoot (~~chapter)" +.fi +.set lhs "Exim ~~version" +.linelength ~~newlinelength +$it{~~lhs}$c[~~sys.pagenumber]$e$it{~~rhs} +.endfoot +.fi + + + + +. +. +. +. +. ============================================================================ +.chapter Introduction +.set runningfoot "introduction" + +.if ~~sys.fancy +$c$bi{If I have seen further it is by standing on the shoulders of giants.}##(Isaac Newton) +.elif !~~html +$c"If I have seen further it is by standing on the shoulders of giants." +.newline +$e (Isaac Newton) +.else +\*If I have seen further it is by standing on the shoulders of giants.*\ +(Isaac Newton). +.fi +.blank 4 + +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, FreeBSD, GNU/Hurd, GNU/Linux, +HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, 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 the program, +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 +.index documentation +.em +This edition of the Exim specification applies to version ~~version of Exim. +Substantive changes from the ~~previousversion edition are marked by bars in +the right-hand margin in the PostScript, PDF, and plain text versions of the +document, and by green text in the HTML version, as shown by this paragraph. +Changes are not marked in the Texinfo version, because Texinfo doesn't support +change bars. Minor corrections and rewordings are not marked. +.nem + +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, the 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. + +.index 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 +.if ~~html +[(A HREF="http://www.uit.co.uk/exim-book/")] +$it{The Exim SMTP Mail Server}, +[(/A)] +published by UIT Cambridge. +.else +$it{The Exim SMTP Mail Server}, published by UIT Cambridge +(\?http://www.uit.co.uk/exim-book/?\). +.fi + +This 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.) + +.index \(doc/NewStuff)\ +.index \(doc/ChangeLog)\ +.index change log +As the program 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. However, +specifications of new features that are not yet in this manual are placed in +the file \(doc/NewStuff)\ in the Exim distribution. All changes to the program +(whether new features, bug fixes, or other kinds of change) are noted briefly +in the file called \(doc/ChangeLog)\. + +.index \(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: +.display rm +.tabs 18 +\(OptionLists.txt)\ $t $rm{list of all options in alphabetical order} +\(dbm.discuss.txt)\ $t $rm{discussion about DBM libraries} +\(exim.8)\ $t $rm{a man page of Exim's command line options} +\(filter.txt)\ $t $rm{specification of the filter language} +\(pcrepattern.txt)\ $t $rm{specification of PCRE regular expressions} +\(pcretest.txt)\ $t $rm{specification of the PCRE testing program} +\(Exim3.upgrade)\ $t $rm{upgrade notes from release 2 to release 3} +\(Exim4.upgrade)\ $t $rm{upgrade notes from release 3 to release 4} +.endd +The main specification and the specification of the filtering language are also +available in other formats (HTML, PostScript, PDF, and Texinfo). Section +~~SECTavail below tells you how to get hold of these. + + +.section FTP and web sites, and mailing list +.index web site +.index FTP site +The primary distribution site for Exim is an FTP site, whose contents are +described in \*Where to find the Exim distribution*\ below. In addition, +there is a web site at \?http://www.exim.org?\ by courtesy of Energis Squared, +formerly Planet Online Ltd, who are situated in the UK. The site is mirrored in +a number of other countries; links to the mirrors are listed on the home page. +The web site contains the Exim distribution, and you can also find the +documentation and the +.index FAQ +.if ~~html +[(A HREF="FAQ.html")] +.fi +FAQ +.if ~~html +[(/A)] +.fi +online there, as well as other relevant material. + +.index mailing lists||for Exim users +Energis Squared also provide resources for the following mailing lists: +.display rm +.tabs 28 +$it{exim-users@@exim.org} $t general discussion list +$it{exim-announce@@exim.org} $t moderated, low volume announcements list +.endd +You can subscribe to these lists, change your existing subscriptions, and view +or search the archives via the +.if ~~html +[(A HREF="http://www.exim.org/maillist.html")] +.fi +mailing lists +.if ~~html +[(/A)] +.fi +link on the Exim home page. The $it{exim-users} mailing list is also forwarded +to \?http://www.egroups.com/list/exim-users?\, an archiving system with +searching capabilities. + +.section Exim training +.index training courses +From time to time (approximately annually at the time of writing), +lecture-based training courses are run by the author of Exim in Cambridge, UK. +Details can be found on the web site +.if ~~html +[(A HREF="http://www-tus.csx.cam.ac.uk/courses/exim/")] +.fi +\?http://www-tus@.csx@.cam@.ac.uk/courses/exim/?\. +.if ~~html +[(/A)] +.fi + +.section Bug reports +.index bug reports +.index reporting bugs +Reports of obvious bugs should be emailed to \*bugs@@exim.org*\. However, if +you are unsure whether some behaviour is a bug or not, the best thing to do is +to post a message to the $it{exim-users} mailing list and have it discussed. + + +.section Where to find the Exim distribution +.rset SECTavail "~~chapter.~~section" +.index FTP site +.index distribution||ftp site +The master ftp site for the Exim distribution is +.display rm +.if ! ~~sys.fancy +.indent 0 +.fi +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\ +.endd +Within that directory there are subdirectories called \(exim3)\ (for previous +Exim 3 distributions), \(exim4)\ (for the latest Exim 4 distributions), and +\(Testing)\ for occasional testing versions. Those mirror sites that I know +about are listed in the file +.display rm +.if ! ~~sys.fancy +.indent 0 +.fi +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Mirrors?\ +.endd +In the \(exim4)\ subdirectory, the current release can always be found in +files called +.display rm +\(exim-$it{n.nn}.tar.gz)\ +\(exim-$it{n.nn}.tar.bz2)\ +.endd +where $it{n.nn} is the highest such version number in the directory. The two +files contain identical data; the only difference is the type of compression. +The \(.bz2)\ file is usually a lot smaller than the \(.gz)\ file. +.index distribution||signing details +.index distribution||public key +.index public key for signed distribution +The distributions are signed with Philip Hazel's GPG key. +The corresponding public key is available from a number of keyservers, and +there is also a copy in the file: +.display rm +.if ! ~~sys.fancy +.indent 0 +.fi +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Public-Key?\ +.endd +The signatures for the tar bundles are in: +.display rm +\(exim-$it{n.nn}.tar.gz.sig)\ +\(exim-$it{n.nn}.tar.bz2.sig)\ +.endd + +When there is only a small amount of change from one release to the next, a +patch file may be provided, with a final component name of the form +.display rm +\(exim-patch-$it{n.nn}-$it{m.mm}.gz)\ +.endd +For each released version, the log of changes is made separately available in +the directory +.display rm +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/ChangeLogs?\ +.endd +so that it is possible to find out what has changed without having to download +the entire distribution. + +.index 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 rm +\(exim-html-$it{n.nn}.tar.gz)\ +\(exim-pdf-$it{n.nn}.tar.gz)\ +\(exim-postscript-$it{n.nn}.tar.gz)\ +\(exim-texinfo-$it{n.nn}.tar.gz)\ +.endd +These tar files contain only the \(doc)\ directory, not the complete +distribution, and are also available in \(.bz2)\ as well as \(.gz)\ forms. + +.index FAQ +The FAQ is available for downloading in two different formats from +.display rm +.if ! ~~sys.fancy +.indent 0 +.fi +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.txt.gz?\ +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.html.tar.gz?\ +.endd +The first of these is a single ASCII file that can be searched with a text +editor. The second is a directory of HTML files, normally accessed by starting +at \(index.html)\. The HTML version of the FAQ (which is also included in the +HTML documentation tarbundle) includes a keyword-in-context index, which is +often the most convenient way of finding your way around. + +.section Wish list +.index wish list +A wish list is maintained, containing ideas for new features that have been +submitted. From time to time the file is exported to the ftp site: +.display rm +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/WishList?\ +.endd +Items are removed from the list if they get implemented. + + +.section Contributed material +.index contributed material +At the ftp site, there is a directory called +.display rm +.if ! ~~sys.fancy +.indent 0 +.fi +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/Contrib/?\ +.endd +which contains miscellaneous files contributed to the Exim community by Exim +users. There is also a collection of contributed configuration examples in +.display rm +.if ! ~~sys.fancy +.indent 0 +.fi +\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/config.samples.tar.gz?\ +.endd +These samples are referenced from the FAQ. + + +.section Limitations +.index limitations of Exim +.numberpars $. +Exim is designed for use as an Internet MTA, and therefore handles addresses +in RFC 2822 domain format only. +.index bang paths||not handled by Exim +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. +.nextp +.index domainless addresses +.index 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. +.nextp +.index transport||external +.index external transports +The only external transport currently implemented is an SMTP transport over a +TCP/IP network (using sockets, 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 some other transport mechanism such as UUCP, provided it +can handle domain-style addresses. Batched SMTP input is also catered for. +.nextp +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. +.nextp +Although Exim does have some 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. +.endp + + + +.section Run time configuration +Exim's run time configuration is held in a single text file that is divided +into a number of sections. The entries in this file consist of keywords and +values, in the style of Smail 3 configuration files. A default configuration +file which is suitable for simple online installations is provided in the +distribution, and is described in chapter ~~CHAPdefconfil below. + + +.section Calling interface +.index 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 on 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 ~~CHAPcommandline +documents all Exim's command line options. This information is automatically +made into the man page that forms part of the Exim distribution. + +Control of messages on the queue can be done via certain privileged command +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 +.index terminology definitions +.index 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. + +.index bounce message||definition of +When a message cannot be delivered, it is normally returned to the sender in a +delivery failure message. 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 $it{not} used in that sense here, where it normally +refers to the part of an email address following the @@ sign. + +.index envelope, definition of +.index 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. + +.index message||header, definition of +.index 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. + +.index local part||definition of +.index domain||definition of +The term \*local part*\, which is taken from RFC 2822, is used to refer to that +part of an email address that precedes the @@ sign. The part that follows the +@@ sign is called the \*domain*\ or \*mail domain*\. + +.index local delivery||definition of +.index 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 a remote host. + +.index return path||definition of +\*Return path*\ is another name that is used for the sender address in a +message's envelope. + +.index 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. + +.index 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. + +.index spool directory||definition of +The term \*spool directory*\ is used for a directory in which Exim keeps the +messages on its queue -- that is, those that it is in the process of +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 +.set runningfoot "incorporated code" +.index incorporated code +.index regular expressions||library +.index PCRE +A number of pieces of external code are included in the Exim distribution. +.numberpars $. +Regular expressions are supported in the main Exim program and in the Exim +monitor using the freely-distributable PCRE library, copyright (c) 2003 +University of Cambridge. The source is distributed in the directory +\(src/pcre)\. However, this is a cut-down version of PCRE. If you want to use +the PCRE library in other programs, you should obtain and install the full +version from \?ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre?\. + +.space 1ld +.nextp +.index cdb||acknowledgement +Support for the cdb (Constant DataBase) lookup method is provided by code +contributed by Nigel Metheringham of Planet Online Ltd. which contains the +following statements: +.rule +.push +.if ~~sgcal +.fontgroup 9 +.font 0 +.fi +Copyright (c) 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 +\?http://www.pobox.com/@~djb/cdb.html?\. This implementation borrows some code +from Dan Bernstein's implementation (which has no license restrictions applied +to it). +.newline +.pop +.rule +The implementation is completely contained within the code of Exim. +It does not link against an external cdb library. +.space 1ld +.nextp +.index SPA authentication +.index Samba project +.index 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. + +.space 1ld +.nextp +.index Cyrus +.index \*pwcheck*\ daemon +.index \*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. + +.rule +.push +.if ~~sgcal +.fontgroup 9 +.font 0 +.fi +Copyright (c) 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: + +.if ~~sgcal +.cancelflag $npbracket +.flag $npbracket "" "." +.fi +.numberpars +Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. +.nextp +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. +.nextp +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 rm +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 +.nextp +Redistributions of any form whatsoever must retain the following +acknowledgment: +.newline +.push +.indent ~~sys.indent + 3em +.justify left +$it{This product includes software developed by Computing Services +at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).} +.newline +.pop +.endp +.if ~~sgcal +.cancelflag $npbracket +.flag $npbracket "(" ")" +.fi + +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. +.newline +.pop +.rule + +.space 1ld +.nextp +.index monitor +.index X-windows +.index 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. + +.rule +.push +.if ~~sgcal +.fontgroup 9 +.font 0 +.fi +Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, +and the Massachusetts Institute of Technology, Cambridge, Massachusetts. +.blank +$c All Rights Reserved +.blank +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. +.newline +.pop +.rule +.endp + + + +. +. +. +. +. ============================================================================ +.chapter How Exim receives and delivers mail +.set runningfoot "receiving & delivering mail" + +.section Overall philosophy +.index 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 +.index policy control||overview +Policy controls are now an important feature of MTAs that are connected to the +Internet. Perhaps their most important job is to stop MTAs being abused as +`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: +.numberpars $. +.index ~~ACL||introduction +Exim 4 (unlike previous versions of Exim) implements policy controls on +incoming SMTP 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. 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 ~~CHAPACL). Denial of access results in an SMTP error code. +.nextp +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. +.nextp +When a message has been received, either from a remote host or from the local +host, but before the final acknowledgement has been sent, a locally supplied C +function called \*local@_scan()*\ can be run to inspect the message and decide +whether to accept it or not (see chapter ~~CHAPlocalscan). If the message is +accepted, the list of recipients can be modified by the function. +.nextp +After a message has been accepted, a further checking mechanism is available in +the form of the $it{system filter} (see chapter ~~CHAPsystemfilter). This runs +at the start of every delivery process. +.endp + +.section User filters +.index filter||introduction +.index 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 ~~CHAPredirect (about the \%redirect%\ router) for the configuration +needed to support this, and the separate document entitled +.if ~~html +[(A HREF="filter_toc.html")] +.fi +\*Exim's interfaces to mail filtering*\ +.if ~~html +[(/A)] +.fi +for user details. Two different kinds of filtering are available: +.numberpars $. +Sieve filters are written in the standard filtering language that is defined by +RFC 3028. +.nextp +Exim filters are written in a syntax that is unique to Exim, but which is more +powerful than Sieve, which it pre-dates. +.endp +User filters are run as part of the routing process, described below. + + +.section Message identification +.rset SECTmessiden "~~chapter.~~section" +.index message||ids, details of format +.index format||of message id +.index id of message +.index base62 +.index base36 +.index Darwin +.index 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 file names, and the names of files in those systems are +not case-sensitive. + +.index 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: +.numberpars $. +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). +.nextp +After the first hyphen, the next six characters are the id of the process that +received the message. +.nextp +There are two different possibilities for the final two characters: +.numberpars alpha +.index \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. +.nextp +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. +.endp +.endp +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 +.index receiving mail +.index message||reception +The only way Exim can receive mail from a remote host is using SMTP over +TCP/IP, in which case the sender and recipient addresses are tranferred using +SMTP commands. However, from a locally running process (such as a user's MUA), +there are several possibilities: +.numberpars $. +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. +.nextp +If the process runs Exim with the \-bS-\ option, the message is also read +non-interactively, but in this case the recipients are listed at the start of +the message in a series of SMTP \\RCPT\\ commands, terminated by a \\DATA\\ +command. This is so-called `batch SMTP' format, +but it isn't really SMTP. The SMTP commands are just another way of passing +envelope addresses in a non-interactive submission. +.nextp +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. +.nextp +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. +.endp + +.index message||sender, constructed by Exim +.index 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 address +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 ~~SECTtrustedadmin 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 +~~CHAPlocalscan) 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 +.index spool directory||files that hold a message +.index 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 $tt{-H} for +the file containing the envelope and header, and $tt{-D} for the data file. + +.index spool directory||\(input)\ sub-directory +By default all these message files are held in a single directory called +\(input)\ inside the general Exim spool directory. Some operating systems do +not perform very well if the number of files in a directory gets very large; to +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. + +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 ~~CHAPspool. + +.index rewriting||addresses +Address rewriting that is specified in the rewrite section of the configuration +(see chapter ~~CHAPrewrite) 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 ~~CHAProutergeneric and ~~CHAPtransportgeneric). + + +.section Life of a message +.index message||life of +.index 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. + +.index frozen messages||thawing +.index 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. + +.index \auto@_thaw\ +There is an option called \auto@_thaw\, which can be used to cause Exim to +retry frozen messages after a certain time. When this is set, no message will +remain on the queue for ever, because the delivery timeout will eventually be +reached. Delivery failure reports (bounce messages) that reach this timeout are +discarded. +.index \timeout@_frozen@_after\ +There is also an option called \timeout@_frozen@_after\, which discards frozen +messages after a certain time. + +.index message||log file for +.index log||file for each message +While Exim is working on a message, it writes information about each delivery +attempt to the main log file. This includes successful, unsuccessful, and +delayed deliveries for each recipient (see chapter ~~CHAPlog). The log lines +are also written to a separate $it{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. + +.index journal file +.index 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 $tt{-J}. At the end of a delivery run, if there are some +addresses left to be tried again later, the first spool file (the $tt{-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 the program 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 +.rset SECTprocaddress "~~chapter.~~section" +.index drivers||definition of +.index router||definition of +.index transport||definition of +The main delivery processing elements of Exim are called $it{routers} and +$it{transports}, and collectively these are known as $it{drivers}. Code for a +number of them is provided in the source distribution, and compile-time options +specify which ones are included in the binary. Run time options specify which +ones are actually used for delivering messages. + +.index drivers||instance definition +Each driver that is specified in the run time 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 $it{router} is a driver that operates on an address, either determining how +its delivery should happen, by routing 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 $it{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 $it{local} +transport, the destination is a file or a pipe on the local host, whereas for a +$it{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. + +.index 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. As a simple example, the diagram below illustrates how each +recipient address in a message is processed in a small configuration of three +routers that are configured in various ways. + +.if ~~sys.fancy +.figure "Routing an address" rm +.indent 0 +.call aspic +centre ~~sys.linelength; +magnify 0.8; +boundingbox 30; + ibox depth 14 "address"; +B: arrow down 44; + textdepth 14; +A: box width 100 "first router" "conditions ok?"; + arrow right "yes"; +C: box width 100 "run" "first router"; + arrow down "fail"; +D: ibox depth 20 "address bounces"; + + arc clockwise from right of C "accept"; + arrow down 10; + ibox "queue for" "transport"; + + arrow down from A align bottom of D plus (0,-20) "no"(-6,20)/r; +E: box width 100 "second router" "conditions ok?"; + arrow right "yes"; +F: box width 100 "run" "second router"; + line right 100 "redirect"; + line up align middle of B; + arrow left to middle of B "new addresses"; + + line down 20 from bottom left of F plus (30,0); + arrow left align centre of E "decline"; + + line down 20 from bottom right of F plus (-30,0); + arrow right "fail"; + ibox width 64 "address" "bounces"; + + arrow down 64 from E "no"(-6,20)/r; +G: box width 100 "third router" "conditions ok?"; + arrow right "yes"; +H: box width 100 "run" "third router"; + arc clockwise from right of H "accept"; + arrow down 10; + ibox "queue for" "transport"; + + line down 20 from bottom of H; + arrow left align centre of G "decline"; + arrow down 64 from G "no"(-6,20)/r; + + ibox "no more routers" "address bounces"; +.endcall +.endfigure +.elif !~~html +.display asis + + address + | + |<------------- new addresses ----------------------------- + V | + ----------------- ----------------- | + | first router |----- yes ----->| run |--- accept | + | conditions ok?| | first router | | | + ----------------- ----------------- | | + | | V | + no | fail | queue for | + | V transport | + | address bounces | + | | + V | + ----------------- ----------------- | + | second router |----- yes ----->| run |----redirect ---- + | conditions ok?| | second router | + ----------------- ----------------- + | | | + no | | | + |<-------- decline ----------- --- fail ---> address + | bounces + V + ----------------- ----------------- + | third router |----- yes ----->| run |--- accept + | conditions ok?| | third router | | + ----------------- ----------------- | + | | V + no | | queue for + |<-------- decline --------------- transport + | + V + no more routers + address bounces +.endd +.else +[(img src="routing.gif" alt="Routing an address")][(br)] +.fi +To make this a more concrete example, we'll describe it 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 specially by the local host. These +are typically 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 $it{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 +queued for a suitable SMTP transport; if it does not succeed, the router is +configured to fail the address. + +The example pictured could be a configuration of this type. The second and +third routers can only be run for addresses for which the preconditions for +the first router are not met. If one of these preconditions checks the +domain, the second and third routers are run only for domains that are somehow +special to the local host. + +The second 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 +.index router||for verification +.index 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 +.rset SECTrunindrou "~~chapter.~~section" +.index router||running details +.index preconditions||checking +.index 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 $it{are} met, +the router is run. What happens next depends on the outcome, which is one of +the following: +.numberpars $. +\*accept*\: The router accepts the address, and either queues it for a +transport, or generates one or more `child' addresses. Processing the original +address ceases, +.index \unseen\ option +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. + +.index case of local parts +.index address||duplicate, discarding +If child addresses are generated, Exim checks to see whether they are +duplicates of any existing recipient addresses. During this check, local parts +are treated as case-sensitive. Duplicate addresses are discarded. Each of the +remaining child addresses is then 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. +.nextp +\*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). +.nextp +\*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. +.nextp +\*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. +.nextp +\*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. +.nextp +\*error*\: There is some error in the router (for example, a syntax error in +its configuration). The action is as for defer. +.endp +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 Router preconditions +.rset SECTrouprecon "~~chapter.~~section" +.index router||preconditions, order of processing +.index 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 ~~CHAProutergeneric. +.numberpars $. +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. +.nextp +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. +.nextp +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. +.nextp +Routers can be designated for use only when verifying an address, as +opposed to routing it for delivery. The \verify@_only\ option controls this. +.nextp +Certain routers can be explicitly skipped when running the routers to check an +address given in the SMTP \\EXPN\\ command (see the \expn\ option). +.nextp +If the \domains\ option is set, the domain of the address must be in the set of +domains that it defines. +.nextp +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) +that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and +\$local@_part@_suffix$\ as necessary. +.nextp +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$\; these values can be used in the +remaining preconditions. +.nextp +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. +.nextp +If the \senders\ option is set, the envelope sender address must be in the set +of addresses that it defines. +.nextp +If the \require@_files\ option is set, the existence or non-existence of +specified files is tested. +.nextp +.index 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 ~~CHAPexpand. +.endp + +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 +.index delivery||in detail +When a message is to be delivered, the sequence of events is as follows: +.numberpars $. +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 +.if ~~html +[(A HREF="filter.html")] +.fi +\*Exim's interfaces to mail filtering*\. +.if ~~html +[(/A)] +.fi +.index 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 +~~CHAPsystemfilter 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. +.nextp +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. +.nextp +.index routing||loops in +.index loop||while routing +A router that accepts an address may set up a local or a remote transport for +it. However, the transport is not run at this time. Instead, the address is +placed on a list for the particular transport, to 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. +.nextp +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. +.nextp +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. +.em +The order in which deliveries are done is not defined, except that all local +deliveries happen before any remote deliveries. +.nem +.nextp +.index 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). +.nextp +.index 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 ~~CHAPretry for details of retry strategies. +.nextp +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. +.nextp +.index 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*\. +.nextp +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. +.endp + + +.section Retry mechanism +.index delivery||retry mechanism +.index retry||description of mechanism +.index 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 on your queue for ever. A queue runner process works +it 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 ~~CHAPretry). 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 +.index 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, +.index hints database +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 +.index delivery||permanent failure +.index 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 ~~CHAPemsgcust for details. + +.index ::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. + +.index 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 ~~SECTmailinglists) it is common to direct bounce messages to the +manager of the list. + + + +.section Failures to deliver bounce messages +.index bounce message||failure to deliver +If a bounce message (either locally generated or received from a remote host) +itself suffers a permanent delivery failure, the message is left on the queue, +but it is frozen, awaiting the attention of an administrator. There are options +which 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 +.set runningfoot "building/installing" + +.index building Exim +.section Unpacking +Exim is distributed as a gzipped or bzipped tar file which, when upacked, +creates a directory with the name of the current release (for example, +\(exim-~~version)\) into which the following files are placed: +.display rm +.if !~~sys.fancy && ~~sgcal +.tabs 16 +.else +.tabs 22 +.fi +\(ACKNOWLEDGMENTS)\ $t contains some acknowledgments +.newline +\(CHANGES)\ $t contains a reference to where changes are documented +\(LICENCE)\ $t the GNU General Public Licence +\(Makefile)\ $t top-level make file +\(NOTICE)\ $t conditions for the use of Exim +\(README)\ $t list of files, directories and simple build instructions +.endd +Other files whose names begin with \(README)\ may also be present. The +following subdirectories are created: +.display rm +.if !~~sys.fancy && ~~sgcal +.tabs 16 +.else +.tabs 22 +.fi +\(Local)\ $t an empty directory for local configuration files +\(OS)\ $t OS-specific files +\(doc)\ $t documentation files +\(exim@_monitor)\$t source files for the Exim monitor +\(scripts)\ $t scripts used in the build process +\(src)\ $t remaining source files +\(util)\ $t independent utilities +.endd +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 +.index 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. +.index 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. + +.section DBM libraries +.rset SECTdb "~~chapter.~~section" +.index DBM||libraries, discussion of +.index 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. + +.index Solaris||DBM library for +.index IRIX, DBM library for +.index BSD, DBM library for +.index 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. + +.index \*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 standardised 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 four +possibilities: +.numberpars +A traditional \*ndbm*\ implementation, such as that supplied as part of +Solaris, operates on two files called \(dbmfile.dir)\ and \(dbmfile.pag)\. +.nextp +.index \*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 +file name is used unmodified. +.nextp +.index 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. +.nextp +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. +.nextp +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.$it{x} and 3.$it{x} were current for a while, but the latest versions are now +numbered 4.$it{x}. Maintenance of some of the earlier releases has ceased. All +versions of Berkeley DB can be obtained from +.display rm +\?http://www.sleepycat.com/?\ +.endd +.nextp +.index \*tdb*\ DBM library +Yet another DBM library, called \*tdb*\, has become available from +.display rm +\?http://download.sourceforge.net/tdb?\ +.endd +It has its own interface, and also operates on a single file. +.endp +.index \\USE@_DB\\ +.index 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: +.display asis +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: +.display asis +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: +.display asis +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 +.index building Exim||pre-building configuration +.index configuration for building Exim +.index \(Local/Makefile)\ +.index \(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 run time configuration file +(\\CONFIGURE@_FILE\\), the directory in which Exim binaries will be installed +(\\BIN@_DIRECTORY\\), and the identity of the Exim user (\\EXIM@_USER\\ and +maybe \\EXIM@_GROUP\\ as well). The value of \\CONFIGURE@_FILE\\ can in fact be +a colon-separated list of file names; Exim uses the first of them that exists. + +There are a few other parameters that can be specified either at build time or +at run time, to enable the same binary to be used on a number of different +machines. However, if the locations of Exim's spool directory and log file +directory (if not within the spool directory) are fixed, it is recommended that +you specify them in \(Local/Makefile)\ instead of at run time, so that errors +detected early in Exim's execution (such as a malformed configuration file) can +be logged. + +.index \(Local/eximon.conf)\ +.index \(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 name of the C compiler, which +defaults to \gcc\. See section ~~SECToverride below for details of how to do +this. + + +.section Support for iconv() +.index \*iconv()*\ support +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 ISO-8859-1). 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 +\?http:/@/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 +.display asis +HAVE_ICONV=yes +.endd +to your \(Local/Makefile)\ and rebuild Exim. + + +.section Including TLS/SSL encryption support +.rset SECTinctlsssl "~~chapter.~~section" +.index TLS||including support for TLS +.index encryption||including support for +.index \\SUPPORT@_TLS\\ +.index OpenSSL||building Exim with +.index GnuTLS||building Exim with +Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\ +command as per RFC 2487. It can also support legacy clients that expect to +start a TLS session immediately on connection to a non-standard port (see 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 OpenSSL is installed, you should set +.display asis +SUPPORT_TLS=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: +.display asis +SUPPORT_TLS=yes +TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto +TLS_INCLUDE=-I/usr/local/openssl/include/ +.endd + +If GnuTLS is installed, you should set +.index \\USE@_GNUTLS\\ +.display asis +SUPPORT_TLS=yes +USE_GNUTLS=yes +TLS_LIBS=-lgnutls -ltasn1 -lgcrypt +.endd +in \(Local/Makefile)\, and again you may need to specify the locations of the +library and include files. For example: +.display asis +SUPPORT_TLS=yes +USE_GNUTLS=yes +TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt +TLS_INCLUDE=-I/usr/gnu/include +.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 ~~CHAPTLS. + + + +.section Use of tcpwrappers +.index tcpwrappers, building Exim to support +.index \\USE@_TCP@_WRAPPERS\\ +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 +.display +USE@_TCP@_WRAPPERS=yes +CFLAGS=-O -I/usr/local/include +.newline +EXTRALIBS@_EXIM=-L/usr/local/lib -lwrap +.endd +in \(Local/Makefile)\. The name to use in the \*tcpwrappers*\ control files is +`exim'. For example, the line +.display +exim : LOCAL 192.168.1. .friendly.domain.example +.endd +in your \(/etc/hosts.allow)\ file allows connections from the local host, from +the subnet 192.168.1.0/24, and from all hosts in \*friendly.domain.example*\. +All other connections are denied. Consult the \*tcpwrappers*\ documentation for +further details. + + +.section Including support for IPv6 +.index 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. + +IPv6 is still changing rapidly. Two different types of DNS record for handling +IPv6 addresses have been defined. AAAA records are already in use, and are +currently seen as the `mainstream', but another record type called A6 is being +argued about. Its status is currently `experimental'. Exim has support for A6 +records, but this is included only if you set \\SUPPORT@_A6=YES\\ in +\(Local/Makefile)\. + + +.section The building process +.index 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. +.index symbolic link||to source files +Symbolic links to relevant source files are installed in the build directory. + +.em +\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the +building process fails if it is set. +.nem + +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 +.if ~~html +[(A HREF="FAQ.html")] +.fi +FAQ, +.if ~~html +[(/A)] +.fi +where some common problems are covered. + + + +.section Overriding build-time options for Exim +.index build-time options, overriding +.rset SECToverride "~~chapter.~~section" +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 rm +\(OS/Makefile-Default)\ +\(OS/Makefile-)\<> +\(Local/Makefile)\ +\(Local/Makefile-)\<> +\(Local/Makefile-)\<> +\(Local/Makefile-)\<>-<> +\(OS/Makefile-Base)\ +.endd +.index \(Local/Makefile)\ +where <> is the operating system type and <> is the +.index building Exim||operating system type +.index building Exim||architecture type +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 <> and <> 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 $it{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. + + +.index 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, +.index 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 +.display +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. + + +.index NIS lookup type||including support for +.index NIS@+ lookup type||including support for +.index LDAP||including support for +.index 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: +.display asis +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 most cases the relevant include files and interface +libraries need to be installed before compiling Exim. +.index cdb||including support for +However, in the case of cdb, which is included in the binary only if +.display asis +LOOKUP_CDB=yes +.endd +is set, the code is entirely contained within Exim, and no external include +files or libraries are required. When a lookup type is not included in the +binary, attempts to configure Exim to use it cause run time configuration +errors. + +.index 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, +.display asis +EXIM_PERL=perl.o +.endd +must be defined in \(Local/Makefile)\. Details of this facility are given in +chapter ~~CHAPperl. + +.index X11 libraries, location of +The location of the X11 libraries is something that varies a lot between +operating systems, and of course there are 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)\: +.display asis +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 +.display asis +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. + +.index \\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. +.index DBM||libraries, configuration for building +There is also \\DBMLIB\\, which appears in the link commands for binaries that +use DBM functions (see also section ~~SECTdb). 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. + +.index 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 +.index \(os.h)\ +.index 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 +.index building Eximon||overriding default options +A similar process is used for overriding things when building the Exim monitor, +where the files that are involved are +.display rm +\(OS/eximon.conf-Default)\ +\(OS/eximon.conf-)\<> +\(Local/eximon.conf)\ +\(Local/eximon.conf-)\<> +\(Local/eximon.conf-)\<> +\(Local/eximon.conf-)\<>-<> +.endd +.index \(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 run time. + + + +.section Installing Exim binaries and scripts +.index installing Exim +.index \\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)\. + +Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting +.index \\CONFIGURE@_FILE\\ +in \(Local/Makefile)\. If this names a single file, and the file does not +exist, the default configuration file \(src/configure.default)\ is copied there +by the installation script. If a run time configuration file already exists, it +is left alone. If \\CONFIGURE@_FILE\\ is a colon-separated list, naming several +alternative files, no default is installed. + +.index system aliases file +.index \(/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. + +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, +.index setuid||installing Exim with +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 +~~CHAPsecurity for details). + +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 +.display asis +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. + +.index installing Exim||what is not installed +Running \*make install*\ does not copy the Exim 4 conversion script +\*convert4r4*\, or the \*pcretest*\ test program. You will probably run the +first of these only once (if you are upgrading from Exim 3), and the second +isn't really part of Exim. None of the documentation files in the \(doc)\ +directory are copied, except for the info files when you have set +\\INFO@_DIRECTORY\\, as described in section ~~SECTinsinfdoc 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). + +.index 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: +.display asis +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: +.display +(cd build-SunOS5-5.5.1-sparc; ../scripts/exim@_install -n) +.endd + +.index installing Exim||install script options +There are two other options that can be supplied to the installation script. +.numberpars $. +\-no@_chown-\ bypasses the call to change the owner of the installed binary +to root, and the call to make it a setuid binary. +.nextp +\-no@_symlink-\ bypasses the setting up of the symbolic link \(exim)\ to the +installed binary. +.endp +\\INSTALL@_ARG\\ can be used to pass these options to the script. For example: +.display asis +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: +.display asis +make INSTALL_ARG='-no_symlink exim' install +.endd + + +.section Installing info documentation +.rset SECTinsinfdoc "~~chapter.~~section" +.index 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 +~~SECTavail). + +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 +.index 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 +.index testing||installation +Having installed Exim, you can check that the run time configuration file is +syntactically valid by running the following command, which assumes that the +Exim binary directory is within your \\PATH\\ environment variable: +.display +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 <> +.endd +should verify that it recognizes a local mailbox, and +.display +exim -bt <> +.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: +.display +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'. + +.index 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 <> +.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 ~~CHAPcommandline for +more details.) + +.index `sticky' bit +.index 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 ~~CHAPappendfile. + +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 run time 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 +.index 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)\ +.index 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. + +.index FreeBSD, MTA indirection +.index \(/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: +.display asis +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 +.if ~~html +[(A HREF="filter.html")] +.fi +\*Exim's interface to mail filtering*\ +.if ~~html +[(/A)] +.fi +available to them. + + +.section Upgrading Exim +.index 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 +to send it a HUP signal, to make it re-exec 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. + + +.section Stopping the Exim daemon on Solaris +.index Solaris||stopping Exim on +The standard command for stopping the mailer daemon on Solaris is +.display +/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 +.display asis +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 +.set runningfoot "command line" +.rset CHAPcommandline ~~chapter +.index command line||options +.index 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 +.index \*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)\. + +.index \*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. + +.index \*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. + +.index \*runq*\ +.index 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. + +.index \*newaliases*\ +.index alias file||building +.index 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 +.rset SECTtrustedadmin "~~chapter.~~section" +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'. + +.numberpars $. +.index trusted user||definition of +.index 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. + +.index `From' line +.index 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. +.index ::From:: header line +.index ::Sender:: header line +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. +.nextp +.index user||admin, definition of +.index 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. +.endp + +\**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 +~~CHAPconf. + + + +.section Command line options +The command options are described in alphabetical order below. + +.startoptions + +.option @- +.index 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. + +.option -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. + +.option B <> +.index 8-bit characters +.index 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. + +.option bd +.index daemon +.index SMTP listener +.index queue runner +This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually +the \-bd-\ option is combined with the \-q-\<