1 . $Cambridge: exim/doc/doc-src/spec.src,v 1.1 2004/10/07 15:04:35 ph10 Exp $
4 .set previousversion "4.30"
5 .set versionmonth "July"
6 .set versionyear "2004"
9 . The last of those is to make ACL index entries easier to type. It is put
10 . up here so that it gets picked up by the HTML converter, which otherwise
11 . skips to the first chapter. A longer version is set below for use in the
20 .linelength ~~sys.linelength + 0.2in
21 .set newlinelength ~~sys.linelength
22 .emphasis ~~sys.linelength + 0.1in
23 .pagedepth ~~sys.pagedepth - 0.2in
24 .bindfont 51 "atl/Times-Bold" 9
25 .bindfont 52 "atl/Times-Roman" 9
26 .bindfont 53 "atl/Times-Roman" 7
27 .bindfont 54 "atl/Courier" 9
28 .bindfont 55 "atl/Courier-Bold" ~~maintypesize
29 .bindfont 56 "atl/Times-Italic" 7
30 .bindfont 57 "atl/Times-Bold" 7
31 .bindfont 58 "atl/Symbol" 7
35 . Used for the "small print" incorporated code stuff. Only rm, it, bf, sp are
36 . actually used at present.
37 . rm it sl bf bi ss tt sp sc
38 .fontgroup 9 = 53 56 0 57 0 0 0 58 0
43 .fontgroup 9 = 0 0 0 0 0 0 0 0 0
49 .flag $smc{ "$push$g0$f54"
50 .flag $sm{ "$push$g0$f53"
51 .flag $smi{ "$push$g0$f56"
52 .flag $as{ "$push$g0$f52"
53 .flag $ab{ "$push$g0$f51"
54 .flag $cb{ "$push$g0$f55"
63 .macro isunderscore "string"
65 .set length length "~~1"
69 .macro undrec "offset"
73 .set sub "~~string"(1,~~1)
83 .macro testunderscore "string"
112 .macro option "option" ""
114 .index \-~~1-\ option
131 .macro item "item" "6"
133 .if ~~sys.leftonpage < ~~2ld
158 .macro conf "option" "type" "default" "6"
160 .if ~~sys.leftonpage < ~~4ld
163 .testunderscore "~~1"
170 \**~~1**\ $c $rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3}
176 .set displayindent 2em
178 .index @$1, @$2, etc. $it{see numerical variables}
179 .index address||rewriting $it{see rewriting}
180 .index CR character $it{see carriage return}
181 .index CRL $it{see certificate revocation list}
182 .index delivery||failure report $it{see bounce message}
183 .index dialup $it{see intermittently connected hosts}
184 .index failover $it{see fallback}
185 .index fallover $it{see fallback}
186 .index filter||Sieve $it{see Sieve filter}
187 .index ident $it{see RFC 1413}
188 .index LF character $it{see linefeed}
189 .index maximum $it{see limit}
190 .index NUL $it{see binary zero}
191 .index process id $it{see pid}
192 .index RBL $it{see DNS list}
193 .index redirection $it{see address redirection}
194 .index return path||$it{see also envelope sender}
195 .index SSL $it{see TLS}
196 .index string||expansion $it{see expansion}
197 .index top bit $it{see 8-bit characters}
198 .index variables $it{see expansion, variables}
199 .index zero, binary $it{see binary zero}
201 . This is used for the printed index. See setting above for
202 . the HTML index value.
204 .set ACL "access control lists (ACLs)"
206 . ======================================================
213 $chead{University of Cambridge Computing Service}
215 $chead{Specification of the Exim Mail Transfer Agent}
220 .space ~~sys.leftonpage - 15*~~sys.linedepth
222 University Computing Service
229 $it{phone:} $t +44 1223 334600
230 $it{fax:} $t +44 1223 334679
231 $it{email:} $t ph10 $it{at} cus.cam.ac.uk
233 Edition for Exim ~~version, ~~versionmonth ~~versionyear
238 $c$rm{Copyright (c) University of Cambridge ~~versionyear}
249 . Blank verso for title page
254 . Set up for actual text pages
256 . The first one to prevent a warning from sgfr
257 . set runningfoot "~~chapter"
263 .if "~~runningfoot" == ""
266 .set rhs "~~runningfoot (~~chapter)"
268 .set lhs "Exim ~~version"
269 .linelength ~~newlinelength
270 $it{~~lhs}$c[~~sys.pagenumber]$e$it{~~rhs}
281 . ============================================================================
282 .chapter Introduction
283 .set runningfoot "introduction"
286 $c$bi{If I have seen further it is by standing on the shoulders of giants.}##(Isaac Newton)
288 $c"If I have seen further it is by standing on the shoulders of giants."
292 \*If I have seen further it is by standing on the shoulders of giants.*\
297 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
298 Unix-like operating systems. It was designed on the assumption that it would be
299 run on hosts that are permanently connected to the Internet. However, it can be
300 used on intermittently connected hosts with suitable configuration adjustments.
302 Configuration files currently exist for the following operating systems: AIX,
303 BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux,
304 HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO
305 SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly
306 Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating
307 systems are no longer current and cannot easily be tested, so the configuration
308 files may no longer work in practice.
310 There are also configuration files for compiling Exim in the Cygwin environment
311 that can be installed on systems running Windows. However, this document does
312 not contain any information about running Exim in the Cygwin environment.
314 The terms and conditions for the use and distribution of Exim are contained in
315 the file \(NOTICE)\. Exim is distributed under the terms of the GNU General
316 Public Licence, a copy of which may be found in the file \(LICENCE)\.
318 The use, supply or promotion of Exim for the purpose of sending bulk,
319 unsolicited electronic mail is incompatible with the basic aims of the program,
320 which revolve around the free provision of a service that enhances the quality
321 of personal communications. The author of Exim regards indiscriminate
322 mass-mailing as an antisocial, irresponsible abuse of the Internet.
324 Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
325 experience of running and working on the Smail 3 code, I could never have
326 contemplated starting to write a new MTA. Many of the ideas and user interfaces
327 were originally taken from Smail 3, though the actual code of Exim is entirely
328 new, and has developed far beyond the initial concept.
330 Many people, both in Cambridge and around the world, have contributed to the
331 development and the testing of Exim, and to porting it to various operating
332 systems. I am grateful to them all. The distribution now contains a file called
333 \(ACKNOWLEDGMENTS)\, in which I have started recording the names of
336 .section Exim documentation
339 This edition of the Exim specification applies to version ~~version of Exim.
340 Substantive changes from the ~~previousversion edition are marked by bars in
341 the right-hand margin in the PostScript, PDF, and plain text versions of the
342 document, and by green text in the HTML version, as shown by this paragraph.
343 Changes are not marked in the Texinfo version, because Texinfo doesn't support
344 change bars. Minor corrections and rewordings are not marked.
347 This document is very much a reference manual; it is not a tutorial. The reader
348 is expected to have some familiarity with the SMTP mail transfer protocol and
349 with general Unix system administration. Although there are some discussions
350 and examples in places, the information is mostly organized in a way that makes
351 it easy to look up, rather than in a natural order for sequential reading.
352 Furthermore, the manual aims to cover every aspect of Exim in detail, including
353 a number of rarely-used, special-purpose features that are unlikely to be of
356 .index books about Exim
357 An `easier' discussion of Exim which provides more in-depth explanatory,
358 introductory, and tutorial material can be found in a book entitled
360 [(A HREF="http://www.uit.co.uk/exim-book/")]
361 $it{The Exim SMTP Mail Server},
363 published by UIT Cambridge.
365 $it{The Exim SMTP Mail Server}, published by UIT Cambridge
366 (\?http://www.uit.co.uk/exim-book/?\).
369 This book also contains a chapter that gives a general introduction to SMTP and
370 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
371 with the latest release of Exim. (Note that the earlier book about Exim,
372 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
374 .index \(doc/NewStuff)\
375 .index \(doc/ChangeLog)\
377 As the program develops, there may be features in newer versions that have not
378 yet made it into this document, which is updated only when the most significant
379 digit of the fractional part of the version number changes. However,
380 specifications of new features that are not yet in this manual are placed in
381 the file \(doc/NewStuff)\ in the Exim distribution. All changes to the program
382 (whether new features, bug fixes, or other kinds of change) are noted briefly
383 in the file called \(doc/ChangeLog)\.
385 .index \(doc/spec.txt)\
386 This specification itself is available as an ASCII file in \(doc/spec.txt)\ so
387 that it can easily be searched with a text editor. Other files in the \(doc)\
391 \(OptionLists.txt)\ $t $rm{list of all options in alphabetical order}
392 \(dbm.discuss.txt)\ $t $rm{discussion about DBM libraries}
393 \(exim.8)\ $t $rm{a man page of Exim's command line options}
394 \(filter.txt)\ $t $rm{specification of the filter language}
395 \(pcrepattern.txt)\ $t $rm{specification of PCRE regular expressions}
396 \(pcretest.txt)\ $t $rm{specification of the PCRE testing program}
397 \(Exim3.upgrade)\ $t $rm{upgrade notes from release 2 to release 3}
398 \(Exim4.upgrade)\ $t $rm{upgrade notes from release 3 to release 4}
400 The main specification and the specification of the filtering language are also
401 available in other formats (HTML, PostScript, PDF, and Texinfo). Section
402 ~~SECTavail below tells you how to get hold of these.
405 .section FTP and web sites, and mailing list
408 The primary distribution site for Exim is an FTP site, whose contents are
409 described in \*Where to find the Exim distribution*\ below. In addition,
410 there is a web site at \?http://www.exim.org?\ by courtesy of Energis Squared,
411 formerly Planet Online Ltd, who are situated in the UK. The site is mirrored in
412 a number of other countries; links to the mirrors are listed on the home page.
413 The web site contains the Exim distribution, and you can also find the
414 documentation and the
417 [(A HREF="FAQ.html")]
423 online there, as well as other relevant material.
425 .index mailing lists||for Exim users
426 Energis Squared also provide resources for the following mailing lists:
429 $it{exim-users@@exim.org} $t general discussion list
430 $it{exim-announce@@exim.org} $t moderated, low volume announcements list
432 You can subscribe to these lists, change your existing subscriptions, and view
433 or search the archives via the
435 [(A HREF="http://www.exim.org/maillist.html")]
441 link on the Exim home page. The $it{exim-users} mailing list is also forwarded
442 to \?http://www.egroups.com/list/exim-users?\, an archiving system with
443 searching capabilities.
445 .section Exim training
446 .index training courses
447 From time to time (approximately annually at the time of writing),
448 lecture-based training courses are run by the author of Exim in Cambridge, UK.
449 Details can be found on the web site
451 [(A HREF="http://www-tus.csx.cam.ac.uk/courses/exim/")]
453 \?http://www-tus@.csx@.cam@.ac.uk/courses/exim/?\.
460 .index reporting bugs
461 Reports of obvious bugs should be emailed to \*bugs@@exim.org*\. However, if
462 you are unsure whether some behaviour is a bug or not, the best thing to do is
463 to post a message to the $it{exim-users} mailing list and have it discussed.
466 .section Where to find the Exim distribution
467 .rset SECTavail "~~chapter.~~section"
469 .index distribution||ftp site
470 The master ftp site for the Exim distribution is
475 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\
477 Within that directory there are subdirectories called \(exim3)\ (for previous
478 Exim 3 distributions), \(exim4)\ (for the latest Exim 4 distributions), and
479 \(Testing)\ for occasional testing versions. Those mirror sites that I know
480 about are listed in the file
485 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Mirrors?\
487 In the \(exim4)\ subdirectory, the current release can always be found in
490 \(exim-$it{n.nn}.tar.gz)\
491 \(exim-$it{n.nn}.tar.bz2)\
493 where $it{n.nn} is the highest such version number in the directory. The two
494 files contain identical data; the only difference is the type of compression.
495 The \(.bz2)\ file is usually a lot smaller than the \(.gz)\ file.
496 .index distribution||signing details
497 .index distribution||public key
498 .index public key for signed distribution
499 The distributions are signed with Philip Hazel's GPG key.
500 The corresponding public key is available from a number of keyservers, and
501 there is also a copy in the file:
506 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Public-Key?\
508 The signatures for the tar bundles are in:
510 \(exim-$it{n.nn}.tar.gz.sig)\
511 \(exim-$it{n.nn}.tar.bz2.sig)\
514 When there is only a small amount of change from one release to the next, a
515 patch file may be provided, with a final component name of the form
517 \(exim-patch-$it{n.nn}-$it{m.mm}.gz)\
519 For each released version, the log of changes is made separately available in
522 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/ChangeLogs?\
524 so that it is possible to find out what has changed without having to download
525 the entire distribution.
527 .index documentation||available formats
528 The main distribution contains ASCII versions of this specification and other
529 documentation; other formats of the documents are available in separate files
530 inside the \(exim4)\ directory of the FTP site:
532 \(exim-html-$it{n.nn}.tar.gz)\
533 \(exim-pdf-$it{n.nn}.tar.gz)\
534 \(exim-postscript-$it{n.nn}.tar.gz)\
535 \(exim-texinfo-$it{n.nn}.tar.gz)\
537 These tar files contain only the \(doc)\ directory, not the complete
538 distribution, and are also available in \(.bz2)\ as well as \(.gz)\ forms.
541 The FAQ is available for downloading in two different formats from
546 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.txt.gz?\
547 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.html.tar.gz?\
549 The first of these is a single ASCII file that can be searched with a text
550 editor. The second is a directory of HTML files, normally accessed by starting
551 at \(index.html)\. The HTML version of the FAQ (which is also included in the
552 HTML documentation tarbundle) includes a keyword-in-context index, which is
553 often the most convenient way of finding your way around.
557 A wish list is maintained, containing ideas for new features that have been
558 submitted. From time to time the file is exported to the ftp site:
560 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/WishList?\
562 Items are removed from the list if they get implemented.
565 .section Contributed material
566 .index contributed material
567 At the ftp site, there is a directory called
572 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/Contrib/?\
574 which contains miscellaneous files contributed to the Exim community by Exim
575 users. There is also a collection of contributed configuration examples in
580 \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/config.samples.tar.gz?\
582 These samples are referenced from the FAQ.
586 .index limitations of Exim
588 Exim is designed for use as an Internet MTA, and therefore handles addresses
589 in RFC 2822 domain format only.
590 .index bang paths||not handled by Exim
591 It cannot handle UUCP `bang paths', though simple two-component bang paths can
592 be converted by a straightforward rewriting configuration. This restriction
593 does not prevent Exim from being interfaced to UUCP as a transport mechanism,
594 provided that domain addresses are used.
596 .index domainless addresses
597 .index address||without domain
598 Exim insists that every address it handles has a domain attached. For incoming
599 local messages, domainless addresses are automatically qualified with a
600 configured domain value. Configuration options specify from which remote
601 systems unqualified addresses are acceptable. These are then qualified on
604 .index transport||external
605 .index external transports
606 The only external transport currently implemented is an SMTP transport over a
607 TCP/IP network (using sockets, including support for IPv6). However, a pipe
608 transport is available, and there are facilities for writing messages to files
609 and pipes, optionally in \*batched SMTP*\ format; these facilities can be used
610 to send messages to some other transport mechanism such as UUCP, provided it
611 can handle domain-style addresses. Batched SMTP input is also catered for.
613 Exim is not designed for storing mail for dial-in hosts. When the volumes of
614 such mail are large, it is better to get the messages `delivered' into files
615 (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by
618 Although Exim does have some facilities for scanning incoming messages, these
619 are not comprehensive enough to do full virus or spam scanning. Such operations
620 are best carried out using additional specialized software packages.
625 .section Run time configuration
626 Exim's run time configuration is held in a single text file that is divided
627 into a number of sections. The entries in this file consist of keywords and
628 values, in the style of Smail 3 configuration files. A default configuration
629 file which is suitable for simple online installations is provided in the
630 distribution, and is described in chapter ~~CHAPdefconfil below.
633 .section Calling interface
634 .index Sendmail compatibility||command line interface
635 Like many MTAs, Exim has adopted the Sendmail command line interface so that it
636 can be a straight replacement for \(/usr/lib/sendmail)\ or
637 \(/usr/sbin/sendmail)\ when sending mail, but you do not need to know anything
638 about Sendmail in order to run Exim. For actions other than sending messages,
639 Sendmail-compatible options also exist, but those that produce output (for
640 example, \-bp-\, which lists the messages on the queue) do so in Exim's own
641 format. There are also some additional options that are compatible with Smail
642 3, and some further options that are new to Exim. Chapter ~~CHAPcommandline
643 documents all Exim's command line options. This information is automatically
644 made into the man page that forms part of the Exim distribution.
646 Control of messages on the queue can be done via certain privileged command
647 line options. There is also an optional monitor program called \*eximon*\, which
648 displays current information in an X window, and which contains a menu
649 interface to Exim's command line administration options.
653 .index terminology definitions
654 .index body of message||definition of
655 The \*body*\ of a message is the actual data that the sender wants to transmit.
656 It is the last part of a message, and is separated from the \*header*\ (see
657 below) by a blank line.
659 .index bounce message||definition of
660 When a message cannot be delivered, it is normally returned to the sender in a
661 delivery failure message. The term \*bounce*\ is commonly used for this action,
662 and the error reports are often called \*bounce messages*\. This is a
663 convenient shorthand for `delivery failure error report'. Such messages have an
664 empty sender address in the message's \*envelope*\ (see below) to ensure that
665 they cannot themselves give rise to further bounce messages.
667 The term \*default*\ appears frequently in this manual. It is used to qualify a
668 value which is used in the absence of any setting in the configuration. It may
669 also qualify an action which is taken unless a configuration setting specifies
672 The term \*defer*\ is used when the delivery of a message to a specific
673 destination cannot immediately take place for some reason (a remote host may be
674 down, or a user's local mailbox may be full). Such deliveries are \*deferred*\
677 The word \*domain*\ is sometimes used to mean all but the first component of a
678 host's name. It is $it{not} used in that sense here, where it normally
679 refers to the part of an email address following the @@ sign.
681 .index envelope, definition of
682 .index sender||definition of
683 A message in transit has an associated \*envelope*\, as well as a header and a
684 body. The envelope contains a sender address (to which bounce messages should
685 be delivered), and any number of recipient addresses. References to the
686 sender or the recipients of a message usually mean the addresses in the
687 envelope. An MTA uses these addresses for delivery, and for returning bounce
688 messages, not the addresses that appear in the header lines.
690 .index message||header, definition of
691 .index header section||definition of
692 The \*header*\ of a message is the first part of a message's text, consisting
693 of a number of lines, each of which has a name such as ::From::, ::To::,
694 ::Subject::, etc. Long header lines can be split over several text lines by
695 indenting the continuations. The header is separated from the body by a blank
698 .index local part||definition of
699 .index domain||definition of
700 The term \*local part*\, which is taken from RFC 2822, is used to refer to that
701 part of an email address that precedes the @@ sign. The part that follows the
702 @@ sign is called the \*domain*\ or \*mail domain*\.
704 .index local delivery||definition of
705 .index remote delivery, definition of
706 The terms \*local delivery*\ and \*remote delivery*\ are used to distinguish
707 delivery to a file or a pipe on the local host from delivery by SMTP over
708 TCP/IP to a remote host.
710 .index return path||definition of
711 \*Return path*\ is another name that is used for the sender address in a
714 .index queue||definition of
715 The term \*queue*\ is used to refer to the set of messages awaiting delivery,
716 because this term is in widespread use in the context of MTAs. However, in
717 Exim's case the reality is more like a pool than a queue, because there is
718 normally no ordering of waiting messages.
720 .index queue runner||definition of
721 The term \*queue runner*\ is used to describe a process that scans the queue
722 and attempts to deliver those messages whose retry times have come. This term
723 is used by other MTAs, and also relates to the command \runq\, but in Exim
724 the waiting messages are normally processed in an unpredictable order.
726 .index spool directory||definition of
727 The term \*spool directory*\ is used for a directory in which Exim keeps the
728 messages on its queue -- that is, those that it is in the process of
729 delivering. This should not be confused with the directory in which local
730 mailboxes are stored, which is called a `spool directory' by some people. In
731 the Exim documentation, `spool' is always used in the first sense.
739 . ============================================================================
740 .chapter Incorporated code
741 .set runningfoot "incorporated code"
742 .index incorporated code
743 .index regular expressions||library
745 A number of pieces of external code are included in the Exim distribution.
747 Regular expressions are supported in the main Exim program and in the Exim
748 monitor using the freely-distributable PCRE library, copyright (c) 2003
749 University of Cambridge. The source is distributed in the directory
750 \(src/pcre)\. However, this is a cut-down version of PCRE. If you want to use
751 the PCRE library in other programs, you should obtain and install the full
752 version from \?ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre?\.
756 .index cdb||acknowledgement
757 Support for the cdb (Constant DataBase) lookup method is provided by code
758 contributed by Nigel Metheringham of Planet Online Ltd. which contains the
759 following statements:
766 Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
768 This program is free software; you can redistribute it and/or modify it under
769 the terms of the GNU General Public License as published by the Free Software
770 Foundation; either version 2 of the License, or (at your option) any later
773 This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information,
774 the spec and sample code for cdb can be obtained from
775 \?http://www.pobox.com/@~djb/cdb.html?\. This implementation borrows some code
776 from Dan Bernstein's implementation (which has no license restrictions applied
781 The implementation is completely contained within the code of Exim.
782 It does not link against an external cdb library.
785 .index SPA authentication
787 .index Microsoft Secure Password Authentication
788 Client support for Microsoft's \*Secure Password Authentication*\ is provided
789 by code contributed by Marc Prud'hommeaux. Server support was contributed by
790 Tom Kistner. This includes code taken from the Samba project, which is released
796 .index \*pwcheck*\ daemon
797 .index \*pwauthd*\ daemon
798 Support for calling the Cyrus \*pwcheck*\ and \*saslauthd*\ daemons is provided
799 by code taken from the Cyrus-SASL library and adapted by Alexander S.
800 Sabourenkov. The permission notice appears below, in accordance with the
801 conditions expressed therein.
809 Copyright (c) 2001 Carnegie Mellon University. All rights reserved.
811 Redistribution and use in source and binary forms, with or without
812 modification, are permitted provided that the following conditions
816 .cancelflag $npbracket
817 .flag $npbracket "" "."
820 Redistributions of source code must retain the above copyright
821 notice, this list of conditions and the following disclaimer.
823 Redistributions in binary form must reproduce the above copyright
824 notice, this list of conditions and the following disclaimer in
825 the documentation and/or other materials provided with the
828 The name `Carnegie Mellon University' must not be used to
829 endorse or promote products derived from this software without
830 prior written permission. For permission or any other legal
831 details, please contact
833 Office of Technology Transfer
834 Carnegie Mellon University
836 Pittsburgh, PA 15213-3890
837 (412) 268-4387, fax: (412) 268-7395
838 tech-transfer@@andrew.cmu.edu
841 Redistributions of any form whatsoever must retain the following
845 .indent ~~sys.indent + 3em
847 $it{This product includes software developed by Computing Services
848 at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).}
853 .cancelflag $npbracket
854 .flag $npbracket "(" ")"
857 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
858 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
859 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
860 FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
861 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
862 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
863 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
873 The Exim Monitor program, which is an X-Window application, includes
874 modified versions of the Athena StripChart and TextPop widgets.
875 This code is copyright by DEC and MIT, and their permission notice appears
876 below, in accordance with the conditions expressed therein.
884 Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
885 and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
887 $c All Rights Reserved
889 Permission to use, copy, modify, and distribute this software and its
890 documentation for any purpose and without fee is hereby granted,
891 provided that the above copyright notice appear in all copies and that
892 both that copyright notice and this permission notice appear in
893 supporting documentation, and that the names of Digital or MIT not be
894 used in advertising or publicity pertaining to distribution of the
895 software without specific, written prior permission.
897 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
898 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
899 DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
900 ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
901 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
902 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
915 . ============================================================================
916 .chapter How Exim receives and delivers mail
917 .set runningfoot "receiving & delivering mail"
919 .section Overall philosophy
920 .index design philosophy
921 Exim is designed to work efficiently on systems that are permanently connected
922 to the Internet and are handling a general mix of mail. In such circumstances,
923 most messages can be delivered immediately. Consequently, Exim does not
924 maintain independent queues of messages for specific domains or hosts, though
925 it does try to send several messages in a single SMTP connection after a host
926 has been down, and it also maintains per-host retry information.
929 .section Policy control
930 .index policy control||overview
931 Policy controls are now an important feature of MTAs that are connected to the
932 Internet. Perhaps their most important job is to stop MTAs being abused as
933 `open relays' by misguided individuals who send out vast amounts of unsolicited
934 junk, and want to disguise its source. Exim provides flexible facilities for
935 specifying policy controls on incoming mail:
937 .index ~~ACL||introduction
938 Exim 4 (unlike previous versions of Exim) implements policy controls on
939 incoming SMTP mail by means of \*Access Control Lists*\ (ACLs). Each list is a
940 series of statements that may either grant or deny access. ACLs can be used at
941 several places in the SMTP dialogue while receiving a message. However, the
942 most common places are after each \\RCPT\\ command, and at the very end of the
943 message. The sysadmin can specify conditions for accepting or rejecting
944 individual recipients or the entire message, respectively, at these two points
945 (see chapter ~~CHAPACL). Denial of access results in an SMTP error code.
947 An ACL is also available for locally generated, non-SMTP messages. In this
948 case, the only available actions are to accept or deny the entire message.
950 When a message has been received, either from a remote host or from the local
951 host, but before the final acknowledgement has been sent, a locally supplied C
952 function called \*local@_scan()*\ can be run to inspect the message and decide
953 whether to accept it or not (see chapter ~~CHAPlocalscan). If the message is
954 accepted, the list of recipients can be modified by the function.
956 After a message has been accepted, a further checking mechanism is available in
957 the form of the $it{system filter} (see chapter ~~CHAPsystemfilter). This runs
958 at the start of every delivery process.
961 .section User filters
962 .index filter||introduction
964 In a conventional Exim configuration, users are able to run private filters by
965 setting up appropriate \(.forward)\ files in their home directories. See
966 chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration
967 needed to support this, and the separate document entitled
969 [(A HREF="filter_toc.html")]
971 \*Exim's interfaces to mail filtering*\
975 for user details. Two different kinds of filtering are available:
977 Sieve filters are written in the standard filtering language that is defined by
980 Exim filters are written in a syntax that is unique to Exim, but which is more
981 powerful than Sieve, which it pre-dates.
983 User filters are run as part of the routing process, described below.
986 .section Message identification
987 .rset SECTmessiden "~~chapter.~~section"
988 .index message||ids, details of format
989 .index format||of message id
995 Every message handled by Exim is given a \*message id*\ which is sixteen
996 characters long. It is divided into three parts, separated by hyphens, for
997 example \"16VDhn-0001bo-D3"\. Each part is a sequence of letters and digits,
998 normally encoding numbers in base 62. However, in the Darwin operating
999 system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
1000 (avoiding the use of lower case letters) is used instead, because the message
1001 id is used to construct file names, and the names of files in those systems are
1004 .index pid (process id)||re-use of
1005 The detail of the contents of the message id have changed as Exim has evolved.
1006 Earlier versions relied on the operating system not re-using a process id (pid)
1007 within one second. On modern operating systems, this assumption can no longer
1008 be made, so the algorithm had to be changed. To retain backward compatibility,
1009 the format of the message id was retained, which is why the following rules are
1012 The first six characters of the message id are the time at which the message
1013 started to be received, to a granularity of one second. That is, this field
1014 contains the number of seconds since the start of the epoch (the normal Unix
1015 way of representing the date and time of day).
1017 After the first hyphen, the next six characters are the id of the process that
1018 received the message.
1020 There are two different possibilities for the final two characters:
1022 .index \localhost@_number\
1023 If \localhost@_number\ is not set, this value is the fractional part of the
1024 time of reception, normally in units of 1/2000 of a second, but for systems
1025 that must use base 36 instead of base 62 (because of case-insensitive file
1026 systems), the units are 1/1000 of a second.
1028 If \localhost@_number\ is set, it is multiplied by 200 (100) and added to
1029 the fractional part of the time, which in this case is in units of 1/200
1030 (1/100) of a second.
1033 After a message has been received, Exim waits for the clock to tick at the
1034 appropriate resolution before proceeding, so that if another message is
1035 received by the same process, or by another process with the same (re-used)
1036 pid, it is guaranteed that the time will be different. In most cases, the clock
1037 will already have ticked while the message was being received.
1039 .section Receiving mail
1040 .index receiving mail
1041 .index message||reception
1042 The only way Exim can receive mail from a remote host is using SMTP over
1043 TCP/IP, in which case the sender and recipient addresses are tranferred using
1044 SMTP commands. However, from a locally running process (such as a user's MUA),
1045 there are several possibilities:
1047 If the process runs Exim with the \-bm-\ option, the message is read
1048 non-interactively (usually via a pipe), with the recipients taken from the
1049 command line, or from the body of the message if \-t-\ is also used.
1051 If the process runs Exim with the \-bS-\ option, the message is also read
1052 non-interactively, but in this case the recipients are listed at the start of
1053 the message in a series of SMTP \\RCPT\\ commands, terminated by a \\DATA\\
1054 command. This is so-called `batch SMTP' format,
1055 but it isn't really SMTP. The SMTP commands are just another way of passing
1056 envelope addresses in a non-interactive submission.
1058 If the process runs Exim with the \-bs-\ option, the message is read
1059 interactively, using the SMTP protocol. A two-way pipe is normally used for
1060 passing data between the local process and the Exim process.
1061 This is `real' SMTP and is handled in the same way as SMTP over TCP/IP. For
1062 example, the ACLs for SMTP commands are used for this form of submission.
1064 A local process may also make a TCP/IP call to the host's loopback address
1065 (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
1066 does not treat the loopback address specially. It treats all such connections
1067 in the same way as connections from other hosts.
1070 .index message||sender, constructed by Exim
1071 .index sender||constructed by Exim
1072 In the three cases that do not involve TCP/IP, the sender address is
1073 constructed from the login name of the user that called Exim and a default
1074 qualification domain (which can be set by the \qualify@_domain\ configuration
1075 option). For local or batch SMTP, a sender address that is passed using the
1076 SMTP \\MAIL\\ command is ignored. However, the system administrator may allow
1077 certain users (`trusted users') to specify a different sender address
1078 unconditionally, or all users to specify certain forms of different sender
1079 address. The \-f-\ option or the SMTP \\MAIL\\ command is used to specify these
1080 different addresses. See section ~~SECTtrustedadmin for details of trusted
1081 users, and the \untrusted@_set@_sender\ option for a way of allowing untrusted
1082 users to change sender addresses.
1084 Messages received by either of the non-interactive mechanisms are subject to
1085 checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
1086 (either over TCP/IP, or interacting with a local process) can be checked by a
1087 number of ACLs that operate at different times during the SMTP session. Either
1088 individual recipients, or the entire message, can be rejected if local policy
1089 requirements are not met. The \*local@_scan()*\ function (see chapter
1090 ~~CHAPlocalscan) is run for all incoming messages.
1092 Exim can be configured not to start a delivery process when a message is
1093 received; this can be unconditional, or depend on the number of incoming SMTP
1094 connections or the system load. In these situations, new messages wait on the
1095 queue until a queue runner process picks them up. However, in standard
1096 configurations under normal conditions, delivery is started as soon as a
1097 message is received.
1102 .section Handling an incoming message
1103 .index spool directory||files that hold a message
1104 .index file||how a message is held
1105 When Exim accepts a message, it writes two files in its spool directory. The
1106 first contains the envelope information, the current status of the message,
1107 and the header lines, and the second contains the body of the message. The
1108 names of the two spool files consist of the message id, followed by $tt{-H} for
1109 the file containing the envelope and header, and $tt{-D} for the data file.
1111 .index spool directory||\(input)\ sub-directory
1112 By default all these message files are held in a single directory called
1113 \(input)\ inside the general Exim spool directory. Some operating systems do
1114 not perform very well if the number of files in a directory gets very large; to
1115 improve performance in such cases, the \split@_spool@_directory\ option can be
1116 used. This causes Exim to split up the input files into 62 sub-directories
1117 whose names are single letters or digits.
1119 The envelope information consists of the address of the message's sender and
1120 the addresses of the recipients. This information is entirely separate from
1121 any addresses contained in the header lines. The status of the message includes
1122 a list of recipients who have already received the message. The format of the
1123 first spool file is described in chapter ~~CHAPspool.
1125 .index rewriting||addresses
1126 Address rewriting that is specified in the rewrite section of the configuration
1127 (see chapter ~~CHAPrewrite) is done once and for all on incoming addresses,
1128 both in the header lines and the envelope, at the time the message is accepted.
1129 If during the course of delivery additional addresses are generated (for
1130 example, via aliasing), these new addresses are rewritten as soon as they are
1131 generated. At the time a message is actually delivered (transported) further
1132 rewriting can take place; because this is a transport option, it can be
1133 different for different forms of delivery. It is also possible to specify the
1134 addition or removal of certain header lines at the time the message is
1135 delivered (see chapters ~~CHAProutergeneric and ~~CHAPtransportgeneric).
1138 .section Life of a message
1139 .index message||life of
1140 .index message||frozen
1141 A message remains in the spool directory until it is completely delivered to
1142 its recipients or to an error address, or until it is deleted by an
1143 administrator or by the user who originally created it. In cases when delivery
1144 cannot proceed -- for example, when a message can neither be delivered to its
1145 recipients nor returned to its sender, the message is marked `frozen' on the
1146 spool, and no more deliveries are attempted.
1148 .index frozen messages||thawing
1149 .index message||thawing frozen
1150 An administrator can `thaw' such messages when the problem has been corrected,
1151 and can also freeze individual messages by hand if necessary. In addition, an
1152 administrator can force a delivery error, causing a bounce message to be sent.
1155 There is an option called \auto@_thaw\, which can be used to cause Exim to
1156 retry frozen messages after a certain time. When this is set, no message will
1157 remain on the queue for ever, because the delivery timeout will eventually be
1158 reached. Delivery failure reports (bounce messages) that reach this timeout are
1160 .index \timeout@_frozen@_after\
1161 There is also an option called \timeout@_frozen@_after\, which discards frozen
1162 messages after a certain time.
1164 .index message||log file for
1165 .index log||file for each message
1166 While Exim is working on a message, it writes information about each delivery
1167 attempt to the main log file. This includes successful, unsuccessful, and
1168 delayed deliveries for each recipient (see chapter ~~CHAPlog). The log lines
1169 are also written to a separate $it{message log} file for each message. These
1170 logs are solely for the benefit of the administrator, and are normally deleted
1171 along with the spool files when processing of a message is complete.
1172 The use of individual message logs can be disabled by setting
1173 \no@_message@_logs\; this might give an improvement in performance on very
1177 .index file||journal
1178 All the information Exim itself needs to set up a delivery is kept in the first
1179 spool file, along with the header lines. When a successful delivery occurs, the
1180 address is immediately written at the end of a journal file, whose name is the
1181 message id followed by $tt{-J}. At the end of a delivery run, if there are some
1182 addresses left to be tried again later, the first spool file (the $tt{-H} file)
1183 is updated to indicate which these are, and the journal file is then deleted.
1184 Updating the spool file is done by writing a new file and renaming it, to
1185 minimize the possibility of data loss.
1187 Should the system or the program crash after a successful delivery but before
1188 the spool file has been updated, the journal is left lying around. The next
1189 time Exim attempts to deliver the message, it reads the journal file and
1190 updates the spool file before proceeding. This minimizes the chances of double
1191 deliveries caused by crashes.
1194 .section Processing an address for delivery
1195 .rset SECTprocaddress "~~chapter.~~section"
1196 .index drivers||definition of
1197 .index router||definition of
1198 .index transport||definition of
1199 The main delivery processing elements of Exim are called $it{routers} and
1200 $it{transports}, and collectively these are known as $it{drivers}. Code for a
1201 number of them is provided in the source distribution, and compile-time options
1202 specify which ones are included in the binary. Run time options specify which
1203 ones are actually used for delivering messages.
1205 .index drivers||instance definition
1206 Each driver that is specified in the run time configuration is an \*instance*\
1207 of that particular driver type. Multiple instances are allowed; for example,
1208 you can set up several different \%smtp%\ transports, each with different
1209 option values that might specify different ports or different timeouts. Each
1210 instance has its own identifying name. In what follows we will normally use the
1211 instance name when discussing one particular instance (that is, one specific
1212 configuration of the driver), and the generic driver name when discussing
1213 the driver's features in general.
1215 A $it{router} is a driver that operates on an address, either determining how
1216 its delivery should happen, by routing it to a specific transport, or
1217 converting the address into one or more new addresses (for example, via an
1218 alias file). A router may also explicitly choose to fail an address, causing it
1221 A $it{transport} is a driver that transmits a copy of the message from Exim's
1222 spool to some destination. There are two kinds of transport: for a $it{local}
1223 transport, the destination is a file or a pipe on the local host, whereas for a
1224 $it{remote} transport the destination is some other host. A message is passed
1225 to a specific transport as a result of successful routing. If a message has
1226 several recipients, it may be passed to a number of different transports.
1228 .index preconditions||definition of
1229 An address is processed by passing it to each configured router instance in
1230 turn, subject to certain preconditions, until a router accepts the address or
1231 specifies that it should be bounced. We will describe this process in more
1232 detail shortly. As a simple example, the diagram below illustrates how each
1233 recipient address in a message is processed in a small configuration of three
1234 routers that are configured in various ways.
1237 .figure "Routing an address" rm
1240 centre ~~sys.linelength;
1243 ibox depth 14 "address";
1246 A: box width 100 "first router" "conditions ok?";
1248 C: box width 100 "run" "first router";
1250 D: ibox depth 20 "address bounces";
1252 arc clockwise from right of C "accept";
1254 ibox "queue for" "transport";
1256 arrow down from A align bottom of D plus (0,-20) "no"(-6,20)/r;
1257 E: box width 100 "second router" "conditions ok?";
1259 F: box width 100 "run" "second router";
1260 line right 100 "redirect";
1261 line up align middle of B;
1262 arrow left to middle of B "new addresses";
1264 line down 20 from bottom left of F plus (30,0);
1265 arrow left align centre of E "decline";
1267 line down 20 from bottom right of F plus (-30,0);
1269 ibox width 64 "address" "bounces";
1271 arrow down 64 from E "no"(-6,20)/r;
1272 G: box width 100 "third router" "conditions ok?";
1274 H: box width 100 "run" "third router";
1275 arc clockwise from right of H "accept";
1277 ibox "queue for" "transport";
1279 line down 20 from bottom of H;
1280 arrow left align centre of G "decline";
1281 arrow down 64 from G "no"(-6,20)/r;
1283 ibox "no more routers" "address bounces";
1291 |<------------- new addresses -----------------------------
1293 ----------------- ----------------- |
1294 | first router |----- yes ----->| run |--- accept |
1295 | conditions ok?| | first router | | |
1296 ----------------- ----------------- | |
1298 no | fail | queue for |
1303 ----------------- ----------------- |
1304 | second router |----- yes ----->| run |----redirect ----
1305 | conditions ok?| | second router |
1306 ----------------- -----------------
1309 |<-------- decline ----------- --- fail ---> address
1312 ----------------- -----------------
1313 | third router |----- yes ----->| run |--- accept
1314 | conditions ok?| | third router | |
1315 ----------------- ----------------- |
1318 |<-------- decline --------------- transport
1325 [(img src="routing.gif" alt="Routing an address")][(br)]
1327 To make this a more concrete example, we'll describe it in terms of some actual
1328 routers, but remember, this is only an example. You can configure Exim's
1329 routers in many different ways, and there may be any number of routers in a
1332 The first router that is specified in a configuration is often one that handles
1333 addresses in domains that are not recognized specially by the local host. These
1334 are typically addresses for arbitrary domains on the Internet. A precondition
1335 is set up which looks for the special domains known to the host (for example,
1336 its own domain name), and the router is run for addresses that do $it{not}
1337 match. Typically, this is a router that looks up domains in the DNS in order to
1338 find the hosts to which this address routes. If it succeeds, the address is
1339 queued for a suitable SMTP transport; if it does not succeed, the router is
1340 configured to fail the address.
1342 The example pictured could be a configuration of this type. The second and
1343 third routers can only be run for addresses for which the preconditions for
1344 the first router are not met. If one of these preconditions checks the
1345 domain, the second and third routers are run only for domains that are somehow
1346 special to the local host.
1348 The second router does redirection -- also known as aliasing and forwarding.
1349 When it generates one or more new addresses from the original, each of them is
1350 routed independently from the start. Otherwise, the router may cause an address
1351 to fail, or it may simply decline to handle the address, in which case the
1352 address is passed to the next router.
1354 The final router in many configurations is one that checks to see if the
1355 address belongs to a local mailbox. The precondition may involve a check to
1356 see if the local part is the name of a login account, or it may look up the
1357 local part in a file or a database. If its preconditions are not met, or if
1358 the router declines, we have reached the end of the routers. When this happens,
1359 the address is bounced.
1362 .section Processing an address for verification
1363 .index router||for verification
1364 .index verifying||address, overview
1365 As well as being used to decide how to deliver to an address, Exim's routers
1366 are also used for \*address verification*\. Verification can be requested as
1367 one of the checks to be performed in an ACL for incoming messages, on both
1368 sender and recipient addresses, and it can be tested using the \-bv-\ and
1369 \-bvs-\ command line options.
1371 When an address is being verified, the routers are run in `verify mode'. This
1372 does not affect the way the routers work, but it is a state that can be
1373 detected. By this means, a router can be skipped or made to behave differently
1374 when verifying. A common example is a configuration in which the first router
1375 sends all messages to a message-scanning program, unless they have been
1376 previously scanned. Thus, the first router accepts all addresses without any
1377 checking, making it useless for verifying. Normally, the \no@_verify\ option
1378 would be set for such a router, causing it to be skipped in verify mode.
1382 .section Running an individual router
1383 .rset SECTrunindrou "~~chapter.~~section"
1384 .index router||running details
1385 .index preconditions||checking
1386 .index router||result of running
1387 As explained in the example above, a number of preconditions are checked before
1388 running a router. If any are not met, the router is skipped, and the address is
1389 passed to the next router. When all the preconditions on a router $it{are} met,
1390 the router is run. What happens next depends on the outcome, which is one of
1393 \*accept*\: The router accepts the address, and either queues it for a
1394 transport, or generates one or more `child' addresses. Processing the original
1396 .index \unseen\ option
1397 unless the \unseen\ option is set on the router. This option
1398 can be used to set up multiple deliveries with different routing (for example,
1399 for keeping archive copies of messages). When \unseen\ is set, the address is
1400 passed to the next router. Normally, however, an \*accept*\ return marks the
1403 .index case of local parts
1404 .index address||duplicate, discarding
1405 If child addresses are generated, Exim checks to see whether they are
1406 duplicates of any existing recipient addresses. During this check, local parts
1407 are treated as case-sensitive. Duplicate addresses are discarded. Each of the
1408 remaining child addresses is then processed independently, starting with the
1409 first router by default. It is possible to change this by setting the
1410 \redirect@_router\ option to specify which router to start at for child
1411 addresses. Unlike \pass@_router\ (see below) the router specified by
1412 \redirect@_router\ may be anywhere in the router configuration.
1414 \*pass*\: The router recognizes the address, but cannot handle it itself. It
1415 requests that the address be passed to another router. By default the address
1416 is passed to the next router, but this can be changed by setting the
1417 \pass@_router\ option. However, (unlike \redirect@_router\) the named router
1418 must be below the current router (to avoid loops).
1420 \*decline*\: The router declines to accept the address because it does not
1421 recognize it at all. By default, the address is passed to the next router, but
1422 this can be prevented by setting the \no@_more\ option. When \no@_more\ is set,
1423 all the remaining routers are skipped.
1425 \*fail*\: The router determines that the address should fail, and queues it for
1426 the generation of a bounce message. There is no further processing of the
1427 original address unless \unseen\ is set on the router.
1429 \*defer*\: The router cannot handle the address at the present time. (A database
1430 may be offline, or a DNS lookup may have timed out.) No further processing of
1431 the address happens in this delivery attempt. It is tried again next time the
1432 message is considered for delivery.
1434 \*error*\: There is some error in the router (for example, a syntax error in
1435 its configuration). The action is as for defer.
1437 If an address reaches the end of the routers without having been accepted by
1438 any of them, it is bounced as unrouteable.
1439 The default error message in this situation is `unrouteable address', but you
1440 can set your own message by making use of the \cannot@_route@_message\ option.
1441 This can be set for any router; the value from the last router that `saw'
1442 the address is used.
1444 Sometimes while routing you want to fail a delivery when some conditions are
1445 met but others are not, instead of passing the address on for further routing.
1446 You can do this by having a second router that explicitly fails the delivery
1447 when the relevant conditions are met. The \%redirect%\ router has a `fail'
1448 facility for this purpose.
1452 .section Router preconditions
1453 .rset SECTrouprecon "~~chapter.~~section"
1454 .index router||preconditions, order of processing
1455 .index preconditions||order of processing
1456 The preconditions that are tested for each router are listed below, in the
1457 order in which they are tested. The individual configuration options are
1458 described in more detail in chapter ~~CHAProutergeneric.
1460 The \local@_part@_prefix\ and \local@_part@_suffix\ options can specify that
1461 the local parts handled by the router may or must have certain prefixes and/or
1462 suffixes. If a mandatory affix (prefix or suffix) is not present, the router is
1463 skipped. These conditions are tested first. When an affix is present, it is
1464 removed from the local part before further processing, including the evaluation
1465 of any other conditions.
1467 Routers can be designated for use only when not verifying an address, that is,
1468 only when routing it for delivery (or testing its delivery routing). If the
1469 \verify\ option is set false, the router is skipped when Exim is verifying an
1471 Setting the \verify\ option actually sets two options, \verify@_sender\ and
1472 \verify@_recipient\, which independently control the use of the router for
1473 sender and recipient verification. You can set these options directly if
1474 you want a router to be used for only one type of verification.
1476 If the \address@_test\ option is set false, the router is skipped when Exim is
1477 run with the \-bt-\ option to test an address routing. This can be helpful when
1478 the first router sends all new messages to a scanner of some sort; it makes it
1479 possible to use \-bt-\ to test subsequent delivery routing without having to
1480 simulate the effect of the scanner.
1482 Routers can be designated for use only when verifying an address, as
1483 opposed to routing it for delivery. The \verify@_only\ option controls this.
1485 Certain routers can be explicitly skipped when running the routers to check an
1486 address given in the SMTP \\EXPN\\ command (see the \expn\ option).
1488 If the \domains\ option is set, the domain of the address must be in the set of
1489 domains that it defines.
1491 If the \local@_parts\ option is set, the local part of the address must be in
1492 the set of local parts that it defines. If \local@_part@_prefix\ or
1493 \local@_part@_suffix\ is in use, the prefix or suffix is removed from the local
1494 part before this check. If you want to do precondition tests on local parts
1495 that include affixes, you can do so by using a \condition\ option (see below)
1496 that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and
1497 \$local@_part@_suffix$\ as necessary.
1499 If the \check@_local@_user\ option is set, the local part must be the name of
1500 an account on the local host.
1501 If this check succeeds, the uid and gid of the local user are placed in
1502 \$local@_user@_uid$\ and \$local@_user@_gid$\; these values can be used in the
1503 remaining preconditions.
1505 If the \router@_home@_directory\ option is set, it is expanded at this point,
1506 because it overrides the value of \$home$\. If this expansion were left till
1507 later, the value of \$home$\ as set by \check@_local@_user\ would be used in
1508 subsequent tests. Having two different values of \$home$\ in the same router
1509 could lead to confusion.
1511 If the \senders\ option is set, the envelope sender address must be in the set
1512 of addresses that it defines.
1514 If the \require@_files\ option is set, the existence or non-existence of
1515 specified files is tested.
1517 .index customizing||precondition
1518 If the \condition\ option is set, it is evaluated and tested. This option uses
1519 an expanded string to allow you to set up your own custom preconditions.
1520 Expanded strings are described in chapter ~~CHAPexpand.
1523 Note that \require@_files\ comes near the end of the list, so you cannot use it
1524 to check for the existence of a file in which to lookup up a domain, local
1525 part, or sender. However, as these options are all expanded, you can use the
1526 \exists\ expansion condition to make such tests within each condition. The
1527 \require@_files\ option is intended for checking files that the router may be
1528 going to use internally, or which are needed by a specific transport (for
1529 example, \(.procmailrc)\).
1532 .section Delivery in detail
1533 .index delivery||in detail
1534 When a message is to be delivered, the sequence of events is as follows:
1536 If a system-wide filter file is specified, the message is passed to it. The
1537 filter may add recipients to the message, replace the recipients, discard the
1538 message, cause a new message to be generated, or cause the message delivery to
1539 fail. The format of the system filter file is the same as for Exim user filter
1540 files, described in the separate document entitled
1542 [(A HREF="filter.html")]
1544 \*Exim's interfaces to mail filtering*\.
1548 .index Sieve filter||not available for system filter
1549 (\**Note**\: Sieve cannot be used for system filter files.)
1550 Some additional features are available in system filters -- see chapter
1551 ~~CHAPsystemfilter for details. Note that a message is passed to the system
1552 filter only once per delivery attempt, however many recipients it has. However,
1553 if there are several delivery attempts because one or more addresses could not
1554 be immediately delivered, the system filter is run each time. The filter
1555 condition \first@_delivery\ can be used to detect the first run of the system
1558 Each recipient address is offered to each configured router in turn, subject to
1559 its preconditions, until one is able to handle it. If no router can handle
1560 the address, that is, if they all decline, the address is failed. Because
1561 routers can be targeted at particular domains, several locally handled domains
1562 can be processed entirely independently of each other.
1564 .index routing||loops in
1565 .index loop||while routing
1566 A router that accepts an address may set up a local or a remote transport for
1567 it. However, the transport is not run at this time. Instead, the address is
1568 placed on a list for the particular transport, to be run later. Alternatively,
1569 the router may generate one or more new addresses (typically from alias,
1570 forward, or filter files). New addresses are fed back into this process from
1571 the top, but in order to avoid loops, a router ignores any address which has an
1572 identically-named ancestor that was processed by itself.
1574 When all the routing has been done, addresses that have been successfully
1575 handled are passed to their assigned transports. When local transports are
1576 doing real local deliveries, they handle only one address at a time, but if a
1577 local transport is being used as a pseudo-remote transport (for example, to
1578 collect batched SMTP messages for transmission by some other means) multiple
1579 addresses can be handled. Remote transports can always handle more than one
1580 address at a time, but can be configured not to do so, or to restrict multiple
1581 addresses to the same domain.
1583 Each local delivery to a file or a pipe runs in a separate process under a
1584 non-privileged uid, and these deliveries are run one at a time. Remote
1585 deliveries also run in separate processes, normally under a uid that is private
1586 to Exim (`the Exim user'), but in this case, several remote deliveries can be
1587 run in parallel. The maximum number of simultaneous remote deliveries for any
1588 one message is set by the \remote@_max@_parallel\ option.
1590 The order in which deliveries are done is not defined, except that all local
1591 deliveries happen before any remote deliveries.
1595 When it encounters a local delivery during a queue run, Exim checks its retry
1596 database to see if there has been a previous temporary delivery failure for the
1597 address before running the local transport. If there was a previous failure,
1598 Exim does not attempt a new delivery until the retry time for the address is
1599 reached. However, this happens only for delivery attempts that are part of a
1600 queue run. Local deliveries are always attempted when delivery immediately
1601 follows message reception, even if retry times are set for them. This makes for
1602 better behaviour if one particular message is causing problems (for example,
1603 causing quota overflow, or provoking an error in a filter file).
1605 .index delivery||retry in remote transports
1606 Remote transports do their own retry handling, since an address may be
1607 deliverable to one of a number of hosts, each of which may have a different
1608 retry time. If there have been previous temporary failures and no host has
1609 reached its retry time, no delivery is attempted, whether in a queue run or
1610 not. See chapter ~~CHAPretry for details of retry strategies.
1612 If there were any permanent errors, a bounce message is returned to an
1613 appropriate address (the sender in the common case), with details of the error
1614 for each failing address. Exim can be configured to send copies of bounce
1615 messages to other addresses.
1617 .index delivery||deferral
1618 If one or more addresses suffered a temporary failure, the message is left on
1619 the queue, to be tried again later. Delivery of these addresses is said to be
1622 When all the recipient addresses have either been delivered or bounced,
1623 handling of the message is complete. The spool files and message log are
1624 deleted, though the message log can optionally be preserved if required.
1628 .section Retry mechanism
1629 .index delivery||retry mechanism
1630 .index retry||description of mechanism
1632 Exim's mechanism for retrying messages that fail to get delivered at the first
1633 attempt is the queue runner process. You must either run an Exim daemon that
1634 uses the \-q-\ option with a time interval to start queue runners at regular
1635 intervals, or use some other means (such as \*cron*\) to start them. If you do
1636 not arrange for queue runners to be run, messages that fail temporarily at the
1637 first attempt will remain on your queue for ever. A queue runner process works
1638 it way through the queue, one message at a time, trying each delivery that has
1639 passed its retry time.
1640 You can run several queue runners at once.
1642 Exim uses a set of configured rules to determine when next to retry the failing
1643 address (see chapter ~~CHAPretry). These rules also specify when Exim should
1644 give up trying to deliver to the address, at which point it generates a bounce
1645 message. If no retry rules are set for a particular host, address, and error
1646 combination, no retries are attempted, and temporary errors are treated as
1650 .section Temporary delivery failure
1651 .index delivery||temporary failure
1652 There are many reasons why a message may not be immediately deliverable to a
1653 particular address. Failure to connect to a remote machine (because it, or the
1654 connection to it, is down) is one of the most common. Temporary failures may be
1655 detected during routing as well as during the transport stage of delivery.
1656 Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
1657 is on a file system where the user is over quota. Exim can be configured to
1658 impose its own quotas on local mailboxes; where system quotas are set they will
1661 If a host is unreachable for a period of time, a number of messages may be
1662 waiting for it by the time it recovers, and sending them in a single SMTP
1663 connection is clearly beneficial. Whenever a delivery to a remote host is
1665 .index hints database
1666 Exim makes a note in its hints database, and whenever a successful
1667 SMTP delivery has happened, it looks to see if any other messages are waiting
1668 for the same host. If any are found, they are sent over the same SMTP
1669 connection, subject to a configuration limit as to the maximum number in any
1674 .section Permanent delivery failure
1675 .index delivery||permanent failure
1676 .index bounce message||when generated
1677 When a message cannot be delivered to some or all of its intended recipients, a
1678 bounce message is generated. Temporary delivery failures turn into permanent
1679 errors when their timeout expires. All the addresses that fail in a given
1680 delivery attempt are listed in a single message. If the original message has
1681 many recipients, it is possible for some addresses to fail in one delivery
1682 attempt and others to fail subsequently, giving rise to more than one bounce
1683 message. The wording of bounce messages can be customized by the administrator.
1684 See chapter ~~CHAPemsgcust for details.
1686 .index ::X-Failed-Recipients:: header line
1687 Bounce messages contain an ::X-Failed-Recipients:: header line that lists the
1688 failed addresses, for the benefit of programs that try to analyse such messages
1691 .index bounce message||recipient of
1692 A bounce message is normally sent to the sender of the original message, as
1693 obtained from the message's envelope. For incoming SMTP messages, this is the
1694 address given in the \\MAIL\\ command. However, when an address is
1695 expanded via a forward or alias file, an alternative address can be specified
1696 for delivery failures of the generated addresses. For a mailing list expansion
1697 (see section ~~SECTmailinglists) it is common to direct bounce messages to the
1698 manager of the list.
1702 .section Failures to deliver bounce messages
1703 .index bounce message||failure to deliver
1704 If a bounce message (either locally generated or received from a remote host)
1705 itself suffers a permanent delivery failure, the message is left on the queue,
1706 but it is frozen, awaiting the attention of an administrator. There are options
1707 which can be used to make Exim discard such failed messages, or to keep them
1708 for only a short time (see \timeout@_frozen@_after\ and
1709 \ignore@_bounce@_errors@_after\).
1717 . ============================================================================
1718 .chapter Building and installing Exim
1719 .set runningfoot "building/installing"
1721 .index building Exim
1723 Exim is distributed as a gzipped or bzipped tar file which, when upacked,
1724 creates a directory with the name of the current release (for example,
1725 \(exim-~~version)\) into which the following files are placed:
1727 .if !~~sys.fancy && ~~sgcal
1732 \(ACKNOWLEDGMENTS)\ $t contains some acknowledgments
1734 \(CHANGES)\ $t contains a reference to where changes are documented
1735 \(LICENCE)\ $t the GNU General Public Licence
1736 \(Makefile)\ $t top-level make file
1737 \(NOTICE)\ $t conditions for the use of Exim
1738 \(README)\ $t list of files, directories and simple build instructions
1740 Other files whose names begin with \(README)\ may also be present. The
1741 following subdirectories are created:
1743 .if !~~sys.fancy && ~~sgcal
1748 \(Local)\ $t an empty directory for local configuration files
1749 \(OS)\ $t OS-specific files
1750 \(doc)\ $t documentation files
1751 \(exim@_monitor)\$t source files for the Exim monitor
1752 \(scripts)\ $t scripts used in the build process
1753 \(src)\ $t remaining source files
1754 \(util)\ $t independent utilities
1756 The main utility programs are contained in the \(src)\ directory, and are built
1757 with the Exim binary. The \(util)\ directory contains a few optional scripts
1758 that may be useful to some sites.
1760 .section Multiple machine architectures and operating systems
1761 .index building Exim||multiple OS/architectures
1762 The building process for Exim is arranged to make it easy to build binaries for
1763 a number of different architectures and operating systems from the same set of
1764 source files. Compilation does not take place in the \(src)\ directory. Instead,
1765 a \*build directory*\ is created for each architecture and operating system.
1766 .index symbolic link||to build directory
1767 Symbolic links to the sources are installed in this directory, which is where
1768 the actual building takes place.
1770 In most cases, Exim can discover the machine architecture and operating system
1771 for itself, but the defaults can be overridden if necessary.
1773 .section DBM libraries
1774 .rset SECTdb "~~chapter.~~section"
1775 .index DBM||libraries, discussion of
1776 .index hints database||DBM files used for
1777 Even if you do not use any DBM files in your configuration, Exim still needs a
1778 DBM library in order to operate, because it uses indexed files for its hints
1779 databases. Unfortunately, there are a number of DBM libraries in existence, and
1780 different operating systems often have different ones installed.
1782 .index Solaris||DBM library for
1783 .index IRIX, DBM library for
1784 .index BSD, DBM library for
1785 .index Linux, DBM library for
1786 If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
1787 Linux distribution, the DBM configuration should happen automatically, and you
1788 may be able to ignore this section. Otherwise, you may have to learn more than
1789 you would like about DBM libraries from what follows.
1791 .index \*ndbm*\ DBM library
1792 Licensed versions of Unix normally contain a library of DBM functions operating
1793 via the \*ndbm*\ interface, and this is what Exim expects by default. Free
1794 versions of Unix seem to vary in what they contain as standard. In particular,
1795 some early versions of Linux have no default DBM library, and different
1796 distributors have chosen to bundle different libraries with their packaged
1797 versions. However, the more recent releases seem to have standardised on the
1798 Berkeley DB library.
1800 Different DBM libraries have different conventions for naming the files they
1801 use. When a program opens a file called \(dbmfile)\, there are four
1804 A traditional \*ndbm*\ implementation, such as that supplied as part of
1805 Solaris, operates on two files called \(dbmfile.dir)\ and \(dbmfile.pag)\.
1807 .index \*gdbm*\ DBM library
1808 The GNU library, \*gdbm*\, operates on a single file. If used via its \*ndbm*\
1809 compatibility interface it makes two different hard links to it with names
1810 \(dbmfile.dir)\ and \(dbmfile.pag)\, but if used via its native interface, the
1811 file name is used unmodified.
1813 .index Berkeley DB library
1814 The Berkeley DB package, if called via its \*ndbm*\ compatibility interface,
1815 operates on a single file called \(dbmfile.db)\, but otherwise looks to the
1816 programmer exactly the same as the traditional \*ndbm*\ implementation.
1818 If the Berkeley package is used in its native mode, it operates on a single
1819 file called \(dbmfile)\; the programmer's interface is somewhat different to
1820 the traditional \*ndbm*\ interface.
1822 To complicate things further, there are several very different versions of the
1823 Berkeley DB package. Version 1.85 was stable for a very long time, releases
1824 2.$it{x} and 3.$it{x} were current for a while, but the latest versions are now
1825 numbered 4.$it{x}. Maintenance of some of the earlier releases has ceased. All
1826 versions of Berkeley DB can be obtained from
1828 \?http://www.sleepycat.com/?\
1831 .index \*tdb*\ DBM library
1832 Yet another DBM library, called \*tdb*\, has become available from
1834 \?http://download.sourceforge.net/tdb?\
1836 It has its own interface, and also operates on a single file.
1839 .index DBM||libraries, configuration for building
1840 Exim and its utilities can be compiled to use any of these interfaces. In order
1841 to use any version of the Berkeley DB package in native mode, you must set
1842 \\USE@_DB\\ in an appropriate configuration file (typically
1843 \(Local/Makefile)\). For example:
1847 Similarly, for gdbm you set \\USE@_GDBM\\, and for tdb you set \\USE@_TDB\\. An
1848 error is diagnosed if you set more than one of these.
1850 At the lowest level, the build-time configuration sets none of these options,
1851 thereby assuming an interface of type (1). However, some operating system
1852 configuration files (for example, those for the BSD operating systems and
1853 Linux) assume type (4) by setting \\USE@_DB\\ as their default, and the
1854 configuration files for Cygwin set \\USE@_GDBM\\. Anything you set in
1855 \(Local/Makefile)\, however, overrides these system defaults.
1857 As well as setting \\USE@_DB\\, \\USE@_GDBM\\, or \\USE@_TDB\\, it may also be
1858 necessary to set \\DBMLIB\\, to cause inclusion of the appropriate library, as
1859 in one of these lines:
1864 Settings like that will work if the DBM library is installed in the standard
1865 place. Sometimes it is not, and the library's header file may also not be in
1866 the default path. You may need to set \\INCLUDE\\ to specify where the header
1867 file is, and to specify the path to the library more fully in \\DBMLIB\\, as in
1870 INCLUDE=-I/usr/local/include/db-4.1
1871 DBMLIB=/usr/local/lib/db-4.1/libdb.a
1874 There is further detailed discussion about the various DBM libraries in the
1875 file \(doc/dbm.discuss.txt)\ in the Exim distribution.
1878 .section Pre-building configuration
1879 .index building Exim||pre-building configuration
1880 .index configuration for building Exim
1881 .index \(Local/Makefile)\
1882 .index \(src/EDITME)\
1883 Before building Exim, a local configuration file that specifies options
1884 independent of any operating system has to be created with the name
1885 \(Local/Makefile)\. A template for this file is supplied as the file
1886 \(src/EDITME)\, and it contains full descriptions of all the option settings
1887 therein. These descriptions are therefore not repeated here. If you are
1888 building Exim for the first time, the simplest thing to do is to copy
1889 \(src/EDITME)\ to \(Local/Makefile)\, then read it and edit it appropriately.
1891 There are three settings that you must supply, because Exim will not build
1892 without them. They are the location of the run time configuration file
1893 (\\CONFIGURE@_FILE\\), the directory in which Exim binaries will be installed
1894 (\\BIN@_DIRECTORY\\), and the identity of the Exim user (\\EXIM@_USER\\ and
1895 maybe \\EXIM@_GROUP\\ as well). The value of \\CONFIGURE@_FILE\\ can in fact be
1896 a colon-separated list of file names; Exim uses the first of them that exists.
1898 There are a few other parameters that can be specified either at build time or
1899 at run time, to enable the same binary to be used on a number of different
1900 machines. However, if the locations of Exim's spool directory and log file
1901 directory (if not within the spool directory) are fixed, it is recommended that
1902 you specify them in \(Local/Makefile)\ instead of at run time, so that errors
1903 detected early in Exim's execution (such as a malformed configuration file) can
1906 .index \(Local/eximon.conf)\
1907 .index \(exim@_monitor/EDITME)\
1908 If you are going to build the Exim monitor, a similar configuration process is
1909 required. The file \(exim@_monitor/EDITME)\ must be edited appropriately for
1910 your installation and saved under the name \(Local/eximon.conf)\. If you are
1911 happy with the default settings described in \(exim@_monitor/EDITME)\,
1912 \(Local/eximon.conf)\ can be empty, but it must exist.
1914 This is all the configuration that is needed in straightforward cases for known
1915 operating systems. However, the building process is set up so that it is easy
1916 to override options that are set by default or by operating-system-specific
1917 configuration files, for example to change the name of the C compiler, which
1918 defaults to \gcc\. See section ~~SECToverride below for details of how to do
1922 .section Support for iconv()
1923 .index \*iconv()*\ support
1924 The contents of header lines in messages may be encoded according to the rules
1925 described RFC 2047. This makes it possible to transmit characters that are not
1926 in the ASCII character set, and to label them as being in a particular
1927 character set. When Exim is inspecting header lines by means of the \@$h@_\
1928 mechanism, it decodes them, and translates them into a specified character set
1929 (default ISO-8859-1). The translation is possible only if the operating system
1930 supports the \*iconv()*\ function.
1932 However, some of the operating systems that supply \*iconv()*\ do not support
1933 very many conversions. The GNU \libiconv\ library (available from
1934 \?http:/@/www.gnu.org/software/libiconv/?\) can be installed on such systems to
1935 remedy this deficiency, as well as on systems that do not supply \*iconv()*\ at
1936 all. After installing \libiconv\, you should add
1940 to your \(Local/Makefile)\ and rebuild Exim.
1943 .section Including TLS/SSL encryption support
1944 .rset SECTinctlsssl "~~chapter.~~section"
1945 .index TLS||including support for TLS
1946 .index encryption||including support for
1947 .index \\SUPPORT@_TLS\\
1948 .index OpenSSL||building Exim with
1949 .index GnuTLS||building Exim with
1950 Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\
1951 command as per RFC 2487. It can also support legacy clients that expect to
1952 start a TLS session immediately on connection to a non-standard port (see the
1953 \-tls-on-connect-\ command line option).
1955 If you want to build Exim with TLS support, you must first install either the
1956 OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
1959 If OpenSSL is installed, you should set
1962 TLS_LIBS=-lssl -lcrypto
1964 in \(Local/Makefile)\. You may also need to specify the locations of the
1965 OpenSSL library and include files. For example:
1968 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
1969 TLS_INCLUDE=-I/usr/local/openssl/include/
1972 If GnuTLS is installed, you should set
1973 .index \\USE@_GNUTLS\\
1977 TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
1979 in \(Local/Makefile)\, and again you may need to specify the locations of the
1980 library and include files. For example:
1984 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
1985 TLS_INCLUDE=-I/usr/gnu/include
1987 You do not need to set \\TLS@_INCLUDE\\ if the relevant directory is already
1988 specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS
1989 are given in chapter ~~CHAPTLS.
1993 .section Use of tcpwrappers
1994 .index tcpwrappers, building Exim to support
1995 .index \\USE@_TCP@_WRAPPERS\\
1996 Exim can be linked with the \*tcpwrappers*\ library in order to check incoming
1997 SMTP calls using the \*tcpwrappers*\ control files. This may be a convenient
1998 alternative to Exim's own checking facilities for installations that are
1999 already making use of \*tcpwrappers*\ for other purposes. To do this, you should
2000 set \\USE@_TCP@_WRAPPERS\\ in \(Local/Makefile)\, arrange for the file
2001 \(tcpd.h)\ to be available at compile time, and also ensure that the library
2002 \(libwrap.a)\ is available at link time, typically by including \-lwrap-\ in
2003 \\EXTRALIBS@_EXIM\\. For example, if \*tcpwrappers*\ is installed in
2004 \(/usr/local)\, you might have
2006 USE@_TCP@_WRAPPERS=yes
2007 CFLAGS=-O -I/usr/local/include
2009 EXTRALIBS@_EXIM=-L/usr/local/lib -lwrap
2011 in \(Local/Makefile)\. The name to use in the \*tcpwrappers*\ control files is
2012 `exim'. For example, the line
2014 exim : LOCAL 192.168.1. .friendly.domain.example
2016 in your \(/etc/hosts.allow)\ file allows connections from the local host, from
2017 the subnet 192.168.1.0/24, and from all hosts in \*friendly.domain.example*\.
2018 All other connections are denied. Consult the \*tcpwrappers*\ documentation for
2022 .section Including support for IPv6
2023 .index IPv6||including support for
2024 Exim contains code for use on systems that have IPv6 support. Setting
2025 \\HAVE@_IPV6=YES\\ in \(Local/Makefile)\ causes the IPv6 code to be included;
2026 it may also be necessary to set \\IPV6@_INCLUDE\\ and \\IPV6@_LIBS\\ on systems
2027 where the IPv6 support is not fully integrated into the normal include and
2030 IPv6 is still changing rapidly. Two different types of DNS record for handling
2031 IPv6 addresses have been defined. AAAA records are already in use, and are
2032 currently seen as the `mainstream', but another record type called A6 is being
2033 argued about. Its status is currently `experimental'. Exim has support for A6
2034 records, but this is included only if you set \\SUPPORT@_A6=YES\\ in
2038 .section The building process
2039 .index build directory
2040 Once \(Local/Makefile)\ (and \(Local/eximon.conf)\, if required) have been
2041 created, run \*make*\ at the top level. It determines the architecture and
2042 operating system types, and creates a build directory if one does not exist.
2043 For example, on a Sun system running Solaris 8, the directory
2044 \(build-SunOS5-5.8-sparc)\ is created.
2045 .index symbolic link||to source files
2046 Symbolic links to relevant source files are installed in the build directory.
2049 \**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the
2050 building process fails if it is set.
2053 If this is the first time \*make*\ has been run, it calls a script that builds
2054 a make file inside the build directory, using the configuration files from the
2055 \(Local)\ directory. The new make file is then passed to another instance of
2056 \*make*\. This does the real work, building a number of utility scripts, and
2057 then compiling and linking the binaries for the Exim monitor (if configured), a
2058 number of utility programs, and finally Exim itself. The command \*make
2059 makefile*\ can be used to force a rebuild of the make file in the build
2060 directory, should this ever be necessary.
2062 If you have problems building Exim, check for any comments there may be in the
2063 \(README)\ file concerning your operating system, and also take a look at the
2065 [(A HREF="FAQ.html")]
2071 where some common problems are covered.
2075 .section Overriding build-time options for Exim
2076 .index build-time options, overriding
2077 .rset SECToverride "~~chapter.~~section"
2078 The main make file that is created at the beginning of the building process
2079 consists of the concatenation of a number of files which set configuration
2080 values, followed by a fixed set of \*make*\ instructions. If a value is set
2081 more than once, the last setting overrides any previous ones. This provides a
2082 convenient way of overriding defaults. The files that are concatenated are, in
2085 \(OS/Makefile-Default)\
2086 \(OS/Makefile-)\<<ostype>>
2088 \(Local/Makefile-)\<<ostype>>
2089 \(Local/Makefile-)\<<archtype>>
2090 \(Local/Makefile-)\<<ostype>>-<<archtype>>
2091 \(OS/Makefile-Base)\
2093 .index \(Local/Makefile)\
2094 where <<ostype>> is the operating system type and <<archtype>> is the
2095 .index building Exim||operating system type
2096 .index building Exim||architecture type
2097 architecture type. \(Local/Makefile)\ is required to exist, and the building
2098 process fails if it is absent. The other three \(Local)\ files are optional,
2099 and are often not needed.
2101 The values used for <<ostype>> and <<archtype>> are obtained from scripts
2102 called \(scripts/os-type)\ and \(scripts/arch-type)\ respectively. If either of
2103 the environment variables \\EXIM@_OSTYPE\\ or \\EXIM@_ARCHTYPE\\ is set, their
2104 values are used, thereby providing a means of forcing particular settings.
2105 Otherwise, the scripts try to get values from the \uname\ command. If this
2106 fails, the shell variables \\OSTYPE\\ and \\ARCHTYPE\\ are inspected. A number
2107 of $it{ad hoc} transformations are then applied, to produce the standard names
2108 that Exim expects. You can run these scripts directly from the shell in order
2109 to find out what values are being used on your system.
2112 \(OS/Makefile-Default)\ contains comments about the variables that are set
2113 therein. Some (but not all) are mentioned below. If there is something that
2114 needs changing, review the contents of this file and the contents of the make
2115 file for your operating system (\(OS/Makefile-<<ostype>>)\) to see what the
2119 .index building Exim||overriding default settings
2120 If you need to change any of the values that are set in \(OS/Makefile-Default)\
2121 or in \(OS/Makefile-<<ostype>>)\, or to add any new definitions, you do not
2122 need to change the original files. Instead, you should make the changes by
2123 putting the new values in an appropriate \(Local)\ file. For example,
2124 .index Tru64-Unix build-time settings
2125 when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX,
2126 formerly DEC-OSF1) operating system, it is necessary to specify that the C
2127 compiler is called \*cc*\ rather than \*gcc*\. Also, the compiler must be
2128 called with the option \-std1-\, to make it recognize some of the features of
2129 Standard C that Exim uses. (Most other compilers recognize Standard C by
2130 default.) To do this, you should create a file called \(Local/Makefile-OSF1)\
2131 containing the lines
2136 If you are compiling for just one operating system, it may be easier to put
2137 these lines directly into \(Local/Makefile)\.
2139 Keeping all your local configuration settings separate from the distributed
2140 files makes it easy to transfer them to new versions of Exim simply by copying
2141 the contents of the \(Local)\ directory.
2144 .index NIS lookup type||including support for
2145 .index NIS@+ lookup type||including support for
2146 .index LDAP||including support for
2147 .index lookup||inclusion in binary
2148 Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
2149 lookup, but not all systems have these components installed, so the default is
2150 not to include the relevant code in the binary. All the different kinds of file
2151 and database lookup that Exim supports are implemented as separate code modules
2152 which are included only if the relevant compile-time options are set. In the
2153 case of LDAP, NIS, and NIS+, the settings for \(Local/Makefile)\ are:
2159 and similar settings apply to the other lookup types. They are all listed in
2160 \(src/EDITME)\. In most cases the relevant include files and interface
2161 libraries need to be installed before compiling Exim.
2162 .index cdb||including support for
2163 However, in the case of cdb, which is included in the binary only if
2167 is set, the code is entirely contained within Exim, and no external include
2168 files or libraries are required. When a lookup type is not included in the
2169 binary, attempts to configure Exim to use it cause run time configuration
2172 .index Perl||including support for
2173 Exim can be linked with an embedded Perl interpreter, allowing Perl
2174 subroutines to be called during string expansion. To enable this facility,
2178 must be defined in \(Local/Makefile)\. Details of this facility are given in
2181 .index X11 libraries, location of
2182 The location of the X11 libraries is something that varies a lot between
2183 operating systems, and of course there are different versions of X11 to cope
2184 with. Exim itself makes no use of X11, but if you are compiling the Exim
2185 monitor, the X11 libraries must be available.
2186 The following three variables are set in \(OS/Makefile-Default)\:
2189 XINCLUDE=-I$(X11)/include
2190 XLFLAGS=-L$(X11)/lib
2192 These are overridden in some of the operating-system configuration files. For
2193 example, in \(OS/Makefile-SunOS5)\ there is
2196 XINCLUDE=-I$(X11)/include
2197 XLFLAGS=-L$(X11)/lib -R$(X11)/lib
2199 If you need to override the default setting for your operating system, place a
2200 definition of all three of these variables into your
2201 \(Local/Makefile-<<ostype>>)\ file.
2203 .index \\EXTRALIBS\\
2204 If you need to add any extra libraries to the link steps, these can be put in a
2205 variable called \\EXTRALIBS\\, which appears in all the link commands, but by
2206 default is not defined. In contrast, \\EXTRALIBS@_EXIM\\ is used only on the
2207 command for linking the main Exim binary, and not for any associated utilities.
2208 .index DBM||libraries, configuration for building
2209 There is also \\DBMLIB\\, which appears in the link commands for binaries that
2210 use DBM functions (see also section ~~SECTdb). Finally, there is
2211 \\EXTRALIBS@_EXIMON\\, which appears only in the link step for the Exim monitor
2212 binary, and which can be used, for example, to include additional X11
2215 .index configuration file||editing
2216 The make file copes with rebuilding Exim correctly if any of the configuration
2217 files are edited. However, if an optional configuration file is deleted, it is
2218 necessary to touch the associated non-optional file (that is, \(Local/Makefile)\
2219 or \(Local/eximon.conf)\) before rebuilding.
2221 .section OS-specific header files
2223 .index building Exim||OS-specific C header files
2224 The \(OS)\ directory contains a number of files with names of the form
2225 \(os.h-<<ostype>>)\. These are system-specific C header files that should not
2226 normally need to be changed. There is a list of macro settings that are
2227 recognized in the file \(OS/os.configuring)\, which should be consulted if you
2228 are porting Exim to a new operating system.
2231 .section Overriding build-time options for the monitor
2232 .index building Eximon||overriding default options
2233 A similar process is used for overriding things when building the Exim monitor,
2234 where the files that are involved are
2236 \(OS/eximon.conf-Default)\
2237 \(OS/eximon.conf-)\<<ostype>>
2238 \(Local/eximon.conf)\
2239 \(Local/eximon.conf-)\<<ostype>>
2240 \(Local/eximon.conf-)\<<archtype>>
2241 \(Local/eximon.conf-)\<<ostype>>-<<archtype>>
2243 .index \(Local/eximon.conf)\
2244 As with Exim itself, the final three files need not exist, and in this case the
2245 \(OS/eximon.conf-<<ostype>>)\ file is also optional. The default values in
2246 \(OS/eximon.conf-Default)\ can be overridden dynamically by setting environment
2247 variables of the same name, preceded by \\EXIMON@_\\. For example, setting
2248 \\EXIMON@_LOG@_DEPTH\\ in the environment overrides the value of
2249 \\LOG@_DEPTH\\ at run time.
2253 .section Installing Exim binaries and scripts
2254 .index installing Exim
2255 .index \\BIN@_DIRECTORY\\
2256 The command \*make install*\ runs the \*exim@_install*\ script with no
2257 arguments. The script copies binaries and utility scripts into the directory
2258 whose name is specified by the \\BIN@_DIRECTORY\\ setting in
2261 Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting
2262 .index \\CONFIGURE@_FILE\\
2263 in \(Local/Makefile)\. If this names a single file, and the file does not
2264 exist, the default configuration file \(src/configure.default)\ is copied there
2265 by the installation script. If a run time configuration file already exists, it
2266 is left alone. If \\CONFIGURE@_FILE\\ is a colon-separated list, naming several
2267 alternative files, no default is installed.
2269 .index system aliases file
2270 .index \(/etc/aliases)\
2271 One change is made to the default configuration file when it is installed: the
2272 default configuration contains a router that references a system aliases file.
2273 The path to this file is set to the value specified by
2274 \\SYSTEM@_ALIASES@_FILE\\ in \(Local/Makefile)\ (\(/etc/aliases)\ by default).
2275 If the system aliases file does not exist, the installation script creates it,
2276 and outputs a comment to the user.
2278 The created file contains no aliases, but it does contain comments about the
2279 aliases a site should normally have. Mail aliases have traditionally been
2280 kept in \(/etc/aliases)\. However, some operating systems are now using
2281 \(/etc/mail/aliases)\. You should check if yours is one of these, and change
2282 Exim's configuration if necessary.
2284 The default configuration uses the local host's name as the only local domain,
2285 and is set up to do local deliveries into the shared directory \(/var/mail)\,
2286 running as the local user. System aliases and \(.forward)\ files in users' home
2287 directories are supported, but no NIS or NIS+ support is configured. Domains
2288 other than the name of the local host are routed using the DNS, with delivery
2291 The install script copies files only if they are newer than the files they are
2292 going to replace. The Exim binary is required to be owned by root and have the
2294 .index setuid||installing Exim with
2295 for normal configurations. Therefore, you must run \*make install*\ as root so
2296 that it can set up the Exim binary in this way. However, in some special
2297 situations (for example, if a host is doing no local deliveries) it may be
2298 possible to run Exim without making the binary setuid root (see chapter
2299 ~~CHAPsecurity for details).
2301 It is possible to install Exim for special purposes (such as building a binary
2302 distribution) in a private part of the file system. You can do this by a
2305 make DESTDIR=/some/directory/ install
2307 This has the effect of pre-pending the specified directory to all the file
2308 paths, except the name of the system aliases file that appears in the default
2309 configuration. (If a default alias file is created, its name \*is*\ modified.)
2310 For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set,
2311 but this usage is deprecated.
2313 .index installing Exim||what is not installed
2314 Running \*make install*\ does not copy the Exim 4 conversion script
2315 \*convert4r4*\, or the \*pcretest*\ test program. You will probably run the
2316 first of these only once (if you are upgrading from Exim 3), and the second
2317 isn't really part of Exim. None of the documentation files in the \(doc)\
2318 directory are copied, except for the info files when you have set
2319 \\INFO@_DIRECTORY\\, as described in section ~~SECTinsinfdoc below.
2321 For the utility programs, old versions are renamed by adding the suffix \(.O)\
2322 to their names. The Exim binary itself, however, is handled differently. It is
2323 installed under a name that includes the version number and the compile number,
2324 for example \(exim-~~version-1)\. The script then arranges for a symbolic link
2325 called \(exim)\ to point to the binary. If you are updating a previous version
2326 of Exim, the script takes care to ensure that the name \(exim)\ is never absent
2327 from the directory (as seen by other processes).
2329 .index installing Exim||testing the script
2330 If you want to see what the \*make install*\ will do before running it for
2331 real, you can pass the \-n-\ option to the installation script by this command:
2333 make INSTALL_ARG=-n install
2335 The contents of the variable \\INSTALL@_ARG\\ are passed to the installation
2336 script. You do not need to be root to run this test. Alternatively, you can run
2337 the installation script directly, but this must be from within the build
2338 directory. For example, from the top-level Exim directory you could use this
2341 (cd build-SunOS5-5.5.1-sparc; ../scripts/exim@_install -n)
2344 .index installing Exim||install script options
2345 There are two other options that can be supplied to the installation script.
2347 \-no@_chown-\ bypasses the call to change the owner of the installed binary
2348 to root, and the call to make it a setuid binary.
2350 \-no@_symlink-\ bypasses the setting up of the symbolic link \(exim)\ to the
2353 \\INSTALL@_ARG\\ can be used to pass these options to the script. For example:
2355 make INSTALL_ARG=-no_symlink install
2358 The installation script can also be given arguments specifying which files are
2359 to be copied. For example, to install just the Exim binary, and nothing else,
2360 without creating the symbolic link, you could use:
2362 make INSTALL_ARG='-no_symlink exim' install
2366 .section Installing info documentation
2367 .rset SECTinsinfdoc "~~chapter.~~section"
2368 .index installing Exim||\*info*\ documentation
2369 Not all systems use the GNU \*info*\ system for documentation, and for this
2370 reason, the Texinfo source of Exim's documentation is not included in the main
2371 distribution. Instead it is available separately from the ftp site (see section
2374 If you have defined \\INFO@_DIRECTORY\\ in \(Local/Makefile)\ and the Texinfo
2375 source of the documentation is found in the source tree, running \*make
2376 install*\ automatically builds the info files and installs them.
2379 .section Setting up the spool directory
2380 .index spool directory||creating
2381 When it starts up, Exim tries to create its spool directory if it does not
2382 exist. The Exim uid and gid are used for the owner and group of the spool
2383 directory. Sub-directories are automatically created in the spool directory as
2389 .index testing||installation
2390 Having installed Exim, you can check that the run time configuration file is
2391 syntactically valid by running the following command, which assumes that the
2392 Exim binary directory is within your \\PATH\\ environment variable:
2396 If there are any errors in the configuration file, Exim outputs error messages.
2397 Otherwise it outputs the version number and build date,
2398 the DBM library that is being used, and information about which drivers and
2399 other optional code modules are included in the binary.
2400 Some simple routing tests can be done by using the address testing option. For
2403 exim -bt <<local username>>
2405 should verify that it recognizes a local mailbox, and
2407 exim -bt <<remote address>>
2409 a remote one. Then try getting it to deliver mail, both locally and remotely.
2410 This can be done by passing messages directly to Exim, without going through a
2411 user agent. For example:
2413 exim -v postmaster@@your.domain.example
2414 From: user@@your.domain.example
2415 To: postmaster@@your.domain.example
2416 Subject: Testing Exim
2418 This is a test message.
2421 The \-v-\ option causes Exim to output some verification of what it is doing.
2422 In this case you should see copies of three log lines, one for the message's
2423 arrival, one for its delivery, and one containing `Completed'.
2425 .index delivery||problems with
2426 If you encounter problems, look at Exim's log files (\*mainlog*\ and
2427 \*paniclog*\) to see if there is any relevant information there. Another source
2428 of information is running Exim with debugging turned on, by specifying the
2429 \-d-\ option. If a message is stuck on Exim's spool, you can force a delivery
2430 with debugging turned on by a command of the form
2432 exim -d -M <<message-id>>
2434 You must be root or an `admin user' in order to do this. The \-d-\ option
2435 produces rather a lot of output, but you can cut this down to specific areas.
2436 For example, if you use \-d-all+route-\ only the debugging information relevant
2437 to routing is included. (See the \-d-\ option in chapter ~~CHAPcommandline for
2442 One specific problem that has shown up on some sites is the inability to do
2443 local deliveries into a shared mailbox directory, because it does not have the
2444 `sticky bit' set on it. By default, Exim tries to create a lock file before
2445 writing to a mailbox file, and if it cannot create the lock file, the delivery
2446 is deferred. You can get round this either by setting the `sticky bit' on the
2447 directory, or by setting a specific group for local deliveries and allowing
2448 that group to create files in the directory (see the comments above the
2449 \%local@_delivery%\ transport in the default configuration file). Another
2450 approach is to configure Exim not to use lock files, but just to rely on
2451 \*fcntl()*\ locking instead. However, you should do this only if all user
2452 agents also use \*fcntl()*\ locking. For further discussion of locking issues,
2453 see chapter ~~CHAPappendfile.
2455 One thing that cannot be tested on a system that is already running an MTA is
2456 the receipt of incoming SMTP mail on the standard SMTP port. However, the
2457 \-oX-\ option can be used to run an Exim daemon that listens on some other
2458 port, or \*inetd*\ can be used to do this. The \-bh-\ option and the
2459 \*exim@_checkaccess*\ utility can be used to check out policy controls on
2462 Testing a new version on a system that is already running Exim can most easily
2463 be done by building a binary with a different \\CONFIGURE@_FILE\\ setting. From
2464 within the run time configuration, all other file and directory names
2465 that Exim uses can be altered, in order to keep it entirely clear of the
2468 .section Replacing another MTA with Exim
2469 .index replacing another MTA
2470 Building and installing Exim for the first time does not of itself put it in
2471 general use. The name by which the system's MTA is called by mail user agents
2472 is either \(/usr/sbin/sendmail)\, or \(/usr/lib/sendmail)\ (depending on the
2473 operating system), and it is necessary to make this name point to the \*exim*\
2474 binary in order to get the user agents to pass messages to Exim. This is
2475 normally done by renaming any existing file and making \(/usr/sbin/sendmail)\
2476 or \(/usr/lib/sendmail)\
2477 .index symbolic link||to \*exim*\ binary
2478 a symbolic link to the \*exim*\ binary. It is a good idea to remove any setuid
2479 privilege and executable status from the old MTA. It is then necessary to stop
2480 and restart the mailer daemon, if one is running.
2482 .index FreeBSD, MTA indirection
2483 .index \(/etc/mail/mailer.conf)\
2484 Some operating systems have introduced alternative ways of switching MTAs. For
2485 example, if you are running FreeBSD, you need to edit the file
2486 \(/etc/mail/mailer.conf)\ instead of setting up a symbolic link as just
2487 described. A typical example of the contents of this file for running Exim is
2490 sendmail /usr/exim/bin/exim
2491 send-mail /usr/exim/bin/exim
2492 mailq /usr/exim/bin/exim -bp
2493 newaliases /usr/bin/true
2496 Once you have set up the symbolic link, or edited \(/etc/mail/mailer.conf)\,
2497 your Exim installation is `live'. Check it by sending a message from your
2498 favourite user agent.
2500 You should consider what to tell your users about the change of MTA. Exim may
2501 have different capabilities to what was previously running, and there are
2502 various operational differences such as the text of messages produced by
2503 command line options and in bounce messages. If you allow your users to make
2504 use of Exim's filtering capabilities, you should make the document entitled
2506 [(A HREF="filter.html")]
2508 \*Exim's interface to mail filtering*\
2515 .section Upgrading Exim
2516 .index upgrading Exim
2517 If you are already running Exim on your host, building and installing a new
2518 version automatically makes it available to MUAs, or any other programs that
2519 call the MTA directly. However, if you are running an Exim daemon, you do need
2520 to send it a HUP signal, to make it re-exec itself, and thereby pick up the new
2521 binary. You do not need to stop processing mail in order to install a new
2525 .section Stopping the Exim daemon on Solaris
2526 .index Solaris||stopping Exim on
2527 The standard command for stopping the mailer daemon on Solaris is
2529 /etc/init.d/sendmail stop
2531 If \(/usr/lib/sendmail)\ has been turned into a symbolic link, this script
2532 fails to stop Exim because it uses the command \*ps -e*\ and greps the output
2533 for the text `sendmail'; this is not present because the actual program name
2534 (that is, `exim') is given by the \*ps*\ command with these options. A solution
2535 is to replace the line that finds the process id with something like
2537 pid=`cat /var/spool/exim/exim-daemon.pid`
2539 to obtain the daemon's pid directly from the file that Exim saves it in.
2541 Note, however, that stopping the daemon does not `stop Exim'. Messages can
2542 still be received from local processes, and if automatic delivery is configured
2543 (the normal case), deliveries will still occur.
2550 . ============================================================================
2551 .chapter The Exim command line
2552 .set runningfoot "command line"
2553 .rset CHAPcommandline ~~chapter
2554 .index command line||options
2555 .index options||command line
2557 Exim's command line takes the standard Unix form of a sequence of options,
2558 each starting with a hyphen character, followed by a number of arguments. The
2559 options are compatible with the main options of Sendmail, and there are also
2560 some additional options, some of which are compatible with Smail 3. Certain
2561 combinations of options do not make sense, and provoke an error if used.
2562 The form of the arguments depends on which options are set.
2564 .section Setting options by program name
2566 If Exim is called under the name \*mailq*\, it behaves as if the option \-bp-\
2567 were present before any other options.
2568 The \-bp-\ option requests a listing of the contents of the mail queue on the
2570 This feature is for compatibility with some systems that contain a command of
2571 that name in one of the standard libraries, symbolically linked to
2572 \(/usr/sbin/sendmail)\ or \(/usr/lib/sendmail)\.
2575 If Exim is called under the name \*rsmtp*\ it behaves as if the option \-bS-\
2576 were present before any other options, for compatibility with Smail. The \-bS-\
2577 option is used for reading in a number of messages in batched SMTP format.
2580 If Exim is called under the name \*rmail*\ it behaves as if the \-i-\ and
2581 \-oee-\ options were present before any other options, for compatibility with
2582 Smail. The name \*rmail*\ is used as an interface by some UUCP systems.
2586 If Exim is called under the name \*runq*\ it behaves as if the option \-q-\ were
2587 present before any other options, for compatibility with Smail. The \-q-\
2588 option causes a single queue runner process to be started.
2590 .index \*newaliases*\
2591 .index alias file||building
2592 .index Sendmail compatibility||calling Exim as \*newaliases*\
2593 If Exim is called under the name \*newaliases*\ it behaves as if the option
2594 \-bi-\ were present before any other options, for compatibility with Sendmail.
2595 This option is used for rebuilding Sendmail's alias file. Exim does not have
2596 the concept of a single alias file, but can be configured to run a given
2597 command if called with the \-bi-\ option.
2599 .section Trusted and admin users
2600 .rset SECTtrustedadmin "~~chapter.~~section"
2601 Some Exim options are available only to \*trusted users*\ and others are
2602 available only to \*admin users*\. In the description below, the phrases `Exim
2603 user' and `Exim group' mean the user and group defined by \\EXIM@_USER\\ and
2604 \\EXIM@_GROUP\\ in \(Local/Makefile)\ or set by the \exim@_user\ and
2605 \exim@_group\ options. These do not necessarily have to use the name `exim'.
2608 .index trusted user||definition of
2609 .index user||trusted, definition of
2610 The trusted users are root, the Exim user, any user listed in the
2611 \trusted@_users\ configuration option, and any user whose current group or any
2612 supplementary group is one of those listed in the \trusted@_groups\
2613 configuration option. Note that the Exim group is not automatically trusted.
2616 .index envelope sender
2617 Trusted users are always permitted to use the \-f-\ option or a leading `From '
2618 line to specify the envelope sender of a message that is passed to Exim through
2619 the local interface (see the \-bm-\ and \-f-\ options below). See the
2620 \untrusted@_set@_sender\ option for a way of permitting non-trusted users to
2621 set envelope senders.
2622 .index ::From:: header line
2623 .index ::Sender:: header line
2624 For a trusted user, there is never any check on the contents of the ::From::
2625 header line, and a ::Sender:: line is never added. Furthermore, any existing
2626 ::Sender:: line in incoming local (non-TCP/IP) messages is not removed.
2628 Trusted users may also specify a host name, host address, interface address,
2629 protocol name, ident value, and authentication data when submitting a message
2630 locally. Thus, they are able to insert messages into Exim's queue locally that
2631 have the characteristics of messages received from a remote host. Untrusted
2632 users may in some circumstances use \-f-\, but can never set the other values
2633 that are available to trusted users.
2635 .index user||admin, definition of
2636 .index admin user||definition of
2637 The admin users are root, the Exim user, and any user that is a member of the
2638 Exim group or of any group listed in the \admin@_groups\ configuration option.
2639 The current group does not have to be one of these groups.
2641 Admin users are permitted to list the queue, and to carry out certain
2642 operations on messages, for example, to force delivery failures. It is also
2643 necessary to be an admin user in order to see the full information provided by
2644 the Exim monitor, and full debugging output.
2646 By default, the use of the \-M-\, \-q-\, \-R-\, and \-S-\ options to cause Exim
2647 to attempt delivery of messages on its queue is restricted to admin users.
2648 However, this restriction can be relaxed by setting the \prod@_requires@_admin\
2649 option false (that is, specifying \no@_prod@_requires@_admin\).
2651 Similarly, the use of the \-bp-\ option to list all the messages in the queue
2652 is restricted to admin users unless \queue@_list@_requires@_admin\ is set
2656 \**Warning**\: If you configure your system so that admin users are able to
2657 edit Exim's configuration file, you are giving those users an easy way of
2658 getting root. There is further discussion of this issue at the start of chapter
2663 .section Command line options
2664 The command options are described in alphabetical order below.
2669 .index options||command line, terminating
2670 This is a pseudo-option whose only purpose is to terminate the options and
2671 therefore to cause subsequent command line items to be treated as arguments
2672 rather than options, even if they begin with hyphens.
2675 This option causes Exim to output a few sentences stating what it is.
2676 The same output is generated if the Exim binary is called with no options and
2680 .index 8-bit characters
2681 .index Sendmail compatibility||8-bit characters
2682 This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit
2683 clean; it ignores this option.
2687 .index SMTP listener
2689 This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually
2690 the \-bd-\ option is combined with the \-q-\<<time>> option, to specify that
2691 the daemon should also initiate periodic queue runs.
2693 The \-bd-\ option can be used only by an admin user. If either of the \-d-\
2694 (debugging) or \-v-\ (verifying) options are set, the daemon does not
2695 disconnect from the controlling terminal. When running this way, it can be
2696 stopped by pressing ctrl-C.
2698 By default, Exim listens for incoming connections to the standard SMTP port on
2699 all the host's running interfaces. However, it is possible to listen on other
2700 ports, on multiple ports, and only on specific interfaces. Chapter
2701 ~~CHAPinterfaces contains a description of the options that control this.
2703 .index daemon||process id (pid)
2704 .index pid (process id)||of daemon
2705 When a listening daemon is started without the use of \-oX-\ (that is, without
2706 overriding the normal configuration), it writes its process id to a file called
2707 \(exim-daemon.pid)\ in Exim's spool directory. This location can be overridden
2708 by setting \\PID@_FILE@_PATH\\ in \(Local/Makefile)\. The file is written while
2709 Exim is still running as root.
2711 When \-oX-\ is used on the command line to start a listening daemon, the
2712 process id is not written to the normal pid file path. However, \-oP-\ can be
2713 used to specify a path on the command line if a pid file is required.
2716 The \\SIGHUP\\ signal can be used to cause the daemon to re-exec itself. This
2717 should be done whenever Exim's configuration file, or any file that is
2718 incorporated into it by means of the \.include\ facility, is changed, and also
2719 whenever a new version of Exim is installed. It is not necessary to do this
2720 when other files that are referenced from the configuration (for example, alias
2721 files) are changed, because these are reread each time they are used.
2724 This option has the same effect as \-bd-\ except that it never disconnects from
2725 the controlling terminal, even when no debugging is specified.
2728 .index testing||string expansion
2729 .index expansion||testing
2730 Run Exim in expansion testing mode. Exim discards its root privilege, to
2731 prevent ordinary users from using this mode to read otherwise inaccessible
2732 files. If no arguments are given, Exim runs interactively, prompting for lines
2733 of data. Long expressions can be split over several lines by using backslash
2735 As in Exim's run time configuration, whitespace at the start of continuation
2738 Each argument or data line is passed through the string expansion mechanism,
2739 and the result is output. Variable values from the configuration file (for
2740 example, \$qualify@_domain$\) are available, but no message-specific values
2741 (such as \$domain$\) are set, because no message is being processed.
2743 .option bF #<<filename>>
2744 .index system filter||testing
2745 .index testing||system filter
2746 This option is the same as \-bf-\ except that it assumes that the filter being
2747 tested is a system filter. The additional commands that are available only in
2748 system filters are recognized.
2750 .option bf #<<filename>>
2751 .index filter||testing
2752 .index testing||filter file
2753 .index forward file||testing
2754 .index testing||forward file
2755 .index Sieve filter||testing
2756 This option runs Exim in filter testing mode; the file is the filter file to be
2757 tested, and a test message must be supplied on the standard input. If there are
2758 no message-dependent tests in the filter, an empty file can be supplied. If a
2759 system filter file is being tested, \-bF-\ should be used instead of \-bf-\. If
2760 the test file does not begin with
2761 one of the special lines
2766 it is taken to be a normal \(.forward)\ file, and is tested for validity under
2767 that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a
2768 description of the possible contents of non-filter redirection lists.
2770 The result of an Exim command that uses \-bf-\, provided no errors are
2771 detected, is a list of the actions that Exim would try to take if presented
2772 with the message for real. More details of filter testing are given in the
2773 separate document entitled \*Exim's interfaces to mail filtering*\.
2776 .index envelope sender
2777 .index \-f-\ option||for filter testing
2778 When testing a filter file, the envelope sender can be set by the \-f-\ option,
2779 or by a `From ' line at the start of the test message. Various parameters that
2780 would normally be taken from the envelope recipient address of the message can
2781 be set by means of additional command line options. These are:
2788 . The odd alignment here gets it lined up in the man page.
2789 \-bfd-\ $t <<domain>> $t $rm{default is the qualify domain}
2790 \-bfl-\ $t <<local@_part>> $t $rm{default is the logged in user}
2791 \-bfp-\ $t <<local@_part@_prefix>> $t $rm{default is null}
2792 \-bfs-\ $t <<local@_part@_suffix>> $t $rm{default is null}
2794 The local part should always be set to the incoming address with any prefix or
2795 suffix stripped, because that is how it appears to the filter when a message is
2796 actually being delivered.
2798 .option bh #<<IP address>>
2799 .index testing||incoming SMTP
2800 .index SMTP||testing incoming
2801 .index testing||relay control
2802 .index relaying||testing configuration
2803 .index policy control||testing
2804 .index debugging||\-bh-\ option
2805 This option runs a fake SMTP session as if from the given IP address, using the
2806 standard input and output. The IP address may include a port number at the end,
2807 after a full stop. For example:
2809 exim -bh 10.9.8.7.1234
2810 exim -bh fe80::a00:20ff:fe86:a061.5678
2812 Comments as to what is going on are written to the standard error file. These
2813 include lines beginning with `LOG' for anything that would have been logged.
2814 This facility is provided for testing configuration options for incoming
2815 messages, to make sure they implement the required policy. For example, you can
2816 test your relay controls using \-bh-\.
2819 \**Warning 1**\: You cannot test features of the configuration that rely on
2820 ident (RFC 1413) callouts. These cannot be done when testing using
2821 \-bh-\ because there is no incoming SMTP connection.
2823 \**Warning 2**\: Address verification callouts (see section ~~SECTcallver) are
2824 also skipped when testing using \-bh-\. If you want these callouts to occur,
2825 use \-bhc-\ instead.
2827 Messages supplied during the testing session are discarded, and nothing is
2828 written to any of the real log files. There may be pauses when DNS (and other)
2829 lookups are taking place, and of course these may time out. The \-oMi-\ option
2830 can be used to specify a specific IP interface and port if this is important.
2832 The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\ whose
2833 output just states whether a given recipient address from a given host is
2834 acceptable or not. See section ~~SECTcheckaccess.
2836 .option bhc #<<IP address>>
2837 This option operates in the same way as \-bh-\, except that address
2838 verification callouts are performed if required. This includes consulting and
2839 updating the callout cache database.
2842 .index alias file||building
2843 .index building alias file
2844 .index Sendmail compatibility||\-bi-\ option
2845 Sendmail interprets the \-bi-\ option as a request to rebuild its alias file.
2846 Exim does not have the concept of a single alias file, and so it cannot mimic
2847 this behaviour. However, calls to \(/usr/lib/sendmail)\ with the \-bi-\ option
2848 tend to appear in various scripts such as NIS make files, so the option must be
2851 If \-bi-\ is encountered, the command specified by the \bi@_command\
2852 configuration option is run, under the uid and gid of the caller of Exim. If
2853 the \-oA-\ option is used, its value is passed to the command as an argument.
2854 The command set by \bi@_command\ may not contain arguments. The command can use
2855 the \*exim@_dbmbuild*\ utility, or some other means, to rebuild alias files if
2856 this is required. If the \bi@_command\ option is not set, calling Exim with
2860 .index local message reception
2861 This option runs an Exim receiving process that accepts an incoming,
2862 locally-generated message on the current input. The recipients are given as the
2863 command arguments (except when \-t-\ is also present -- see below). Each
2864 argument can be a comma-separated list of RFC 2822 addresses. This is the
2865 default option for selecting the overall action of an Exim call; it is assumed
2866 if no other conflicting option is present.
2868 If any addresses in the message are unqualified (have no domain), they are
2869 qualified by the values of the \qualify@_domain\ or \qualify@_recipient\
2870 options, as appropriate. The \-bnq-\ option (see below) provides a way of
2871 suppressing this for special cases.
2873 Policy checks on the contents of local messages can be enforced by means of the
2874 non-SMTP ACL. See chapter ~~CHAPACL for details.
2875 .index return code||for \-bm-\
2876 The return code is zero if the message is successfully accepted. Otherwise, the
2877 action is controlled by the \-oe$it{x}-\ option setting -- see below.
2879 .index message||format
2880 .index format||message
2882 .index UUCP||`From' line
2883 .index Sendmail compatibility||`From' line
2884 The format of the message must be as defined in RFC 2822, except that, for
2885 compatibility with Sendmail and Smail, a line in one of the forms
2887 From sender Fri Jan 5 12:55 GMT 1997
2888 From sender Fri, 5 Jan 97 12:55:01
2890 (with the weekday optional, and possibly with additional text after the date)
2891 is permitted to appear at the start of the message. There appears to be no
2892 authoritative specification of the format of this line. Exim recognizes it by
2893 matching against the regular expression defined by the \uucp@_from@_pattern\
2894 option, which can be changed if necessary.
2895 .index \-f-\ option||overriding `From' line
2896 The specified sender is treated as if it were given as the argument to the
2897 \-f-\ option, but if a \-f-\ option is also present, its argument is used in
2898 preference to the address taken from the message. The caller of Exim must be a
2899 trusted user for the sender of a message to be set in this way.
2902 .index address||qualification, suppressing
2903 By default, Exim automatically qualifies unqualified addresses (those
2904 without domains) that appear in messages that are submitted locally (that
2905 is, not over TCP/IP). This qualification applies both to addresses in
2906 envelopes, and addresses in header lines. Sender addresses are qualified using
2907 \qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which
2908 defaults to the value of \qualify@_domain\).
2910 Sometimes, qualification is not wanted. For example, if \-bS-\ (batch SMTP) is
2911 being used to re-submit messages that originally came from remote hosts after
2912 content scanning, you probably do not want to qualify unqualified addresses in
2913 header lines. (Such lines will be present only if you have not enabled a header
2914 syntax check in the appropriate ACL.)
2916 The \-bnq-\ option suppresses all qualification of unqualified addresses in
2917 messages that originate on the local host. When this is used, unqualified
2918 addresses in the envelope provoke errors (causing message rejection) and
2919 unqualified addresses in header lines are left alone.
2923 .index configuration options, extracting
2924 .index options||configuration, extracting
2925 If this option is given with no arguments, it causes the values of all Exim's
2926 main configuration options to be written to the standard output. The values
2927 of one or more specific options can be requested by giving their names as
2928 arguments, for example:
2930 exim -bP qualify@_domain hold@_domains
2932 However, any option setting that is preceded by the word `hide' in the
2933 configuration file is not shown in full, except to an admin user. For other
2934 users, the output is as in this example:
2936 mysql_servers = <value not displayable>
2938 If \configure@_file\ is given as an argument, the name of the run time
2939 configuration file is output.
2940 If a list of configuration files was supplied, the value that is output here
2941 is the name of the file that was actually used.
2943 .index daemon||process id (pid)
2944 .index pid (process id)||of daemon
2945 If \log__file__path\ or \pid@_file@_path\ are given, the names of the
2946 directories where log files and daemon pid files are written are output,
2947 respectively. If these values are unset, log files are written in a
2948 sub-directory of the spool directory called \log\, and the pid file is written
2949 directly into the spool directory.
2951 If \-bP-\ is followed by a name preceded by \"+"\, for example,
2953 exim -bP +local_domains
2955 it searches for a matching named list of any type (domain, host, address, or
2956 local part) and outputs what it finds.
2958 .index options||router, extracting
2959 .index options||transport, extracting
2960 If one of the words \router\, \transport\, or \authenticator\ is given,
2961 followed by the name of an appropriate driver instance, the option settings for
2962 that driver are output. For example:
2964 exim -bP transport local@_delivery
2966 The generic driver options are output first, followed by the driver's private
2967 options. A list of the names of drivers of a particular type can be obtained by
2968 using one of the words \router@_list\, \transport@_list\, or
2969 \authenticator@_list\, and a complete list of all drivers with their option
2970 settings can be obtained by using \routers\, \transports\, or \authenticators\.
2974 .index queue||listing messages on
2975 .index listing||messages on the queue
2976 This option requests a listing of the contents of the mail queue on the
2977 standard output. If the \-bp-\ option is followed by a list of message ids,
2978 just those messages are listed. By default, this option can be used only by an
2979 admin user. However, the \queue__list__requires__admin\ option can be set false
2980 to allow any user to see the queue.
2982 Each message on the queue is displayed as in the following example:
2984 25m 2.9K 0t5C6f-0000c8-00 <alice@@wonderland.fict.example>
2985 red.king@@looking-glass.fict.example
2988 .index message||size in queue listing
2989 .index size||of message
2990 The first line contains the length of time the message has been on the queue
2991 (in this case 25 minutes), the size of the message (2.9K), the unique local
2992 identifier for the message, and the message sender, as contained in the
2993 envelope. For bounce messages, the sender address is empty, and appears as
2994 `<>'. If the message was submitted locally by an untrusted user who overrode
2995 the default sender address, the user's login name is shown in parentheses
2996 before the sender address.
2997 .index frozen messages||in queue listing
2998 If the message is frozen (attempts to deliver it are suspended) then the text
2999 `$*$$*$$*$ frozen $*$$*$$*$' is displayed at the end of this line.
3001 The recipients of the message (taken from the envelope, not the headers) are
3002 displayed on subsequent lines. Those addresses to which the message has already
3003 been delivered are marked with the letter D. If an original address gets
3004 expanded into several addresses via an alias or forward file, the original is
3005 displayed with a D only when deliveries for all of its child addresses are
3010 This option operates like \-bp-\, but in addition it shows delivered addresses
3011 that were generated from the original top level address(es) in each message by
3012 alias or forwarding operations. These addresses are flagged with `+D' instead
3017 .index queue||count of messages on
3018 This option counts the number of messages on the queue, and writes the total
3019 to the standard output. It is restricted to admin users, unless
3020 \queue__list__requires__admin\ is set false.
3024 This option operates like \-bp-\, but the output is not sorted into
3025 chronological order of message arrival. This can speed it up when there are
3026 lots of messages on the queue, and is particularly useful if the output is
3027 going to be post-processed in a way that doesn't need the sorting.
3030 This option is a combination of \-bpr-\ and \-bpa-\.
3033 This option is a combination of \-bpr-\ and \-bpu-\.
3037 This option operates like \-bp-\ but shows only undelivered top-level addresses
3038 for each message displayed. Addresses generated by aliasing or forwarding are
3039 not shown, unless the message was deferred after processing by a router with
3040 the \one@_time\ option set.
3044 .index testing||retry configuration
3045 .index retry||configuration testing
3046 This option is for testing retry rules, and it must be followed by up to three
3047 arguments. It causes Exim to look for a retry rule that matches the values
3048 and to write it to the standard output. For example:
3050 exim -brt bach.comp.mus.example
3051 Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
3053 See chapter ~~CHAPretry for a description of Exim's retry rules. The first
3054 argument, which is required, can be a complete address in the form
3055 \*local@_part@@domain*\, or it can be just a domain name. The second argument is
3056 an optional second domain name; if no retry rule is found for the first
3057 argument, the second is tried. This ties in with Exim's behaviour when looking
3058 for retry rules for remote hosts -- if no rule is found that matches the host,
3059 one that matches the mail domain is sought. The final argument is the name of a
3060 specific delivery error, as used in setting up retry rules, for example
3064 .index testing||rewriting
3065 .index rewriting||testing
3066 This option is for testing address rewriting rules, and it must be followed by
3067 a single argument, consisting of either a local part without a domain, or a
3068 complete address with a fully qualified domain. Exim outputs how this address
3069 would be rewritten for each possible place it might appear. See chapter
3070 ~~CHAPrewrite for further details.
3073 .index SMTP||batched incoming
3074 .index batched SMTP input
3075 This option is used for batched SMTP input, which is an alternative interface
3076 for non-interactive local message submission. A number of messages can be
3077 submitted in a single run. However, despite its name, this is not really SMTP
3078 input. Exim reads each message's envelope from SMTP commands on the standard
3079 input, but generates no responses. If the caller is trusted, or
3080 \untrusted@_set@_sender\ is set, the senders in the SMTP \\MAIL\\ commands are
3081 believed; otherwise the sender is always the caller of Exim.
3083 The message itself is read from the standard input, in SMTP format (leading
3084 dots doubled), terminated by a line containing just a single dot. An error is
3085 provoked if the terminating dot is missing. A further message may then follow.
3087 As for other local message submissions, the contents of incoming batch SMTP
3088 messages can be checked using the non-SMTP ACL (see chapter ~~CHAPACL).
3089 Unqualified addresses are automatically qualified using \qualify@_domain\ and
3090 \qualify@_recipient\, as appropriate, unless the \-bnq-\ option is used.
3092 Some other SMTP commands are recognized in the input. \\HELO\\ and \\EHLO\\ act
3093 as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\, and \\HELP\\ act as \\NOOP\\;
3094 \\QUIT\\ quits, ignoring the rest of the standard input.
3096 If any error is encountered, reports are written to the standard output and
3097 error streams, and Exim gives up immediately.
3098 .index return code||for \-bS-\
3099 The return code is 0 if no error was detected; it is 1 if one or more messages
3100 were accepted before the error was detected; otherwise it is 2.
3102 More details of input using batched SMTP are given in section
3103 ~~SECTincomingbatchedSMTP.
3106 .index SMTP||local input
3107 .index local SMTP input
3108 This option causes Exim to accept one or more messages by reading SMTP commands
3109 on the standard input, and producing SMTP replies on the standard output. SMTP
3110 policy controls, as defined in ACLs (see chapter ~~CHAPACL) are applied.
3112 Some user agents use this interface as a way of passing locally-generated
3113 messages to the MTA.
3114 .index sender||source of
3115 In this usage, if the caller of Exim is trusted, or \untrusted@_set@_sender\ is
3116 set, the senders of messages are taken from the SMTP \\MAIL\\ commands.
3117 Otherwise the content of these commands is ignored and the sender is set up as
3118 the calling user. Unqualified addresses are automatically qualified using
3119 \qualify@_domain\ and \qualify@_recipient\, as appropriate, unless the \-bnq-\
3123 The \-bs-\ option is also used to run Exim from \*inetd*\, as an alternative to
3124 using a listening daemon. Exim can distinguish the two cases by checking
3125 whether the standard input is a TCP/IP socket. When Exim is called from
3126 \*inetd*\, the source of the mail is assumed to be remote, and the comments
3127 above concerning senders and qualification do not apply. In this situation,
3128 Exim behaves in exactly the same way as it does when receiving a message via
3129 the listening daemon.
3132 .index testing||addresses
3133 .index address||testing
3134 This option runs Exim in address testing mode, in which each argument is taken
3135 as an address to be tested for deliverability. The results are written to the
3137 If a test fails, and the caller is not an admin user, no details of the
3138 failure are output, because these might contain sensitive information such as
3139 usernames and passwords for database lookups.
3141 If no arguments are given, Exim runs in an interactive manner, prompting with a
3142 right angle bracket for addresses to be tested. Each address is handled as if
3143 it were the recipient address of a message (compare the \-bv-\ option). It is
3144 passed to the routers and the result is written to the standard output.
3145 However, any router that has \no@_address@_test\ set is bypassed. This can
3146 make \-bt-\ easier to use for genuine routing tests if your first router passes
3147 everything to a scanner program.
3149 .index return code||for \-bt-\
3150 The return code is 2 if any address failed outright; it is 1 if no address
3151 failed outright but at least one could not be resolved for some reason. Return
3152 code 0 is given only when all addresses succeed.
3154 \**Warning**\: \-bt-\ can only do relatively simple testing. If any of the
3155 routers in the configuration makes any tests on the sender address of a
3157 .index \-f-\ option||for address testing
3158 you can use the \-f-\ option to set an appropriate sender when running
3159 \-bt-\ tests. Without it, the sender is assumed to be the calling user at the
3160 default qualifying domain. However, if you have set up (for example) routers
3161 whose behaviour depends on the contents of an incoming message, you cannot test
3162 those conditions using \-bt-\. The \-N-\ option provides a possible way of
3166 .index version number of Exim, verifying
3167 This option causes Exim to write the current version number, compilation
3168 number, and compilation date of the \*exim*\ binary to the standard output.
3169 It also lists the DBM library this is being used, the optional modules (such as
3170 specific lookup types), the drivers that are included in the binary, and the
3171 name of the run time configuration file that is in use.
3174 .index verifying||address, using \-bv-\
3175 .index address||verification
3176 This option runs Exim in address verification mode, in which each argument is
3177 taken as an address to be verified. During normal operation, verification
3178 happens mostly as a consequence processing a \verify\ condition in an ACL (see
3179 chapter ~~CHAPACL). If you want to test an entire ACL, see the \-bh-\ option.
3181 If verification fails, and the caller is not an admin user, no details of the
3182 failure are output, because these might contain sensitive information such as
3183 usernames and passwords for database lookups.
3185 If no arguments are given, Exim runs in an interactive manner, prompting with a
3186 right angle bracket for addresses to be verified. Verification differs from
3187 address testing (the \-bt-\ option) in that routers that have \no@_verify\ set
3188 are skipped, and if the address is accepted by a router that has \fail@_verify\
3189 set, verification fails. The address is verified as a recipient if \-bv-\ is
3190 used; to test verification for a sender address, \-bvs-\ should be used.
3192 If the \-v-\ option is not set, the output consists of a single line for each
3193 address, stating whether it was verified or not, and giving a reason in the
3194 latter case. Otherwise, more details are given of how the address has been
3195 handled, and in the case of address redirection, all the generated addresses
3196 are also considered. Without \-v-\, generating more than one address by
3197 redirection causes verification to end sucessfully.
3199 .index return code||for \-bv-\
3200 The return code is 2 if any address failed outright; it is 1 if no address
3201 failed outright but at least one could not be resolved for some reason. Return
3202 code 0 is given only when all addresses succeed.
3204 If any of the routers in the configuration makes any tests on the sender
3205 address of a message, you should use the \-f-\ option to set an appropriate
3206 sender when running \-bv-\ tests. Without it, the sender is assumed to be the
3207 calling user at the default qualifying domain.
3210 This option acts like \-bv-\, but verifies the address as a sender rather
3211 than a recipient address. This affects any rewriting and qualification that
3214 .option C #<<filelist>>
3215 .index configuration file||alternate
3216 .index \\CONFIGURE@_FILE\\
3217 .index alternate configuration file
3218 This option causes Exim to find the run time configuration file from the given
3219 list instead of from the list specified by the \\CONFIGURE@_FILE\\
3220 compile-time setting. Usually, the list will consist of just a single file
3221 name, but it can be a colon-separated list of names. In this case, the first
3222 file that exists is used. Failure to open an existing file stops Exim from
3223 proceeding any further along the list, and an error is generated.
3225 When this option is used by a caller other than root or the Exim user,
3226 and the list is different from the compiled-in list, Exim gives up
3227 its root privilege immediately, and runs with the real and effective uid and
3228 gid set to those of the caller.
3229 However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in \(Local/Makefile)\, root
3230 privilege is retained for \-C-\ only if the caller of Exim is root.
3231 This option is not set by default.
3233 Setting \\ALT@_CONFIG@_ROOT@_ONLY\\ locks out the possibility of testing a
3234 configuration using \-C-\ right through message reception and delivery, even if
3235 the caller is root. The reception works, but by that time, Exim is running as
3236 the Exim user, so when it re-execs to regain privilege for the delivery, the
3237 use of \-C-\ causes privilege to be lost. However, root can test reception and
3238 delivery using two separate commands (one to put a message on the queue, using
3239 \-odq-\, and another to do the delivery, using \-M-\).
3241 If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a
3242 prefix string with which any file named in a \-C-\ command line option
3243 must start. In addition, the file name must not contain the sequence \"/../"\.
3244 However, if the value of the \-C-\ option is identical to the value of
3245 \\CONFIGURE@_FILE\\ in \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as
3246 usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is
3247 unset, any file name can be used with \-C-\.
3249 \\ALT@_CONFIG@_PREFIX\\ can be used to confine alternative configuration files
3250 to a directory to which only root has access. This prevents someone who has
3251 broken into the Exim account from running a privileged Exim with an arbitrary
3254 The \-C-\ facility is useful for ensuring that configuration files are
3255 syntactically correct, but cannot be used for test deliveries, unless the
3256 caller is privileged, or unless it is an exotic configuration that does not
3257 require privilege. No check is made on the owner or group of the files
3258 specified by this option.
3260 .option D <<macro>>=<<value>>
3261 .index macro||setting on command line
3262 This option can be used to override macro definitions in the configuration file
3263 (see section ~~SECTmacrodefs). However, like \-C-\, if it is used by an
3264 unprivileged caller, it causes Exim to give up its root privilege.
3265 If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is
3266 completely disabled, and its use causes an immediate error exit.
3268 The entire option (including equals sign if present) must all be within one
3269 command line item. \-D-\ can be used to set the value of a macro to the empty
3270 string, in which case the equals sign is optional. These two commands are
3276 To include spaces in a macro definition item, quotes must be used. If you use
3277 quotes, spaces are permitted around the macro name and the equals sign. For
3280 exim '-D ABC = something' ...
3282 \-D-\ may be repeated up to 10 times on a command line.
3284 .option d <<debug options>>
3285 .index debugging||list of selectors
3286 .index debugging||\-d-\ option
3287 This option causes debugging information to be written to the standard
3288 error stream. It is restricted to admin users because debugging output may show
3289 database queries that contain password information. Also, the details of users'
3290 filter files should be protected. When \-d-\ is used, \-v-\ is assumed. If
3291 \-d-\ is given on its own, a lot of standard debugging data is output. This can
3292 be reduced, or increased to include some more rarely needed information, by
3293 following \-d-\ with a string made up of names preceded by plus or minus
3294 characters. These add or remove sets of debugging data, respectively. For
3295 example, \-d+filter-\ adds filter debugging, whereas \-d-all+filter-\ selects
3296 only filter debugging. The available debugging categories are:
3300 . The odd formatting of the lines below is deliberate. It does not affect the
3301 . SGCAL output, but by putting in the space it keeps things aligned in the man
3302 . page that is automatically generated from this text.
3304 acl $t $rm{ACL interpretation}
3305 auth $t $rm{authenticators}
3306 deliver $t $rm{general delivery logic}
3307 dns $t $rm{DNS lookups (see also resolver)}
3308 dnsbl $t $rm{DNS black list (aka RBL) code}
3309 exec $t $rm{arguments for \execv@(@)\ calls}
3310 expand $t $rm{detailed debugging for string expansions}
3311 filter $t $rm{filter handling}
3312 hints@_lookup $t $rm{hints data lookups}
3313 host@_lookup $t $rm{all types of name-to-IP address handling}
3314 ident $t $rm{ident lookup}
3315 interface $t $rm{lists of local interfaces}
3316 lists $t $rm{matching things in lists}
3317 load $t $rm{system load checks}
3318 local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)}
3319 lookup $t $rm{general lookup code and all lookups}
3320 memory $t $rm{memory handling}
3321 pid $t $rm{add pid to debug output lines}
3322 process@_info $t $rm{setting info for the process log}
3323 queue@_run $t $rm{queue runs}
3324 receive $t $rm{general message reception logic}
3325 resolver $t $rm{turn on the DNS resolver's debugging output}
3326 retry $t $rm{retry handling}
3327 rewrite $t $rm{address rewriting}
3328 route $t $rm{address routing}
3329 timestamp $t $rm{add timestamp to debug output lines}
3330 tls $t $rm{TLS logic}
3331 transport $t $rm{transports}
3332 uid $t $rm{changes of uid/gid and looking up uid/gid}
3333 verify $t $rm{address verification logic}
3335 all $t $rm{all of the above, and also \-v-\}
3338 .index resolver, debugging output
3339 .index DNS||resolver, debugging output
3340 The \"resolver"\ option produces output only if the DNS resolver was compiled
3341 with \\DEBUG\\ enabled. This is not the case in some operating systems. Also,
3342 unfortunately, debugging output from the DNS resolver is written to stdout
3346 The default (\-d-\ with no argument) omits \"expand"\, \"filter"\,
3347 \"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\.
3348 However, the \"pid"\ selector is forced when debugging is turned on for a
3349 daemon, which then passes it on to any re-executed Exims. Exim also
3350 automatically adds the pid to debug lines when several remote deliveries are
3353 The \"timestamp"\ selector causes the current time to be inserted at the start
3354 of all debug output lines. This can be useful when trying to track down delays
3357 If the \debug@_print\ option is set in any driver, it produces output whenever
3358 any debugging is selected, or if \-v-\ is used.
3361 This is an obsolete option that is now a no-op. It used to affect the way Exim
3362 handled CR and LF characters in incoming messages. What happens now is
3363 described in section ~~SECTlineendings.
3367 .index bounce message||generating
3368 This option specifies that an incoming message is a locally-generated delivery
3369 failure report. It is used internally by Exim when handling delivery failures
3370 and is not intended for external use. Its only effect is to stop Exim
3371 generating certain messages to the postmaster, as otherwise message cascades
3372 could occur in some situations. As part of the same option, a message id may
3373 follow the characters \-E-\. If it does, the log entry for the receipt of the
3374 new message contains the id, following `R=', as a cross-reference.
3377 There are a number of Sendmail options starting with \-oe-\ which seem to be
3378 called by various programs without the leading \o\ in the option. For example,
3379 the \vacation\ program uses \-eq-\. Exim treats all options of the form
3380 \-e$it{x}-\ as synonymous with the corresponding \-oe$it{x}-\ options.
3382 .option F #<<string>>
3384 .index name||of sender
3385 This option sets the sender's full name for use when a locally-generated
3386 message is being accepted. In the absence of this option, the user's \*gecos*\
3387 entry from the password data is used. As users are generally permitted to alter
3388 their \*gecos*\ entries, no security considerations are involved. White space
3389 between \-F-\ and the <<string>> is optional.
3391 .option f #<<address>>
3392 .index sender||address
3393 .index address||sender
3395 .index envelope sender
3396 .index user||trusted
3397 This option sets the address of the envelope sender of a locally-generated
3398 message (also known as the return path). The option can normally be used only
3399 by a trusted user, but \untrusted@_set@_sender\ can be set to allow untrusted
3400 users to use it. In the absence of \-f-\, or if the caller is not allowed to
3401 use it, the sender of a local message is set to the caller's login name at the
3402 default qualify domain.
3404 There is one exception to the restriction on the use of \-f-\: an empty sender
3405 can be specified by any user, to create a message that can never provoke a
3406 bounce. An empty sender can be specified either as an empty string, or as a
3407 pair of angle brackets with nothing between them, as in these examples of shell
3410 exim -f '<>' user@domain
3411 exim -f "" user@domain
3413 In addition, the use of \-f-\ is not restricted when testing a filter file with
3414 \-bf-\ or when testing or verifying addresses using the \-bt-\ or \-bv-\
3417 Allowing untrusted users to change the sender address does not of itself make
3418 it possible to send anonymous mail. Exim still checks that the ::From:: header
3419 refers to the local user, and if it does not, it adds a ::Sender:: header,
3420 though this can be overridden by setting \no@_local@_from@_check\.
3423 White space between \-f-\ and the <<address>> is optional
3424 (that is, they can be given as two arguments or one combined argument).
3425 The sender of a locally-generated message can also be set (when permitted) by
3426 an initial `From ' line in the message -- see the description of \-bm-\ above
3427 -- but if \-f-\ is also present, it overrides `From'.
3430 .index Sendmail compatibility||\-G-\ option ignored
3431 This is a Sendmail option which is ignored by Exim.
3433 .option h #<<number>>
3434 .index Sendmail compatibility||\-h-\ option ignored
3435 This option is accepted for compatibility with Sendmail, but has no effect. (In
3436 Sendmail it overrides the `hop count' obtained by counting ::Received::
3440 .index Solaris||\*mail*\ command
3441 .index dot||in incoming, non-SMTP message
3442 This option, which has the same effect as \-oi-\, specifies that a dot on a
3443 line by itself should not terminate an incoming, non-SMTP message. I can find
3444 no documentation for this option in Solaris 2.4 Sendmail, but the \*mailx*\
3445 command in Solaris 2.4 uses it. See also \-ti-\.
3447 .option M #<<message id>>#<<message id>> ...
3448 .index forcing delivery
3449 .index delivery||forcing attempt
3450 .index frozen messages||forcing delivery
3451 This option requests Exim to run a delivery attempt on each message in turn. If
3452 any of the messages are frozen, they are automatically thawed before the
3453 delivery attempt. The settings of \queue@_domains\, \queue@_smtp@_domains\, and
3454 \hold@_domains\ are ignored.
3455 .index hints database||overriding retry hints
3456 Retry hints for any of the addresses are
3457 overridden -- Exim tries to deliver even if the normal retry time has not yet
3458 been reached. This option requires the caller to be an admin user. However,
3459 there is an option called \prod@_requires@_admin\ which can be set false to
3460 relax this restriction (and also the same requirement for the \-q-\, \-R-\, and
3464 .option Mar #<<message id>>#<<address>>#<<address>> ...
3465 .index message||adding recipients
3466 .index recipient||adding
3467 This option requests Exim to add the addresses to the list of recipients of the
3468 message (`ar' for `add recipients'). The first argument must be a message id,
3469 and the remaining ones must be email addresses. However, if the message is
3470 active (in the middle of a delivery attempt), it is not altered. This option
3471 can be used only by an admin user.
3473 .index SMTP||passed connection
3474 .index SMTP||multiple deliveries
3475 .index multiple SMTP deliveries
3476 .option MC #<<transport>>#<<hostname>>#<<sequence number>>#<<message id>>
3477 This option is not intended for use by external callers. It is used internally
3478 by Exim to invoke another instance of itself to deliver a waiting message using
3479 an existing SMTP connection, which is passed as the standard input. Details are
3480 given in chapter ~~CHAPSMTP. This must be the final option, and the caller must
3481 be root or the Exim user in order to use it.
3484 This option is not intended for use by external callers. It is used internally
3485 by Exim in conjunction with the \-MC-\ option. It signifies that the connection
3486 to the remote host has been authenticated.
3489 This option is not intended for use by external callers. It is used internally
3490 by Exim in conjunction with the \-MC-\ option. It signifies that the server to
3491 which Exim is connected supports pipelining.
3493 .option MCQ #<<process id>> <<pipe fd>>
3494 This option is not intended for use by external callers. It is used internally
3495 by Exim in conjunction with the \-MC-\ option when the original delivery was
3496 started by a queue runner. It passes on the process id of the queue runner,
3497 together with the file descriptor number of an open pipe. Closure of the pipe
3498 signals the final completion of the sequence of processes that are passing
3499 messages through the same SMTP connection.
3502 This option is not intended for use by external callers. It is used internally
3503 by Exim in conjunction with the \-MC-\ option, and passes on the fact that the
3504 SMTP \\SIZE\\ option should be used on messages delivered down the existing
3508 This option is not intended for use by external callers. It is used internally
3509 by Exim in conjunction with the \-MC-\ option, and passes on the fact that the
3510 host to which Exim is connected supports TLS encryption.
3512 .option Mc #<<message id>>#<<message id>> ...
3513 .index hints database||not overridden by \-Mc-\
3514 .index delivery||manually started, not forced
3515 This option requests Exim to run a delivery attempt on each message in turn,
3516 but unlike the \-M-\ option, it does check for retry hints, and respects any
3517 that are found. This option is not very useful to external callers. It is
3518 provided mainly for internal use by Exim when it needs to re-invoke itself in
3519 order to regain root privilege for a delivery (see chapter ~~CHAPsecurity).
3520 However, \-Mc-\ can be useful when testing, in order to run a delivery that
3521 respects retry times and other options such as \hold@_domains\ that are
3522 overridden when \-M-\ is used. Such a delivery does not count as a queue run.
3523 If you want to run a specific delivery as if in a queue run, you should use
3524 \-q-\ with a message id argument. A distinction between queue run deliveries
3525 and other deliveries is made in one or two places.
3527 .option Mes #<<message id>>#<<address>>
3528 .index message||changing sender
3529 .index sender||changing
3530 This option requests Exim to change the sender address in the message to the
3531 given address, which must be a fully qualified address or `<>' (`es' for `edit
3532 sender'). There must be exactly two arguments. The first argument must be a
3533 message id, and the second one an email address. However, if the message is
3534 active (in the middle of a delivery attempt), its status is not altered. This
3535 option can be used only by an admin user.
3537 .option Mf #<<message id>>#<<message id>> ...
3538 .index freezing messages
3539 .index message||manually freezing
3540 This option requests Exim to mark each listed message as `frozen'. This
3541 prevents any delivery attempts taking place until the message is `thawed',
3542 either manually or as a result of the \auto@_thaw\ configuration option.
3543 However, if any of the messages are active (in the middle of a delivery
3544 attempt), their status is not altered. This option can be used only by an admin
3547 .option Mg #<<message id>>#<<message id>> ...
3548 .index giving up on messages
3549 .index message||abandoning delivery attempts
3550 .index delivery||abandoning further attempts
3551 This option requests Exim to give up trying to deliver the listed messages,
3552 including any that are frozen. However, if any of the messages are active,
3553 their status is not altered.
3554 For non-bounce messages, a delivery error message is sent to the sender,
3555 containing the text `cancelled by administrator'. Bounce messages are just
3557 This option can be used only by an admin user.
3559 .option Mmad #<<message id>>#<<message id>> ...
3560 .index delivery||cancelling all
3561 This option requests Exim to mark all the recipient addresses in the messages
3562 as already delivered (`mad' for `mark all delivered'). However, if any message
3563 is active (in the middle of a delivery attempt), its status is not altered.
3564 This option can be used only by an admin user.
3566 .option Mmd #<<message id>>#<<address>>#<<address>> ...
3567 .index delivery||cancelling by address
3568 .index recipient||removing
3569 .index removing recipients
3570 This option requests Exim to mark the given addresses as already delivered
3571 (`md' for `mark delivered'). The first argument must be a message id, and the
3572 remaining ones must be email addresses. These are matched to recipient
3573 addresses in the message in a case-sensitive manner. If the message is active
3574 (in the middle of a delivery attempt), its status is not altered. This option
3575 can be used only by an admin user.
3577 .option Mrm #<<message id>>#<<message id>> ...
3578 .index removing messages
3579 .index abandoning mail
3580 .index message||manually discarding
3581 This option requests Exim to remove the given messages from the queue. No
3582 bounce messages are sent; each message is simply forgotten. However, if any of
3583 the messages are active, their status is not altered. This option can be used
3584 only by an admin user or by the user who originally caused the message to be
3585 placed on the queue.
3587 .option Mt #<<message id>>#<<message id>> ...
3588 .index thawing messages
3589 .index unfreezing messages
3590 .index frozen messages||thawing
3591 .index message||thawing frozen
3592 This option requests Exim to `thaw' any of the listed messages that are
3593 `frozen', so that delivery attempts can resume. However, if any of the messages
3594 are active, their status is not altered. This option can be used only by an
3597 .option Mvb #<<message id>>
3598 .index listing||message body
3599 .index message||listing body of
3600 This option causes the contents of the message body (-D) spool file to be
3601 written to the standard output. This option can be used only by an admin user.
3603 .option Mvh #<<message id>>
3604 .index listing||message headers
3605 .index header lines||listing
3606 .index message||listing header lines
3607 This option causes the contents of the message headers (-H) spool file to be
3608 written to the standard output. This option can be used only by an admin user.
3610 .option Mvl #<<message id>>
3611 .index listing||message log
3612 .index message||listing message log
3613 This option causes the contents of the message log spool file to be written to
3614 the standard output. This option can be used only by an admin user.
3617 This is apparently a synonym for \-om-\ that is accepted by Sendmail, so Exim
3618 treats it that way too.
3621 .index debugging||\-N-\ option
3622 .index debugging||suppressing delivery
3623 This is a debugging option that inhibits delivery of a message at the transport
3624 level. It implies \-v-\. Exim goes through many of the motions of delivery --
3625 it just doesn't actually transport the message, but instead behaves as if it
3626 had successfully done so. However, it does not make any updates to the retry
3627 database, and the log entries for deliveries are flagged with `$*$>' rather
3630 Because \-N-\ discards any message to which it applies, only root or the Exim
3631 user are allowed to use it with \-bd-\, \-q-\, \-R-\ or \-M-\. In other words,
3632 an ordinary user can use it only when supplying an incoming message to which it
3633 will apply. Although transportation never fails when \-N-\ is set, an address
3634 may be deferred because of a configuration problem on a transport, or a routing
3635 problem. Once \-N-\ has been used for a delivery attempt, it sticks to the
3636 message, and applies to any subsequent delivery attempts that may happen for
3640 .index Sendmail compatibility||\-n-\ option ignored
3641 This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by
3645 This option is interpreted by Sendmail to mean `set option`. It is ignored by
3648 .option oA #<<file name>>
3649 .index Sendmail compatibility||\-oA-\ option
3650 This option is used by Sendmail in conjunction with \-bi-\ to specify an
3651 alternative alias file name. Exim handles \-bi-\ differently; see the
3654 .index SMTP||passed connection
3656 .index SMTP||multiple deliveries
3657 .index multiple SMTP deliveries
3658 This is a debugging option which limits the maximum number of messages that can
3659 be delivered down one SMTP connection, overriding the value set in any \%smtp%\
3660 transport. If <<n>> is omitted, the limit is set to 1.
3663 .index background delivery
3664 .index delivery||in the background
3665 This option applies to all modes in which Exim accepts incoming messages,
3666 including the listening daemon. It requests `background' delivery of such
3667 messages, which means that the accepting process automatically starts delivery
3668 process for each message received, but does not wait for the delivery process
3669 to complete. This is the default action if none of the \-od-\ options are
3672 If one of the queueing options in the configuration file
3673 (\queue@_only\ or \queue@_only@_file\, for example) is in effect, \-odb-\
3674 overrides it if \queue@_only@_override\ is set true, which is the default
3675 setting. If \queue@_only@_override\ is set false, \-odb-\ has no effect.
3678 .index foreground delivery
3679 .index delivery||in the foreground
3680 This option requests `foreground' (synchronous) delivery when Exim has accepted
3681 a locally-generated message. (For the daemon it is exactly the same as
3682 \-odb-\.) A delivery process is automatically started to deliver the
3683 message, and Exim waits for it to complete before proceeding.
3684 However, like \-odb-\, this option has no effect if \queue@_only@_override\ is
3685 false and one of the queueing options in the configuration file is in effect.
3688 This option is synonymous with \-odf-\. It is provided for compatibility with
3692 .index non-immediate delivery
3693 .index delivery||suppressing immediate
3694 .index queueing incoming messages
3695 This option applies to all modes in which Exim accepts incoming messages,
3696 including the listening daemon. It specifies that the accepting process should
3697 not automatically start a delivery process for each message received. Messages
3698 are placed on the queue, and remain there until a subsequent queue runner
3699 process encounters them.
3700 There are several configuration options (such as \queue@_only\) that can be
3701 used to queue incoming messages under certain conditions. This option overrides
3702 all of them and also \-odqs-\. It always forces queueing.
3705 .index SMTP||delaying delivery
3706 This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\.
3707 However, like \-odb-\ and \-odi-\, this option has no effect if
3708 \queue@_only@_override\ is false and one of the queueing options in the
3709 configuration file is in effect.
3711 When \-odqs-\ does operate, a delivery process is started for each incoming
3712 message, in the background by default, but in the foreground if \-odi-\ is also
3714 The recipient addresses are routed, and local deliveries are done in the normal
3715 way. However, if any SMTP deliveries are required, they are not done at this
3716 time, so the message remains on the queue until a subsequent queue runner
3717 process encounters it. Because routing was done, Exim knows which messages are
3718 waiting for which hosts, and so a number of messages for the same host can be
3719 sent in a single SMTP connection. The \queue@_smtp@_domains\ configuration
3720 option has the same effect for specific domains. See also the \-qq-\ option.
3723 .index error||reporting
3724 If an error is detected while a non-SMTP message is being received (for
3725 example, a malformed address), the error is reported to the sender in a mail
3727 .index return code||for \-oee-\
3728 Provided this error message is successfully sent, the Exim receiving process
3729 exits with a return code of zero. If not, the return code is 2 if the problem
3730 is that the original message has no recipients, or 1 any other error. This is
3731 the default \-oe$it{x}-\ option if Exim is called as \*rmail*\.
3734 .index error||reporting
3735 .index return code||for \-oem-\
3736 This is the same as \-oee-\, except that Exim always exits with a non-zero
3737 return code, whether or not the error message was successfully sent.
3738 This is the default \-oe$it{x}-\ option, unless Exim is called as \*rmail*\.
3741 .index error||reporting
3742 If an error is detected while a non-SMTP message is being received, the
3743 error is reported by writing a message to the standard error file (stderr).
3744 .index return code||for \-oep-\
3745 The return code is 1 for all errors.
3748 .index error||reporting
3749 This option is supported for compatibility with Sendmail, but has the same
3753 .index error||reporting
3754 This option is supported for compatibility with Sendmail, but has the same
3758 .index dot||in incoming, non-SMTP message
3759 This option, which has the same effect as \-i-\, specifies that a dot on a line
3760 by itself should not terminate an incoming, non-SMTP message.
3762 Otherwise, a single dot does terminate, though Exim does no special processing
3763 for other lines that start with a dot.
3765 This option is set by default if Exim is called as \*rmail*\. See also \-ti-\.
3768 This option is treated as synonymous with \-oi-\.
3770 .option oMa #<<host address>>
3771 .index sender||host address, specifying for local message
3772 A number of options starting with \-oM-\ can be used to set values associated
3773 with remote hosts on locally-submitted messages (that is, messages not received
3774 over TCP/IP). These options can be used by any caller in conjunction with the
3777 \-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they
3778 are ignored unless the caller is trusted.
3780 The \-oMa-\ option sets the sender host address. This may include a port number
3781 at the end, after a full stop (period). For example:
3783 exim -bs -oMa 10.9.8.7.1234
3785 An alternative syntax is to enclose the IP address in square brackets, followed
3786 by a colon and the port number:
3788 exim -bs -oMa [10.9.8.7]:1234
3790 The IP address is placed in the \$sender@_host@_address$\ variable, and the
3791 port, if present, in \$sender@_host@_port$\.
3793 .option oMaa #<<name>>
3794 .index authentication||name, specifying for local message
3795 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMaa-\
3796 option sets the value of \$sender@_host@_authenticated$\ (the authenticator
3797 name). See chapter ~~CHAPSMTPAUTH for a discussion of SMTP authentication.
3799 .option oMai #<<string>>
3800 .index authentication||id, specifying for local message
3801 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\
3803 value of \$authenticated@_id$\ (the id that was authenticated).
3804 This overrides the default value (the caller's login id) for messages from
3805 local sources. See chapter ~~CHAPSMTPAUTH for a discussion of authenticated
3808 .option oMas #<<address>>
3809 .index authentication||sender, specifying for local message
3810 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMas-\
3811 option sets the authenticated sender value
3812 in \$authenticated@_sender$\.
3813 It overrides the sender address that is created from the caller's login id for
3814 messages from local sources. See chapter ~~CHAPSMTPAUTH for a discussion of
3815 authenticated senders.
3817 .option oMi #<<interface address>>
3818 .index interface||address, specifying for local message
3819 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMi-\
3820 option sets the IP interface address value. A port number may be included,
3821 using the same syntax as for \-oMa-\.
3822 The interface address is placed in \$interface@_address$\ and the port number,
3823 if present, in \$interface@_port$\.
3825 .option oMr #<<protocol name>>
3826 .index protocol||incoming, specifying for local message
3827 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMr-\
3828 option sets the received protocol value
3829 in \$received@_protocol$\.
3830 However, this applies only when \-bs-\ is not used. For interactive SMTP input,
3831 the protocol is determined by whether \\EHLO\\ or \\HELO\\ is used, and is
3832 always either `local-esmtp' or `local-smtp'. For \-bS-\ (batch SMTP) however,
3833 the protocol can be set by \-oMr-\.
3835 .option oMs #<<host name>>
3836 .index sender||host name, specifying for local message
3837 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMs-\
3838 option sets the sender host name
3839 in \$sender@_host@_name$\. When this option is present, Exim does not attempt
3840 to look up a host name from an IP address; it uses the name it is given.
3842 .option oMt #<<ident string>>
3843 .index sender||ident string, specifying for local message
3844 See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMt-\
3845 option sets the sender ident value
3846 in \$sender@_ident$\.
3847 The default setting for local callers is the login id of the calling process.
3850 .index Sendmail compatibility||\-om-\ option ignored
3851 In Sendmail, this option means `me too', indicating that the sender of a
3852 message should receive a copy of the message if the sender appears in an alias
3853 expansion. Exim always does this, so the option does nothing.
3856 .index Sendmail compatibility||\-oo-\ option ignored
3857 This option is ignored. In Sendmail it specifies `old style headers', whatever
3860 .option oP #<<path>>
3861 .index pid (process id)||of daemon
3862 .index daemon||process id (pid)
3863 This option is useful only in conjunction with \-bd-\ or \-q-\ with a time
3864 value. The option specifies the file to which the process id of the daemon is
3865 written. When \-oX-\ is used with \-bd-\, or when \-q-\ with a time is used
3866 without \-bd-\, this is the only way of causing Exim to write a pid file,
3867 because in those cases, the normal pid file is not used.
3869 .option or #<<time>>
3870 .index timeout||for non-SMTP input
3871 This option sets a timeout value for incoming non-SMTP messages. If it is not
3872 set, Exim will wait forever for the standard input. The value can also be set
3873 by the \receive@_timeout\ option. The format used for specifying times is
3874 described in section ~~SECTtimeformat.
3876 .option os #<<time>>
3877 .index timeout||for SMTP input
3878 .index SMTP||timeout, input
3879 This option sets a timeout value for incoming SMTP messages. The timeout
3880 applies to each SMTP command and block of data. The value can also be set by
3881 the \smtp@_receive@_timeout\ option; it defaults to 5 minutes. The format used
3882 for specifying times is described in section ~~SECTtimeformat.
3885 This option has exactly the same effect as \-v-\.
3887 .option oX #<<number or string>>
3888 .index TCP/IP||setting listening ports
3889 .index TCP/IP||setting listening interfaces
3890 .index port||receiving TCP/IP
3891 This option is relevant only when the \-bd-\ (start listening daemon) option is
3892 also given. It controls which ports and interfaces the daemon uses. Details of
3893 the syntax, and how it interacts with configuration file options, are given in
3894 chapter ~~CHAPinterfaces. When \-oX-\ is used to start a daemon, no pid file is
3895 written unless \-oP-\ is also present to specify a pid file name.
3898 .index Perl||starting the interpreter
3899 This option applies when an embedded Perl interpreter is linked with Exim (see
3900 chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option,
3901 forcing the starting of the interpreter to be delayed until it is needed.
3904 .index Perl||starting the interpreter
3905 This option applies when an embedded Perl interpreter is linked with Exim (see
3906 chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option,
3907 forcing the starting of the interpreter to occur as soon as Exim is started.
3910 .option p<<rval>>:<<sval>>
3911 For compatibility with Sendmail, this option
3914 -oMr <<rval>> -oMs <<sval>>
3916 It sets the incoming protocol and host name (for trusted callers). The
3917 host name and its colon can be omitted when only the protocol is to be set.
3918 Note the Exim already has two private options, \-pd-\ and \-ps-\, that refer to
3919 embedded Perl. It is therefore impossible to set a protocol value of \"p"\ or
3920 \"s"\ using this option (but that does not seem a real limitation).
3924 .index queue runner||starting manually
3925 This option is normally restricted to admin users. However, there is a
3926 configuration option called \prod@_requires@_admin\ which can be set false to
3927 relax this restriction (and also the same requirement for the \-M-\, \-R-\, and
3930 .index queue runner||description of operation
3931 The \-q-\ option starts one queue runner process. This scans the queue of
3932 waiting messages, and runs a delivery process for each one in turn. It waits
3933 for each delivery process to finish before starting the next one. A delivery
3934 process may not actually do any deliveries if the retry times for the addresses
3935 have not been reached. Use \-qf-\ (see below) if you want to override this.
3936 .index SMTP||passed connection
3937 .index SMTP||multiple deliveries
3938 .index multiple SMTP deliveries
3939 If the delivery process spawns other processes to deliver other messages down
3940 passed SMTP connections, the queue runner waits for these to finish before
3943 When all the queued messages have been considered, the original queue runner
3944 process terminates. In other words, a single pass is made over the waiting
3945 mail, one message at a time. Use \-q-\ with a time (see below) if you want this
3946 to be repeated periodically.
3948 Exim processes the waiting messages in an unpredictable order. It isn't very
3949 random, but it is likely to be different each time, which is all that matters.
3950 If one particular message screws up a remote MTA, other messages to the same
3951 MTA have a chance of getting through if they get tried first.
3953 It is possible to cause the messages to be processed in lexical message id
3954 order, which is essentially the order in which they arrived, by setting the
3955 \queue@_run@_in@_order\ option, but this is not recommended for normal use.
3957 .option q <<qflags>>
3958 The \-q-\ option may be followed by one or more flag letters that change its
3959 behaviour. They are all optional, but if more than one is present, they must
3960 appear in the correct order. Each flag is described in a separate item below.
3963 .index queue||double scanning
3964 .index queue||routing
3965 .index routing||whole queue before delivery
3966 An option starting with \-qq-\ requests a two-stage queue run. In the first
3967 stage, the queue is scanned as if the \queue@_smtp@_domains\ option matched
3968 every domain. Addresses are routed, local deliveries happen, but no remote
3970 .index hints database||remembering routing
3971 The hints database that remembers which messages are
3972 waiting for specific hosts is updated, as if delivery to those hosts had been
3973 deferred. After this is complete, a second, normal queue scan happens, with
3974 routing and delivery taking place as normal. Messages that are routed to the
3975 same host should mostly be delivered down a single SMTP
3976 .index SMTP||passed connection
3977 .index SMTP||multiple deliveries
3978 .index multiple SMTP deliveries
3979 connection because of the hints that were set up during the first queue scan.
3980 This option may be useful for hosts that are connected to the Internet
3984 .index queue||initial delivery
3985 If the \*i*\ flag is present, the queue runner runs delivery processes only for
3986 those messages that haven't previously been tried. (\*i*\ stands for `initial
3987 delivery'.) This can be helpful if you are putting messages on the queue using
3988 \-odq-\ and want a queue runner just to process the new messages.
3991 .index queue||forcing delivery
3992 .index delivery||forcing in queue run
3993 If one \*f*\ flag is present, a delivery attempt is forced for each non-frozen
3994 message, whereas without \f\ only those non-frozen addresses that have passed
3995 their retry times are tried.
3997 .option q[q][i]ff...
3998 .index frozen messages||forcing delivery
3999 If \*ff*\ is present, a delivery attempt is forced for every message, whether
4002 .option q[q][i][f[f]]l
4003 .index queue||local deliveries only
4004 The \*l*\ (the letter `ell') flag specifies that only local deliveries are to be
4005 done. If a message requires any remote deliveries, it remains on the queue for
4008 .option q <<qflags>>#<<start id>>#<<end id>>
4009 .index queue||delivering specific messages
4010 When scanning the queue, Exim can be made to skip over messages whose ids are
4011 lexically less than a given value by following the \-q-\ option with a starting
4012 message id. For example:
4014 exim -q 0t5C6f-0000c8-00
4016 Messages that arrived earlier than \"0t5C6f-0000c8-00"\ are not inspected. If a
4017 second message id is given, messages whose ids are lexically greater than it
4018 are also skipped. If the same id is given twice, for example,
4020 exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
4022 just one delivery process is started, for that message. This differs from \-M-\
4023 in that retry data is respected, and it also differs from \-Mc-\ in that it
4024 counts as a delivery from a queue run. Note that the selection mechanism does
4025 not affect the order in which the messages are scanned. There are also other
4026 ways of selecting specific sets of messages for delivery in a queue run -- see
4029 .option q <<qflags>><<time>>
4030 .index queue runner||starting periodically
4031 .index periodic queue running
4032 When a time value is present, the \-q-\ option causes Exim to run as a daemon,
4033 starting a queue runner process at intervals specified by the given time value
4034 (whose format is described in section ~~SECTtimeformat). This form of the \-q-\
4035 option is commonly combined with the \-bd-\ option, in which case a single
4036 daemon process handles both functions. A common way of starting up a combined
4037 daemon at system boot time is to use a command such as
4039 /usr/exim/bin/exim -bd -q30m
4041 Such a daemon listens for incoming SMTP calls, and also starts a queue runner
4042 process every 30 minutes.
4044 When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid
4045 file is written unless one is explicitly requested by the \-oP-\ option.
4047 .option qR <<rsflags>>#<<string>>
4048 This option is synonymous with \-R-\. It is provided for Sendmail
4051 .option qS <<rsflags>>#<<string>>
4052 This option is synonymous with \-S-\.
4054 .option R <<rsflags>>#<<string>>
4055 .index queue runner||for specific recipients
4056 .index delivery||to given domain
4057 .index domain||delivery to
4058 The <<rsflags>> may be empty, in which case the white space before the string
4059 is optional, unless the string is \*f*\, \*ff*\, \*r*\, \*rf*\, or \*rff*\,
4060 which are the possible values for <<rsflags>>. White space is required if
4061 <<rsflags>> is not empty.
4063 This option is similar to \-q-\ with no time value, that is, it causes Exim to
4064 perform a single queue run, except that, when scanning the messages on the
4065 queue, Exim processes only those that have at least one undelivered recipient
4066 address containing the given string, which is checked in a case-independent
4067 way. If the <<rsflags>> start with \*r*\, <<string>> is interpreted as a regular
4068 expression; otherwise it is a literal string.
4070 Once a message is selected, all its addresses are processed. For the first
4071 selected message, Exim overrides any retry information and forces a delivery
4072 attempt for each undelivered address. This means that if delivery of any
4073 address in the first message is successful, any existing retry information is
4074 deleted, and so delivery attempts for that address in subsequently selected
4075 messages (which are processed without forcing) will run. However, if delivery
4076 of any address does not succeed, the retry information is updated, and in
4077 subsequently selected messages, the failing address will be skipped.
4079 If the <<rsflags>> contain \*f*\ or \*ff*\, the delivery forcing applies to all
4080 selected messages, not just the first;
4081 .index frozen messages||forcing delivery
4082 frozen messages are included when \*ff*\ is present.
4084 The \-R-\ option makes it straightforward to initiate delivery of all messages
4085 to a given domain after a host has been down for some time. When the SMTP
4086 command \\ETRN\\ is accepted by its ACL (see chapter ~~CHAPACL), its default
4087 effect is to run Exim with the \-R-\ option, but it can be configured to run an
4088 arbitrary command instead.
4091 This is a documented (for Sendmail) obsolete alternative name for \-f-\.
4093 .index delivery||from given sender
4094 .option S <<rsflags>>#<<string>>
4095 .index queue runner||for specific senders
4096 This option acts like \-R-\ except that it checks the string against each
4097 message's sender instead of against the recipients. If \-R-\ is also set, both
4098 conditions must be met for a message to be selected. If either of the options
4099 has \*f*\ or \*ff*\ in its flags, the associated action is taken.
4102 .option Tqt#<<times>>
4103 This an option that is exclusively for use by the Exim testing suite.
4104 It is not recognized when Exim is run normally. It allows for the setting up
4105 of explicit `queue times' so that various warning/retry features can be
4110 .index recipient||extracting from header lines
4111 .index ::Bcc:: header line
4112 .index ::Cc:: header line
4113 .index ::To:: header line
4114 When Exim is receiving a locally-generated, non-SMTP message on its standard
4115 input, the \-t-\ option causes the recipients of the message to be obtained
4116 from the ::To::, ::Cc::, and ::Bcc:: header lines in the message instead of from
4117 the command arguments. The addresses are extracted before any rewriting takes
4120 .index Sendmail compatibility||\-t-\ option
4121 If the command has any arguments, they specify addresses to which the message
4122 is $it{not} to be delivered. That is, the argument addresses are removed from
4123 the recipients list obtained from the headers. This is compatible with Smail 3
4124 and in accordance with the documented behaviour of several versions of
4125 Sendmail, as described in man pages on a number of operating systems (e.g.
4126 Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail $it{add}
4127 argument addresses to those obtained from the headers, and the O'Reilly
4128 Sendmail book documents it that way. Exim can be made to add argument addresses
4129 instead of subtracting them by setting the option
4130 \extract__addresses__remove__arguments\ false.
4132 If a ::Bcc:: header line is present, it is removed from the message unless
4133 there is no ::To:: or ::Cc::, in which case a ::Bcc:: line with no data is
4134 created. This is necessary for conformity with the original RFC 822 standard;
4135 the requirement has been removed in RFC 2822, but that is still very new.
4137 .index \Resent@-\ header lines||with \-t-\
4138 If there are any \Resent@-\ header lines in the message, Exim extracts
4139 recipients from all ::Resent-To::, ::Resent-Cc::, and ::Resent-Bcc:: header
4140 lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility
4141 with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
4142 \-t-\ was used in conjunction with \Resent@-\ header lines.)
4144 RFC 2822 talks about different sets of \Resent@-\ header lines (for when a
4145 message is resent several times). The RFC also specifies that they should be
4146 added at the front of the message, and separated by ::Received:: lines. It is
4147 not at all clear how \-t-\ should operate in the present of multiple sets,
4148 nor indeed exactly what constitutes a `set'.
4149 In practice, it seems that MUAs do not follow the RFC. The \Resent@-\ lines are
4150 often added at the end of the header, and if a message is resent more than
4151 once, it is common for the original set of \Resent@-\ headers to be renamed as
4152 \X-Resent@-\ when a new set is added. This removes any possible ambiguity.
4155 This option is exactly equivalent to \-t-\ \-i-\. It is provided for
4156 compatibility with Sendmail.
4158 .option tls-on-connect
4159 .index TLS||use without STARTTLS
4160 .index TLS||automatic start
4161 This option is available when Exim is compiled with TLS support. It makes it
4162 possible to support legacy clients that do not support the \\STARTTLS\\
4163 command, but instead expect to start up a TLS session as soon as a connection
4164 to the server is established. These clients use a special port (usually called
4165 the `ssmtp' port) instead of the normal SMTP port 25. The \-tls-on-connect-\
4166 option can be used to run Exim in this way from \*inetd*\, and it can also be
4167 used to run a special daemon that operates in this manner (use \-oX-\ to
4168 specify the port). However, although it is possible to run one daemon that
4169 listens on several ports, it is not possible to have some of them operate one
4170 way and some the other. With only a few clients that need the legacy support, a
4171 convenient approach is to use a daemon for normal SMTP (with or without
4172 \\STARTTLS\\) and \*inetd*\ with \-tls-on-connect-\ for the legacy clients.
4175 .index Sendmail compatibility||\-U-\ option ignored
4176 Sendmail uses this option for `initial message submission', and its
4177 documentation states that in future releases, it may complain about
4178 syntactically invalid messages rather than fixing them when this flag is not
4179 set. Exim ignores this option.
4182 This option causes Exim to write information to the standard error stream,
4183 describing what it is doing. In particular, it shows the log lines for
4184 receiving and delivering a message, and if an SMTP connection is made, the SMTP
4185 dialogue is shown. Some of the log lines shown may not actually be written to
4186 the log if the setting of \log@_selector\ discards them. Any relevant selectors
4187 are shown with each log line. If none are shown, the logging is unconditional.
4190 AIX uses \-x-\ for a private purpose (`mail from a local mail program has
4191 National Language Support extended characters in the body of the mail item').
4192 It sets \-x-\ when calling the MTA from its \mail\ command. Exim ignores this
4203 . ============================================================================
4204 .chapter The Exim run time configuration file
4205 .set runningfoot "configuration file"
4206 .rset CHAPconf ~~chapter
4208 .index run time configuration
4209 .index configuration file||general description
4210 .index \\CONFIGURE@_FILE\\
4211 Exim uses a single run time configuration file that is read whenever an Exim
4212 binary is executed. Note that in normal operation, this happens frequently,
4213 because Exim is designed to operate in a distributed manner, without central
4216 The name of the configuration file is compiled into the binary for security
4217 reasons, and is specified by the \\CONFIGURE@_FILE\\ compilation option. In
4218 most configurations, this specifies a single file. However, it is permitted to
4219 give a colon-separated list of file names, in which case Exim uses the first
4220 existing file in the list.
4222 .index \\EXIM@_USER\\
4223 .index \\EXIM@_GROUP\\
4224 .index configuration file||ownership
4225 .index ownership||configuration file
4226 The run time configuration file must be owned by root or by the user that
4227 is specified at compile time by the \\EXIM@_USER\\ option,
4229 or by the user that is specified at compile time by the \\CONFIGURE@_OWNER\\
4232 The configuration file must not be world-writeable or group-writeable, unless
4233 its group is the one specified at compile time by the \\EXIM@_GROUP\\ option.
4235 \**Warning**\: In a conventional configuration, where the Exim binary is setuid
4236 to root, anybody who is able to edit the run time configuration file has an
4237 easy way to run commands as root. If you make your mail administrators members
4238 of the Exim group, but do not trust them with root, make sure that the run time
4239 configuration is not group writeable.
4242 A default configuration file, which will work correctly in simple situations,
4243 is provided in the file \(src/configure.default)\.
4244 If \\CONFIGURE@_FILE\\ defines just one file name, the installation process
4245 copies the default configuration to a new file of that name if it did not
4246 previously exist. If \\CONFIGURE@_FILE\\ is a list, no default is automatically
4247 installed. Chapter ~~CHAPdefconfil is a `walk-through' discussion of the
4248 default configuration.
4250 .index configuration file||errors in
4251 .index error||in configuration file
4252 .index return code||for bad configuration
4253 If a syntax error is detected while reading the configuration file, Exim
4254 writes a message on the standard error, and exits with a non-zero return code.
4255 The message is also written to the panic log.
4258 .section Using a different configuration file
4259 .index configuration file||alternate
4260 A one-off alternate configuration can be specified by the \-C-\ command line
4261 option, which may specify a single file or a list of files. However, when \-C-\
4262 is used, Exim gives up its root privilege, unless called by root or the Exim
4263 user (or unless the argument for \-C-\ is identical to the built-in value from
4264 \\CONFIGURE@_FILE\\). \-C-\ is useful mainly for checking the syntax of
4265 configuration files before installing them. No owner or group checks are done
4266 on a configuration file specified by \-C-\.
4268 The privileged use of \-C-\ by the Exim user can be locked out by setting
4269 \\ALT@_CONFIG@_ROOT@_ONLY\\ in \(Local/Makefile)\ when building Exim. However,
4270 if you do this, you also lock out the possibility of testing a
4271 configuration using \-C-\ right through message reception and delivery, even if
4272 the caller is root. The reception works, but by that time, Exim is running as
4273 the Exim user, so when it re-execs to regain privilege for the delivery, the
4274 use of \-C-\ causes privilege to be lost. However, root can test reception and
4275 delivery using two separate commands (one to put a message on the queue, using
4276 \-odq-\, and another to do the delivery, using \-M-\).
4278 If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a
4279 prefix string with which any file named in a \-C-\ command line option must
4280 start. In addition, the file name must not contain the sequence \"/../"\. There
4281 is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is unset, any file
4282 name can be used with \-C-\.
4284 One-off changes to a configuration can be specified by the \-D-\ command line
4285 option, which defines and overrides values for macros used inside the
4286 configuration file. However, like \-C-\, the use of this option by a
4287 non-privileged user causes Exim to discard its root privilege.
4288 If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is
4289 completely disabled, and its use causes an immediate error exit.
4291 Some sites may wish to use the same Exim binary on different machines that
4292 share a file system, but to use different configuration files on each machine.
4293 If \\CONFIGURE@_FILE@_USE@_NODE\\ is defined in \(Local/Makefile)\, Exim first
4294 looks for a file whose name is the configuration file name followed by a dot
4295 and the machine's node name, as obtained from the \*uname()*\ function. If this
4296 file does not exist, the standard name is tried. This processing occurs for
4297 each file name in the list given by \\CONFIGURE@_FILE\\ or \-C-\.
4299 In some esoteric situations different versions of Exim may be run under
4300 different effective uids and the \\CONFIGURE@_FILE@_USE@_EUID\\ is defined to
4301 help with this. See the comments in \(src/EDITME)\ for details.
4304 .section Configuration file format
4305 .rset SECTconffilfor "~~chapter.~~section"
4306 .index configuration file||format of
4307 .index format||configuration file
4308 Exim's configuration file is divided into a number of different parts. General
4309 option settings must always appear at the start of the file. The other parts
4310 are all optional, and may appear in any order. Each part other than the first
4311 is introduced by the word `begin' followed by the name of the part. The
4315 \*ACL*\: Access control lists for controlling incoming SMTP mail.
4317 .index \\AUTH\\||configuration
4318 \*authenticators*\: Configuration settings for the authenticator drivers. These
4319 are concerned with the SMTP \\AUTH\\ command (see chapter ~~CHAPSMTPAUTH).
4321 \*routers*\: Configuration settings for the router drivers. Routers process
4322 addresses and determine how the message is to be delivered.
4324 \*transports*\: Configuration settings for the transport drivers. Transports
4325 define mechanisms for copying messages to destinations.
4327 \*retry*\: Retry rules, for use when a message cannot be immediately delivered.
4329 \*rewrite*\: Global address rewriting rules, for use when a message arrives and
4330 when new addresses are generated during delivery.
4332 \*local@_scan*\: Private options for the \*local@_scan()*\ function. If you
4333 want to use this feature, you must set
4335 LOCAL_SCAN_HAS_OPTIONS=yes
4337 in \(Local/Makefile)\ before building Exim. Full details of the
4338 \*local@_scan()*\ facility are given in chapter ~~CHAPlocalscan.
4340 Blank lines in the file, and lines starting with a @# character (ignoring
4341 leading white space) are treated as comments and are ignored. \**Note**\: a
4342 @# character other than at the beginning of a line is not treated specially,
4343 and does not introduce a comment.
4345 Any non-comment line can be continued by ending it with a backslash. Trailing
4346 white space after the backslash is ignored, and leading white space at the
4347 start of continuation lines is also ignored.
4348 Comment lines beginning with @# (but not empty lines) may appear in the middle
4349 of a sequence of continuation lines.
4351 A convenient way to create a configuration file is to start from the
4352 default, which is supplied in \(src/configure.default)\, and add, delete, or
4353 change settings as required.
4355 The ACLs, retry rules, and rewriting rules have their own syntax which is
4356 described in chapters ~~CHAPACL, ~~CHAPretry, and ~~CHAPrewrite, respectively.
4357 The other parts of the configuration file have some syntactic items in common,
4358 and these are described below, from section ~~SECTcos onwards. Before that, the
4359 inclusion, macro, and conditional facilities are described.
4362 .section File inclusions in the configuration file
4363 .index inclusions in configuration file
4364 .index configuration file||including other files
4365 .index .include in configuration file
4366 .index .include@_if@_exists in configuration file
4367 You can include other files inside Exim's run time configuration file by
4370 @.include <<file name>>
4374 @.include@_if@_exists <<file name>>
4376 on a line by itself. Double quotes round the file name are optional. If you use
4377 the first form, a configuration error occurs if the file does not exist; the
4378 second form does nothing for non-existent files.
4380 Includes may be nested to any depth, but remember that Exim reads its
4381 configuration file often, so it is a good idea to keep them to a minimum.
4382 If you change the contents of an included file, you must HUP the daemon,
4383 because an included file is read only when the configuration itself is read.
4385 The processing of inclusions happens early, at a physical line level, so, like
4386 comment lines, an inclusion can be used in the middle of an option setting,
4389 hosts_lookup = a.b.c \
4392 Include processing happens
4394 macro processing (see below). Its effect is to process the lines of the file as
4395 if they occurred inline where the inclusion appears.
4398 .section Macros in the configuration file
4399 .rset SECTmacrodefs "~~chapter.~~section"
4400 .index macro||description of
4401 .index configuration file||macros
4402 If a line in the main part of the configuration (that is, before the first
4403 `begin' line) begins with an upper case letter, it is taken as a macro
4404 definition, and must be of the form
4406 <<name>> = <<rest of line>>
4408 The name must consist of letters, digits, and underscores, and need not all be
4409 in upper case, though that is recommended. The rest of the line, including any
4410 continuations, is the replacement text, and has leading and trailing white
4411 space removed. Quotes are not removed. The replacement text can never end with
4412 a backslash character, but this doesn't seem to be a serious limitation.
4414 Once a macro is defined, all subsequent lines in the file (and any included
4415 files) are scanned for the macro name; if there are several macros, the line is
4416 scanned for each in turn, in the order in which they are defined. The
4417 replacement text is not re-scanned for the current macro, though it is scanned
4418 for subsequently defined macros. For this reason, a macro name may not contain
4419 the name of a previously defined macro as a substring. You could, for example,
4422 ABCD_XYZ = <<something>>
4423 ABCD = <<something else>>
4425 but putting the definitions in the opposite order would provoke a configuration
4428 Macro expansion is applied to individual lines from the file, before checking
4429 for line continuation or file inclusion (see below). If a line consists solely
4430 of a macro name, and the expansion of the macro is empty, the line is ignored.
4431 A macro at the start of a line may turn the line into a comment line or a
4434 As an example of macro usage, consider a configuration where aliases are looked
4435 up in a MySQL database. It helps to keep the file less cluttered if long
4436 strings such as SQL statements are defined separately as macros, for example:
4438 ALIAS_QUERY = select mailbox from user where \
4439 login=${quote_mysql:$local_part};
4441 This can then be used in a \%redirect%\ router setting like this:
4443 data = ${lookup mysql{ALIAS_QUERY}}
4445 In earlier versions of Exim macros were sometimes used for domain, host, or
4446 address lists. In Exim 4 these are handled better by named lists -- see section
4449 Macros in the configuration file can be overridden by the \-D-\ command line
4450 option, but Exim gives up its root privilege when \-D-\ is used, unless called
4451 by root or the Exim user.
4454 .section Conditional skips in the configuration file
4455 .index configuration file||conditional skips
4457 You can use the directives \".ifdef"\, \".ifndef"\, \".elifdef"\,
4458 \".elifndef"\, \".else"\, and \".endif"\ to dynamically include or exclude
4459 portions of the configuration file. The processing happens whenever the file is
4460 read (that is, when an Exim binary starts to run).
4462 The implementation is very simple. Instances of the first four directives must
4463 be followed by text that includes the names of one or macros. The condition
4464 that is tested is whether or not any macro substitution has taken place in the
4468 message@_size@_limit = 50M
4470 message@_size@_limit = 100M
4473 sets a message size limit of 50M if the macro \"AAA"\ is defined, and 100M
4474 otherwise. If there is more than one macro named on the line, the condition
4475 is true if any of them are defined. That is, it is an `or' condition. To
4476 obtain an `and' condition, you need to use nested \".ifdef"\s.
4478 Although you can use a macro expansion to generate one of these directives,
4479 it is not very useful, because the condition `there was a macro substitution
4480 in this line' will always be true.
4482 Text following \".else"\ and \".endif"\ is ignored, and can be used as comment
4483 to clarify complicated nestings.
4486 .section Common option syntax
4487 .rset SECTcos "~~chapter.~~section"
4488 .index common option syntax
4489 .index syntax of common options
4490 .index configuration file||common option syntax
4491 For the main set of options, driver options, and \*local@_scan()*\ options,
4492 each setting is on a line by itself, and starts with a name consisting of
4493 lower-case letters and underscores. Many options require a data value, and in
4494 these cases the name must be followed by an equals sign (with optional white
4495 space) and then the value. For example:
4497 qualify_domain = mydomain.example.com
4499 Some option settings may contain sensitive data, for example, passwords for
4500 accessing databases. To stop non-admin users from using the \-bP-\ command line
4501 option to read these values, you can precede the option settings with the word
4502 `hide'. For example:
4504 hide mysql_servers = localhost/users/admin/secret-password
4506 For non-admin users, such options are displayed like this:
4508 mysql_servers = <value not displayable>
4510 If `hide' is used on a driver option, it hides the value of that option on all
4511 instances of the same driver.
4513 The following sections describe the syntax used for the different data types
4514 that are found in option settings.
4516 .section Boolean options
4517 .index format||boolean
4518 .index boolean configuration values
4519 Options whose type is given as boolean are on/off switches. There are two
4520 different ways of specifying such options: with and without a data value. If
4521 the option name is specified on its own without data, the switch is turned on;
4522 if it is preceded by `no@_' or `not@_' the switch is turned off. However,
4523 boolean options may optionally be followed by an equals sign and one of the
4524 words `true', `false', `yes', or `no', as an alternative syntax. For example,
4525 the following two settings have exactly the same effect:
4530 The following two lines also have the same (opposite) effect:
4535 You can use whichever syntax you prefer.
4539 .section Integer values
4540 .index integer configuration values
4541 .index format||integer
4542 If an integer data item starts with the characters `0x', the remainder of it
4543 is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it
4544 starts with the digit 0, and decimal if not. If an integer value is followed by
4545 the letter K, it is multiplied by 1024; if it is followed by the letter M, it
4546 is multiplied by 1024x1024.
4548 When the values of integer option settings are output, values which are an
4549 exact multiple of 1024 or 1024x1024 are
4550 sometimes, but not always,
4551 printed using the letters K and M. The printing style is independent of the
4552 actual input format that was used.
4554 .section Octal integer values
4555 .index integer format
4556 .index format||octal integer
4557 The value of an option specified as an octal integer is always interpreted in
4558 octal, whether or not it starts with the digit zero. Such options are always
4562 .section Fixed point number values
4563 .index fixed point configuration values
4564 .index format||fixed point
4565 A fixed point number consists of a decimal integer, optionally followed by a
4566 decimal point and up to three further digits.
4569 .section Time interval values
4570 .index time interval||specifying in configuration
4571 .index format||time interval
4572 .rset SECTtimeformat "~~chapter.~~section"
4573 A time interval is specified as a sequence of numbers, each followed by one of
4574 the following letters, with no intervening white space:
4583 For example, `3h50m' specifies 3 hours and 50 minutes. The values of time
4584 intervals are output in the same format.
4585 Exim does not restrict the values; it is perfectly acceptable, for example, to
4586 specify `90m' instead of `1h30m'.
4589 .section String values
4590 .index string||format of configuration values
4591 .index format||string
4592 .rset SECTstrings "~~chapter.~~section"
4593 If a string data item does not start with a double-quote character, it is taken
4594 as consisting of the remainder of the line plus any continuation lines,
4595 starting at the first character after any leading white space, with trailing
4596 white space characters removed, and with no interpretation of the characters in
4597 the string. Because Exim removes comment lines (those beginning with @#) at an
4598 early stage, they can appear in the middle of a multi-line string. The
4599 following settings are therefore equivalent:
4601 trusted_users = uucp:mail
4603 trusted_users = uucp:\
4604 # This comment line is ignored
4607 .index string||quoted
4608 .index escape characters in quoted strings
4609 If a string does start with a double-quote, it must end with a closing
4610 double-quote, and any backslash characters other than those used for line
4611 continuation are interpreted as escape characters, as follows:
4614 @\@\ $t $rm{single backslash}
4616 @\r $t $rm{carriage return}
4618 @\<<octal digits>> $t $rm{up to 3 octal digits specify one character}
4619 @\x<<hex digits>> $t $rm{up to 2 hexadecimal digits specify one character}
4621 If a backslash is followed by some other character, including a double-quote
4622 character, that character replaces the pair.
4624 Quoting is necessary only if you want to make use of the backslash escapes to
4625 insert special characters, or if you need to specify a value with leading or
4626 trailing spaces. These cases are rare, so quoting is almost never needed in
4627 current versions of Exim. In versions of Exim before 3.14, quoting was required
4628 in order to continue lines, so you may come across older configuration files
4629 and examples that apparently quote unnecessarily.
4631 .section Expanded strings
4632 .index string||expansion, definition of
4633 .index expansion||definition of
4634 Some strings in the configuration file are subjected to \*string expansion*\,
4635 by which means various parts of the string may be changed according to the
4636 circumstances (see chapter ~~CHAPexpand). The input syntax for such strings is
4637 as just described; in particular, the handling of backslashes in quoted strings
4638 is done as part of the input process, before expansion takes place. However,
4639 backslash is also an escape character for the expander, so any backslashes that
4640 are required for that reason must be doubled if they are within a quoted
4641 configuration string.
4643 .section User and group names
4644 .index user name||format of
4645 .index format||user name
4646 .index group||name format
4647 .index format||group name
4648 User and group names are specified as strings, using the syntax described
4649 above, but the strings are interpreted specially. A user or group name must
4650 either consist entirely of digits, or be a name that can be looked up using the
4651 \*getpwnam()*\ or \*getgrnam()*\ function, as appropriate.
4653 .section List construction
4654 .index list||syntax of in configuration
4655 .index format||list item in configuration
4656 .index string list, definition
4657 .rset SECTlistconstruct "~~chapter.~~section"
4658 The data for some configuration options is a colon-separated list of items.
4659 Many of these options are shown with type `string list' in the descriptions
4660 later in this document. Others are listed as `domain list', `host list',
4661 `address list', or `local part list'. Syntactically, they are all the same;
4662 however, those other than `string list' are subject to particular kinds of
4663 interpretation, as described in chapter ~~CHAPdomhosaddlists.
4665 In all these cases, the entire list is treated as a single string as far as the
4666 input syntax is concerned. The \trusted@_users\ setting in section
4667 ~~SECTstrings above is an example. If a colon is actually needed in an item in
4668 a list, it must be entered as two colons. Leading and trailing white space on
4669 each item in a list is ignored. This makes it possible to include items that
4670 start with a colon, and in particular, certain forms of IPv6 address. For
4673 local_interfaces = 127.0.0.1 : ::::1
4675 contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address
4676 @:@:1. IPv6 addresses are going to become more and more common as the new
4677 protocol gets more widely deployed.
4678 .index list||separator, changing
4679 .index IPv6||addresses in lists
4680 Doubling their colons is an unwelcome chore, so a mechanism was introduced to
4681 allow the separator character to be changed. If a list begins with a left angle
4682 bracket, followed by any punctuation character, that character is used instead
4683 of colon as the list separator. For example, the list above can be rewritten to
4684 use a semicolon separator like this:
4686 local_interfaces = <; 127.0.0.1 ; ::1
4688 This facility applies to all lists, with the exception of the list in
4689 \log@_file@_path\. It is recommended that the use of non-colon separators be
4690 confined to circumstances where they really are needed.
4693 .section Format of driver configurations
4694 .rset SECTfordricon "~~chapter.~~section"
4695 .index drivers||configuration format
4696 There are separate parts in the configuration for defining routers, transports,
4697 and authenticators. In each part, you are defining a number of driver
4698 instances, each with its own set of options. Each driver instance is defined by
4699 a sequence of lines like this:
4706 In the following example, the instance name is \%localuser%\, and it is
4707 followed by three options settings:
4712 transport = local_delivery
4714 For each driver instance, you specify which Exim code module it uses -- by the
4715 setting of the \driver\ option -- and (optionally) some configuration settings.
4716 For example, in the case of transports, if you want a transport to deliver with
4717 SMTP you would use the \%smtp%\ driver; if you want to deliver to a local file
4718 you would use the \%appendfile%\ driver. Each of the drivers is described in
4719 detail in its own separate chapter later in this manual.
4721 You can have several routers, transports, or authenticators that are based on
4722 the same underlying driver (each must have a different name).
4724 The order in which routers are defined is important, because addresses are
4725 passed to individual routers one by one, in order. The order in which
4726 transports are defined does not matter at all. The order in which
4727 authenticators are defined is used only when Exim, as a client, is searching
4728 them to find one that matches an authentication mechanism offered by the
4731 .index generic options
4732 .index options||generic, definition of
4733 Within a driver instance definition, there are two kinds of option:
4734 $it{generic} and $it{private}. The generic options are those that apply to all
4735 drivers of the same type (that is, all routers, all transports or all
4737 The \driver\ option is a generic option that must appear in every definition.
4738 .index private options
4739 The private options are special for each driver, and none need appear, because
4740 they all have default values.
4742 The options may appear in any order, except that the \driver\ option must
4743 precede any private options, since these depend on the particular driver. For
4744 this reason, it is recommended that \driver\ always be the first option.
4746 Driver instance names, which are used for reference in log entries and
4747 elsewhere, can be any sequence of letters, digits, and underscores (starting
4748 with a letter) and must be unique among drivers of the same type. A router and
4749 a transport (for example) can each have the same name, but no two router
4750 instances can have the same name. The name of a driver instance should not be
4751 confused with the name of the underlying driver module. For example, the
4752 configuration lines:
4757 create an instance of the \%smtp%\ transport driver whose name is
4758 \%remote@_smtp%\. The same driver code can be used more than once, with
4759 different instance names and different option settings each time. A second
4760 instance of the \%smtp%\ transport, with different options, might be defined
4766 command_timeout = 10s
4768 The names \%remote@_smtp%\ and \%special@_smtp%\ would be used to reference
4769 these transport instances from routers, and these names would appear in log
4772 Comment lines may be present in the middle of driver specifications. The full
4773 list of option settings for any particular driver instance, including all the
4774 defaulted values, can be extracted by making use of the \-bP-\ command line
4786 . ============================================================================
4787 .chapter The default configuration file
4788 .set runningfoot "default configuration"
4789 .rset CHAPdefconfil "~~chapter"
4790 .index configuration file||default, `walk through'
4791 .index default||configuration file `walk through'
4792 The default configuration file supplied with Exim as \(src/configure.default)\
4793 is sufficient for a host with simple mail requirements. As an introduction to
4794 the way Exim is configured, this chapter `walks through' the default
4795 configuration, giving brief explanations of the settings. Detailed descriptions
4796 of the options are given in subsequent chapters. The default configuration file
4797 itself contains extensive comments about ways you might want to modify the
4798 initial settings. However, note that there are many options that are not
4799 mentioned at all in the default configuration.
4802 .section Main configuration settings
4803 The main (global) configuration option settings must always come first in the
4804 file. The first thing you'll see in the file, after some initial comments, is
4807 # primary_hostname =
4809 This is a commented-out setting of the \primary@_hostname\ option. Exim needs
4810 to know the official, fully qualified name of your host, and this is where you
4811 can specify it. However, in most cases you do not need to set this option. When
4812 it is unset, Exim uses the \*uname()*\ system function to obtain the host name.
4814 The first three non-comment configuration lines are as follows:
4816 domainlist local_domains = @
4817 domainlist relay_to_domains =
4818 hostlist relay_from_hosts = 127.0.0.1
4820 These are not, in fact, option settings. They are definitions of two named
4821 domain lists and one named host list. Exim allows you to give names to lists of
4822 domains, hosts, and email addresses, in order to make it easier to manage the
4823 configuration file (see section ~~SECTnamedlists).
4825 The first line defines a domain list called \*local@_domains*\; this is used
4826 later in the configuration to identify domains that are to be delivered
4828 .index @@ in a domain list
4829 There is just one item in this list, the string `@@'. This is a special form of
4830 entry which means `the name of the local host'. Thus, if the local host is
4831 called \*a.host.example*\, mail to \*any.user@@a.host.example*\ is expected to
4832 be delivered locally. Because the local host's name is referenced indirectly,
4833 the same configuration file can be used on different hosts.
4835 The second line defines a domain list called \*relay@_to@_domains*\, but the
4836 list itself is empty. Later in the configuration we will come to the part that
4837 controls mail relaying through the local host; it allows relaying to any
4838 domains in this list. By default, therefore, no relaying on the basis of a mail
4839 domain is permitted.
4841 The third line defines a host list called \*relay@_from@_hosts*\. This list is
4842 used later in the configuration to permit relaying from any host or IP address
4843 that matches the list. The default contains just the IP address of the IPv4
4844 loopback interface, which means that processes on the local host are able to
4845 submit mail for relaying by sending it over TCP/IP to that interface. No other
4846 hosts are permitted to submit messages for relaying.
4848 Just to be sure there's no misunderstanding: at this point in the configuration
4849 we aren't actually setting up any controls. We are just defining some domains
4850 and hosts that will be used in the controls that are specified later.
4852 The next configuration line is a genuine option setting:
4854 acl_smtp_rcpt = acl_check_rcpt
4856 This option specifies an \*Access Control List*\ (ACL) which is to be used
4857 during an incoming SMTP session for every recipient of a message (every
4858 \\RCPT\\ command). The name of the list is \*acl@_check@_rcpt*\, and we will
4859 come to its definition below, in the ACL section of the configuration. ACLs
4860 control which recipients are accepted for an incoming message -- if a
4861 configuration does not provide an ACL to check recipients, no SMTP mail can be
4864 Two commented-out options settings are next:
4867 # qualify_recipient =
4869 The first of these specifies a domain that Exim uses when it constructs a
4870 complete email address from a local login name. This is often needed when Exim
4871 receives a message from a local process. If you do not set \qualify@_domain\,
4872 the value of \primary@_hostname\ is used. If you set both of these options, you
4873 can have different qualification domains for sender and recipient addresses. If
4874 you set only the first one, its value is used in both cases.
4876 .index domain literal||recognizing format
4877 The following line must be uncommented if you want Exim to recognize
4878 addresses of the form \*user@@[10.11.12.13]*\ that is, with a `domain literal'
4879 (an IP address) instead of a named domain.
4881 # allow_domain_literals
4884 The RFCs still require this form, but many people think that in the modern
4885 Internet it makes little sense to permit mail to be sent to specific hosts by
4886 quoting their IP addresses. This ancient format has been used by people who
4887 try to abuse hosts by using them for unwanted relaying. However, some
4888 people believe there are circumstances (for example, messages addressed to
4889 \*postmaster*\) where domain literals are still useful.
4892 The next configuration line is a kind of trigger guard:
4896 It specifies that no delivery must ever be run as the root user. The normal
4897 convention is to set up \*root*\ as an alias for the system administrator. This
4898 setting is a guard against slips in the configuration.
4899 The list of users specified by \never@_users\ is not, however, the complete
4900 list; the build-time configuration in \(Local/Makefile)\ has an option called
4901 \\FIXED@_NEVER@_USERS\\ specifying a list that cannot be overridden. The
4902 contents of \never@_users\ are added to this list. By default
4903 \\FIXED@_NEVER@_USERS\\ also specifies root.
4905 When a remote host connects to Exim in order to send mail, the only information
4906 Exim has about the host's identity is its IP address. The next configuration
4911 specifies that Exim should do a reverse DNS lookup on all incoming connections,
4912 in order to get a host name. This improves the quality of the logging
4913 information, but if you feel it is too expensive, you can remove it entirely,
4914 or restrict the lookup to hosts on `nearby' networks.
4915 Note that it is not always possible to find a host name from an IP address,
4916 because not all DNS reverse zones are maintained, and sometimes DNS servers are
4919 The next two lines are concerned with \*ident*\ callbacks, as defined by RFC
4920 1413 (hence their names):
4923 rfc1413_query_timeout = 30s
4925 These settings cause Exim to make ident callbacks for all incoming SMTP calls.
4926 You can limit the hosts to which these calls are made, or change the timeout
4927 that is used. If you set the timeout to zero, all ident calls are disabled.
4928 Although they are cheap and can provide useful information for tracing problem
4929 messages, some hosts and firewalls have problems with ident calls. This can
4930 result in a timeout instead of an immediate refused connection, leading to
4931 delays on starting up an incoming SMTP session.
4933 When Exim receives messages over SMTP connections, it expects all addresses to
4934 be fully qualified with a domain, as required by the SMTP definition. However,
4935 if you are running a server to which simple clients submit messages, you may
4936 find that they send unqualified addresses. The two commented-out options:
4938 # sender_unqualified_hosts =
4939 # recipient_unqualified_hosts =
4941 show how you can specify hosts that are permitted to send unqualified sender
4942 and recipient addresses, respectively.
4944 The \percent@_hack@_domains\ option is also commented out:
4946 # percent_hack_domains =
4948 It provides a list of domains for which the `percent hack' is to operate. This
4949 is an almost obsolete form of explicit email routing. If you do not know
4950 anything about it, you can safely ignore this topic.
4952 The last two settings in the main part of the default configuration are
4953 concerned with messages that have been `frozen' on Exim's queue. When a message
4954 is frozen, Exim no longer continues to try to deliver it. Freezing occurs when
4955 a bounce message encounters a permanent failure because the sender address of
4956 the original message that caused the bounce is invalid, so the bounce cannot be
4957 delivered. This is probably the most common case, but there are also other
4958 conditions that cause freezing, and frozen messages are not always bounce
4961 ignore_bounce_errors_after = 2d
4962 timeout_frozen_after = 7d
4964 The first of these options specifies that failing bounce messages are to be
4965 discarded after 2 days on the queue. The second specifies that any frozen
4966 message (whether a bounce message or not) is to be timed out (and discarded)
4967 after a week. In this configuration, the first setting ensures that no failing
4968 bounce message ever lasts a week.
4971 .section ACL configuration
4972 .index default||ACLs
4973 .index ~~ACL||default configuration
4974 In the default configuration, the ACL section follows the main configuration.
4975 It starts with the line
4979 and it contains the definition of one ACL called \*acl@_check@_rcpt*\ that was
4980 referenced in the setting of \acl@_smtp@_rcpt\ above.
4981 .index \\RCPT\\||ACL for
4982 This ACL is used for every \\RCPT\\ command in an incoming SMTP message. Each
4983 \\RCPT\\ command specifies one of the message's recipients. The ACL statements
4984 are considered in order, until the recipient address is either accepted or
4985 rejected. The \\RCPT\\ command is then accepted or rejected, according to the
4986 result of the ACL processing.
4990 This line, consisting of a name terminated by a colon, marks the start of the
4995 This ACL statement accepts the recipient if the sending host matches the list.
4996 But what does that strange list mean? It doesn't actually contain any host
4997 names or IP addresses. The presence of the colon puts an empty item in the
4998 list; Exim matches this only if the incoming message didn't come from a remote
4999 host. The colon is important. Without it, the list itself is empty, and can
5000 never match anything.
5002 What this statement is doing is to accept unconditionally all recipients in
5003 messages that are submitted by SMTP from local processes using the standard
5004 input and output (that is, not using TCP/IP). A number of MUAs operate in this
5007 deny domains = +local_domains
5008 local_parts = ^[.] : ^.*[@%!/|]
5010 deny domains = !+local_domains
5011 local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
5013 These statements are concerned with local parts that contain any of the
5014 characters `@@', `%', `!', `/', `|', or dots in unusual places. Although these
5015 characters are entirely legal in local parts (in the case of `@@' and leading
5016 dots, only if correctly quoted), they do not commonly occur in Internet mail
5019 The first three have in the past been associated with explicitly routed
5020 addresses (percent is still sometimes used -- see the \percent@_hack@_domains\
5021 option). Addresses containing these characters are regularly tried by spammers
5022 in an attempt to bypass relaying restrictions, and also by open relay testing
5023 programs. Unless you really need them it is safest to reject these characters
5024 at this early stage. This configuration is heavy-handed in rejecting these
5025 characters for all messages it accepts from remote hosts. This is a deliberate
5026 policy of being as safe as possible.
5028 The first rule above is stricter, and is applied to messages that are addressed
5029 to one of the local domains handled by this host. This is implemented by the
5030 first condition, which restricts it to domains that are listed in the
5031 \*local@_domains*\ domain list. The `+' character is used to indicate a
5032 reference to a named list. In this configuration, there is just one domain in
5033 \*local@_domains*\, but in general there may be many.
5035 The second condition on the first statement uses two regular expressions to
5036 block local parts that begin with a dot or contain `@@', `%', `!', `/', or `|'.
5037 If you have local accounts that include these characters, you will have to
5040 Empty components (two dots in a row) are not valid in RFC 2822, but Exim
5041 allows them because they have been encountered in practice. (Consider local
5042 parts constructed as `first-initial.second-initial.family-name' when applied to
5043 someone like the author of Exim, who has no second initial.) However, a local
5044 part starting with a dot or containing `/../' can cause trouble if it is used
5045 as part of a file name (for example, for a mailing list). This is also true for
5046 local parts that contain slashes. A pipe symbol can also be troublesome if the
5047 local part is incorporated unthinkingly into a shell command line.
5049 The second rule above applies to all other domains, and is less strict. This
5050 allows your own users to send outgoing messages to sites that use slashes
5051 and vertical bars in their local parts. It blocks local parts that begin
5052 with a dot, slash, or vertical bar, but allows these characters within the
5053 local part. However, the sequence `/../' is barred. The use of `@@', `%', and
5054 `!' is blocked, as before. The motivation here is to prevent your users (or
5055 your users' viruses) from mounting certain kinds of attack on remote sites.
5058 accept local_parts = postmaster
5059 domains = +local_domains
5061 This statement, which has two conditions, accepts an incoming address if the
5062 local part is \*postmaster*\ and the domain is one of those listed in the
5063 \*local@_domains*\ domain list. The `+' character is used to indicate a
5064 reference to a named list. In this configuration, there is just one domain in
5065 \*local@_domains*\, but in general there may be many.
5067 The presence of this statement means that mail to postmaster is never blocked
5068 by any of the subsequent tests. This can be helpful while sorting out problems
5069 in cases where the subsequent tests are incorrectly denying access.
5071 require verify = sender
5073 This statement requires the sender address to be verified before any subsequent
5074 ACL statement can be used. If verification fails, the incoming recipient
5075 address is refused. Verification consists of trying to route the address, to
5078 message could be delivered to it. In the case of remote addresses, basic
5079 verification checks only the domain, but \*callouts*\ can be used for more
5080 verification if required. Section ~~SECTaddressverification discusses the
5081 details of address verification.
5084 # deny message = rejected because $sender_host_address is \
5085 # in a black list at $dnslist_domain\n\
5087 # dnslists = black.list.example
5089 # warn message = X-Warning: $sender_host_address is \
5090 # in a black list at $dnslist_domain
5091 # log_message = found in $dnslist_domain
5092 # dnslists = black.list.example
5094 These commented-out lines are examples of how you could configure Exim to check
5095 sending hosts against a DNS black list. The first statement rejects messages
5096 from blacklisted hosts, whereas the second merely inserts a warning header
5100 accept domains = +local_domains
5102 message = unknown user
5105 This statement accepts the incoming recipient address if its domain is one of
5106 the local domains, but only if the address can be verified. Verification of
5107 local addresses normally checks both the local part and the domain. The
5108 \endpass\ line needs some explanation: if the condition above \endpass\ fails,
5109 that is, if the address is not in a local domain, control is passed to the next
5110 ACL statement. However, if the condition below \endpass\ fails, that is, if a
5111 recipient in a local domain cannot be verified, access is denied and the
5112 recipient is rejected.
5113 .index customizing||ACL failure message
5114 The \message\ modifier provides a customized error message for the failure.
5116 accept domains = +relay_to_domains
5118 message = unrouteable address
5121 This statement accepts the incoming recipient address if its domain is one of
5122 the domains for which this host is a relay, but again, only if the address can
5125 accept hosts = +relay_from_hosts
5127 Control reaches this statement only if the recipient's domain is neither a
5128 local domain, nor a relay domain. The statement accepts the address if the
5129 message is coming from one of the hosts that are defined as being allowed to
5130 relay through this host. Recipient verification is omitted here, because in
5131 many cases the clients are dumb MUAs that do not cope well with SMTP error
5132 responses. If you are actually relaying out from MTAs, you should probably add
5133 recipient verification here.
5135 accept authenticated = *
5137 Control reaches here for attempts to relay to arbitrary domains from arbitrary
5138 hosts. The statement accepts the address only if the client host has
5139 authenticated itself. The default configuration does not define any
5140 authenticators, which means that no client can in fact authenticate. You will
5141 need to add authenticator definitions if you want to make use of this ACL
5144 deny message = relay not permitted
5146 The final statement denies access, giving a specific error message. Reaching
5147 the end of the ACL also causes access to be denied, but with the generic
5148 message `administrative prohibition'.
5151 .section Router configuration
5152 .index default||routers
5153 .index routers||default
5154 The router configuration comes next in the default configuration, introduced
5159 Routers are the modules in Exim that make decisions about where to send
5160 messages. An address is passed to each router in turn, until it is either
5161 accepted, or failed. This means that the order in which you define the routers
5162 matters. Each router is fully described in its own chapter later in this
5163 manual. Here we give only brief overviews.
5165 .index domain literal||default router
5168 # driver = ipliteral
5169 # domains = !+local_domains
5170 # transport = remote_smtp
5172 This router is commented out because the majority of sites do not want to
5173 support domain literal addresses (those of the form \*user@@[10.9.8.7]*\). If
5174 you uncomment this router, you also need to uncomment the setting of
5175 \allow@_domain@_literals\ in the main part of the configuration.
5180 domains = ! +local_domains
5181 transport = remote_smtp
5183 ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
5187 The first uncommented router handles addresses that do not involve any local
5188 domains. This is specified by the line
5190 domains = ! +local_domains
5192 The \domains\ option lists the domains to which this router applies, but the
5193 exclamation mark is a negation sign, so the router is used only for domains
5194 that are not in the domain list called \*local@_domains*\ (which was defined at
5195 the start of the configuration). The plus sign before \*local@_domains*\
5196 indicates that it is referring to a named list. Addresses in other domains are
5197 passed on to the following routers.
5199 The name of the router driver is \%dnslookup%\,
5200 and is specified by the \driver\ option. Do not be confused by the fact that
5201 the name of this router instance is the same as the name of the driver. The
5202 instance name is arbitrary, but the name set in the \driver\ option must be one
5203 of the driver modules that is in the Exim binary.
5205 The \%dnslookup%\ router routes addresses by looking up their domains in the
5206 DNS in order to obtain a list of hosts to which the address is routed. If the
5207 router succeeds, the address is queued for the \%remote@_smtp%\ transport, as
5208 specified by the \transport\ option. If the router does not find the domain in
5209 the DNS, no further routers are tried because of the \no@_more\ setting, so the
5210 address fails and is bounced.
5212 The \ignore@_target@_hosts\ option specifies a list of IP addresses that are to
5213 be entirely ignored. This option is present because a number of cases have been
5214 encountered where MX records in the DNS point to host names
5215 whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1).
5216 Completely ignoring these IP addresses causes Exim to fail to route the
5217 email address, so it bounces. Otherwise, Exim would log a routing problem, and
5218 continue to try to deliver the message periodically until the address timed
5225 data = ${lookup{$local_part}lsearch{/etc/aliases}}
5227 file_transport = address_file
5228 pipe_transport = address_pipe
5230 Control reaches this and subsequent routers only for addresses in the local
5231 domains. This router checks to see whether the local part is defined as an
5232 alias in the \(/etc/aliases)\ file, and if so, redirects it according to the
5233 data that it looks up from that file. If no data is found for the local part,
5234 the value of the \data\ option is empty, causing the address to be passed to
5237 \(/etc/aliases)\ is a conventional name for the system aliases file that is
5238 often used. That is why it is referenced by from the default configuration
5239 file. However, you can change this by setting \\SYSTEM@_ALIASES@_FILE\\ in
5240 \(Local/Makefile)\ before building Exim.
5246 file = $home/.forward
5251 file_transport = address_file
5252 pipe_transport = address_pipe
5253 reply_transport = address_reply
5255 This is the most complicated router in the default configuration. It is another
5256 redirection router, but this time it is looking for forwarding data set up by
5257 individual users. The \check@_local@_user\ setting means that the first thing it
5258 does is to check that the local part of the address is the login name of a
5259 local user. If it is not, the router is skipped. When a local user is found,
5260 the file called \(.forward)\ in the user's home directory is consulted. If it
5261 does not exist, or is empty, the router declines. Otherwise, the contents of
5262 \(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect
5265 .index Sieve filter||enabling in default router
5266 Traditional \(.forward)\ files contain just a list of addresses, pipes, or
5267 files. Exim supports this by default. However, if \allow@_filter\ is set (it is
5268 commented out by default), the contents of the file are interpreted as a set of
5269 Exim or Sieve filtering instructions, provided the file begins with `@#Exim
5270 filter' or `@#Sieve filter', respectively. User filtering is discussed in the
5271 separate document entitled \*Exim's interfaces to mail filtering*\.
5273 The \no@_verify\ and \no@_expn\ options mean that this router is skipped when
5274 verifying addresses, or when running as a consequence of an SMTP \\EXPN\\
5276 There are two reasons for doing this:
5278 Whether or not a local user has a \(.forward)\ file is not really relevant when
5279 checking an address for validity; it makes sense not to waste resources doing
5282 More importantly, when Exim is verifying addresses or handling an \\EXPN\\
5283 command during an SMTP session, it is running as the Exim user, not as root.
5284 The group is the Exim group, and no additional groups are set up.
5285 It may therefore not be possible for Exim to read users' \(.forward)\ files at
5289 The setting of \check@_ancestor\ prevents the router from generating a new
5290 address that is the same as any previous address that was redirected. (This
5291 works round a problem concerning a bad interaction between aliasing and
5292 forwarding -- see section ~~SECTredlocmai).
5294 The final three option settings specify the transports that are to be used when
5295 forwarding generates a direct delivery to a file, or to a pipe, or sets up an
5296 auto-reply, respectively. For example, if a \(.forward)\ file contains
5298 a.nother@elsewhere.example, /home/spqr/archive
5300 the delivery to \(/home/spqr/archive)\ is done by running the \address@_file\
5306 transport = local_delivery
5308 The final router sets up delivery into local mailboxes, provided that the local
5309 part is the name of a local login, by accepting the address and queuing it for
5310 the \%local@_delivery%\ transport. Otherwise, we have reached the end of the
5311 routers, so the address is bounced.
5314 .section Transport configuration
5315 .index default||transports
5316 .index transports||default
5317 Transports define mechanisms for actually delivering messages. They operate
5318 only when referenced from routers, so the order in which they are defined does
5319 not matter. The transports section of the configuration starts with
5323 One remote transport and four local transports are defined.
5328 This transport is used for delivering messages over SMTP connections. All its
5329 options are defaulted. The list of remote hosts comes from the router.
5333 file = /var/mail/$local_part
5340 This \%appendfile%\ transport is used for local delivery to user mailboxes in
5341 traditional BSD mailbox format. By default it runs under the uid and gid of the
5342 local user, which requires the sticky bit to be set on the \(/var/mail)\
5343 directory. Some systems use the alternative approach of running mail deliveries
5344 under a particular group instead of using the sticky bit. The commented options
5345 show how this can be done.
5347 Exim adds three headers to the message as it delivers it: ::Delivery-date::,
5348 ::Envelope-to:: and ::Return-path::. This action is requested by the three
5349 similarly-named options above.
5355 This transport is used for handling deliveries to pipes that are generated by
5356 redirection (aliasing or users' \(.forward)\ files). The \return@_output\
5357 option specifies that any output generated by the pipe is to be returned to the
5366 This transport is used for handling deliveries to files that are generated by
5367 redirection. The name of the file is not specified in this instance of
5368 \%appendfile%\, because it comes from the \%redirect%\ router.
5373 This transport is used for handling automatic replies generated by users'
5377 .section Default retry rule
5378 .index retry||default rule
5379 .index default||retry rule
5380 The retry section of the configuration file contains rules which affect the way
5381 Exim retries deliveries that cannot be completed at the first attempt. It is
5382 introduced by the line
5386 In the default configuration, there is just one rule, which applies to all
5389 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
5391 This causes any temporarily failing address to be retried every 15 minutes for
5392 2 hours, then at intervals starting at one hour and increasing by a factor of
5393 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
5394 is not delivered after 4 days of failure, it is bounced.
5397 .section Rewriting configuration
5398 The rewriting section of the configuration, introduced by
5402 contains rules for rewriting addresses in messages as they arrive. There are no
5403 rewriting rules in the default configuration file.
5406 .section Authenticators configuration
5407 .index \\AUTH\\||configuration
5408 The authenticators section of the configuration, introduced by
5410 begin authenticators
5412 defines mechanisms for the use of the SMTP \\AUTH\\ command. No authenticators
5413 are specified in the default configuration file.
5421 . ============================================================================
5422 .chapter Regular expressions
5423 .set runningfoot "regular expressions"
5424 .rset CHAPregexp ~~chapter
5426 .index regular expressions||library
5428 Exim supports the use of regular expressions in many of its options. It
5429 uses the PCRE regular expression library; this provides regular expression
5430 matching that is compatible with Perl 5. The syntax and semantics of
5431 regular expressions is discussed in many Perl reference books, and also in
5434 [(A HREF="http://www.oreilly.com/catalog/regex/")]
5436 $it{Mastering Regular Expressions}
5440 (O'Reilly, ISBN 0-596-00289-0).
5442 The documentation for the syntax and semantics of the regular expressions that
5443 are supported by PCRE is included in plain text in the file
5444 \(doc/pcrepattern.txt)\ in the Exim distribution, and also in the HTML
5445 tarbundle of Exim documentation, and as an appendix to the
5447 [(A HREF="http://www.uit.co.uk/exim-book/")]
5453 It describes in detail the features of the regular expressions that PCRE
5454 supports, so no further description is included here. The PCRE functions are
5455 called from Exim using the default option settings (that is, with no PCRE
5456 options set), except that the \\PCRE@_CASELESS\\ option is set when the
5457 matching is required to be case-insensitive.
5460 In most cases, when a regular expression is required in an Exim configuration,
5461 it has to start with a circumflex, in order to distinguish it from plain text
5462 or an `ends with' wildcard. In this example of a configuration setting, the
5463 second item in the colon-separated list is a regular expression.
5465 domains = a.b.c : ^\\d{3} : *.y.z : ...
5467 The doubling of the backslash is required because of string expansion that
5468 precedes interpretation -- see section ~~SECTlittext for more discussion of
5469 this issue, and a way of avoiding the need for doubling backslashes. The
5470 regular expression that is eventually used in this example contains just one
5471 backslash. The circumflex is included in the regular expression, and has the
5472 normal effect of `anchoring' it to the start of the string that is being
5475 There are, however, two cases where a circumflex is not required for the
5476 recognition of a regular expression: these are the \match\ condition in a
5477 string expansion, and the \matches\ condition in an Exim filter file. In these
5478 cases, the relevant string is always treated as a regular expression; if it
5479 does not start with a circumflex, the expression is not anchored, and can match
5480 anywhere in the subject string.
5482 In all cases, if you want a regular expression to match at the end of a string,
5483 you must code the @$ metacharacter to indicate this. For example:
5485 domains = ^\\d{3}\\.example
5487 matches the domain \*123.example*\, but it also matches \*123.example.com*\.
5490 domains = ^\\d{3}\\.example\$
5492 if you want \*example*\ to be the top-level domain. (The backslash before the
5493 @$ is another artefact of string expansion.)
5497 .section Testing regular expressions
5498 .index testing||regular expressions
5499 .index regular expressions||testing
5501 A program called \*pcretest*\ forms part of the PCRE distribution and is built
5502 with PCRE during the process of building Exim. It is primarily intended for
5503 testing PCRE itself, but it can also be used for experimenting with regular
5504 expressions. After building Exim, the binary can be found in the build
5505 directory (it is not installed anywhere automatically). There is documentation
5506 of various options in \(doc/pcretest.txt)\, but for simple testing, none are
5507 needed. This is the output of a sample run of \*pcretest*\:
5509 re> $cb{/^([^@@]+)@@.+@\.(ac|edu)@\.(?!kr)[a-z]@{2@}@$/}
5510 data> $cb{x@@y.ac.uk}
5514 data> $cb{x@@y.ac.kr}
5516 data> $cb{x@@y.edu.com}
5518 data> $cb{x@@y.edu.co}
5524 Input typed by the user is shown in bold face.
5526 After the `re>' prompt, a regular expression enclosed in delimiters is
5527 expected. If this compiles without error, `data>' prompts are given for strings
5528 against which the expression is matched. An empty data line causes a new
5529 regular expression to be read. If the match is successful, the captured
5530 substring values (that is, what would be in the variables \$0$\, \$1$\, \$2$\,
5531 etc.) are shown. The above example tests for an email address whose domain ends
5532 with either `ac' or `edu' followed by a two-character top-level domain that is
5533 not `kr'. The local part is captured in \$1$\ and the `ac' or `edu' in \$2$\.
5544 . ============================================================================
5545 .chapter File and database lookups
5546 .set runningfoot "file/database lookups"
5547 .rset CHAPfdlookup "~~chapter"
5549 .index database lookups
5550 .index lookup||description of
5551 Exim can be configured to look up data in files or databases as it processes
5552 messages. Two different kinds of syntax are used:
5554 A string that is to be expanded may contain explicit lookup requests. These
5555 cause parts of the string to be replaced by data that is obtained from the
5558 Lists of domains, hosts, and email addresses can contain lookup requests as a
5559 way of avoiding excessively long linear lists. In this case, the data that is
5560 returned by the lookup is often (but not always) discarded; whether the lookup
5561 succeeds or fails is what really counts. These kinds of list are described in
5562 chapter ~~CHAPdomhosaddlists.
5564 It is easy to confuse the two different kinds of lookup, especially as the
5565 lists that may contain the second kind are always expanded before being
5566 processed as lists. Therefore, they may also contain lookups of the first kind.
5567 Be careful to distinguish between the following two examples:
5569 domains = ${lookup{$sender_host_address}lsearch{/some/file}}
5570 domains = lsearch;/some/file
5572 The first uses a string expansion, the result of which must be a domain list.
5573 String expansions are described in detail in chapter ~~CHAPexpand. The
5574 expansion takes place first, and the file that is searched could contain lines
5577 192.168.3.4: domain1 : domain2 : ...
5578 192.168.1.9: domain3 : domain4 : ...
5580 Thus, the result of the expansion is a list of domains (and possibly other
5581 types of item that are allowed in domain lists).
5583 In the second case, the lookup is a single item in a domain list. It causes
5584 Exim to use a lookup to see if the domain that is being processed can be found
5585 in the file. The file could contains lines like this:
5590 Any data that follows the keys is not relevant when checking that the domain
5591 matches the list item.
5593 It is possible to use both kinds of lookup at once. Consider a file containing
5596 192.168.5.6: lsearch;/another/file
5598 If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the
5599 first \domains\ setting above generates the second setting, which therefore
5600 causes a second lookup to occur.
5602 The rest of this chapter describes the different lookup types that are
5603 available. Any of them can be used in either of the circumstances described
5604 above. The syntax requirements for the two cases are described in chapters
5605 ~~CHAPexpand and ~~CHAPdomhosaddlists, respectively.
5607 .section Lookup types
5608 .index lookup||types of
5609 .index single-key lookup||definition of
5610 Two different styles of data lookup are implemented:
5612 The \*single-key*\ style requires the specification of a file in which to look,
5613 and a single key to search for. The lookup type determines how the file is
5616 .index query-style lookup||definition of
5617 The \*query*\ style accepts a generalized database query.
5618 No particular key value is assumed by Exim for query-style lookups. You can
5619 use whichever Exim variable(s) you need to construct the database query.
5621 The code for each lookup type is in a separate source file that is included in
5622 the binary of Exim only if the corresponding compile-time option is set. The
5623 default settings in \(src/EDITME)\ are:
5628 which means that only linear searching and DBM lookups are included by default.
5629 For some types of lookup (e.g. SQL databases), you need to install appropriate
5630 libraries and header files before building Exim.
5634 .section Single-key lookup types
5635 .rset SECTsinglekeylookups "~~chapter.~~section"
5636 .index lookup||single-key types
5637 .index single-key lookup||list of types
5638 The following single-key lookup types are implemented:
5640 .index cdb||description of
5642 .index binary zero||in lookup key
5643 \%cdb%\: The given file is searched as a Constant DataBase file, using the key
5644 string without a terminating binary zero. The cdb format is designed for
5645 indexed files that are read frequently and never updated, except by total
5646 re-creation. As such, it is particulary suitable for large files containing
5647 aliases or other indexed data referenced by an MTA. Information about cdb can
5648 be found in several places:
5650 \?http://www.pobox.com/@~djb/cdb.html?\
5651 \?ftp://ftp.corpit.ru/pub/tinycdb/?\
5652 \?http://packages.debian.org/stable/utils/freecdb.html?\
5654 A cdb distribution is not needed in order to build Exim with cdb support,
5655 because the code for reading cdb files is included directly in Exim itself.
5656 However, no means of building or testing cdb files is provided with Exim, so
5657 you need to obtain a cdb distribution in order to do this.
5659 .index DBM||lookup type
5661 .index binary zero||in lookup key
5662 \%dbm%\: Calls to DBM library functions are used to extract data from the given
5663 DBM file by looking up the record with the given key. A terminating binary
5664 zero is included in the key that is passed to the DBM library. See section
5665 ~~SECTdb for a discussion of DBM libraries.
5666 .index Berkeley DB library||file format
5667 For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database
5668 when building DBM files using the \exim@_dbmbuild\ utility. However, when using
5669 Berkeley DB versions 3 or 4, it opens existing databases for reading with the
5670 \\DB@_UNKNOWN\\ option. This enables it to handle any of the types of database
5671 that the library supports, and can be useful for accessing DBM files created by
5672 other applications. (For earlier DB versions, \\DB@_HASH\\ is always used.)
5675 .index lookup||dbmnz
5676 .index lookup||dbm, terminating zero
5677 .index binary zero||in lookup key
5679 .index \(/etc/userdbshadow.dat)\
5680 .index dmbnz lookup type
5681 \%dbmnz%\: This is the same as \%dbm%\, except that a terminating binary zero
5682 is not included in the key that is passed to the DBM library. You may need this
5683 if you want to look up data in files that are created by or shared with some
5684 other application that does not use terminating zeros. For example, you need to
5685 use \%dbmnz%\ rather than \%dbm%\ if you want to authenticate incoming SMTP
5686 calls using the passwords from Courier's \(/etc/userdbshadow.dat)\ file. Exim's
5687 utility program for creating DBM files (\*exim@_dbmbuild*\) includes the zeros
5688 by default, but has an option to omit them (see section ~~SECTdbmbuild).
5690 .index lookup||dsearch
5691 .index dsearch lookup type
5692 \%dsearch%\: The given file must be a directory; this is searched for a file
5693 whose name is the key. The key may not contain any forward slash characters.
5694 The result of a successful lookup is the name of the file. An example of how
5695 this lookup can be used to support virtual domains is given in section
5696 ~~SECTvirtualdomains.
5698 .index lookup||iplsearch
5699 .index iplsearch lookup type
5701 \%iplsearch%\: The given file is a text file containing keys and data. A key is
5702 terminated by a colon or white space or the end of the line. The keys in the
5703 file must be IP addresses, or IP addresses with CIDR masks. Keys that involve
5704 IPv6 addresses must be enclosed in quotes to prevent the first internal colon
5705 being interpreted as a key terminator. For example:
5707 1.2.3.4: data for 1.2.3.4
5708 192.168.0.0/16 data for 192.168.0.0/16
5709 "abcd::cdab": data for abcd::cdab
5710 "abcd:abcd::/32" data for abcd:abcd::/32
5712 The key for an \%iplsearch%\ lookup must be an IP address (without a mask). The
5713 file is searched linearly, using the CIDR masks where present, until a matching
5714 key is found. The first key that matches is used; there is no attempt to find a
5715 `best' match. Apart from the way the keys are matched, the processing for
5716 \%iplsearch%\ is the same as for \%lsearch%\.
5718 \**Warning 1**\: Unlike most other single-key lookup types, a file of data for
5719 \%iplsearch%\ can \*not*\ be turned into a DBM or cdb file, because those
5720 lookup types support only literal keys.
5722 \**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that
5723 the implicit key is the host's IP address rather than its name (see section
5724 ~~SECThoslispatsikey).
5728 .index linear search
5729 .index lookup||lsearch
5730 .index lsearch lookup type
5731 \%lsearch%\: The given file is a text file that is searched linearly for a
5732 line beginning with the search key, terminated by a colon or white space or the
5733 end of the line. The first occurrence that is found in the file is used. White
5734 space between the key and the colon is permitted. The remainder of the line,
5735 with leading and trailing white space removed, is the data. This can be
5736 continued onto subsequent lines by starting them with any amount of white
5737 space, but only a single space character is included in the data at such a
5738 junction. If the data begins with a colon, the key must be terminated by a
5743 Empty lines and lines beginning with @# are ignored, even if they occur in the
5744 middle of an item. This is the traditional textual format of alias files. Note
5745 that the keys in an \%lsearch%\ file are literal strings. There is no
5746 wildcarding of any kind.
5748 .index lookup||lsearch, colons in keys
5749 In most \%lsearch%\ files, keys are not required to contain colons
5751 or @# characters, or
5753 whitespace. However, if you need this feature, it is available. If a key begins
5754 with a doublequote character, it is terminated only by a matching quote (or end
5755 of line), and the normal escaping rules apply to its contents (see section
5756 ~~SECTstrings). An optional colon is permitted after quoted keys (exactly as
5757 for unquoted keys). There is no special handling of quotes for the data part of
5758 an \%lsearch%\ line.
5760 .index NIS lookup type
5762 .index binary zero||in lookup key
5763 \%nis%\: The given file is the name of a NIS map, and a NIS lookup is done with
5764 the given key, without a terminating binary zero. There is a variant called
5765 \%nis0%\ which does include the terminating binary zero in the key. This is
5766 reportedly needed for Sun-style alias files. Exim does not recognize NIS
5767 aliases; the full map names must be used.
5769 .index wildlsearch lookup type
5770 .index lookup||wildlsearch
5771 .index nwildlsearch lookup type
5772 .index lookup||nwildlsearch
5773 \%wildlsearch%\ or \%nwildlsearch%\: These search a file linearly, like
5774 \%lsearch%\, but instead of being interpreted as a literal string, each key may
5775 be wildcarded. The difference between these two lookup types is that for
5776 \%wildlsearch%\, each key in the file is string-expanded before being used,
5777 whereas for \%nwildlsearch%\, no expansion takes place.
5779 Like \%lsearch%\, the testing is done case-insensitively. The following forms
5780 of wildcard are recognized:
5782 The string may begin with an asterisk to mean `begins with'. For example:
5784 *.a.b.c data for anything.a.b.c
5785 *fish data for anythingfish
5788 The string may begin with a circumflex to indicate a regular expression. For
5789 example, for \%wildlsearch%\:
5791 ^\N\d+\.a\.b\N data for <digits>.a.b
5793 Note the use of \"@\N"\ to disable expansion of the contents of the regular
5794 expression. If you are using \%nwildlsearch%\, where the keys are not
5795 string-expanded, the equivalent entry is:
5797 ^\d+\.a\.b data for <digits>.a.b
5800 If the regular expression contains white space or colon characters, you must
5801 either quote it (see \%lsearch%\ above), or represent these characters in other
5802 ways. For example, \"@\s"\ can be used for white space and \"@\x3A"\ for a
5803 colon. This may be easier than quoting, because if you quote, you have to
5804 escape all the backslashes inside the quotes.
5806 Although I cannot see it being of much use, the general matching function
5807 that is used to implement
5809 means that the string may begin with a lookup name terminated by a semicolon,
5810 and followed by lookup data. For example:
5812 cdb;/some/file data for keys that match the file
5814 The data that is obtained from the nested lookup is discarded.
5816 Keys that do not match any of these patterns are interpreted literally. The
5817 continuation rules for the data are the same as for \%lsearch%\, and keys may
5818 be followed by optional colons.
5820 \**Warning**\: Unlike most other single-key lookup types, a file of data for
5821 \%(n)wildlsearch%\ can \*not*\ be turned into a DBM or cdb file, because those
5822 lookup types support only literal keys.
5825 .section Query-style lookup types
5826 .index lookup||query-style types
5827 .index query-style lookup||list of types
5828 The supported query-style lookup types are listed below. Further details about
5829 many of them are given in later sections.
5831 .index DNS||as a lookup type
5833 \%dnsdb%\: This does a DNS search for a record whose domain name is the supplied
5834 query. The resulting data is the contents of the record. See section
5837 .index Interbase lookup type
5838 .index lookup||Interbase
5839 \%ibase%\: This does a lookup in an Interbase database.
5841 .index LDAP||lookup type
5843 \%ldap%\: This does an LDAP lookup using a query in the form of a URL, and
5844 returns attributes from a single entry. There is a variant called \%ldapm%\
5845 that permits values from multiple entries to be returned. A third variant
5846 called \%ldapdn%\ returns the Distinguished Name of a single entry instead of
5847 any attribute values. See section ~~SECTldap.
5849 .index MySQL||lookup type
5850 .index lookup||MySQL
5851 \%mysql%\: The format of the query is an SQL statement that is passed to a MySQL
5852 database. See section ~~SECTsql.
5854 .index NIS@+ lookup type
5856 \%nisplus%\: This does a NIS+ lookup using a query that can specify the name of
5857 the field to be returned. See section ~~SECTnisplus.
5859 .index Oracle||lookup type
5860 .index lookup||Oracle
5861 \%oracle%\: The format of the query is an SQL statement that is passed to an
5862 Oracle database. See section ~~SECTsql.
5864 .index lookup||passwd
5865 .index passwd lookup type
5866 \%passwd%\ is a query-style lookup with queries that are just user names. The
5867 lookup calls \*getpwnam()*\ to interrogate the system password data, and on
5868 success, the result string is the same as you would get from an \%lsearch%\
5869 lookup on a traditional \(/etc/passwd file)\, though with \"*"\ for the
5870 password value. For example:
5872 *:42:42:King Rat:/home/kr:/bin/bash
5875 .index PostgreSQL lookup type
5876 .index lookup||PostgreSQL
5877 \%pgsql%\: The format of the query is an SQL statement that is passed to a
5878 PostgreSQL database. See section ~~SECTsql.
5880 \%testdb%\: This is a lookup type that is used for testing Exim. It is
5881 not likely to be useful in normal operation.
5883 .index whoson lookup type
5884 .index lookup||whoson
5885 \%whoson%\: \*Whoson*\ (\?http://whoson.sourceforge.net?\) is a proposed
5886 Internet protocol that allows Internet server programs to check whether a
5887 particular (dynamically allocated) IP address is currently allocated to a known
5888 (trusted) user and, optionally, to obtain the identity of the said user. In
5889 Exim, this can be used to implement `POP before SMTP' checking using ACL
5892 require condition = \
5893 ${lookup whoson {$sender_host_address}{yes}{no}}
5895 The query consists of a single IP address. The value returned is the name of
5896 the authenticated user.
5899 .section Temporary errors in lookups
5900 .index lookup||temporary error in
5901 Lookup functions can return temporary error codes if the lookup cannot be
5902 completed. For example, a NIS or LDAP database might be unavailable. For this
5903 reason, it is not advisable to use a lookup that might do this for critical
5904 options such as a list of local domains.
5906 When a lookup cannot be completed in a router or transport, delivery
5907 of the message (to the relevant address) is deferred, as for any other
5908 temporary error. In other circumstances Exim may assume the lookup has failed,
5909 or may give up altogether.
5912 .section Default values in single-key lookups
5913 .rset SECTdefaultvaluelookups "~~chapter.~~section"
5914 .index wildcard lookups
5915 .index lookup||default values
5916 .index lookup||wildcard
5917 .index lookup||$*$ added to type
5918 .index default||in single-key lookups
5919 In this context, a `default value' is a value specified by the administrator
5920 that is to be used if a lookup fails.
5922 If `$*$' is added to a single-key lookup type (for example, \lsearch$*$\) and
5923 the initial lookup fails, the key `$*$' is looked up in the file to provide
5924 a default value. See also the section on partial matching below.
5926 .index @*@@ with single-key lookup
5927 .index lookup||$*$@@ added to type
5928 .index alias file||per-domain default
5929 Alternatively, if `$*$@@' is added to a single-key lookup type (for example
5930 \dbm$*$@@\) then, if the initial lookup fails and the key contains an @@
5931 character, a second lookup is done with everything before the last @@ replaced
5932 by $*$. This makes it possible to provide per-domain defaults in alias files
5933 that include the domains in the keys. If the second lookup fails (or doesn't
5934 take place because there is no @@ in the key), `$*$' is looked up.
5935 For example, a \%redirect%\ router might contain:
5937 data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}}
5939 Suppose the address that is being processed is \*jane@@eyre.example*\. Exim
5940 looks up these keys, in this order:
5946 The data is taken from whichever key it finds first. \**Note**\: in an
5947 \%lsearch%\ file, this does not mean the first of these keys in the file. A
5948 complete scan is done for each key, and only if it is not found at all does
5949 Exim move on to try the next key.
5952 .section Partial matching in single-key lookups
5953 .rset SECTpartiallookup "~~chapter.~~section"
5954 .index partial matching
5955 .index wildcard lookups
5956 .index lookup||partial matching
5957 .index lookup||wildcard
5958 .index asterisk||in search type
5959 The normal operation of a single-key lookup is to search the file for an exact
5960 match with the given key. However, in a number of situations where domains are
5961 being looked up, it is useful to be able to do partial matching. In this case,
5962 information in the file that has a key starting with `$*$.' is matched by any
5963 domain that ends with the components that follow the full stop. For example, if
5964 a key in a DBM file is
5966 *.dates.fict.example
5968 then when partial matching is enabled this is matched by (amongst others)
5969 \*2001.dates.fict.example*\ and \*1984.dates.fict.example*\. It is also matched
5970 by \*dates.fict.example*\, if that does not appear as a separate key in the
5973 \**Note**\: Partial matching is not available for query-style lookups. It is
5974 also not available for any lookup items in address lists (see section
5977 Partial matching is implemented by doing a series of separate lookups using
5978 keys constructed by modifying the original subject key. This means that it can
5979 be used with any of the single-key lookup types, provided that
5980 partial matching keys
5981 beginning with a special prefix (default `$*$.') are included in the data file.
5982 Keys in the file that do not begin with the prefix are matched only by
5983 unmodified subject keys when partial matching is in use.
5985 Partial matching is requested by adding the string `partial-' to the front of
5986 the name of a single-key lookup type, for example, \partial-dbm\. When this is
5987 done, the subject key is first looked up unmodified; if that fails, `$*$.'
5988 is added at the start of the subject key, and it is looked up again. If that
5989 fails, further lookups are tried with dot-separated components removed
5990 from the start of the subject key, one-by-one, and `$*$.' added on the front of
5993 A minimum number of two non-$*$ components are required. This can be adjusted
5994 by including a number before the hyphen in the search type. For example,
5995 \partial3-lsearch\ specifies a minimum of three non-$*$ components in the
5996 modified keys. Omitting the number is equivalent to `partial2-'. If the subject
5997 key is \*2250.dates.fict.example*\ then the following keys are looked up when
5998 the minimum number of non-$*$ components is two:
6000 2250.dates.fict.example
6001 *.2250.dates.fict.example
6002 *.dates.fict.example
6005 As soon as one key in the sequence is successfully looked up, the lookup
6008 .index lookup||partial matching, changing prefix
6009 .index prefix||for partial matching
6010 The use of `$*$.' as the partial matching prefix is a default that can be
6011 changed. The motivation for this feature is to allow Exim to operate with file
6012 formats that are used by other MTAs. A different prefix can be supplied in
6013 parentheses instead of the hyphen after `partial'. For example:
6015 domains = partial(.)lsearch;/some/file
6017 In this example, if the domain is \*a.b.c*\, the sequence of lookups is
6018 \"a.b.c"\, \".a.b.c"\, and \".b.c"\ (the default minimum of 2 non-wild
6019 components is unchanged). The prefix may consist of any punctuation characters
6020 other than a closing parenthesis. It may be empty, for example:
6022 domains = partial1()cdb;/some/file
6024 For this example, if the domain is \*a.b.c*\, the sequence of lookups is
6025 \"a.b.c"\, \"b.c"\, and \"c"\.
6027 If `partial0' is specified, what happens at the end (when the lookup with just
6028 one non-wild component has failed, and the original key is shortened right down
6029 to the null string) depends on the prefix:
6031 If the prefix has zero length, the whole lookup fails.
6033 If the prefix has length 1, a lookup for just the prefix is done. For
6034 example, the final lookup for `partial0(.)' is for \"."\ alone.
6036 Otherwise, if the prefix ends in a dot, the dot is removed, and the
6037 remainder is looked up. With the default prefix, therefore, the final lookup is
6038 for `$*$' on its own.
6040 Otherwise, the whole prefix is looked up.
6043 If the search type ends in `$*$' or `$*$@@' (see section
6044 ~~SECTdefaultvaluelookups above), the search for an ultimate default that this
6045 implies happens after all partial lookups have failed. If `partial0' is
6046 specified, adding `$*$' to the search type has no effect with the default
6047 prefix, because the `$*$' key is already included in the sequence of partial
6048 lookups. However, there might be a use for lookup types such as
6049 `partial0(.)lsearch$*$'.
6051 The use of `$*$' in lookup partial matching differs from its use as a wildcard
6052 in domain lists and the like. Partial matching works only in terms of
6053 dot-separated components; a key such as \"*fict.example"\
6054 in a database file is useless, because the asterisk in a partial matching
6055 subject key is always followed by a dot.
6059 .section Lookup caching
6060 .index lookup||caching
6061 .index caching||lookup data
6063 caches the most recent lookup result on a per-file basis for single-key
6064 lookup types, and keeps the relevant files open. In some types of configuration
6065 this can lead to many files being kept open for messages with many recipients.
6066 To avoid hitting the operating system limit on the number of simultaneously
6067 open files, Exim closes the least recently used file when it needs to open more
6068 files than its own internal limit, which can be changed via the
6069 \lookup@_open@_max\ option.
6071 For query-style lookups, a single data cache per lookup type is kept. The files
6072 are closed and the caches flushed at strategic points during delivery -- for
6073 example, after all routing is complete.
6076 .section Quoting lookup data
6077 .index lookup||quoting
6078 .index quoting||in lookups
6079 When data from an incoming message is included in a query-style lookup, there
6080 is the possibility of special characters in the data messing up the syntax of
6081 the query. For example, a NIS+ query that contains
6085 will be broken if the local part happens to contain a closing square bracket.
6086 For NIS+, data can be enclosed in double quotes like this:
6088 [name="$local_part"]
6090 but this still leaves the problem of a double quote in the data. The rule for
6091 NIS+ is that double quotes must be doubled. Other lookup types have different
6092 rules, and to cope with the differing requirements, an expansion operator
6093 of the following form is provided:
6095 @$@{quote@_<<lookup-type>>:<<string>>@}
6097 For example, the safest way to write the NIS+ query is
6099 [name="${quote_nisplus:$local_part}"]
6101 See chapter ~~CHAPexpand for full coverage of string expansions. The quote
6102 operator can be used for all lookup types, but has no effect for single-key
6103 lookups, since no quoting is ever needed in their key strings.
6107 .section More about dnsdb
6108 .rset SECTdnsdb "~~chapter.~~section"
6110 .index lookup||dnsdb
6111 .index DNS||as a lookup type
6112 The \%dnsdb%\ lookup type uses the DNS as its database. A query consists of a
6113 record type and a domain name, separated by an equals sign. For example, an
6114 expansion string could contain:
6116 ${lookup dnsdb{mx=a.b.example}{$value}fail}
6119 The supported record types are A, CNAME, MX, NS, PTR, SRV, and TXT,
6121 and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
6122 configured). If no type is given, TXT is assumed. When the type is PTR, the
6123 address should be given as normal; it is converted to the necessary inverted
6124 format internally. For example:
6126 ${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
6129 .index MX record||in \%dnsdb%\ lookup
6130 For MX records, both the preference value and the host name are returned,
6131 separated by a space.
6133 .index SRV record||in \%dnsdb%\ lookup
6134 For SRV records, the priority, weight, port, and host name are returned,
6135 separated by spaces. For any record type,
6137 if multiple records are found (or, for A6 lookups, if a single record leads to
6138 multiple addresses), the data is returned as a concatenation, separated by
6139 newlines. The order, of course, depends on the DNS resolver.
6144 .section More about LDAP
6145 .rset SECTldap "~~chapter.~~section"
6148 .index Solaris||LDAP
6149 The original LDAP implementation came from the University of Michigan; this has
6150 become `Open LDAP', and there are now two different releases. Another
6151 implementation comes from Netscape, and Solaris 7 and subsequent releases
6152 contain inbuilt LDAP support. Unfortunately, though these are all compatible at
6153 the lookup function level, their error handling is different. For this reason
6154 it is necessary to set a compile-time variable when building Exim with LDAP, to
6155 indicate which LDAP library is in use. One of the following should appear in
6156 your \(Local/Makefile)\:
6158 LDAP_LIB_TYPE=UMICHIGAN
6159 LDAP_LIB_TYPE=OPENLDAP1
6160 LDAP_LIB_TYPE=OPENLDAP2
6161 LDAP_LIB_TYPE=NETSCAPE
6162 LDAP_LIB_TYPE=SOLARIS
6164 If \\LDAP@_LIB@_TYPE\\ is not set, Exim assumes \"OPENLDAP1"\, which has the
6165 same interface as the University of Michigan version.
6167 There are three LDAP lookup types in Exim. These behave slightly differently in
6168 the way they handle the results of a query:
6170 \%ldap%\ requires the result to contain just one entry; if there are more, it
6173 \%ldapdn%\ also requires the result to contain just one entry, but it is the
6174 Distinguished Name that is returned rather than any attribute values.
6176 \%ldapm%\ permits the result to contain more than one entry; the attributes from
6177 all of them are returned.
6180 For \%ldap%\ and \%ldapm%\, if a query finds only entries with no attributes,
6181 Exim behaves as if the entry did not exist, and the lookup fails. The format of
6182 the data returned by a successful lookup is described in the next section.
6183 First we explain how LDAP queries are coded.
6185 .section Format of LDAP queries
6186 .rset SECTforldaque "~~chapter.~~section"
6187 .index LDAP||query format
6188 An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
6189 the configuration of a \%redirect%\ router one might have this setting:
6191 data = ${lookup ldap \
6192 {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
6193 c=UK?mailbox?base?}}
6195 .index LDAP||with TLS
6196 The URL may begin with \"ldap"\ or \"ldaps"\ if your LDAP library supports
6197 secure (encrypted) LDAP connections. The second of these ensures that an
6198 encrypted TLS connection is used.
6200 .section LDAP quoting
6201 .index LDAP||quoting
6202 Two levels of quoting are required in LDAP queries, the first for LDAP itself
6203 and the second because the LDAP query is represented as a URL. Furthermore,
6204 within an LDAP query, two different kinds of quoting are required. For this
6205 reason, there are two different LDAP-specific quoting operators.
6207 The \quote@_ldap\ operator is designed for use on strings that are part of
6208 filter specifications. Conceptually, it first does the following conversions on
6216 in accordance with RFC 2254. The resulting string is then quoted according
6217 to the rules for URLs, that is, all characters except
6221 are converted to their hex values, preceded by a percent sign. For example:
6223 ${quote_ldap: a(bc)*, a<yz>; }
6227 %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
6229 Removing the URL quoting, this is (with a leading and a trailing space):
6231 a\28bc\29\2A, a<yz>;
6234 The \quote@_ldap@_dn\ operator is designed for use on strings that are part of
6235 base DN specifications in queries. Conceptually, it first converts the string
6236 by inserting a backslash in front of any of the following characters:
6240 It also inserts a backslash before any leading spaces or @# characters, and
6241 before any trailing spaces. (These rules are in RFC 2253.) The resulting string
6242 is then quoted according to the rules for URLs. For example:
6244 ${quote_ldap_dn: a(bc)*, a<yz>; }
6248 %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
6250 Removing the URL quoting, this is (with a trailing space):
6252 \ a(bc)*\, a\<yz\>\;\
6254 There are some further comments about quoting in the section on LDAP
6255 authentication below.
6257 .section LDAP connections
6258 .index LDAP||connections
6259 The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
6260 is in use, via a Unix domain socket. The example given above does not specify
6261 an LDAP server. A server that is reached by TCP/IP can be specified in a query
6264 ldap://<<hostname>>:<<port>>/...
6266 If the port (and preceding colon) are omitted, the standard LDAP port (389) is
6267 used. When no server is specified in a query, a list of default servers is
6268 taken from the \ldap@_default@_servers\ configuration option. This supplies a
6269 colon-separated list of servers which are tried in turn until one successfully
6270 handles a query, or there is a serious error. Successful handling either
6271 returns the requested data, or indicates that it does not exist. Serious errors
6272 are syntactical, or multiple values when only a single value is expected.
6273 Errors which cause the next server to be tried are connection failures, bind
6274 failures, and timeouts.
6276 For each server name in the list, a port number can be given. The standard way
6277 of specifing a host and port is to use a colon separator (RFC 1738). Because
6278 \ldap@_default@_servers\ is a colon-separated list, such colons have to be
6279 doubled. For example
6281 ldap_default_servers = ldap1.example.com::145:ldap2.example.com
6283 If \ldap@_default@_servers\ is unset, a URL with no server name is passed
6284 to the LDAP library with no server name, and the library's default (normally
6285 the local host) is used.
6287 If you are using the OpenLDAP library, you can connect to an LDAP server using
6288 a Unix domain socket instead of a TCP/IP connection. This is specified by using
6289 \"ldapi"\ instead of \"ldap"\ in LDAP queries. What follows here applies only
6290 to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
6293 For this type of connection, instead of a host name for the server, a pathname
6294 for the socket is required, and the port number is not relevant. The pathname
6295 can be specified either as an item in \ldap@_default@_servers\, or inline in
6296 the query. In the former case, you can have settings such as
6298 ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
6300 When the pathname is given in the query, you have to escape the slashes as
6301 \"%2F"\ to fit in with the LDAP URL syntax. For example:
6303 ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
6305 When Exim processes an LDAP lookup and finds that the `hostname' is really
6306 a pathname, it uses the Unix domain socket code, even if the query actually
6307 specifies \"ldap"\ or \"ldaps"\. In particular, no encryption is used for a
6308 socket connection. This behaviour means that you can use a setting of
6309 \ldap@_default@_servers\ such as in the example above with traditional \"ldap"\
6310 or \"ldaps"\ queries, and it will work. First, Exim tries a connection via
6311 the Unix domain socket; if that fails, it tries a TCP/IP connection to the
6314 If an explicit \"ldapi"\ type is given in a query when a host name is
6315 specified, an error is diagnosed. However, if there are more items in
6316 \ldap@_default@_servers\, they are tried. In other words:
6318 Using a pathname with \"ldap"\ or \"ldaps"\ forces the use of the Unix domain
6321 Using \"ldapi"\ with a host name causes an error.
6324 Using \"ldapi"\ with no host or path in the query, and no setting of
6325 \ldap@_default@_servers\, does whatever the library does by default.
6328 .section LDAP authentication and control information
6329 .index LDAP||authentication
6330 The LDAP URL syntax provides no way of passing authentication and other control
6331 information to the server. To make this possible, the URL in an LDAP query may
6332 be preceded by any number of `<<name>>=<<value>>' settings, separated by
6333 spaces. If a value contains spaces it must be enclosed in double quotes, and
6334 when double quotes are used, backslash is interpreted in the usual way inside
6337 The following names are recognized:
6339 CONNECT $rm{set a connection timeout}
6341 DEREFERENCE $rm{set the dereferencing parameter}
6342 USER $rm{set the DN, for authenticating the LDAP bind}
6343 PASS $rm{set the password, likewise}
6344 SIZE $rm{set the limit for the number of entries returned}
6345 TIME $rm{set the maximum waiting time for a query}
6347 The value of the \\DEREFERENCE\\ parameter must be one of the words `never',
6348 `searching', `finding', or `always'.
6350 Here is an example of an LDAP query in an Exim lookup that uses some of these
6351 values. This is a single line, folded for ease of reading:
6355 {user="cn=manager,o=University of Cambridge,c=UK" pass=secret
6356 ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
6359 The encoding of spaces as %20 is a URL thing which should not be done for any
6360 of the auxiliary data. Exim configuration settings that include lookups which
6361 contain password information should be preceded by `hide' to prevent non-admin
6362 users from using the \-bP-\ option to see their values.
6364 The auxiliary data items may be given in any order. The default is no
6365 connection timeout (the system timeout is used), no user or password, no limit
6366 on the number of entries returned, and no time limit on queries.
6368 The time limit for connection is given in seconds; zero means use the default.
6369 This facility is available in Netscape SDK 4.1; it may not be available in
6370 other LDAP implementations. Exim uses the given value if
6371 \\LDAP@_X@_OPT@_CONNECT@_TIMEOUT\\ is defined in the LDAP headers.
6373 When a DN is quoted in the \\USER=\\ setting for LDAP authentication, Exim
6374 removes any URL quoting that it may contain before passing it LDAP. Apparently
6375 some libraries do this for themselves, but some do not. Removing the URL
6376 quoting has two advantages:
6378 It makes it possible to use the same \quote@_ldap@_dn\ expansion for \\USER=\\
6379 DNs as with DNs inside actual queries.
6381 It permits spaces inside \\USER=\\ DNs.
6383 For example, a setting such as
6385 USER=cn=${quote_ldap_dn:$1}
6387 should work even if \$1$\ contains spaces.
6389 Expanded data for the \\PASS=\\ value should be quoted using the \quote\
6390 expansion operator, rather than the LDAP quote operators. The only reason this
6391 field needs quoting is to ensure that it conforms to the Exim syntax, which
6392 does not allow unquoted spaces. For example:
6397 The LDAP authentication mechanism can be used to check passwords as part of
6398 SMTP authentication. See the \ldapauth\ expansion string condition in chapter
6402 .section Format of data returned by LDAP
6403 .index LDAP||returned data formats
6404 The \%ldapdn%\ lookup type returns the Distinguished Name from a single entry as
6405 a sequence of values, for example
6407 cn=manager, o=University of Cambridge, c=UK
6410 The \%ldap%\ lookup type generates an error if more than one entry matches the
6411 search filter, whereas \%ldapm%\ permits this case, and inserts a newline in the
6412 result between the data from different entries. It is possible for multiple
6413 values to be returned for both \%ldap%\ and \%ldapm%\, but in the former case you
6414 know that whatever values are returned all came from a single entry in the
6417 In the common case where you specify a single attribute in your LDAP query, the
6418 result is not quoted, and does not contain the attribute name. If the attribute
6419 has multiple values, they are separated by commas.
6421 If you specify multiple attributes, the result contains space-separated, quoted
6422 strings, each preceded by the attribute name and an equals sign. Within the
6423 quotes, the quote character, backslash, and newline are escaped with
6424 backslashes, and commas are used to separate multiple values for the attribute.
6425 Apart from the escaping, the string within quotes takes the same form as the
6426 output when a single attribute is requested. Specifying no attributes is the
6427 same as specifying all of an entry's attributes.
6429 Here are some examples of the output format. The first line of each pair is an
6430 LDAP query, and the second is the data that is returned. The attribute called
6431 \attr1\ has two values, whereas \attr2\ has only one value:
6433 ldap:///o=base?attr1?sub?(uid=fred)
6436 ldap:///o=base?attr2?sub?(uid=fred)
6439 ldap:///o=base?attr1,attr2?sub?(uid=fred)
6440 attr1="value1.1, value1.2" attr2="value two"
6442 ldap:///o=base??sub?(uid=fred)
6443 objectClass="top" attr1="value1.1, value1.2" attr2="value two"
6445 The \extract\ operator in string expansions can be used to pick out individual
6446 fields from data that consists of $it{key}=$it{value} pairs. You can make use
6447 of Exim's \-be-\ option to run expansion tests and thereby check the results of
6452 .section More about NIS+
6453 .rset SECTnisplus "~~chapter.~~section"
6454 .index NIS@+ lookup type
6456 NIS+ queries consist of a NIS+ \*indexed name*\ followed by an optional colon
6457 and field name. If this is given, the result of a successful query is the
6458 contents of the named field; otherwise the result consists of a concatenation
6459 of \*field-name=field-value*\ pairs, separated by spaces. Empty values and
6460 values containing spaces are quoted. For example, the query
6462 [name=mg1456],passwd.org_dir
6464 might return the string
6466 name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
6467 home=/home/mg1456 shell=/bin/bash shadow=""
6469 (split over two lines here to fit on the page), whereas
6471 [name=mg1456],passwd.org_dir:gcos
6477 with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
6478 for the given indexed key. The effect of the \quote@_nisplus\ expansion
6479 operator is to double any quote characters within the text.
6482 .section More about MySQL, PostgreSQL, Oracle, and Interbase
6483 .rset SECTsql "~~chapter.~~section"
6484 .index MySQL||lookup type
6485 .index PostgreSQL lookup type
6486 .index lookup||MySQL
6487 .index lookup||PostgreSQL
6488 .index Oracle||lookup type
6489 .index lookup||Oracle
6490 .index Interbase lookup type
6491 .index lookup||Interbase
6492 If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the
6493 \mysql@_servers\, \pgsql@_servers\, \oracle@_servers\, or \ibase@_servers\
6494 option (as appropriate) must be set to a colon-separated list of server
6495 information. Each item in the list is a slash-separated list of four items:
6496 host name, database name, user name, and password. In the case of Oracle, the
6497 host name field is used for the `service name', and the database name field is
6498 not used and should be empty. For example:
6500 hide oracle_servers = oracle.plc.example//ph10/abcdwxyz
6502 Because password data is sensitive, you should always precede the setting with
6503 `hide', to prevent non-admin users from obtaining the setting via the \-bP-\
6504 option. Here is an example where two MySQL servers are listed:
6506 hide mysql_servers = localhost/users/root/secret:\
6507 otherhost/users/root/othersecret
6509 For MySQL and PostgreSQL, a host may be specified as <<name>>:<<port>> but
6510 because this is a colon-separated list, the colon has to be doubled.
6512 For each query, these parameter groups are tried in order until a connection
6513 and a query succeeds. Queries for these databases are SQL statements, so an
6517 ${lookup mysql{select mailbox from users where id='ph10'}{$value}fail}
6519 If the result of the query contains more than one field, the data for
6520 each field in the row is returned, preceded by its name, so the result
6524 ${lookup pgsql{select home,name from users where id='ph10'}{$value}}
6528 home=/home/ph10 name="Philip Hazel"
6530 Values containing spaces and empty values are double quoted, with embedded
6531 quotes escaped by a backslash.
6533 If the result of the query contains just one field, the value is passed back
6534 verbatim, without a field name, for example:
6538 If the result of the query yields more than one row, it is all concatenated,
6539 with a newline between the data for each row.
6541 The \quote@_mysql\, \quote@_pgsql\, and \quote@_oracle\ expansion operators
6542 convert newline, tab, carriage return, and backspace to @\n, @\t, @\r, and @\b
6543 respectively, and the characters single-quote, double-quote, and backslash
6544 itself are escaped with backslashes. The \quote@_pgsql\ expansion operator, in
6545 addition, escapes the percent and underscore characters. This cannot be done
6546 for MySQL because these escapes are not recognized in contexts where these
6547 characters are not special.
6550 .section Special MySQL features
6551 For MySQL, an empty host name or the use of `localhost' in \mysql@_servers\
6552 causes a connection to the server on the local host by means of a Unix domain
6553 socket. An alternate socket can be specified in parentheses. The full syntax of
6554 each item in \mysql@_servers\ is:
6556 <<hostname>>@:@:<<port>>(<<socket name>>)/<<database>>/<<user>>/<<password>>
6558 Any of the three sub-parts of the first field can be omitted. For normal use on
6559 the local host it can be left blank or set to just `localhost'.
6561 No database need be supplied -- but if it is absent here, it must be given in
6564 If a MySQL query is issued that does not request any data (an insert, update,
6565 or delete command), the result of the lookup is the number of rows affected.
6569 .section Special PostgreSQL features
6570 PostgreSQL lookups can also use Unix domain socket connections to the database.
6571 This is usually faster and costs less CPU time than a TCP/IP connection.
6572 However it can be used only if the mail server runs on the same machine as the
6573 database server. A configuration line for PostgreSQL via Unix domain sockets
6576 hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
6578 In other words, instead of supplying a host name, a path to the socket is
6579 given. The path name is enclosed in parentheses so that its slashes aren't
6580 visually confused with the delimiters for the other server parameters.
6582 If a PostgreSQL query is issued that does not request any data (an insert,
6583 update, or delete command), the result of the lookup is the number of rows
6593 . ============================================================================
6594 .chapter Domain, host, address, and local part lists
6595 .set runningfoot "domain, host, and address lists"
6596 .rset CHAPdomhosaddlists "~~chapter"
6597 .index list||of domains, hosts, etc.
6598 A number of Exim configuration options contain lists of domains, hosts,
6599 email addresses, or local parts. For example, the \hold@_domains\ option
6600 contains a list of domains whose delivery is currently suspended. These lists
6601 are also used as data in ACL statements (see chapter ~~CHAPACL).
6603 Each item in one of these lists is a pattern to be matched against a domain,
6604 host, email address, or local part, respectively. In the sections below, the
6605 different types of pattern for each case are described, but first we cover some
6606 general facilities that apply to all four kinds of list.
6609 .section Expansion of lists
6610 .index expansion||of lists
6611 Each list is expanded as a single string before it is used. If the expansion is
6612 forced to fail, Exim behaves as if the item it is testing (domain, host,
6613 address, or local part) is not in the list. Other expansion failures cause
6616 If an item in a list is a regular expression, backslashes, dollars and possibly
6617 other special characters in the expression must be protected against
6618 misinterpretation by the string expander. The easiest way to do this is to use
6619 the \"@\N"\ expansion feature to indicate that the contents of the regular
6620 expression should not be expanded. For example, in an ACL you might have:
6622 deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N :
6623 ${lookup{$domain}lsearch{/badsenders/bydomain}}
6625 The first item is a regular expression that is protected from expansion by
6626 \"@\N"\, whereas the second uses the expansion to obtain a list of unwanted
6627 senders based on the receiving domain.
6629 After expansion, the list is split up into separate items for matching.
6630 Normally, colon is used as the separator character, but this can be varied if
6631 necessary, as described in section ~~SECTlistconstruct.
6634 .section Negated items in lists
6635 .index list||negation
6636 .index negation in lists
6637 Items in a list may be positive or negative. Negative items are indicated by a
6638 leading exclamation mark, which may be followed by optional white space. A list
6639 defines a set of items (domains, etc). When Exim processes one of these lists,
6640 it is trying to find out whether a domain, host, address, or local part
6641 (respectively) is in the set that is defined by the list. It works like this:
6643 The list is scanned from left to right. If a positive item is matched, the
6644 subject that is being checked is in the set; if a negative item is matched, the
6645 subject is not in the set. If the end of the list is reached without the
6646 subject having matched any of the patterns, it is in the set if the last item
6647 was a negative one, but not if it was a positive one. For example, the list in
6649 domainlist relay_domains = !a.b.c : *.b.c
6651 matches any domain ending in \*.b.c*\ except for \*a.b.c*\. Domains that match
6652 neither \*a.b.c*\ nor \*@*.b.c*\ do not match, because the last item in the
6653 list is positive. However, if the setting were
6655 domainlist relay_domains = !a.b.c
6657 then all domains other than \*a.b.c*\ would match because the last item in the
6658 list is negative. In other words, a list that ends with a negative item behaves
6659 as if it had an extra item \":*"\ on the end.
6661 Another way of thinking about positive and negative items in lists is to read
6662 the connector as `or' after a positive item and as `and' after a negative
6666 .section File names in lists
6667 .rset SECTfilnamlis "~~chapter.~~section"
6668 .index list||file name in
6669 If an item in a domain, host, address, or local part list is an absolute file
6670 name (beginning with a slash character), each line of the file is read and
6671 processed as if it were an independent item in the list, except that further
6672 file names are not allowed,
6673 and no expansion of the data from the file takes place.
6674 Empty lines in the file are ignored, and the file may also contain comment
6677 For domain and host lists, if a @# character appears anywhere in a line of the
6678 file, it and all following characters are ignored.
6680 Because local parts may legitimately contain @# characters, a comment in an
6681 address list or local part list file is recognized only if @# is preceded by
6682 white space or the start of the line. For example:
6684 not#comment@x.y.z # but this is a comment
6687 Putting a file name in a list has the same effect as inserting each line of the
6688 file as an item in the list (blank lines and comments excepted). However, there
6689 is one important difference: the file is read each time the list is processed,
6690 so if its contents vary over time, Exim's behaviour changes.
6692 If a file name is preceded by an exclamation mark, the sense of any match
6693 within the file is inverted. For example, if
6695 hold_domains = !/etc/nohold-domains
6697 and the file contains the lines
6702 then \*a.b.c*\ is in the set of domains defined by \hold@_domains\, whereas any
6703 domain matching \"*.b.c"\ is not.
6706 .section An lsearch file is not an out-of-line list
6707 As will be described in the sections that follow, lookups can be used in lists
6708 to provide indexed methods of checking list membership. There has been some
6709 confusion about the way \%lsearch%\ lookups work in lists. Because
6710 an \%lsearch%\ file contains plain text and is scanned sequentially, it is
6711 sometimes thought that it is allowed to contain wild cards and other kinds of
6712 non-constant pattern. This is not the case. The keys in an \%lsearch%\ file are
6713 always fixed strings, just as for any other single-key lookup type.
6715 If you want to use a file to contain wild-card patterns that form part of a
6716 list, just give the file name on its own, without a search type, as described
6717 in the previous section.
6721 .section Named lists
6722 .rset SECTnamedlists "~~chapter.~~section"
6725 A list of domains, hosts, email addresses, or local parts can be given a name
6726 which is then used to refer to the list elsewhere in the configuration. This is
6727 particularly convenient if the same list is required in several different
6728 places. It also allows lists to be given meaningful names, which can improve
6729 the readability of the configuration. For example, it is conventional to define
6730 a domain list called \*local@_domains*\ for all the domains that are handled
6731 locally on a host, using a configuration line such as
6733 domainlist local_domains = localhost:my.dom.example
6735 Named lists are referenced by giving their name preceded by a plus sign, so,
6736 for example, a router that is intended to handle local domains would be
6737 configured with the line
6739 domains = +local_domains
6741 The first router in a configuration is often one that handles all domains
6742 except the local ones, using a configuration with a negated item like this:
6746 domains = ! +local_domains
6747 transport = remote_smtp
6750 The four kinds of named list are created by configuration lines starting with
6751 the words \domainlist\, \hostlist\, \addresslist\, or \localpartlist\,
6752 respectively. Then there follows the name that you are defining, followed by an
6753 equals sign and the list itself. For example:
6755 hostlist relay_hosts = 192.168.23.0/24 : my.friend.example
6756 addresslist bad_senders = cdb;/etc/badsenders
6758 A named list may refer to other named lists:
6760 domainlist dom1 = first.example : second.example
6761 domainlist dom2 = +dom1 : third.example
6762 domainlist dom3 = fourth.example : +dom2 : fifth.example
6765 \**Warning**\: If the last item in a referenced list is a negative one, the
6766 effect may not be what you intended, because the negation does not propagate
6767 out to the higher level. For example, consider:
6769 domainlist dom1 = !a.b
6770 domainlist dom2 = +dom1 : *.b
6772 The second list specifies `either in the \dom1\ list or \*@*.b*\'. The first
6773 list specifies just `not \*a.b*\', so the domain \*x.y*\ matches it. That means
6774 it matches the second list as well. The effect is not the same as
6776 domainlist dom2 = !a.b : *.b
6778 where \*x.y*\ does not match. It's best to avoid negation altogether in
6779 referenced lists if you can.
6781 Named lists may have a performance advantage. When Exim is routing an
6782 address or checking an incoming message, it caches the result of tests on named
6783 lists. So, if you have a setting such as
6785 domains = +local_domains
6787 on several of your routers
6788 or in several ACL statements,
6789 the actual test is done only for the first one. However, the caching works only
6790 if there are no expansions within the list itself or any sublists that it
6791 references. In other words, caching happens only for lists that are known to be
6792 the same each time they are referenced.
6794 By default, there may be up to 16 named lists of each type. This limit can be
6795 extended by changing a compile-time variable. The use of domain and host lists
6796 is recommended for concepts such as local domains, relay domains, and relay
6797 hosts. The default configuration is set up like this.
6800 .section Named lists compared with macros
6801 .index list||named compared with macro
6802 .index macro||compared with named list
6803 At first sight, named lists might seem to be no different from macros in the
6804 configuration file. However, macros are just textual substitutions. If you
6807 ALIST = host1 : host2
6808 auth_advertise_hosts = !ALIST
6810 it probably won't do what you want, because that is exactly the same as
6812 auth_advertise_hosts = !host1 : host2
6814 Notice that the second host name is not negated. However, if you use a host
6817 hostlist alist = host1 : host2
6818 auth_advertise_hosts = ! +alist
6820 the negation applies to the whole list, and so that is equivalent to
6822 auth_advertise_hosts = !host1 : !host2
6827 .section Named list caching
6828 .index list||caching of named
6829 .index caching||named lists
6830 While processing a message, Exim caches the result of checking a named list if
6831 it is sure that the list is the same each time. In practice, this means that
6832 the cache operates only if the list contains no @$ characters, which guarantees
6833 that it will not change when it is expanded. Sometimes, however, you may have
6834 an expanded list that you know will be the same each time within a given
6835 message. For example:
6837 domainlist special_domains = \
6838 ${lookup{$sender_host_address}cdb{/some/file}}
6840 This provides a list of domains that depends only on the sending host's IP
6841 address. If this domain list is referenced a number of times (for example,
6842 in several ACL lines, or in several routers) the result of the check is not
6843 cached by default, because Exim does not know that it is going to be the
6844 same list each time.
6846 By appending \"@_cache"\ to \"domainlist"\ you can tell Exim to go ahead and
6847 cache the result anyway. For example:
6849 domainlist_cache special_domains = ${lookup{...
6851 If you do this, you should be absolutely sure that caching is going to do
6852 the right thing in all cases. When in doubt, leave it out.
6856 .section Domain lists
6857 .rset SECTdomainlist "~~chapter.~~section"
6858 .index domain list||patterns for
6859 .index list||domain list
6860 Domain lists contain patterns that are to be matched against a mail domain.
6861 The following types of item may appear in domain lists:
6863 .index primary host name
6864 .index host||name, matched in domain list
6865 .index \primary@_hostname\
6866 .index domain list||matching primary host name
6867 .index @@ in a domain list
6868 If a pattern consists of a single @@ character, it matches the local host name,
6869 as set by the \primary@_hostname\ option (or defaulted). This makes it possible
6870 to use the same configuration file on several different hosts that differ only
6873 .index @@[] in a domain list
6874 .index domain list||matching local IP interfaces
6875 .index domain literal
6876 If a pattern consists of the string \"@@[]"\ it matches any local IP interface
6877 address, enclosed in square brackets, as in an email address that contains a
6880 In today's Internet, the use of domain literals is controversial.
6884 .index @@mx@_primary
6885 .index @@mx@_secondary
6886 .index domain list||matching MX pointers to local host
6887 If a pattern consists of the string \"@@mx@_any"\ it matches any domain that
6888 has an MX record pointing to the local host or to any host that is listed in
6889 .index \hosts@_treat@_as@_local\
6890 \hosts@_treat@_as@_local\. The items \"@@mx@_primary"\ and \"@@mx@_secondary"\
6891 are similar, except that the first matches only when a primary MX target is the
6892 local host, and the second only when no primary MX target is the local host,
6893 but a secondary MX target is. `Primary' means an MX record with the lowest
6894 preference value -- there may of course be more than one of them.
6897 The MX lookup that takes place when matching a pattern of this type is
6898 performed with the resolver options for widening names turned off. Thus, for
6899 example, a single-component domain will \*not*\ be expanded by adding the
6900 resolver's default domain. See the \qualify@_single\ and \search@_parents\
6901 options of the \%dnslookup%\ router for a discussion of domain widening.
6903 Sometimes you may want to ignore certain IP addresses when using one of these
6904 patterns. You can specify this by following the pattern with \"/ignore=<<ip
6905 list>>"\, where <<ip list>> is a list of IP addresses. These addresses are
6906 ignored when processing the pattern (compare the \ignore@_target@_hosts\ option
6907 on a router). For example:
6909 domains = @mx_any/ignore=127.0.0.1
6911 This example matches any domain that has an MX record pointing to one of
6912 the local host's IP addresses other than 127.0.0.1.
6914 The list of IP addresses is in fact processed by the same code that processes
6915 host lists, so it may contain CIDR-coded network specifications and it may also
6916 contain negative items.
6918 Because the list of IP addresses is a sublist within a domain list, you have to
6919 be careful about delimiters if there is more than one address. Like any other
6920 list, the default delimiter can be changed. Thus, you might have:
6922 domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \
6923 an.other.domain : ...
6925 so that the sublist uses semicolons for delimiters. When IPv6 addresses are
6926 involved, it is easiest to change the delimiter for the main list as well:
6928 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
6929 an.other.domain ? ...
6934 .index asterisk||in domain list
6935 .index domain list||asterisk in
6936 .index domain list||matching `ends with'
6937 If a pattern starts with an asterisk, the remaining characters of the pattern
6938 are compared with the terminating characters of the domain. The use of `$*$' in
6939 domain lists differs from its use in partial matching lookups. In a domain
6940 list, the character following the asterisk need not be a dot, whereas partial
6941 matching works only in terms of dot-separated components. For example, a domain
6942 list item such as \"*key.ex"\ matches \*donkey.ex*\ as well as
6945 .index regular expressions||in domain list
6946 .index domain list||matching regular expression
6947 If a pattern starts with a circumflex character, it is treated as a regular
6948 expression, and matched against the domain using a regular expression matching
6949 function. The circumflex is treated as part of the regular expression.
6950 References to descriptions of the syntax of regular expressions are given in
6951 chapter ~~CHAPregexp.
6953 \**Warning**\: Because domain lists are expanded before being processed, you
6954 must escape any backslash and dollar characters in the regular expression, or
6955 use the special \"@\N"\ sequence (see chapter ~~CHAPexpand) to specify that it
6956 is not to be expanded (unless you really do want to build a regular expression
6957 by expansion, of course).
6959 .index lookup||in domain list
6960 .index domain list||matching by lookup
6961 If a pattern starts with the name of a single-key lookup type followed by a
6962 semicolon (for example, `dbm;' or `lsearch;'), the remainder of the pattern
6963 must be a file name in a suitable format for the lookup type. For example, for
6964 `cdb;' it must be an absolute path:
6966 domains = cdb;/etc/mail/local_domains.cdb
6968 The appropriate type of lookup is done on the file using the domain name as the
6969 key. In most cases, the data that is looked up is not used; Exim is interested
6970 only in whether or not the key is present in the file. However, when a lookup
6971 is used for the \domains\ option on a router
6972 or a \domains\ condition in an ACL statement, the data is preserved in the
6973 \$domain@_data$\ variable and can be referred to in other router options or
6974 other statements in the same ACL.
6976 Any of the single-key lookup type names may be preceded by `partial<<n>>-',
6977 where the <<n>> is optional, for example,
6979 domains = partial-dbm;/partial/domains
6981 This causes partial matching logic to be invoked; a description of how this
6982 works is given in section ~~SECTpartiallookup.
6984 .index asterisk||in lookup type
6985 Any of the single-key lookup types may be followed by an asterisk. This causes
6986 a default lookup for a key consisting of a single asterisk to be done if the
6987 original lookup fails. This is not a useful feature when using a domain list to
6988 select particular domains (because any domain would match), but it might have
6989 value if the result of the lookup is being used via the \$domain@_data$\
6992 If the pattern starts with the name of a query-style lookup type followed by a
6993 semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern
6994 must be an appropriate query for the lookup type, as described in chapter
6995 ~~CHAPfdlookup. For example:
6997 hold_domains = mysql;select domain from holdlist \
6998 where domain = '$domain';
7000 In most cases, the data that is looked up is not used (so for an SQL query, for
7001 example, it doesn't matter what field you select). Exim is interested only in
7002 whether or not the query succeeds. However, when a lookup is used for the
7003 \domains\ option on a router, the data is preserved in the \$domain@_data$\
7004 variable and can be referred to in other options.
7006 .index domain list||matching literal domain name
7007 If none of the above cases apply, a caseless textual comparison is made between
7008 the pattern and the domain.
7011 Here is an example that uses several different kinds of pattern:
7013 domainlist funny_domains = \
7016 *.foundation.fict.example : \
7017 \N^[1-2]\d{3}\.fict\.example$\N : \
7018 partial-dbm;/opt/data/penguin/book : \
7019 nis;domains.byname : \
7020 nisplus;[name=$domain,status=local],domains.org_dir
7022 There are obvious processing trade-offs among the various matching modes. Using
7023 an asterisk is faster than a regular expression, and listing a few names
7024 explicitly probably is too. The use of a file or database lookup is expensive,
7025 but may be the only option if hundreds of names are required. Because the
7026 patterns are tested in order, it makes sense to put the most commonly matched
7031 .rset SECThostlist "~~chapter.~~section"
7032 .index host list||patterns in
7033 .index list||host list
7034 Host lists are used to control what remote hosts are allowed to do. For
7035 example, some hosts may be allowed to use the local host as a relay, and some
7036 may be permitted to use the SMTP \\ETRN\\ command. Hosts can be identified in
7037 two different ways, by name or by IP address. In a host list, some types of
7038 pattern are matched to a host name, and some are matched to an IP address.
7039 You need to be particularly careful with this when single-key lookups are
7040 involved, to ensure that the right value is being used as the key.
7042 .section Special host list patterns
7043 .index empty item in hosts list
7044 .index host list||empty string in
7045 If a host list item is the empty string, it matches only when no remote host is
7046 involved. This is the case when a message is being received from a local
7047 process using SMTP on the standard input, that is, when a TCP/IP connection is
7050 .index asterisk||in host list
7051 The special pattern `$*$' in a host list matches any host or no host. Neither
7052 the IP address nor the name is actually inspected.
7055 .section Host list patterns that match by IP address
7056 .rset SECThoslispatip "~~chapter.~~section"
7057 .index host list||matching IP addresses
7058 If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
7059 the incoming address actually appears in the IPv6 host as
7060 `@:@:$tt{ffff}:<<v4address>>'. When such an address is tested against a host
7061 list, it is converted into a traditional IPv4 address first. (Not all operating
7062 systems accept IPv4 calls on IPv6 sockets, as there have been some security
7065 The following types of pattern in a host list check the remote host by
7066 inspecting its IP address:
7068 If the pattern is a plain domain name (not a regular expression, not starting
7069 with $*$, not a lookup of any kind), Exim calls the operating system function
7070 to find the associated IP address(es). Exim uses the newer
7071 \*getipnodebyname()*\ function when available, otherwise \*gethostbyname()*\.
7072 This typically causes a forward DNS lookup of the name. The result is compared
7073 with the IP address of the subject host.
7076 If there is a temporary problem (such as a DNS timeout) with the host name
7077 lookup, a temporary error occurs. For example, if the list is being used in an
7078 ACL condition, the ACL gives a `defer' response, usually leading to a temporary
7079 SMTP error code. If no IP address can be found for the host name, what happens
7080 is described in section ~~SECTbehipnot below.
7084 .index @@ in a host list
7085 If the pattern is `@@', the primary host name is substituted and used as a
7086 domain name, as just described.
7088 If the pattern is an IP address, it is matched against the IP address of the
7089 subject host. IPv4 addresses are given in the normal `dotted-quad' notation.
7090 IPv6 addresses can be given in colon-separated format, but the colons have to
7091 be doubled so as not to be taken as item separators when the default list
7092 separator is used. IPv6 addresses are recognized even when Exim is compiled
7093 without IPv6 support. This means that if they appear in a host list on an
7094 IPv4-only host, Exim will not treat them as host names. They are just addresses
7095 that can never match a client host.
7097 .index @@[] in a host list
7098 If the pattern is `@@[]', it matches the IP address of any IP interface on
7099 the local host. For example, if the local host is an IPv4 host with one
7100 interface address 10.45.23.56, these two ACL statements have the same effect:
7102 accept hosts = 127.0.0.1 : 10.45.23.56
7106 If the pattern is an IP address followed by a slash and a mask length (for
7107 example 10.11.42.0/24), it is matched against the IP address of the subject
7108 host under the given mask.
7109 This allows, an entire network of hosts to be included (or excluded) by a
7111 .index CIDR notation
7112 The mask uses CIDR notation; it specifies the number of address bits that must
7113 match, starting from the most significant end of the address.
7115 \**Note**\: the mask is \*not*\ a count of addresses, nor is it the high number
7116 of a range of addresses. It is the number of bits in the network portion of the
7117 address. The above example specifies a 24-bit netmask, so it matches all 256
7118 addresses in the 10.11.42.0 network. An item such as
7122 matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of
7123 32 for an IPv4 address is the same as no mask at all; just a single address
7126 Here is another example which shows an IPv4 and an IPv6 network:
7128 recipient_unqualified_hosts = 192.168.0.0/16: \
7129 3ffe::ffff::836f::::/48
7131 The doubling of list separator characters applies only when these items
7132 appear inline in a host list. It is not required when indirecting via a file.
7135 recipient_unqualified_hosts = /opt/exim/unqualnets
7137 could make use of a file containing
7142 to have exactly the same effect as the previous example. When listing IPv6
7143 addresses inline, it is usually more convenient to use the facility for
7144 changing separator characters. This list contains the same two networks:
7146 recipient_unqualified_hosts = <; 172.16.0.0/12; \
7149 The separator is changed to semicolon by the leading `<;' at the start of the
7154 .section Host list patterns for single-key lookups by host address
7155 .rset SECThoslispatsikey "~~chapter.~~section"
7156 .index host list||lookup of IP address
7157 When a host is to be identified by a single-key lookup of its complete IP
7158 address, the pattern takes this form:
7160 net-<<single-key-search-type>>;<<search-data>>
7164 hosts_lookup = net-cdb;/hosts-by-ip.db
7166 The text form of the IP address of the subject host is used as the lookup key.
7167 IPv6 addresses are converted to an unabbreviated form, using lower case
7168 letters, with dots as separators because colon is the key terminator in
7169 \%lsearch%\ files. [Colons can in fact be used in keys in \%lsearch%\ files by
7170 quoting the keys, but this is a facility that was added later.] The data
7171 returned by the lookup is not used.
7173 .index IP address||masking
7174 .index host list||masked IP address
7175 Single-key lookups can also be performed using masked IP addresses, using
7176 patterns of this form:
7178 net<<number>>-<<single-key-search-type>>;<<search-data>>
7182 net24-dbm;/networks.db
7184 The IP address of the subject host is masked using <<number>> as the mask
7185 length. A textual string is constructed from the masked value, followed by the
7186 mask, and this is used as the lookup key. For example, if the host's IP address
7187 is 192.168.34.6, the key that is looked up for the above example is
7188 `192.168.34.0/24'. IPv6 addresses are converted to a text value using lower
7189 case letters and dots as separators instead of the more usual colon, because
7190 colon is the key terminator in \%lsearch%\ files. Full, unabbreviated IPv6
7191 addresses are always used.
7193 \**Warning**\: Specifing \net32@-\ (for an IPv4 address) or \net128@-\ (for an
7194 IPv6 address) is not the same as specifing just \net@-\ without a number. In
7195 the former case the key strings include the mask value, whereas in the latter
7196 case the IP address is used on its own.
7199 .section Host list patterns that match by host name
7200 .rset SECThoslispatnam "~~chapter.~~section"
7201 .index host||lookup failures
7202 .index unknown host name
7203 .index host list||matching host name
7204 There are several types of pattern that require Exim to know the name of the
7205 remote host. These are either wildcard patterns or lookups by name. (If a
7206 complete hostname is given without any wildcarding, it is used to find an IP
7207 address to match against, as described in the section ~~SECThoslispatip above.)
7209 If the remote host name is not already known when Exim encounters one of these
7210 patterns, it has to be found from the IP address.
7212 Although many sites on the Internet are conscientious about maintaining reverse
7213 DNS data for their hosts, there are also many that do not do this.
7214 Consequently, a name cannot always be found, and this may lead to unwanted
7215 effects. Take care when configuring host lists with wildcarded name patterns.
7216 Consider what will happen if a name cannot be found.
7218 Because of the problems of determining host names from IP addresses, matching
7219 against host names is not as common as matching against IP addresses.
7221 By default, in order to find a host name, Exim first does a reverse DNS lookup;
7222 if no name is found in the DNS, the system function (\*gethostbyaddr()*\ or
7223 \*getipnodebyaddr()*\ if available) is tried. The order in which these lookups
7224 are done can be changed by setting the \host@_lookup@_order\ option.
7226 There are some options that control what happens if a host name cannot be
7227 found. These are described in section ~~SECTbehipnot below.
7231 .index host||alias for
7232 .index alias for host
7233 As a result of aliasing, hosts may have more than one name. When processing any
7234 of the following types of pattern, all the host's names are checked:
7236 .index asterisk||in host list
7237 If a pattern starts with `$*$' the remainder of the item must match the end of
7238 the host name. For example, \"*.b.c"\ matches all hosts whose names end in
7239 \*.b.c*\. This special simple form is provided because this is a very common
7240 requirement. Other kinds of wildcarding require the use of a regular
7243 .index regular expressions||in host list
7244 .index host list||regular expression in
7245 If the item starts with `@^' it is taken to be a regular expression which is
7246 matched against the host name. For example,
7250 is a regular expression that matches either of the two hosts \*a.c.d*\ or
7251 \*b.c.d*\. When a regular expression is used in a host list, you must take care
7252 that backslash and dollar characters are not misinterpreted as part of the
7253 string expansion. The simplest way to do this is to use \"@\N"\ to mark that
7254 part of the string as non-expandable. For example:
7256 sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
7259 \**Warning**\: If you want to match a complete host name, you must include the
7260 \"@$"\ terminating metacharacter in the regular expression, as in the above
7261 example. Without it, a match at the start of the host name is all that is
7268 .section Behaviour when an IP address or name cannot be found
7269 .rset SECTbehipnot "~~chapter.~~section"
7270 .index host||lookup failures
7271 While processing a host list, Exim may need to look up an IP address from a
7272 name (see section ~~SECThoslispatip), or it may need to look up a host name
7273 from an IP address (see section ~~SECThoslispatnam). In either case, the
7274 behaviour when it fails to find the information it is seeking is the same.
7276 .index \"+include@_unknown"\
7277 .index \"+ignore@_unknown"\
7278 By default, Exim behaves as if the host does not match the list. This may not
7279 always be what you want to happen. To change Exim's behaviour, the special
7280 items \"+include@_unknown"\ or \"+ignore@_unknown"\ may appear in the list (at
7281 top level -- they are not recognized in an indirected file).
7283 If any item that follows \"+include@_unknown"\ requires information that
7284 cannot found, Exim behaves as if the host does match the list. For example,
7286 host_reject_connection = +include_unknown:*.enemy.ex
7288 rejects connections from any host whose name matches \"*.enemy.ex"\, and also
7289 any hosts whose name it cannot find.
7291 If any item that follows \"+ignore@_unknown"\ requires information that cannot
7292 be found, Exim ignores that item and proceeds to the rest of the list. For
7295 accept hosts = +ignore_unknown : friend.example : \
7298 accepts from any host whose name is \*friend.example*\ and from 192.168.4.5,
7299 whether or not its host name can be found. Without \"+ignore@_unknown"\, if no
7300 name can be found for 192.168.4.5, it is rejected.
7302 Both \"+include@_unknown"\ and \"+ignore@_unknown"\ may appear in the same
7303 list. The effect of each one lasts until the next, or until the end of the
7306 \**Note**\: This section applies to permanent lookup failures. It does \*not*\
7307 apply to temporary DNS errors. They always cause a defer action.
7311 .section Host list patterns for single-key lookups by host name
7312 .rset SECThoslispatnamsk "~~chapter.~~section"
7313 .index host||lookup failures
7314 .index unknown host name
7315 .index host list||matching host name
7316 If a pattern is of the form
7318 <<single-key-search-type>>;<<search-data>>
7322 dbm;/host/accept/list
7324 a single-key lookup is performend, using the host name as its key. If the
7325 lookup succeeds, the host matches the item. The actual data that is looked up
7328 \**Reminder**\: With this kind of pattern, you must have host $it{names} as
7329 keys in the file, not IP addresses. If you want to do lookups based on IP
7330 addresses, you must precede the search type with `net-' (see section
7331 ~~SECThoslispatsikey). There is, however, no reason why you could not use two
7332 items in the same list, one doing an address lookup and one doing a name
7333 lookup, both using the same file.
7336 .section Host list patterns for query-style lookups
7337 If a pattern is of the form
7339 <<query-style-search-type>>;<<query>>
7341 the query is obeyed, and if it succeeds, the host matches the item. The actual
7342 data that is looked up is not used. The variables \$sender@_host@_address$\ and
7343 \$sender@_host@_name$\ can be used in the query. For example:
7345 hosts_lookup = pgsql;\
7346 select ip from hostlist where ip='$sender_host_address'
7348 The value of \$sender@_host@_address$\ for an IPv6 address uses colon
7349 separators. You can use the \sg\ expansion item to change this if you need to.
7350 If you want to use masked IP addresses in database queries, you can use the
7351 \mask\ expansion operator.
7353 If the query contains a reference to \$sender@_host@_name$\, Exim automatically
7354 looks up the host name if has not already done so. (See section
7355 ~~SECThoslispatnam for comments on finding host names.)
7357 Historical note: prior to release 4.30, Exim would always attempt to find a
7358 host name before running the query, unless the search type was preceded by
7359 \"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is
7360 still recognized for query-style lookups, but its presence or absence has no
7361 effect. (Of course, for single-key lookups, \"net-"\ $it{is} important.)
7364 .section Mixing wildcarded host names and addresses in host lists
7365 .rset SECTmixwilhos "~~chapter.~~section"
7366 .index host list||mixing names and addresses in
7367 If you have name lookups or wildcarded host names and IP addresses in the same
7368 host list, you should normally put the IP addresses first. For example, in an
7371 accept hosts = 10.9.8.7 : *.friend.example
7373 The reason for this lies in the left-to-right way that Exim processes lists.
7374 It can test IP addresses without doing any DNS lookups, but when it reaches an
7375 item that requires a host name, it fails if it cannot find a host name to
7376 compare with the pattern. If the above list is given in the opposite order, the
7377 \accept\ statement fails for a host whose name cannot be found, even if its
7378 IP address is 10.9.8.7.
7380 If you really do want to do the name check first, and still recognize the IP
7381 address, you can rewrite the ACL like this:
7383 accept hosts = *.friend.example
7384 accept hosts = 10.9.8.7
7386 If the first \accept\ fails, Exim goes on to try the second one. See chapter
7387 ~~CHAPACL for details of ACLs.
7392 .section Address lists
7393 .index list||address list
7394 .index address list||empty item
7395 .index address list||patterns
7396 .rset SECTaddresslist "~~chapter.~~section"
7397 Address lists contain patterns that are matched against mail addresses. There
7398 is one special case to be considered: the sender address of a bounce message is
7399 always empty. You can test for this by providing an empty item in an address
7400 list. For example, you can set up a router to process bounce messages by
7401 using this option setting:
7405 The presence of the colon creates an empty item. If you do not provide any
7406 data, the list is empty and matches nothing. The empty sender can also be
7407 detected by a regular expression that matches an empty string.
7409 The following kinds of pattern are supported in address lists:
7411 .index regular expressions||in address list
7412 .index address list||regular expression in
7413 If (after expansion) a pattern starts with `@^', a regular expression match is
7414 done against the complete address, with the pattern as the regular expression.
7415 You must take care that backslash and dollar characters are not misinterpreted
7416 as part of the string expansion. The simplest way to do this is to use \"@\N"\
7417 to mark that part of the string as non-expandable. For example:
7419 deny senders = \N^\d{8}.+@spamhaus.example$\N : ...
7421 The \"@\N"\ sequences are removed by the expansion, so the item does start
7422 with `@^' by the time it is being interpreted as an address pattern.
7424 .index @@@@ with single-key lookup
7425 .index address list||@@@@ lookup type
7426 .index address list||split local part and domain
7427 If a pattern starts with `@@@@' followed by a single-key lookup item
7428 (for example, \"@@@@lsearch;/some/file"\), the address that is being checked is
7429 split into a local part and a domain. The domain is looked up in the file. If
7430 it is not found, there is no match. If it is found, the data that is looked up
7431 from the file is treated as a colon-separated list of local part patterns, each
7432 of which is matched against the subject local part in turn.
7434 .index asterisk||in address list
7435 The lookup may be a partial one, and/or one involving a search for a default
7436 keyed by `$*$' (see section ~~SECTdefaultvaluelookups). The local part patterns
7437 that are looked up can be regular expressions or begin with `$*$', or even be
7438 further lookups. They may also be independently negated. For example, with
7440 deny senders = @@dbm;/etc/reject-by-domain
7442 the data from which the DBM file is built could contain lines like
7444 baddomain.com: !postmaster : *
7446 to reject all senders except \postmaster\ from that domain.
7447 .index local part||starting with !
7448 If a local part that actually begins with an exclamation mark is required, it
7449 has to be specified using a regular expression. In \%lsearch%\ files, an entry
7450 may be split over several lines by indenting the second and subsequent lines,
7451 but the separating colon must still be included at line breaks. White space
7452 surrounding the colons is ignored. For example:
7454 aol.com: spammer1 : spammer2 : ^[0-9]+$ :
7457 As in all colon-separated lists in Exim, a colon can be included in an item by
7460 If the last item in the list starts with a right angle-bracket, the remainder
7461 of the item is taken as a new key to look up in order to obtain a continuation
7462 list of local parts. The new key can be any sequence of characters. Thus one
7463 might have entries like
7465 aol.com: spammer1 : spammer 2 : >*
7466 xyz.com: spammer3 : >*
7469 in a file that was searched with \@@@@dbm$*$\, to specify a match for 8-digit
7470 local parts for all domains, in addition to the specific local parts listed for
7471 each domain. Of course, using this feature costs another lookup each time a
7472 chain is followed, but the effort needed to maintain the data is reduced.
7473 .index loop||in lookups
7474 It is possible to construct loops using this facility, and in order to catch
7475 them, the chains may be no more than fifty items long.
7477 The @@@@<<lookup>> style of item can also be used with a query-style
7478 lookup, but in this case, the chaining facility is not available. The lookup
7479 can only return a single list of local parts.
7481 .index address list||lookup for complete address
7482 Complete addresses can be looked up by using a pattern that
7483 starts with a lookup type terminated by a semicolon, follwed by the data for
7487 deny senders = cdb;/etc/blocked.senders : \
7488 mysql;select address from blocked where \
7489 address='${quote_mysql:$sender_address}'
7491 For a single-key lookup type, Exim uses the complete address as the key.
7492 Partial matching (section ~~SECTpartiallookup) cannot be used, and is ignored
7493 if specified, with an entry being written to the panic log.
7495 .index @*@@ with single-key lookup
7496 You can configure lookup defaults, as described in section
7497 ~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of
7498 default. For example, with this lookup:
7500 accept senders = lsearch*@;/some/file
7502 the file could contains lines like this:
7504 user1@domain1.example
7507 and for the sender address \*nimrod@@jaeger.example*\, the sequence of keys
7510 nimrod@jaeger.example
7514 \**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that
7515 would mean that every address matches, thus rendering the test useless.
7517 \**Warning 2**\: Do not confuse these two kinds of item:
7519 deny recipients = dbm*@;/some/file
7520 deny recipients = *@dbm;/some/file
7522 The first does a whole address lookup, with defaulting, as just described,
7523 because it starts with a lookup type. The second matches the local part and
7524 domain independently, as described in the next paragraph.
7526 If a pattern contains an @@ character, but is not a regular expression
7527 and does not begin with a lookup type
7528 as described above, the local part of the subject address is compared with the
7529 local part of the pattern, which may start with an asterisk. If the local parts
7530 match, the domain is checked in exactly the same way as for a pattern in a
7531 domain list. For example, the domain can be wildcarded, refer to a named list,
7534 deny senders = *@*.spamming.site:\
7535 *@+hostile_domains:\
7536 bozo@partial-lsearch;/list/of/dodgy/sites:\
7538 *@dbm;/bad/domains.db
7540 .index local part||starting with !
7541 .index address list||local part starting with !
7542 If a local part that begins with an exclamation mark is required, it has to be
7543 specified using a regular expression, because otherwise the exclamation mark is
7544 treated as a sign of negation.
7546 If a pattern is not one of the above syntax forms, that is, if a pattern which
7547 is not a regular expression or a lookup does not contain an @@ character, it is
7548 matched against the domain part of the subject address. The only two formats
7549 that are recognized this way are a literal domain, or a domain pattern that
7550 starts with $*$. In both these cases, the effect is the same as if \"*@@"\
7551 preceded the pattern.
7554 \**Warning**\: there is an important difference between the address list items
7555 in these two examples:
7558 senders = *@+my_list
7560 In the first one, \"my@_list"\ is a named address list, whereas in the second
7561 example it is a named domain list.
7565 .section Case of letters in address lists
7566 .rset SECTcasletadd "~~chapter.~~section"
7567 .index case of local parts
7568 .index address list||case forcing
7569 .index case forcing in address lists
7570 Domains in email addresses are always handled caselessly, but for local parts
7571 case may be significant on some systems (see \caseful@_local@_part\ for how
7572 Exim deals with this when routing addresses). However, RFC 2505 ($it{Anti-Spam
7573 Recommendations for SMTP MTAs}) suggests that matching of addresses to blocking
7574 lists should be done in a case-independent manner. Since most address lists in
7575 Exim are used for this kind of control, Exim attempts to do this by default.
7577 The domain portion of an address is always lowercased before matching it to an
7578 address list. The local part is lowercased by default, and any string
7579 comparisons that take place are done caselessly. This means that the data in
7580 the address list itself, in files included as plain file names, and in any file
7581 that is looked up using the `@@@@' mechanism, can be in any case. However, the
7582 keys in files that are looked up by a search type other than \%lsearch%\ (which
7583 works caselessly) must be in lower case, because these lookups are not
7587 To allow for the possibility of caseful address list matching, if an item in
7588 an address list is the string `+caseful', the original case of the local
7589 part is restored for any comparisons that follow, and string comparisons are no
7590 longer case-independent. This does not affect the domain, which remains in
7591 lower case. However, although independent matches on the domain alone are still
7592 performed caselessly, regular expressions that match against an entire address
7593 become case-sensitive after `+caseful' has been seen.
7596 .section Local part lists
7597 .rset SECTlocparlis "~~chapter.~~section"
7598 .index list||local part list
7599 .index local part||list
7600 Case-sensitivity in local part lists is handled in the same way as for address
7601 lists, as just described. The `+caseful' item can be used if required. In a
7602 setting of the \local@_parts\ option in a router with \caseful@_local@_part\
7603 set false, the subject is lowercased and the matching is initially
7604 case-insensitive. In this case, `+caseful' will restore case-sensitive matching
7605 in the local part list, but not elsewhere in the router. If
7606 \caseful@_local@_part\ is set true in a router, matching in the \local@_parts\
7607 option is case-sensitive from the start.
7609 If a local part list is indirected to a file (see section ~~SECTfilnamlis),
7610 comments are handled in the same way as address lists -- they are recognized
7611 only if the @# is preceded by white space or the start of the line.
7612 Otherwise, local part lists are matched in the same way as domain lists, except
7613 that the special items that refer to the local host (\"@@"\, \"@@[]"\,
7614 \"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\) are not recognized.
7615 Refer to section ~~SECTdomainlist for details of the other available item
7624 . ============================================================================
7625 .chapter String expansions
7626 .set runningfoot "string expansions"
7627 .rset CHAPexpand ~~chapter
7628 .index expansion||of strings
7629 Many strings in Exim's run time configuration are expanded before use. Some of
7630 them are expanded every time they are used; others are expanded only once.
7632 When a string is being expanded it is copied verbatim from left to right except
7633 when a dollar or backslash character is encountered. A dollar specifies the
7634 start of a portion of the string which is interpreted and replaced as described
7635 below in section ~~SECTexpansionitems onwards. Backslash is used as an escape
7636 character, as described in the following section.
7639 .section Literal text in expanded strings
7640 .rset SECTlittext "~~chapter.~~section"
7641 .index expansion||including literal text
7642 An uninterpreted dollar can be included in an expanded string by putting a
7643 backslash in front of it. A backslash can be used to prevent any special
7644 character being treated specially in an expansion, including itself. If the
7645 string appears in quotes in the configuration file, two backslashes are
7646 required because the quotes themselves cause interpretation of backslashes when
7647 the string is read in (see section ~~SECTstrings).
7649 .index expansion||non-expandable substrings
7650 A portion of the string can specified as non-expandable by placing it between
7651 two occurrences of \"@\N"\. This is particularly useful for protecting regular
7652 expressions, which often contain backslashes and dollar signs. For example:
7654 deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
7656 On encountering the first \"@\N"\, the expander copies subsequent characters
7657 without interpretation until it reaches the next \"@\N"\ or the end of the
7661 .section Character escape sequences in expanded strings
7662 .index expansion||escape sequences
7663 A backslash followed by one of the letters `n', `r', or `t' in an expanded
7664 string is recognized as an escape sequence for the character newline, carriage
7665 return, or tab, respectively. A backslash followed by up to three octal digits
7666 is recognized as an octal encoding for a single character, and a backslash
7667 followed by `x' and up to two hexadecimal digits is a hexadecimal encoding.
7669 These escape sequences are also recognized in quoted strings when they are read
7670 in. Their interpretation in expansions as well is useful for unquoted strings,
7671 and for other cases such as looked-up strings that are then expanded.
7673 .section Testing string expansions
7674 .index expansion||testing
7675 .index testing||string expansion
7676 .index \-be-\ option
7677 Many expansions can be tested by calling Exim with the \-be-\ option. This takes
7678 the command arguments, or lines from the standard input if there are no
7679 arguments, runs them through the string expansion code, and writes the results
7680 to the standard output. Variables based on configuration values are set up, but
7681 since no message is being processed, variables such as \$local@_part$\ have no
7682 value. Nevertheless the \-be-\ option can be useful for checking out file and
7683 database lookups, and the use of expansion operators such as \sg\, \substr\ and
7686 Exim gives up its root privilege when it is called with the \-be-\ option, and
7687 instead runs under the uid and gid it was called with, to prevent users from
7688 using \-be-\ for reading files to which they do not have access.
7691 .section Expansion items
7692 .rset SECTexpansionitems "~~chapter.~~section"
7693 The following items are recognized in expanded strings. White space may be used
7694 between sub-items that are keywords or substrings enclosed in braces inside an
7695 outer set of braces, to improve readability. \**Warning**\: Within braces,
7696 white space is significant.
7700 .item "@$<<variable name>>#$rm{or}#@$@{<<variable name>>@}"
7701 .index expansion||variables
7702 Substitute the contents of the named variable, for example
7707 The second form can be used to separate the name from subsequent alphanumeric
7708 characters. This form (using curly brackets) is available only for variables;
7709 it does $it{not} apply to message headers. The names of the variables are given
7710 in section ~~SECTexpvar below. If the name of a non-existent variable is given,
7711 the expansion fails.
7713 .item "@$@{<<op>>:<<string>>@}"
7714 .index expansion||operators
7715 The string is first itself expanded, and then the operation specified by <<op>>
7716 is applied to it. For example,
7720 The string starts with the first character after the colon, which may be
7721 leading white space. A list of operators is given in section ~~SECTexpop below.
7722 The operator notation is used for simple expansion items that have just one
7723 argument, because it reduces the number of braces and therefore makes the
7724 string easier to understand.
7726 .item "@$@{extract@{<<key>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
7727 .index expansion||extracting substrings by key
7728 The key and <<string1>> are first expanded separately.
7729 Leading and trailing whitespace is removed from the key (but not from any of
7731 The key must not consist entirely of digits. The expanded <<string1>> must be
7734 <<key1>> = <<value1>> <<key2>> = <<value2>> ...
7736 where the equals signs and spaces (but not both) are optional. If any of the
7737 values contain white space, they must be enclosed in double quotes, and any
7738 values that are enclosed in double quotes are subject to escape processing as
7739 described in section ~~SECTstrings. The expanded <<string1>> is searched for
7740 the value that corresponds to the key. The search is case-insensitive. If the
7741 key is found, <<string2>> is expanded, and replaces the whole item; otherwise
7742 <<string3>> is used. During the expansion of <<string2>> the variable \$value$\
7743 contains the value that has been extracted. Afterwards, it is restored to any
7744 previous value it might have had.
7746 If @{<<string3>>@} is omitted, the item is replaced by an empty string if the
7747 key is not found. If @{<<string2>>@} is also omitted, the value that was
7748 extracted is used. Thus, for example, these two expansions are identical, and
7751 @$@{extract@{gid@}{uid=1984 gid=2001@}@}
7752 @$@{extract@{gid@}{uid=1984 gid=2001@}@{@$value@}@}
7754 Instead of @{<<string3>>@} the word `fail' (not in curly brackets) can appear,
7757 @$@{extract@{Z@}@{A=... B=...@}@{@$value@} fail @}
7759 @{<<string2>>@} must be present for `fail' to be recognized. When this syntax
7760 is used, if the extraction fails, the entire string expansion fails in a way
7761 that can be detected by the code in Exim which requested the expansion. This is
7762 called `forced expansion failure', and its consequences depend on the
7763 circumstances. In some cases it is no different from any other expansion
7764 failure, but in others a different action may be taken. Such variations are
7765 mentioned in the documentation of the option which is expanded.
7768 .item "@$@{extract@{<<number>>@}@{<<separators>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
7769 .index expansion||extracting substrings by number
7770 The <<number>> argument must consist entirely of decimal digits,
7771 apart from leading and trailing whitespace, which is ignored.
7772 This is what distinguishes this form of \extract\ from the previous kind. It
7773 behaves in the same way, except that, instead of extracting a named field, it
7774 extracts from <<string1>> the field whose number is given as the first
7775 argument. You can use \$value$\ in <<string2>> or \"fail"\ instead of
7776 <<string3>> as before.
7778 The fields in the string are separated by any one of the characters in the
7779 separator string. These may include space or tab characters.
7780 The first field is numbered one. If the number is negative, the fields are
7781 counted from the end of the string, with the rightmost one numbered -1. If the
7782 number given is zero, the entire string is returned. If the modulus of the
7783 number is greater than the number of fields in the string, the result is the
7784 expansion of <<string3>>, or the empty string if <<string3>> is not provided.
7787 ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}}
7791 ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}}
7793 yields `99'. Two successive separators mean that the field between them is
7794 empty (for example, the fifth field above).
7797 .item "@$@{hash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
7798 .index hash function||textual
7799 .index expansion||textual hash
7800 This is a textual hashing function, and was the first to be implemented in
7801 early versions of Exim. In current releases, there are other hashing functions
7802 (numeric, MD5, and SHA-1), which are described below.
7804 The first two strings, after expansion, must be numbers. Call them <<m>> and
7805 <<n>>. If you are using fixed values for these numbers, that is, if <<string1>>
7806 and <<string2>> do not change when they are expanded, you can use the
7807 simpler operator notation that avoids some of the braces:
7809 @$@{hash@_<<n>>@_<<m>>:<<string>>@}
7811 The second number is optional (in both notations).
7813 If <<n>> is greater than or equal to the length of the string, the expansion
7814 item returns the string. Otherwise it computes a new string of length <<n>> by
7815 applying a hashing function to the string. The new string consists of
7816 characters taken from the first <<m>> characters of the string
7818 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
7820 If <<m>> is not present the value 26 is used, so that only lower case
7821 letters appear. For example:
7823 @$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\
7824 @$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\
7825 @$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\
7829 .item "@$header@_<<header name>>:#$rm{or}#@$h@_<<header name>>:"
7830 .item "@$bheader@_<<header name>>:#$rm{or}#@$bh@_<<header name>>:"
7831 .item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:"
7832 .index expansion||header insertion
7834 .index \$bheader@_$\
7835 .index \$rheader@_$\
7836 .index header lines||in expansion strings
7837 .index header lines||character sets
7838 .index header lines||decoding
7839 Substitute the contents of the named message header line, for example
7843 The newline that terminates a header line is not included in the expansion, but
7844 internal newlines (caused by splitting the header line over several physical
7845 lines) may be present.
7847 The difference between \rheader\, \bheader\, and \header\ is in the way the
7848 data in the header line is interpreted.
7850 \rheader\ gives the original `raw' content of the header line, with no
7851 processing at all, and without the removal of leading and trailing whitespace.
7853 .index base64 encoding||in header lines
7854 \bheader\ removes leading and trailing whitespace, and then decodes base64 or
7855 quoted-printable MIME `words' within the header text, but does no character
7856 set translation. If decoding of what looks superficially like a MIME `word'
7857 fails, the raw string is returned.
7858 .index binary zero||in header line
7859 If decoding produces a binary zero character, it is replaced by a question mark
7860 -- this is what Exim does for binary zeros that are actually received in header
7863 \header\ tries to translate the string as decoded by \bheader\ to a standard
7864 character set. This is an attempt to produce the same string as would be
7865 displayed on a user's MUA. If translation fails, the \bheader\ string is
7866 returned. Translation is attempted only on operating systems that support the
7867 \*iconv()*\ function. This is indicated by the compile-time macro
7868 \\HAVE@_ICONV\\ in a system Makefile or in \(Local/Makefile)\.
7871 In a filter file, the target character set for \header\ can be specified by a
7872 command of the following form:
7874 headers charset "UTF-8"
7876 This command affects all references to \$h@_$\ (or \$header@_$\) expansions in
7877 subsequently obeyed filter commands. In the absence of this command, the target
7878 character set in a filter is taken from the setting of the \headers@_charset\
7879 option in the runtime configuration. The value of this option defaults to the
7880 value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The ultimate default is
7883 Header names follow the syntax of RFC 2822, which states that they may contain
7884 any printing characters except space and colon. Consequently, curly brackets
7885 $it{do not} terminate header names, and should not be used to enclose them as
7886 if they were variables. Attempting to do so causes a syntax error.
7888 Only header lines that are common to all copies of a message are visible to
7889 this mechanism. These are the original header lines that are received with the
7890 message, and any that are added by
7891 an ACL \warn\ statement or by
7892 a system filter. Header lines that are added to a particular copy of a message
7893 by a router or transport are not accessible.
7895 For incoming SMTP messages, no header lines are visible in ACLs that are obeyed
7896 before the \\DATA\\ ACL, because the header structure is not set up until the
7897 message is received. Header lines that are added by \warn\ statements in a
7898 \\RCPT\\ ACL (for example) are saved until the message's incoming header lines
7899 are available, at which point they are added. When a \\DATA\\ ACL is running,
7900 however, header lines added by earlier ACLs are visible.
7902 Upper case and lower case letters are synonymous in header names. If the
7903 following character is white space, the terminating colon may be omitted, but
7904 this is not recommended, because you may then forget it when it is needed. When
7905 white space terminates the header name, it is included in the expanded string.
7906 If the message does not contain the given header, the expansion item is
7907 replaced by an empty string. (See the \def\ condition in section ~~SECTexpcond
7908 for a means of testing for the existence of a header.)
7910 If there is more than one header with the same name, they are all concatenated
7911 to form the substitution string, up to a maximum length of 64K. A newline
7912 character is inserted between each line.
7913 For the \header\ expansion, for those headers that contain lists of addresses,
7914 a comma is also inserted at the junctions between lines. This does not happen
7915 for the \rheader\ expansion.
7919 .item "@$@{hmac@{<<hashname>>@}@{<<secret>>@}@{<<string>>@}@}"
7920 .index expansion||hmac hashing
7921 This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
7922 shared secret and some text into a message authentication code, as specified in
7924 This differs from \"@$@{md5:secret@_text...@}"\ or
7925 \"@$@{sha1:secret@_text...@}"\ in that the hmac step adds a signature to the
7926 cryptographic hash, allowing for authentication that is not possible with MD5
7928 The hash name must expand to either \"md5"\ or \"sha1"\ at present. For
7931 ${hmac{md5}{somesecret}{$primary_hostname $tod_log}}
7933 For the hostname \*mail.example.com*\ and time 2002-10-17 11:30:59, this
7936 dd97e3ba5d1a61b5006108f8c8252953
7938 As an example of how this might be used, you might put in the main part of
7939 an Exim configuration:
7941 SPAMSCAN_SECRET=cohgheeLei2thahw
7943 In a router or a transport you could then have:
7946 X-Spam-Scanned: ${primary_hostname} ${message_id} \
7947 ${hmac{md5}{SPAMSCAN_SECRET}\
7948 {${primary_hostname},${message_id},$h_message-id:}}
7950 Then given a message, you can check where it was scanned by looking at the
7951 ::X-Spam-Scanned:: header line. If you know the secret, you can check that this
7952 header line is authentic by recomputing the authentication code from the host
7953 name, message ID and the ::Message-id:: header line. This can be done using
7954 Exim's \-be-\ option, or by other means, for example by using the
7955 \*hmac@_md5@_hex()*\ function in Perl.
7959 .item "@${if <<condition>> @{<<string1>>@}@{<<string2>>@}@}"
7960 .index expansion||conditional
7961 If <<condition>> is true, <<string1>> is expanded and replaces the whole item;
7962 otherwise <<string2>> is used. For example,
7964 ${if eq {$local_part}{postmaster} {yes}{no} }
7966 The second string need not be present; if it is not and the condition is not
7967 true, the item is replaced with nothing. Alternatively, the word `fail' may be
7968 present instead of the second string (without any curly brackets). In this
7969 case, the expansion is forced to fail if the condition is not true. The
7970 available conditions are described in section ~~SECTexpcond below.
7973 .item "@$@{length@{<<string1>>@}@{<<string2>>@}@}"
7974 .index expansion||string truncation
7975 The \length\ item is used to extract the initial portion of a string. Both
7976 strings are expanded, and the first one must yield a number, <<n>>, say. If you
7977 are using a fixed value for the number, that is, if <<string1>> does not change
7978 when expanded, you can use the simpler operator notation that avoids some of
7981 @$@{length@_<<n>>:<<string>>@}
7983 The result of this item is either the first <<n>> characters or the whole
7984 of <<string2>>, whichever is the shorter. Do not confuse \length\ with
7985 \strlen\, which gives the length of a string.
7988 .item "@${lookup@{<<key>>@} <<search type>> @{<<file>>@} @{<<string1>>@} @{<<string2>>@}@}"
7989 .item "@${lookup <<search type>> @{<<query>>@} @{<<string1>>@} @{<<string2>>@}@}"
7990 .index expansion||lookup in
7992 .index lookup||in expanded string
7993 These items specify data lookups in files and databases, as discussed in
7994 chapter ~~CHAPfdlookup. The first form is used for single-key lookups, and the
7995 second is used for query-style lookups. The <<key>>, <<file>>, and <<query>>
7996 strings are expanded before use.
7998 If there is any white space in a lookup item which is part of a filter command,
7999 a retry or rewrite rule, a routing rule for the \%manualroute%\ router, or any
8000 other place where white space is significant, the lookup item must be enclosed
8001 in double quotes. The use of data lookups in users' filter files may be locked
8002 out by the system administrator.
8005 If the lookup succeeds, <<string1>> is expanded and replaces the entire item.
8006 During its expansion, the variable \$value$\ contains the data returned by the
8007 lookup. Afterwards it reverts to the value it had previously (at the outer
8008 level it is empty). If the lookup fails, <<string2>> is expanded and replaces
8009 the entire item. If @{<<string2>>@} is omitted, the replacement is null on
8010 failure. Alternatively, <<string2>> can itself be a nested lookup, thus
8011 providing a mechanism for looking up a default value when the original lookup
8014 If a nested lookup is used as part of <<string1>>, \$value$\ contains the data
8015 for the outer lookup while the parameters of the second lookup are expanded,
8016 and also while <<string2>> of the second lookup is expanded, should the second
8019 Instead of @{<<string2>>@} the word `fail' can appear, and in this case, if the
8020 lookup fails, the entire expansion is forced to fail. If both @{<<string1>>@}
8021 and @{<<string2>>@} are omitted, the result is the looked up value in the case
8022 of a successful lookup, and nothing in the case of failure.
8024 For single-key lookups, the string `partial' is permitted to precede the
8025 search type in order to do partial matching, and $*$ or $*$@@ may follow a
8026 search type to request default lookups if the key does not match (see sections
8027 ~~SECTdefaultvaluelookups and ~~SECTpartiallookup for details).
8029 .index numerical variables (\$1$\, \$2$\, etc)||in lookup expansion
8030 If a partial search is used, the variables \$1$\ and \$2$\ contain the wild
8031 and non-wild parts of the key during the expansion of the replacement text.
8032 They return to their previous values at the end of the lookup item.
8034 This example looks up the postmaster alias in the conventional alias file:
8036 ${lookup {postmaster} lsearch {/etc/aliases} {$value}}
8038 This example uses NIS+ to look up the full name of the user corresponding to
8039 the local part of an address, forcing the expansion to fail if it is not found:
8041 ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
8046 .item "@$@{nhash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
8047 .index expansion||numeric hash
8048 .index hash function||numeric
8049 The three strings are expanded; the first two must yield numbers. Call them
8050 <<n>> and <<m>>. If you are using fixed values for these numbers, that is, if
8051 <<string1>> and <<string2>> do not change when they are expanded, you can use
8052 the simpler operator notation that avoids some of the braces:
8054 @$@{nhash@_<<n>>@_<<m>>:<<string>>@}
8056 The second number is optional (in both notations). If there is only one number,
8057 the result is a number in the range 0--<<n>>-1. Otherwise, the string is
8058 processed by a div/mod hash function that returns two numbers, separated by a
8059 slash, in the ranges 0 to <<n>>-1 and 0 to <<m>>-1, respectively. For example,
8061 ${nhash{8}{64}{supercalifragilisticexpialidocious}}
8063 returns the string `6/33'.
8067 .item "@$@{perl@{<<subroutine>>@}@{<<arg>>@}@{<<arg>>@}...@}"
8068 .index Perl||use in expanded string
8069 .index expansion||calling Perl from
8070 This item is available only if Exim has been built to include an embedded Perl
8071 interpreter. The subroutine name and the arguments are first separately
8072 expanded, and then the Perl subroutine is called with those arguments. No
8073 additional arguments need be given; the maximum number permitted, including the
8074 name of the subroutine, is nine.
8076 The return value of the subroutine is inserted into the expanded string, unless
8077 the return value is \undef\. In that case, the expansion fails in the same way
8078 as an explicit `fail' on a lookup item.
8079 The return value is a scalar. Whatever you return is evaluated in a scalar
8080 context. For example, if you return the name of a Perl vector, the
8081 return value is the size of the vector, not its contents.
8083 If the subroutine exits by calling Perl's \die\ function, the expansion fails
8084 with the error message that was passed to \die\. More details of the embedded
8085 Perl facility are given in chapter ~~CHAPperl.
8087 The \%redirect%\ router has an option called \forbid@_filter@_perl\ which locks
8088 out the use of this expansion item in filter files.
8091 .item "@$@{readfile@{<<file name>>@}@{<<eol string>>@}@}"
8092 .index expansion||inserting an entire file
8093 .index file||inserting into expansion
8094 The file name and end-of-line string are first expanded separately. The file is
8095 then read, and its contents replace the entire item. All newline characters in
8096 the file are replaced by the end-of-line string if it is present. Otherwise,
8097 newlines are left in the string.
8098 String expansion is not applied to the contents of the file. If you want this,
8099 you must wrap the item in an \expand\ operator. If the file cannot be read, the
8100 string expansion fails.
8102 The \%redirect%\ router has an option called \forbid@_filter@_readfile\ which
8103 locks out the use of this expansion item in filter files.
8107 .item "@$@{readsocket@{<<name>>@}@{<<request>>@}@{<<timeout>>@}@{<<eol string>>@}@{<<fail string>>@}@}"
8108 .index expansion||inserting from a socket
8109 .index socket, use of in expansion
8110 This item inserts data that is read from a Unix domain socket into the expanded
8111 string. The minimal way of using it uses just two arguments:
8113 ${readsocket{/socket/name}{request string}}
8115 Exim connects to the socket, writes the request string (unless it is an
8116 empty string) and reads from the socket until an end-of-file is read. A timeout
8117 of 5 seconds is applied. Additional, optional arguments extend what can be
8118 done. Firstly, you can vary the timeout. For example:
8120 ${readsocket{/socket/name}{request-string}{3s}}
8122 A fourth argument allows you to change any newlines that are in the data
8123 that is read, in the same way as for \readfile\ (see above). This example turns
8126 ${readsocket{/socket/name}{request-string}{3s}{ }}
8128 As with all expansions, the substrings are expanded before the processing
8129 happens. Errors in these sub-expansions cause the expansion to fail. In
8130 addition, the following errors can occur:
8132 Failure to create a socket file descriptor;
8134 Failure to connect the socket;
8136 Failure to write the request-string;
8138 Timeout on reading from the socket.
8140 By default, any of these errors causes the expansion to fail. However, if
8141 you supply a fifth substring, it is expanded and used when any of the above
8142 errors occurs. For example:
8144 ${readsocket{/socket/name}{request-string}{3s}{\n}\
8147 You can test for the existence of the socket by wrapping this expansion in
8148 \"@$@{if exists"\, but there is a race condition between that test and the
8149 actual opening of the socket, so it is safer to use the fifth argument if you
8150 want to be absolutely sure of avoiding an expansion error for a non-existent
8153 The \%redirect%\ router has an option called \forbid@_filter@_readsocket\ which
8154 locks out the use of this expansion item in filter files.
8156 .item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:"
8157 This item inserts `raw' header lines. It is described with the \header\
8158 expansion item above.
8162 .item "@$@{run@{<<command>> <<args>>@}@{<<string1>>@}@{<<string2>>@}@}"
8163 .index expansion||running a command
8164 The command and its arguments are first expanded separately, and then the
8165 command is run in a separate process, but under the same uid and gid. As in
8166 other command executions from Exim, a shell is not used by default. If you want
8167 a shell, you must explicitly code it.
8168 .index return code||from \run\ expansion
8169 If the command succeeds (gives a zero return code) <<string1>> is expanded and
8170 replaces the entire item; during this expansion, the standard output from the
8171 command is in the variable \$value$\. If the command fails, <<string2>>, if
8172 present, is expanded. If it is absent, the result is empty. Alternatively,
8173 <<string2>> can be the word `fail' (not in braces) to force expansion failure
8174 if the command does not succeed. If both strings are omitted, the result is the
8175 standard output on success, and nothing on failure.
8177 The return code from the command is put in the variable \$runrc$\, and this
8178 remains set afterwards, so in a filter file you can do things like this:
8180 if "${run{x y z}{}}$runrc" is 1 then ...
8181 elif $runrc is 2 then ...
8185 If execution of the command fails (for example, the command does not exist),
8186 the return code is 127 -- the same code that shells use for non-existent
8189 \**Warning**\: In a router or transport, you cannot assume the order in which
8190 option values are expanded, except for those pre-conditions whose order of
8191 testing is documented. Therefore, you cannot reliably expect to set \$runrc$\
8192 by the expansion of one option, and use it in another.
8194 The \%redirect%\ router has an option called \forbid@_filter@_run\ which locks
8195 out the use of this expansion item in filter files.
8198 .item "@$@{sg@{<<subject>>@}@{<<regex>>@}@{<<replacement>>@}@}"
8199 .index expansion||string substitution
8200 This item works like Perl's substitution operator (s) with the global (/g)
8201 option; hence its name. However, unlike the Perl equivalent, Exim does not
8202 modify the subject string; instead it returns the modified string for insertion
8203 into the overall expansion. The item takes three arguments: the subject string,
8204 a regular expression, and a substitution string. For example
8206 ${sg{abcdefabcdef}{abc}{xyz}}
8208 yields `xyzdefxyzdef'. Because all three arguments are expanded before use, if
8209 any @$ or @\ characters are required in the regular expression or in the
8210 substitution string, they have to be escaped. For example
8212 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
8214 yields `defabc', and
8216 ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
8218 yields `K1=A K4=D K3=C'.
8219 Note the use of \"@\N"\ to protect the contents of the regular expression from
8224 .item "@$@{substr@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
8226 .index substring extraction
8227 .index expansion||substring extraction
8228 The three strings are expanded; the first two must yield numbers. Call them
8229 <<n>> and <<m>>. If you are using fixed values for these numbers, that is, if
8230 <<string1>> and <<string2>> do not change when they are expanded, you can use
8231 the simpler operator notation that avoids some of the braces:
8233 @$@{substr@_<<n>>@_<<m>>:<<string>>@}
8235 The second number is optional (in both notations).
8237 The \substr\ item can be used to extract more general substrings than \length\.
8238 The first number, <<n>>, is a starting offset, and <<m>> is the length
8239 required. For example
8241 ${substr{3}{2}{$local_part}}
8243 If the starting offset is greater than the string length the result is the null
8244 string; if the length plus starting offset is greater than the string length,
8245 the result is the right-hand part of the string, starting from the given
8246 offset. The first character in the string has offset zero.
8248 The \substr\ expansion item can take negative offset values to count
8249 from the right-hand end of its operand. The last character is offset -1, the
8250 second-last is offset -2, and so on. Thus, for example,
8252 ${substr{-5}{2}{1234567}}
8254 yields `34'. If the absolute value of a negative offset is greater than the
8255 length of the string, the substring starts at the beginning of the string, and
8256 the length is reduced by the amount of overshoot. Thus, for example,
8258 ${substr{-5}{2}{12}}
8260 yields an empty string, but
8262 ${substr{-3}{2}{12}}
8266 If the second number is omitted from \substr\, the remainder of the string is
8267 taken if the offset was positive. If it was negative, all characters in the
8268 string preceding the offset point are taken. For example, an offset of -1 and
8269 no length yields all but the last character of the string.
8273 .item "@$@{tr@{<<subject>>@}@{<<characters>>@}@{<<replacements>>@}@}"
8274 .index expansion||character translation
8275 This item does single-character translation on its subject string. The second
8276 argument is a list of characters to be translated in the subject string. Each
8277 matching character is replaced by the corresponding character from the
8278 replacement list. For example
8280 ${tr{abcdea}{ac}{13}}
8282 yields `1b3de1'. If there are duplicates in the second character string, the
8283 last occurrence is used. If the third string is shorter than the second, its
8284 last character is replicated. However, if it is empty, no translation takes
8290 .section Expansion operators
8291 .rset SECTexpop "~~chapter.~~section"
8292 .index expansion||operators
8293 For expansion items that perform transformations on a single argument string,
8294 the `operator' notation is used because it is simpler and uses fewer braces.
8295 The substring is first expanded before the operation is applied to it. The
8296 following operations can be performed:
8300 .item "@$@{address:<<string>>@}"
8301 .index expansion||RFC 2822 address handling
8302 The string is interpreted as an RFC 2822 address, as it might appear in a
8303 header line, and the effective address is extracted from it. If the string does
8304 not parse successfully, the result is empty.
8307 .item "@$@{base62:<<digits>>@}"
8309 .index expansion||conversion to base 62
8310 The string must consist entirely of decimal digits. The number is converted to
8311 base 62 (sic) and output as a string of six characters, including leading
8312 zeros. \**Note**\: Just to be absolutely clear: this is \*not*\ base64
8316 .item "@$@{base62d:<<base-62 digits>>@}"
8318 .index expansion||conversion to base 62
8319 The string must consist entirely of base-62 digits. The number is converted to
8320 decimal and output as a string.
8324 .item "@$@{domain:<<string>>@}"
8325 .index domain||extraction
8326 .index expansion||domain extraction
8327 The string is interpreted as an RFC 2822 address and the domain is extracted
8328 from it. If the string does not parse successfully, the result is empty.
8331 .item "@$@{escape:<<string>>@}"
8332 .index expansion||escaping non-printing characters
8333 If the string contains any non-printing characters, they are converted to
8334 escape sequences starting with a backslash. Whether characters with the most
8335 significant bit set (so-called `8-bit characters') count as printing or not is
8336 controlled by the \print@_topbitchars\ option.
8340 .item "@$@{eval:<<string>>@}"
8341 .item "@$@{eval10:<<string>>@}"
8342 .index expansion||expression evaluation
8343 .index expansion||arithmetic expression
8344 These items supports simple arithmetic in expansion strings. The string (after
8345 expansion) must be a conventional arithmetic expression, but it is limited to
8346 the four basic operators (plus, minus, times, divide) and parentheses. All
8347 operations are carried out using integer arithmetic. Plus and minus have a
8348 lower priority than times and divide; operators with the same priority are
8349 evaluated from left to right.
8351 For \eval\, numbers may be decimal, octal (starting with `0') or hexadecimal
8352 (starting with `0x'). For \eval10\, all numbers are taken as decimal, even if
8353 they start with a leading zero. This can be useful when processing numbers
8354 extracted from dates or times, which often do have leading zeros.
8357 A number may be followed by `K' or `M' to multiply it by 1024 or 1024$*$1024,
8358 respectively. Negative numbers are supported. The result of the computation is
8359 a decimal representation of the answer (without `K' or `M'). For example:
8361 @$@{eval:1+1@} $rm{yields} 2
8362 @$@{eval:1+2*3@} $rm{yields} 7
8363 @$@{eval:(1+2)*3@} $rm{yields} 9
8365 As a more realistic example, in an ACL you might have
8367 deny message = Too many bad recipients
8370 {>{$rcpt_count}{10}} \
8373 {$recipients_count} \
8374 {${eval:$rcpt_count/2}} \
8378 The condition is true if there have been more than 10 \\RCPT\\ commands and
8379 fewer than half of them have resulted in a valid recipient.
8382 .item "@$@{expand:<<string>>@}"
8383 .index expansion||re-expansion of substring
8384 The \expand\ operator causes a string to be expanded for a second time. For
8387 ${expand:${lookup{$domain}dbm{/some/file}{$value}}}
8389 first looks up a string in a file while expanding the operand for \expand\, and
8390 then re-expands what it has found.
8393 .item "@$@{from@_utf8:<<string>>@}"
8395 .index UTF-8||conversion from
8396 .index expansion||UTF-8 conversion
8397 The world is slowly moving towards Unicode, although there are no standards for
8398 email yet. However, other applications (including some databases) are starting
8399 to store data in Unicode, using UTF-8 encoding. This operator converts from a
8400 UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are
8401 converted to underscores. The input must be a valid UTF-8 string. If it is not,
8402 the result is an undefined sequence of bytes.
8404 Unicode code points with values less than 256 are compatible with ASCII and
8405 ISO-8859-1 (also known as Latin-1).
8406 For example, character 169 is the copyright symbol in both cases, though the
8407 way it is encoded is different. In UTF-8, more than one byte is needed for
8408 characters with code values greater than 127, whereas ISO-8859-1 is a
8409 single-byte encoding (but thereby limited to 256 characters). This makes
8410 translation from UTF-8 to ISO-8859-1 straightforward.
8413 .item "@$@{hash@_<<n>>@_<<m>>:<<string>>@}"
8414 .index hash function||textual
8415 .index expansion||textual hash
8416 The \hash\ operator is a simpler interface to the hashing function that can be
8417 used when the two parameters are fixed numbers (as opposed to strings that
8418 change when expanded). The effect is the same as
8420 @$@{hash@{<<n>>@}@{<<m>>@}@{<<string>>@}@}
8422 See the description of the general \hash\ item above for details. The
8423 abbreviation \h\ can be used when \hash\ is used as an operator.
8427 .item "@$@{hex2b64:<<hexstring>>@}"
8428 .index base64 encoding||conversion from hex
8429 .index expansion||hex to base64
8430 This operator converts a hex string into one that is base64 encoded. This can
8431 be useful for processing the output of the MD5 and SHA-1 hashing functions.
8434 .item "@$@{lc:<<string>>@}"
8435 .index case forcing in strings
8436 .index string||case forcing
8438 .index expansion||case forcing
8439 This forces the letters in the string into lower-case, for example:
8445 .item "@$@{length@_<<number>>:<<string>>@}"
8446 .index expansion||string truncation
8447 The \length\ operator is a simpler interface to the \length\ function that can
8448 be used when the parameter is a fixed number (as opposed to a string that
8449 changes when expanded). The effect is the same as
8451 @$@{length@{<<number>>@}@{<<string>>@}@}
8453 See the description of the general \length\ item above for details. Note that
8454 \length\ is not the same as \strlen\. The abbreviation \l\ can be used when
8455 \length\ is used as an operator.
8458 .item "@$@{local@_part:<<string>>@}"
8459 .index expansion||local part extraction
8460 The string is interpreted as an RFC 2822 address and the local part is
8461 extracted from it. If the string does not parse successfully, the result is
8465 .item "@$@{mask:<<IP address>>/<<bit count>>@}"
8466 .index masked IP address
8467 .index IP address||masking
8468 .index CIDR notation
8469 .index expansion||IP address masking
8470 If the form of the string to be operated on is not an IP address followed by a
8471 slash and an integer (that is, a network address in CIDR notation), the
8472 expansion fails. Otherwise, this operator converts the IP address to binary,
8473 masks off the least significant bits according to the bit count, and converts
8474 the result back to text, with mask appended. For example,
8476 ${mask:10.111.131.206/28}
8478 returns the string `10.111.131.192/28'. Since this operation is expected to be
8479 mostly used for looking up masked addresses in files, the result for an IPv6
8480 address uses dots to separate components instead of colons, because colon
8481 terminates a key string in lsearch files. So, for example,
8483 ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99}
8487 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
8489 Letters in IPv6 addresses are always output in lower case.
8492 .item "@$@{md5:<<string>>@}"
8494 .index expansion||MD5 hash
8495 The \md5\ operator computes the MD5 hash value of the string, and returns it as
8496 a 32-digit hexadecimal number,
8497 in which any letters are in lower case.
8500 .item "@$@{nhash@_<<n>>@_<<m>>:<<string>>@}"
8501 .index expansion||numeric hash
8502 .index hash function||numeric
8503 The \nhash\ operator is a simpler interface to the numeric hashing function
8504 that can be used when the two parameters are fixed numbers (as opposed to
8505 strings that change when expanded). The effect is the same as
8507 @$@{nhash@{<<n>>@}@{<<m>>@}@{<<string>>@}@}
8509 See the description of the general \nhash\ item above for details.
8512 .item "@$@{quote:<<string>>@}"
8513 .index quoting||in string expansions
8514 .index expansion||quoting
8515 The \quote\ operator puts its argument into double quotes if it
8516 is an empty string or
8517 contains anything other than letters, digits, underscores, dots, and hyphens.
8518 Any occurrences of double quotes and backslashes are escaped with a backslash.
8519 Newlines and carriage returns are converted to \"@\n"\ and \"@\r"\,
8520 respectively For example,
8528 The place where this is useful is when the argument is a substitution from a
8529 variable or a message header.
8531 .item "@$@{quote@_local@_part:<<string>>@}"
8532 This operator is like \quote\, except that it quotes the string only if
8533 required to do so by the rules of RFC 2822 for quoting local parts. For
8534 example, a plus sign would not cause quoting (but it would for \quote\).
8535 If you are creating a new email address from the contents of \$local@_part$\
8536 (or any other unknown data), you should always use this operator.
8539 .item "@$@{quote@_<<lookup-type>>:<<string>>@}"
8540 .index quoting||lookup-specific
8541 This operator applies lookup-specific quoting rules to the string. Each
8542 query-style lookup type has its own quoting rules which are described with
8543 the lookups in chapter ~~CHAPfdlookup. For example,
8545 ${quote_ldap:two * two}
8551 For single-key lookup types, no quoting is ever necessary and this operator
8552 yields an unchanged string.
8555 .item "@$@{rxquote:<<string>>@}"
8556 .index quoting||in regular expressions
8557 .index regular expressions||quoting
8558 The \rxquote\ operator inserts a backslash before any non-alphanumeric
8559 characters in its argument. This is useful when substituting the values of
8560 variables or headers inside regular expressions.
8563 .item "@$@{rfc2047:<<string>>@}"
8564 .index expansion||RFC 2047
8565 This operator encodes text according to the rules of RFC 2047. This is an
8566 encoding that is used in header lines to encode non-ASCII characters. It is
8567 assumed that the input string is in the encoding specified by the
8568 \headers@_charset\ option, which defaults to ISO-8859-1.
8569 If the string contains only characters in the range 33--126, and no instances
8572 ? = ( ) < > @ , ; : \ " . [ ] _
8574 it is not modified. Otherwise, the result is the RFC 2047 encoding, as a single
8578 .item "@$@{sha1:<<string>>@}"
8580 .index expansion||SHA-1 hashing
8581 The \sha1\ operator computes the SHA-1 hash value of the string, and returns it
8582 as a 40-digit hexadecimal number, in which any letters are in upper case.
8585 .item "@$@{stat:<<string>>@}"
8586 .index expansion||statting a file
8587 .index file||extracting characteristics
8588 The string, after expansion, must be a file path. A call to the \*stat()*\
8589 function is made for this path. If \*stat()*\ fails, an error occurs and the
8590 expansion fails. If it succeeds, the data from the stat replaces the item, as a
8591 series of <<name>>=<<value>> pairs, where the values are all numerical,
8592 except for the value of `smode'. The names are: `mode' (giving the mode as a
8593 4-digit octal number), `smode' (giving the mode in symbolic format as a
8594 10-character string, as for the \*ls*\ command), `inode', `device', `links',
8595 `uid', `gid', `size', `atime', `mtime', and `ctime'. You can extract individual
8596 fields using the \extract\ expansion item. \**Warning**\: The file size may be
8597 incorrect on 32-bit systems for files larger than 2GB.
8600 .item "@$@{strlen:<<string>>@}"
8601 .index expansion||string length
8602 .index string||length in expansion
8603 The item is replace by the length of the expanded string, expressed as a
8604 decimal number. \**Note**\: Do not confuse \strlen\ with \length\.
8607 .item "@$@{substr@_<<start>>@_<<length>>:<<string>>@}"
8609 .index substring extraction
8610 .index expansion||substring expansion
8611 The \substr\ operator is a simpler interface to the \substr\ function that can
8612 be used when the two parameters are fixed numbers (as opposed to strings that
8613 change when expanded). The effect is the same as
8615 @$@{substr@{<<start>>@}@{<<length>>@}@{<<string>>@}@}
8617 See the description of the general \substr\ item above for details. The
8618 abbreviation \s\ can be used when \substr\ is used as an operator.
8621 .item "@$@{time@_interval:<<string>>@}"
8622 .index \time@_interval\
8623 .index time interval||formatting
8624 The argument (after sub-expansion) must be a sequence of decimal digits that
8625 represents an interval of time as a number of seconds. It is converted into a
8626 number of larger units and output in Exim's normal time format, for example,
8630 .item "@$@{uc:<<string>>@}"
8631 .index case forcing in strings
8632 .index string||case forcing
8634 .index expansion||case forcing
8635 This forces the letters in the string into upper-case.
8641 .section Expansion conditions
8642 .rset SECTexpcond "~~chapter.~~section"
8643 .index expansion||conditions
8644 The following conditions are available for testing by the \@$@{if\ construct
8645 while expanding strings:
8649 .item "!<<condition>>"
8650 .index expansion||negating a condition
8651 Preceding any condition with an exclamation mark negates the result of the
8654 .item "<<symbolic operator>> @{<<string1>>@}@{<<string2>>@}"
8655 .index numeric comparison
8656 .index expansion||numeric comparison
8657 There are a number of symbolic operators for doing numeric comparisons. They
8664 >= $t $rm{greater or equal}
8666 <= $t $rm{less or equal}
8670 ${if >{$message_size}{10M} ...
8672 Note that the general negation operator provides for inequality testing. The
8673 two strings must take the form of optionally signed decimal integers,
8674 optionally followed by one of the letters `K' or `M' (in either upper or lower
8675 case), signifying multiplication by 1024 or 1024$*$1024, respectively.
8677 .item "crypteq @{<<string1>>@}@{<<string2>>@}"
8678 .index expansion||encrypted comparison
8679 .index encrypted strings, comparing
8680 This condition is included in the Exim binary if it is built to support any
8681 authentication mechanisms (see chapter ~~CHAPSMTPAUTH). Otherwise, it is
8682 necessary to define \\SUPPORT@_CRYPTEQ\\ in \(Local/Makefile)\ to get \crypteq\
8683 included in the binary.
8685 The \crypteq\ condition has two arguments. The first is encrypted and compared
8686 against the second, which is already encrypted. The second string may be in the
8687 LDAP form for storing encrypted strings, which starts with the encryption type
8688 in curly brackets, followed by the data. If the second string does not begin
8689 with `{' it is assumed to be encrypted with \*crypt()*\
8690 or \*crypt16()*\ (see below),
8691 since such strings cannot begin with `{'. Typically this will be a field from a
8694 An example of an encrypted string in LDAP form is:
8696 {md5}CY9rzUYh03PK3k6DJie09g==
8698 If such a string appears directly in an expansion, the curly brackets have to
8699 be quoted, because they are part of the expansion syntax. For example:
8701 ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
8703 The following encryption types
8704 (whose names are matched case-independently)
8708 .index base64 encoding||in encrypted password
8709 \@{md5@}\ computes the MD5 digest of the first string, and expresses this as
8710 printable characters to compare with the remainder of the second string. If the
8711 length of the comparison string is 24, Exim assumes that it is base64 encoded
8712 (as in the above example). If the length is 32, Exim assumes that it is a
8713 hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the
8717 \@{sha1@}\ computes the SHA-1 digest of the first string, and expresses this as
8718 printable characters to compare with the remainder of the second string. If the
8719 length of the comparison string is 28, Exim assumes that it is base64 encoded.
8720 If the length is 40, Exim assumes that it is a hexadecimal encoding of the
8721 SHA-1 digest. If the length is not 28 or 40, the comparison fails.
8724 \@{crypt@}\ calls the \*crypt()*\ function, which uses only the first eight
8725 characters of the password.
8727 .index \*crypt16()*\
8728 \@{crypt16@}\ calls the \*crypt16()*\ function (also known as \*bigcrypt()*\),
8729 which uses up to 16 characters of the password.
8731 Exim has its own version of \*crypt16()*\ (which is just a double call to
8732 \*crypt()*\). For operating systems that have their own version, setting
8733 \\HAVE@_CRYPT16\\ in \(Local/Makefile)\ when building Exim causes it to use the
8734 operating system version instead of its own. This option is set by default in
8735 the OS-dependent \(Makefile)\ for those operating systems that are known to
8736 support \*crypt16()*\.
8738 If you do not put any curly bracket encryption type in a \crypteq\ comparison,
8739 the default is either \"@{crypt@}"\ or \"@{crypt16@}"\, as determined by the
8740 setting of \\DEFAULT@_CRYPT\\ in \(Local/Makefile)\. The default default is
8741 \"@{crypt@}"\. Whatever the default, you can always use either function by
8742 specifying it explicitly in curly brackets.
8744 Note that if a password is no longer than 8 characters, the results of
8745 encrypting it with \*crypt()*\ and \*crypt16()*\ are identical. That means that
8746 \*crypt16()*\ is backwards compatible, as long as nobody feeds it a password
8747 longer than 8 characters.
8750 .item "def:<<variable name>>"
8751 .index expansion||checking for empty variable
8752 The \def\ condition must be followed by the name of one of the expansion
8753 variables defined in section ~~SECTexpvar. The condition is true if the named
8754 expansion variable does not contain the empty string, for example
8756 ${if def:sender_ident {from $sender_ident}}
8758 Note that the variable name is given without a leading \@$\ character. If the
8759 variable does not exist, the expansion fails.
8761 .item "def:header@_<<header name>>:##or##def:h@_<<header name>>:"
8762 .index expansion||checking header line existence
8763 This condition is true if a message is being processed and the named header
8764 exists in the message. For example,
8766 ${if def:header_reply-to:{$h_reply-to:}{$h_from:}}
8768 Note that no \@$\ appears before \header@_\ or \h@_\ in the condition,
8769 and that header names must be terminated by colons if white space does not
8772 .item "eq @{<<string1>>@}@{<<string2>>@}"
8773 .item "eqi @{<<string1>>@}@{<<string2>>@}"
8774 .index string||comparison
8775 .index expansion||string comparison
8776 The two substrings are first expanded. The condition is true if the two
8777 resulting strings are identical: for \eq\ the comparison includes the case of
8778 letters, whereas for \eqi\ the comparison is case-independent.
8780 .item "exists @{<<file name>>@}"
8781 .index expansion||file existence test
8782 .index file||existence test
8783 The substring is first expanded and then interpreted as an absolute path. The
8784 condition is true if the named file (or directory) exists. The existence test
8785 is done by calling the \*stat()*\ function. The use of the \exists\ test in
8786 users' filter files may be locked out by the system administrator.
8788 .item "first@_delivery"
8789 .index delivery||first
8790 .index first delivery
8791 .index expansion||first delivery test
8792 This condition, which has no data, is true during a message's first delivery
8793 attempt. It is false during any subsequent delivery attempts.
8796 .item "ge @{<<string1>>@}@{<<string2>>@}"
8797 .item "gei @{<<string1>>@}@{<<string2>>@}"
8798 .index string||comparison
8799 .index expansion||string comparison
8800 The two substrings are first expanded. The condition is true if the first
8801 string is lexically greater than or equal to the second string: for \ge\ the
8802 comparison includes the case of letters, whereas for \gei\ the comparison is
8805 .item "gt @{<<string1>>@}@{<<string2>>@}"
8806 .item "gti @{<<string1>>@}@{<<string2>>@}"
8807 .index string||comparison
8808 .index expansion||string comparison
8809 The two substrings are first expanded. The condition is true if the first
8810 string is lexically greater than the second string: for \gt\ the comparison
8811 includes the case of letters, whereas for \gti\ the comparison is
8815 .item "isip @{<<string>>@}" 8
8816 .item "isip4 @{<<string>>@}"
8817 .item "isip6 @{<<string>>@}"
8818 .index IP address||testing string format
8819 .index string||testing for IP address
8820 The substring is first expanded, and then tested to see if it has the form of
8821 an IP address. Both IPv4 and IPv6 addresses are valid for \isip\, whereas
8822 \isip4\ and \isip6\ test just for IPv4 or IPv6 addresses, respectively. For
8823 example, you could use
8825 ${if isip4{$sender_host_address}...
8827 to test which version of IP an incoming SMTP connection is using.
8830 .item "ldapauth @{<<ldap query>>@}"
8831 .index LDAP||use for authentication
8832 .index expansion||LDAP authentication test
8833 This condition supports user authentication using LDAP. See section ~~SECTldap
8834 for details of how to use LDAP in lookups and the syntax of queries. For this
8835 use, the query must contain a user name and password. The query itself is not
8836 used, and can be empty. The condition is true if
8837 the password is not empty, and the user name and password are accepted by the
8838 LDAP server. An empty password is rejected without calling LDAP because LDAP
8839 binds with an empty password are considered anonymous regardless of
8840 the username, and will succeed in most configurations.
8841 See chapter ~~CHAPSMTPAUTH for details of SMTP authentication, and chapter
8842 ~~CHAPplaintext for an example of how this can be used.
8846 .item "le @{<<string1>>@}@{<<string2>>@}"
8847 .item "lei @{<<string1>>@}@{<<string2>>@}"
8848 .index string||comparison
8849 .index expansion||string comparison
8850 The two substrings are first expanded. The condition is true if the first
8851 string is lexically less than or equal to the second string: for \le\ the
8852 comparison includes the case of letters, whereas for \lei\ the comparison is
8855 .item "lt @{<<string1>>@}@{<<string2>>@}"
8856 .item "lti @{<<string1>>@}@{<<string2>>@}"
8857 .index string||comparison
8858 .index expansion||string comparison
8859 The two substrings are first expanded. The condition is true if the first
8860 string is lexically less than the second string: for \lt\ the comparison
8861 includes the case of letters, whereas for \lti\ the comparison is
8866 .item "match @{<<string1>>@}@{<<string2>>@}"
8867 .index expansion||regular expression comparison
8868 .index regular expressions||match in expanded string
8869 The two substrings are first expanded. The second is then treated as a regular
8870 expression and applied to the first. Because of the pre-expansion, if the
8871 regular expression contains dollar, or backslash characters, they must be
8872 escaped. Care must also be taken if the regular expression contains braces
8873 (curly brackets). A closing brace must be escaped so that it is not taken as a
8874 premature termination of <<string2>>. The easiest approach is to use the
8875 \"@\N"\ feature to disable expansion of the regular expression.
8878 ${if match {$local_part}{\N^\d{3}\N} ...
8880 If the whole expansion string is in double quotes, further escaping of
8881 backslashes is also required.
8883 The condition is true if the regular expression match succeeds.
8885 The regular expression is not required to begin with a circumflex
8886 metacharacter, but if there is no circumflex, the expression is not anchored,
8887 and it may match anywhere in the subject, not just at the start. If you want
8888 the pattern to match at the end of the subject, you must include the \"@$"\
8889 metacharacter at an appropriate point.
8892 .index numerical variables (\$1$\, \$2$\, etc)||in \if\ expansion
8893 At the start of an \if\ expansion the values of the numeric variable
8894 substitutions \$1$\ etc. are remembered. Obeying a \match\ condition that
8895 succeeds causes them to be reset to the substrings of that condition and they
8896 will have these values during the expansion of the success string. At the end
8897 of the \if\ expansion, the previous values are restored. After testing a
8898 combination of conditions using \or\, the subsequent values of the numeric
8899 variables are those of the condition that succeeded.
8902 .item "match@_domain @{<<string1>>@}@{<<string2>>@}"
8903 .item "match@_address @{<<string1>>@}@{<<string2>>@}"
8904 .item "match@_local@_part @{<<string1>>@}@{<<string2>>@}"
8905 .index domain list||in expansion condition
8906 .index address list||in expansion condition
8907 .index local part list||in expansion condition
8908 These conditions make it possible to test domain, address, and local
8909 part lists within expansions. Each condition requires two arguments: an item
8910 and a list to match. A trivial example is:
8912 ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
8914 In each case, the second argument may contain any of the allowable items for a
8915 list of the appropriate type. Also, because the second argument (after
8916 expansion) is a standard form of list, it is possible to refer to a named list.
8917 Thus, you can use conditions like this:
8919 ${if match_domain{$domain}{+local_domains}{...
8922 For address lists, the matching starts off caselessly, but the \"+caseful"\
8923 item can be used, as in all address lists, to cause subsequent items to
8924 have their local parts matched casefully. Domains are always matched
8927 \**Note**\: Host lists are \*not*\ supported in this way. This is because
8928 hosts have two identities: a name and an IP address, and it is not clear
8929 how to specify cleanly how such a test would work. At least, I haven't come
8930 up with anything yet.
8933 .item "pam {<<string1>>:<<string2>>:...@}"
8934 .index PAM authentication
8935 .index \\AUTH\\||with PAM
8936 .index Solaris||PAM support
8937 .index expansion||PAM authentication test
8938 \*Pluggable Authentication Modules*\
8939 (\?http://www.kernel.org/pub/linux/libs/pam/?\)
8940 are a facility which is available in the latest releases of Solaris and in some
8941 GNU/Linux distributions. The Exim support, which is intended for use in
8942 conjunction with the SMTP \\AUTH\\ command, is available only if Exim is
8947 in \(Local/Makefile)\. You probably need to add \-lpam-\ to \\EXTRALIBS\\, and
8948 in some releases of GNU/Linux \-ldl-\ is also needed.
8950 The argument string is first expanded, and the result must be a colon-separated
8952 Leading and trailing whitespace is ignored.
8953 The PAM module is initialized with the service name `exim' and the user name
8954 taken from the first item in the colon-separated data string (<<string1>>). The
8955 remaining items in the data string are passed over in response to requests from
8956 the authentication function. In the simple case there will only be one request,
8957 for a password, so the data consists of just two strings.
8959 There can be problems if any of the strings are permitted to contain colon
8960 characters. In the usual way, these have to be doubled to avoid being taken as
8961 separators. If the data is being inserted from a variable, the \sg\ expansion
8962 item can be used to double any existing colons. For example, the configuration
8963 of a LOGIN authenticator might contain this setting:
8965 server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}}
8967 For a PLAIN authenticator you could use:
8969 server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}}
8971 In some operating systems, PAM authentication can be done only from a process
8972 running as root. Since Exim is running as the Exim user when receiving
8973 messages, this means that PAM cannot be used directly in those systems.
8974 A patched version of the \*pam@_unix*\ module that comes with the
8975 Linux PAM package is available from \?http:@/@/www.e-admin.de/pam@_exim/?\.
8976 The patched module allows one special uid/gid combination, in addition to root,
8977 to authenticate. If you build the patched module to allow the Exim user and
8978 group, PAM can then be used from an Exim authenticator.
8981 .item "pwcheck {<<string1>>:<<string2>>@}"
8982 .index \*pwcheck*\ daemon
8984 .index expansion||\*pwcheck*\ authentication test
8985 This condition supports user authentication using the Cyrus \*pwcheck*\ daemon.
8986 This is one way of making it possible for passwords to be checked by a process
8987 that is not running as root.
8988 \**Note:**\ The use of \*pwcheck*\ is now deprecated. Its replacement is
8989 \*saslauthd*\ (see below).
8991 The pwcheck support is not included in Exim by default. You need to specify
8992 the location of the pwcheck daemon's socket in \(Local/Makefile)\ before
8993 building Exim. For example:
8995 CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck
8997 You do not need to install the full Cyrus software suite in order to use
8998 the pwcheck daemon. You can compile and install just the daemon alone
8999 from the Cyrus SASL library. Ensure that \*exim*\ is the only user that has
9000 access to the \(/var/pwcheck)\ directory.
9002 The \pwcheck\ condition takes one argument, which must be the user name and
9003 password, separated by a colon. For example, in a LOGIN authenticator
9004 configuration, you might have this:
9006 server_condition = ${if pwcheck{$1:$2}{1}{0}}
9009 .item "queue@_running"
9010 .index queue runner||detecting when delivering from
9011 .index expansion||queue runner test
9012 This condition, which has no data, is true during delivery attempts that are
9013 initiated by queue runner processes, and false otherwise.
9016 .item "radius {<<authentication string>>@}"
9018 .index expansion||Radius authentication
9019 Radius authentication (RFC 2865) is supported in a similar way to PAM. You must
9020 set \\RADIUS@_CONFIG@_FILE\\ in \(Local/Makefile)\ to specify the location of
9021 the Radius client configuration file in order to build Exim with Radius
9023 You may also have to supply a suitable setting in \\EXTRALIBS\\ so that the
9024 Radius library can be found when Exim is linked.
9025 The string specified by \\RADIUS@_CONFIG@_FILE\\ is expanded and passed to the
9026 Radius client library, which calls the Radius server. The condition is true if
9027 the authentication is successful. For example
9029 server@_condition = @$@{if radius@{<<arguments>>@}@{yes@}@{no@}@}
9034 .item "saslauthd @{@{<<user>>@}@{<<password>>@}@{<<service>>@}@{<<realm>>@}@}"
9035 .index \*saslauthd*\ daemon
9037 .index expansion||\*saslauthd*\ authentication test
9038 This condition supports user authentication using the Cyrus \*saslauthd*\
9039 daemon. This replaces the older \*pwcheck*\ daemon, which is now deprecated.
9040 Using this daemon is one way of making it possible for passwords to be checked
9041 by a process that is not running as root.
9043 The saslauthd support is not included in Exim by default. You need to specify
9044 the location of the saslauthd daemon's socket in \(Local/Makefile)\ before
9045 building Exim. For example:
9047 CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux
9049 You do not need to install the full Cyrus software suite in order to use
9050 the saslauthd daemon. You can compile and install just the daemon alone
9051 from the Cyrus SASL library.
9053 Up to four arguments can be supplied to the \saslauthd\ condition, but only two
9054 are mandatory. For example:
9056 server_condition = ${if saslauthd{{$1}{$2}}{1}{0}}
9058 The service and the realm are optional (which is why the arguments are enclosed
9059 in their own set of braces). For details of the meaning of the service and
9060 realm, and how to run the daemon, consult the Cyrus documentation.
9066 .section Combining expansion conditions
9067 .index expansion||combining conditions
9068 Several conditions can be tested at once by combining them using the \and\ and
9069 \or\ combination conditions. Note that \and\ and \or\ are complete conditions
9070 on their own, and precede their lists of sub-conditions. Each sub-condition
9071 must be enclosed in braces within the overall braces that contain the list. No
9072 repetition of \if\ is used.
9076 .item "or @{@{<<cond1>>@}@{<<cond2>>@}...@}"
9077 .index `or' expansion condition
9078 .index expansion||`or' of conditions
9079 The sub-conditions are evaluated from left to right. The condition is true if
9080 any one of the sub-conditions is true.
9083 ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...
9085 When a true sub-condition is found, the following ones are parsed but not
9086 evaluated. If there are several `match' sub-conditions the values of the
9087 numeric variables afterwards are taken from the first one that succeeds.
9089 .item "and @{@{<<cond1>>@}@{<<cond2>>@}...@}"
9090 .index `and' expansion condition
9091 .index expansion||`and' of conditions
9092 The sub-conditions are evaluated from left to right. The condition is true if
9093 all of the sub-conditions are true. If there are several `match'
9094 sub-conditions, the values of the numeric variables afterwards are taken from
9095 the last one. When a false sub-condition is found, the following ones are
9096 parsed but not evaluated.
9102 .section Expansion variables
9103 .rset SECTexpvar "~~chapter.~~section"
9104 .index expansion||variables, list of
9106 The variables that are available for use in expansion strings are:
9111 .index numerical variables (\$1$\, \$2$\, etc)
9112 \$0$\, \$1$\, etc: When a \match\ expansion condition succeeds, these
9113 variables contain the captured substrings identified by the regular expression
9114 during subsequent processing of the success string of the containing \if\
9115 expansion item. They may also be set externally by some other matching process
9116 which precedes the expansion of the string. For example, the commands available
9117 in Exim filter files include an \if\ command with its own regular expression
9121 \$acl@_c0$\ -- \$acl@_c9$\: Values can be placed in these variables by the
9122 \set\ modifier in an ACL. The values persist throughout the lifetime of an SMTP
9123 connection. They can be used to pass information between ACLs and different
9124 invocations of the same ACL.
9125 When a message is received, the values of these variables are saved with the
9126 message, and can be accessed by filters, routers, and transports during
9127 subsequent delivery.
9130 \$acl@_m0$\ -- \$acl@_m9$\: Values can be placed in these variables by the
9131 \set\ modifier in an ACL. They retain their values while a message is being
9132 received, but are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\,
9133 \\EHLO\\, \\HELO\\, and after starting a TLS session.
9134 When a message is received, the values of these variables are saved with the
9135 message, and can be accessed by filters, routers, and transports during
9136 subsequent delivery.
9140 \$acl@_verify@_message$\: During the expansion of the \message\ and
9141 \log@_message\ modifiers in an ACL statement after an address verification has
9142 failed, this variable contains the original failure message that will be
9143 overridden by the expanded string.
9146 \$address@_data$\: This variable is set by means of the \address@_data\
9147 option in routers. The value then remains with the address while it is
9148 processed by subsequent routers and eventually a transport. If the transport is
9149 handling multiple addresses, the value from the first address is used. See
9150 chapter ~~CHAProutergeneric for more details.
9151 \**Note**\: the contents of \$address@_data$\ are visible in user filter files.
9153 If \$address@_data$\ is set when the routers are called to verify an address
9154 from an ACL, the final value remains available in subsequent conditions in the
9155 ACL statement. If routing the address caused it to be redirected to a single
9156 address, the child address is also routed as part of the verification, and in
9157 this case the final value of \$address@_data$\ is from the child's routing.
9160 \$address@_file$\: When, as a result of aliasing, forwarding, or filtering, a
9161 message is directed to a specific file, this variable holds the name of the
9162 file when the transport is running. At other times, the variable is empty. For
9163 example, using the default configuration, if user \r2d2\ has a \(.forward)\
9168 then when the \%address@_file%\ transport is running, \$address@_file$\
9169 contains `/home/r2d2/savemail'.
9170 .index Sieve filter||value of \$address@_file$\
9171 For Sieve filters, the value may be `inbox' or a relative folder name. It is
9172 then up to the transport configuration to generate an appropriate absolute path
9173 to the relevant file.
9177 \$address@_pipe$\: When, as a result of aliasing or forwarding, a message is
9178 directed to a pipe, this variable holds the pipe command when the transport is
9181 .index authentication||id
9183 \$authenticated@_id$\: When a server successfully authenticates a client it may
9184 be configured to preserve some of the authentication information in the
9185 variable \$authenticated@_id$\ (see chapter ~~CHAPSMTPAUTH). For example, a
9186 user/password authenticator configuration might preserve the user name for use
9187 in the routers. When a message is submitted locally (that is, not over a TCP
9188 connection), the value of \$authenticated@_id$\ is the login name of the
9191 .index sender||authenticated
9192 .index authentication||sender
9193 .index \\AUTH\\||on \\MAIL\\ command
9195 \$authenticated@_sender$\:
9197 When acting as a server, Exim takes note of the \\AUTH=\\ parameter on an
9198 incoming SMTP \\MAIL\\ command
9200 if it believes the sender is sufficiently trusted, as described in section
9201 ~~SECTauthparamail. Unless the data is the string `@<@>', it is set as the
9202 authenticated sender of the message, and the value is available during delivery
9203 in the \$authenticated@_sender$\ variable. If the sender is not trusted, Exim
9204 accepts the syntax of \\AUTH=\\, but ignores the data.
9206 When a message is submitted locally (that is, not over a TCP connection), the
9207 value of \$authenticated@_sender$\ is an address constructed from the login
9208 name of the calling process and \$qualify@_domain$\.
9211 .index authentication||failure
9213 \$authentication@_failed$\:
9214 This variable is set to `1' in an Exim server if a client issues an \\AUTH\\
9215 command that does not succeed. Otherwise it is set to `0'. This makes it
9216 possible to distinguish between `did not try to authenticate'
9217 (\$sender@_host@_authenticated$\ is empty and \$authentication__failed$\ is set
9218 to `0') and `tried to authenticate but failed' (\$sender@_host@_authenticated$\
9219 is empty and \$authentication@_failed$\ is set to `1'). Failure includes any
9220 negative response to an \\AUTH\\ command, including (for example) an attempt to
9221 use an undefined mechanism.
9224 .index message||body, line count
9225 .index body of message||line count
9227 \$body@_linecount$\:
9228 When a message is being received or delivered, this variable contains the
9229 number of lines in the message's body.
9231 .index message||body, binary zero count
9232 .index body of message||binary zero count
9233 .index binary zero||in message body
9236 \$body@_zerocount$\:
9237 When a message is being received or delivered, this variable contains the
9238 number of binary zero bytes in the message's body.
9242 \$bounce@_recipient$\:
9243 This is set to the recipient address of a bounce message while Exim is creating
9244 it. It is useful if a customized bounce message text file is in use (see
9245 chapter ~~CHAPemsgcust).
9248 \$bounce@_return@_size@_limit$\: This contains the value set in the
9249 \bounce@_return@_size@_limit\ option, rounded up to a multiple of 1000. It is
9250 useful when a customized error message text file is in use (see chapter
9253 .index gid (group id)||caller
9255 \$caller@_gid$\: The
9259 group id under which the process that called Exim was
9260 running. This is not the same as the group id of the originator of a message
9261 (see \$originator@_gid$\). If Exim re-execs itself, this variable in the new
9262 incarnation normally contains the Exim gid.
9264 .index uid (user id)||caller
9266 \$caller@_uid$\: The
9270 user id under which the process that called Exim was
9271 running. This is not the same as the user id of the originator of a message
9272 (see \$originator@_uid$\). If Exim re-execs itself, this variable in the new
9273 incarnation normally contains the Exim uid.
9276 \$compile@_date$\: The date on which the Exim binary was compiled.
9279 \$compile@_number$\: The building process for Exim keeps a count of the number
9280 of times it has been compiled. This serves to distinguish different
9281 compilations of the same version of the program.
9283 .index black list (DNS)
9285 \$dnslist@_domain$\: When a client host is found to be on a DNS (black) list,
9286 the list's domain name is put into this variable so that it can be included in
9287 the rejection message.
9290 \$dnslist@_text$\: When a client host is found to be on a DNS (black) list, the
9291 contents of any associated TXT record are placed in this variable.
9294 \$dnslist@_value$\: When a client host is found to be on a DNS (black) list,
9295 the IP address from the resource record is placed in this variable.
9296 If there are multiple records, all the addresses are included, comma-space
9300 \$domain$\: When an address is being routed, or delivered on its own, this
9301 variable contains the domain. Global address rewriting happens when a message
9302 is received, so the value of \$domain$\ during routing and delivery is the
9303 value after rewriting. \$domain$\ is set during user filtering, but not during
9304 system filtering, because a message may have many recipients and the system
9305 filter is called just once.
9307 When more than one address is being delivered at once (for example, several
9308 \\RCPT\\ commands in one SMTP delivery), \$domain$\ is set only if they all
9309 have the same domain. Transports can be restricted to handling only one domain
9310 at a time if the value of \$domain$\ is required at transport time -- this is
9311 the default for local transports. For further details of the environment in
9312 which local transports are run, see chapter ~~CHAPenvironment.
9314 .index \delay@_warning@_condition\
9315 At the end of a delivery, if all deferred addresses have the same domain, it is
9316 set in \$domain$\ during the expansion of \delay@_warning@_condition\.
9318 The \$domain$\ variable is also used in some other circumstances:
9320 When an ACL is running for a \\RCPT\\ command, \$domain$\ contains the domain
9321 of the recipient address.
9322 \**Note:**\ the domain of the sender address is in \$sender@_address@_domain$\
9323 at \\MAIL\\ time and at \\RCPT\\ time. \$domain$\ is not set for the \\MAIL\\
9326 When a rewrite item is being processed (see chapter ~~CHAPrewrite), \$domain$\
9327 contains the domain portion of the address that is being rewritten; it can be
9328 used in the expansion of the replacement address, for example, to rewrite
9329 domains by file lookup.
9331 With one important exception, whenever a domain list is being scanned,
9332 \$domain$\ contains the subject domain. \**Exception**\: When a domain list in
9333 a \sender@_domains\ condition in an ACL is being processed, the subject domain
9334 is in \$sender@_address@_domain$\ and not in \$domain$\. It works this way so
9335 that, in a \\RCPT\\ ACL, the sender domain list can be dependent on the
9336 recipient domain (which is what is in \$domain$\ at this time).
9338 .index \\ETRN\\||value of \$domain$\
9339 .index \smtp@_etrn@_command\
9340 When the \smtp@_etrn@_command\ option is being expanded, \$domain$\ contains
9341 the complete argument of the \\ETRN\\ command (see section ~~SECTETRN).
9345 \$domain@_data$\: When the \domains\ option on a router matches a domain by
9346 means of a lookup, the data read by the lookup is available during the running
9347 of the router as \$domain@_data$\. In addition, if the driver routes the
9348 address to a transport, the value is available in that transport. If the
9349 transport is handling multiple addresses, the value from the first address is
9352 \$domain@_data$\ is also set when the \domains\ condition in an ACL matches a
9353 domain by means of a lookup. The data read by the lookup is available during
9354 the rest of the ACL statement. In all other situations, this variable expands
9359 \$exim@_gid$\: This variable contains the numerical value of the Exim group id.
9362 \$exim@_path$\: This variable contains the path to the Exim binary.
9365 \$exim@_uid$\: This variable contains the numerical value of the Exim user id.
9369 \$header@_<<name>>$\: This is not strictly an expansion variable. It is
9370 expansion syntax for inserting the message header line with the given name.
9371 Note that the name must be terminated by colon or white space, because it may
9372 contain a wide variety of characters.
9373 Note also that braces must \*not*\ be used.
9377 When the \check@_local@_user\ option is set for a router, the user's home
9378 directory is placed in \$home$\ when the check succeeds. In particular, this
9379 means it is set during the running of users' filter files. A router may also
9380 explicitly set a home directory for use by a transport; this can be overridden
9381 by a setting on the transport itself.
9383 When running a filter test via the \-bf-\ option, \$home$\ is set to the value
9384 of the environment variable \\HOME\\.
9388 When the \%smtp%\ transport is expanding its options for encryption using TLS,
9389 \$host$\ contains the name of the host to which it is connected. Likewise, when
9390 used in the client part of an authenticator configuration (see chapter
9391 ~~CHAPSMTPAUTH), \$host$\ contains the name of the server to which the client
9393 .index transport||filter
9394 .index filter||transport filter
9395 When used in a transport filter (see chapter ~~CHAPtransportgeneric) \$host$\
9396 refers to the host involved in the current connection. When a local transport
9397 is run as a result of a router that sets up a host list, \$host$\ contains the
9398 name of the first host.
9402 This variable is set to the remote host's IP address whenever \$host$\ is set
9403 for a remote connection.
9407 If a \hosts\ condition in an ACL is satisfied by means of a lookup, the result
9408 of the lookup is made available in the \$host@_data$\ variable. This
9409 allows you, for example, to do things like this:
9411 deny hosts = net-lsearch;/some/file
9412 message = $host_data
9415 .index host||name lookup, failure of
9417 \$host@_lookup@_failed$\:
9418 This variable contains `1' if the message came from a remote host and there was
9419 an attempt to look up the host's name from its IP address, but the attempt
9420 failed. Otherwise the value of the variable is `0'.
9422 Exim checks that a forward lookup of at least one of the names it receives from
9423 a reverse lookup yields the original IP address. If this is not the case, Exim
9424 does not accept the looked up name(s), and \$host@_lookup@_failed$\ is set to
9425 `1'. Thus, being able to find a name from an IP address (for example, the
9426 existence of a PTR record in the DNS) is not sufficient on its own for the
9427 success of a host name lookup.
9432 The only time this variable is set is while expanding the \directory@_file\
9433 option in the \%appendfile%\ transport. The variable contains the inode number
9434 of the temporary file which is about to be renamed. It can be used to construct
9435 a unique name for the file.
9438 \$interface@_address$\:
9439 When a message is received over a TCP/IP connection, this variable contains the
9440 address of the local IP interface. See also the \-oMi-\ command line option.
9441 This variable can be used in ACLs and also, for example, to make the file name
9442 for a TLS certificate depend on which interface is being used.
9445 \$interface@_port$\:
9446 When a message is received over a TCP/IP connection, this variable contains the
9447 local port number. See also the \-oMi-\ command line option.
9448 This variable can be used in ACLs and also, for example, to make the file name
9449 for a TLS certificate depend on which port is being used.
9453 This variable, which is available only when Exim is compiled with LDAP support,
9454 contains the DN from the last entry in the most recently successful LDAP
9460 This variable contains the system load average, multiplied by 1000 to that it
9461 is an integer. For example, if the load average is 0.21, the value of the
9462 variable is 210. The value is recomputed every time the variable is referenced.
9465 \$local@_part$\: When an address is being routed, or delivered on its own, this
9466 variable contains the local part. When a number of addresses are being
9467 delivered together (for example, multiple \\RCPT\\ commands in an SMTP
9468 session), \$local@_part$\ is not set.
9470 Global address rewriting happens when a message is received, so the value of
9471 \$local@_part$\ during routing and delivery is the value after rewriting.
9472 \$local@_part$\ is set during user filtering, but not during system filtering,
9473 because a message may have many recipients and the system filter is called just
9476 If a local part prefix or suffix has been recognized, it is not included in the
9477 value of \$local@_part$\ during routing and subsequent delivery. The values of
9478 any prefix or suffix are in \$local@_part@_prefix$\ and
9479 \$local@_part@_suffix$\, respectively.
9481 When a message is being delivered to a file, pipe, or autoreply transport as a
9482 result of aliasing or forwarding, \$local@_part$\ is set to the local part of
9483 the parent address, not to the file name or command (see \$address@_file$\ and
9486 When an ACL is running for a \\RCPT\\ command, \$local@_part$\ contains the
9487 local part of the recipient address.
9489 When a rewrite item is being processed (see chapter ~~CHAPrewrite),
9490 \$local@_part$\ contains the local part of the address that is being rewritten;
9491 it can be used in the expansion of the replacement address, for example.
9493 In all cases, all quoting is removed from the local part. For example, for both
9496 "abc:xyz"@test.example
9497 abc\:xyz@test.example
9499 the value of \$local@_part$\ is
9503 If you use \$local@_part$\ to create another address, you should always wrap it
9504 inside a quoting operator. For example, in a \%redirect%\ router you could have:
9506 data = ${quote_local_part:$local_part}@new.domain.example
9509 \**Note**\: The value of \$local@_part$\ is normally lower cased. If you want
9510 to process local parts in a case-dependent manner in a router, you can set the
9511 \caseful@_local@_part\ option (see chapter ~~CHAProutergeneric).
9515 \$local@_part@_data$\:
9516 When the \local@_parts\ option on a router matches a local part by means of a
9517 lookup, the data read by the lookup is available during the running of the
9518 router as \$local@_part@_data$\. In addition, if the driver routes the address
9519 to a transport, the value is available in that transport. If the transport is
9520 handling multiple addresses, the value from the first address is used.
9522 \$local@_part@_data$\ is also set when the \local@_parts\ condition in an ACL
9523 matches a local part by means of a lookup. The data read by the lookup is
9524 available during the rest of the ACL statement. In all other situations, this
9525 variable expands to nothing.
9528 \$local@_part@_prefix$\: When an address is being routed or delivered, and a
9529 specific prefix for the local part was recognized, it is available in this
9530 variable, having been removed from \$local@_part$\.
9533 \$local@_part@_suffix$\: When an address is being routed or delivered, and a
9534 specific suffix for the local part was recognized, it is available in this
9535 variable, having been removed from \$local@_part$\.
9538 \$local@_scan@_data$\: This variable contains the text returned by the
9539 \*local@_scan()*\ function when a message is received. See chapter
9540 ~~CHAPlocalscan for more details.
9543 \$local@_user@_gid$\: See \$local@_user@_uid$\.
9546 \$local@_user@_uid$\: This variable and \$local@_user@_gid$\ are set to
9547 the uid and gid after the \check__local__user\ router precondition succeeds.
9548 This means that their values are available for the remaining preconditions
9549 (\senders\, \require@_files\, and \condition\), for the \address@_data\
9550 expansion, and for any router-specific expansions. At all other times, the
9551 values in these variables are \"(uid@_t)(-1)"\ and \"(gid@_t)(-1)"\,
9556 \$localhost@_number$\: This contains the expanded value of the
9557 \localhost@_number\ option. The expansion happens after the main options have
9561 \$mailstore@_basename$\: This variable is set only when doing deliveries in
9562 `mailstore' format in the \%appendfile%\ transport. During the expansion of the
9563 \mailstore@_prefix\, \mailstore@_suffix\, \message__prefix\, and
9564 \message@_suffix\ options, it contains the basename of the files that are being
9565 written, that is, the name without the `.tmp', `.env', or `.msg' suffix. At all
9566 other times, this variable is empty.
9568 .index message||age of
9570 \$message@_age$\: This variable is set at the start of a delivery attempt to
9571 contain the number of seconds since the message was received. It does not
9572 change during a single delivery attempt.
9574 .index body of message||expansion variable
9575 .index message||body, in expansion
9576 .index binary zero||in message body
9578 \$message@_body$\: This variable contains the initial portion of a message's
9579 body while it is being delivered, and is intended mainly for use in filter
9580 files. The maximum number of characters of the body that are put into the
9581 variable is set by the \message@_body@_visible\ configuration option; the
9582 default is 500. Newlines are converted into spaces to make it easier to search
9583 for phrases that might be split over a line break.
9584 Binary zeros are also converted into spaces.
9586 .index body of message||expansion variable
9587 .index message||body, in expansion
9589 \$message@_body@_end$\: This variable contains the final portion of a message's
9590 body while it is being delivered. The format and maximum size are as for
9593 .index body of message||size
9594 .index message||body, size
9596 \$message@_body@_size$\: When a message is being processed, this variable
9597 contains the size of the body in bytes. The count starts from the character
9598 after the blank line that separates the body from the header. Newlines are
9599 included in the count. See also \$message@_size$\ and \$body@_linecount$\.
9602 \$message@_headers$\:
9603 This variable contains a concatenation of all the header lines when a message
9604 is being processed, except for lines added by routers or transports. The header
9605 lines are separated by newline characters.
9609 When a message is being received or delivered, this variable contains the
9610 unique message id that is used by Exim to identify the message.
9611 An id is not created for a message until after its header has been
9612 successfully received.
9614 \**Note**\: This is \*not*\ the contents of the ::Message-ID:: header line; it
9615 is the local id that Exim assigns to the message, for example:
9616 \"1BXTIK-0001yO-VA"\.
9619 .index size||of message
9620 .index message||size
9623 When a message is being processed, this variable contains its size in bytes. In
9624 most cases, the size includes those headers that were received with the
9625 message, but not those (such as ::Envelope-to::) that are added to individual
9626 deliveries as they are written. However, there is one special case: during the
9627 expansion of the \maildir@_tag\ option in the \%appendfile%\ transport while
9628 doing a delivery in maildir format, the value of \$message@_size$\ is the
9629 precise size of the file that has been written. See also
9630 \$message@_body@_size$\ and \$body@_linecount$\.
9632 .index \\RCPT\\||value of \$message@_size$\
9633 While running an ACL at the time of an SMTP \\RCPT\\ command, \$message@_size$\
9634 contains the size supplied on the \\MAIL\\ command, or
9636 if no size was given. The value may not, of course, be truthful.
9639 \$n0$\ -- \$n9$\: These variables are counters that can be incremented by means
9640 of the \add\ command in filter files.
9643 \$original@_domain$\: When a top-level address is being processed for delivery,
9644 this contains the same value as \$domain$\. However, if a `child' address (for
9645 example, generated by an alias, forward, or filter file) is being processed,
9646 this variable contains the domain of the original address. This differs from
9647 \$parent@_domain$\ only when there is more than one level of aliasing or
9648 forwarding. When more than one address is being delivered in a single transport
9649 run, \$original@_domain$\ is not set.
9651 If new an address is created by means of a \deliver\ command in a system
9652 filter, it is set up with an artificial `parent' address. This has the local
9653 part \*system-filter*\ and the default qualify domain.
9656 \$original@_local@_part$\: When a top-level address is being processed for
9657 delivery, this contains the same value as \$local@_part$\, unless a prefix or
9658 suffix was removed from the local part, in which case \$original@_local@_part$\
9659 contains the full local part. When a `child' address (for example, generated by
9660 an alias, forward, or filter file) is being processed, this variable contains
9661 the full local part of the original address. If the router that did the
9662 redirection processed the local part case-insensitively, the value in
9663 \$original@_local@_part$\ is in lower case. This variable differs from
9664 \$parent@_local@_part$\ only when there is more than one level of aliasing or
9665 forwarding. When more than one address is being delivered in a single transport
9666 run, \$original@_local@_part$\ is not set.
9668 If new an address is created by means of a \deliver\ command in a system
9669 filter, it is set up with an artificial `parent' address. This has the local
9670 part \*system-filter*\ and the default qualify domain.
9673 .index gid (group id)||of originating user
9676 \$originator@_gid$\: The value of \$caller@_gid$\ that was set when the message
9677 was received. For messages received via the command line, this is the gid of
9678 the sending user. For messages received by SMTP over TCP/IP, this is normally
9679 the gid of the Exim user.
9681 .index uid (user id)||of originating user
9684 \$originator@_uid$\: The value of \$caller@_uid$\ that was set when the message
9685 was received. For messages received via the command line, this is the uid of
9686 the sending user. For messages received by SMTP over TCP/IP, this is normally
9687 the uid of the Exim user.
9690 \$parent@_domain$\: This variable is similar to \$original@_domain$\ (see
9691 above), except that it refers to the immediately preceding parent address.
9694 \$parent@_local@_part$\: This variable is similar to \$original@_local@_part$\
9695 (see above), except that it refers to the immediately preceding parent address.
9697 .index pid (process id)||of current process
9699 \$pid$\: This variable contains the current process id.
9701 .index filter||transport filter
9702 .index transport||filter
9704 \$pipe@_addresses$\: This is not an expansion variable, but is mentioned here
9705 because the string `@$pipe@_addresses' is handled specially in the command
9706 specification for the \%pipe%\ transport (chapter ~~CHAPpipetransport) and in
9707 transport filters (described under \transport@_filter\ in chapter
9708 ~~CHAPtransportgeneric). It cannot be used in general expansion strings, and
9709 provokes an `unknown variable' error if encountered.
9712 \$primary@_hostname$\: The value set in the configuration file, or read by the
9713 \*uname()*\ function. If \*uname()*\ returns a single-component name, Exim
9714 calls \*gethostbyname()*\ (or \*getipnodebyname()*\ where available) in an
9715 attempt to acquire a fully qualified host name.
9717 See also \$smtp@_active@_hostname$\.
9721 \$qualify@_domain$\: The value set for this option in the configuration file.
9724 \$qualify@_recipient$\: The value set for this option in the configuration file,
9725 or if not set, the value of \$qualify@_domain$\.
9728 \$rcpt@_count$\: When a message is being received by SMTP, this variable
9729 contains the number of \\RCPT\\ commands received for the current message. If
9730 this variable is used in a \\RCPT\\ ACL, its value includes the current
9734 \$rcpt@_defer@_count$\: When a message is being received by SMTP, this variable
9735 contains the number of \\RCPT\\ commands in the current message that have
9736 previously been rejected with a temporary (4\*xx*\) response.
9739 \$rcpt@_fail@_count$\: When a message is being received by SMTP, this variable
9740 contains the number of \\RCPT\\ commands in the current message that have
9741 previously been rejected with a permanent (5\*xx*\) response.
9744 \$received@_count$\: This variable contains the number of ::Received:: header
9745 lines in the message, including the one added by Exim (so its value is always
9746 greater than zero). It is available in the \\DATA\\ ACL, the non-SMTP ACL, and
9747 while routing and delivering.
9750 \$received@_for$\: If there is only a single recipient address in an incoming
9751 message, this variable contains that address when the ::Received:: header line
9754 The value is copied after recipient rewriting has happened, but before the
9755 \*local@_scan()*\ function is run.
9759 \$received@_protocol$\: When a message is being processed, this variable
9760 contains the name of the protocol by which it was received. See also the
9765 \$recipient@_data$\: This variable is set after an indexing lookup success in
9766 an ACL \recipients\ condition. It contains the data from the lookup, and the
9767 value remains set until the next \recipients\ test. Thus, you can do things
9770 require recipients = cdb*@@;/some/file
9771 deny \*some further test involving*\ @$recipient@_data
9773 \**Warning**\: This variable is set only when a lookup is used as an indexing
9774 method in the address list, using the semicolon syntax as in the example above.
9775 The variable is not set for a lookup that is used as part of the string
9776 expansion that all such lists undergo before being interpreted.
9780 \$recipients$\: This variable contains a list of envelope recipients for a
9781 message. A comma and a space separate the addresses in the replacement text.
9782 However, the variable is not generally available, to prevent exposure of Bcc
9783 recipients in unprivileged users' filter files. You can use \$recipients$\ only
9785 In a system filter file.
9787 In the \\DATA\\ or non-SMTP ACL, that is, in the final ACL for accepting a
9792 \$recipients@_count$\: When a message is being processed, this variable
9793 contains the number of envelope recipients that came with the message.
9794 Duplicates are not excluded from the count. While a message is being received
9795 over SMTP, the number increases for each accepted recipient. It can be
9796 referenced in an ACL.
9799 \$reply@_address$\: When a message is being processed, this variable contains
9800 the contents of the ::Reply-To:: header line if one exists
9801 and it is not empty,
9802 or otherwise the contents of the ::From:: header line.
9805 \$return@_path$\: When a message is being delivered, this variable contains the
9806 return path -- the sender field that will be sent as part of the envelope. It
9807 is not enclosed in @<@> characters.
9808 At the start of routing an address,
9809 \$return@_path$\ has the same value as \$sender@_address$\, but if, for
9810 example, an incoming message to a mailing list has been expanded by a router
9811 which specifies a different address for bounce messages, \$return@_path$\
9812 subsequently contains the new bounce address, whereas \$sender@_address$\
9813 always contains the original sender address that was received with the message.
9814 In other words, \$sender@_address$\ contains the incoming envelope sender, and
9815 \$return@_path$\ contains the outgoing envelope sender.
9818 \$return@_size@_limit$\: This is an obsolete name for
9819 \$bounce@_return@_size@_limit$\.
9821 .index return code||from \run\ expansion
9823 \$runrc$\: This variable contains the return code from a command that is run by
9824 the \@$@{run...@}\ expansion item.
9825 \**Warning**\: In a router or transport, you cannot assume the order in which
9826 option values are expanded, except for those pre-conditions whose order of
9827 testing is documented. Therefore, you cannot reliably expect to set \$runrc$\
9828 by the expansion of one option, and use it in another.
9831 \$self@_hostname$\: When an address is routed to a supposedly remote host that
9832 turns out to be the local host, what happens is controlled by the
9833 .index \self\ option||value of host name
9834 \self\ generic router option. One of its values causes the address to be passed
9835 to another router. When this happens, \$self@_hostname$\ is set to the name of
9836 the local host that the original router encountered. In other circumstances its
9840 \$sender@_address$\: When a message is being processed, this variable contains
9841 the sender's address that was received in the message's envelope. For bounce
9842 messages, the value of this variable is the empty string.
9843 See also \$return@_path$\.
9846 \$sender@_address@_domain$\: The domain portion of \$sender@_address$\.
9849 \$sender@_address@_local@_part$\: The local part portion of \$sender@_address$\.
9853 \$sender@_data$\: This variable is set after a lookup success in an ACL
9854 \senders\ condition or in a router \senders\ option. It contains the data from
9855 the lookup, and the value remains set until the next \senders\ test. Thus, you
9856 can do things like this:
9858 require senders = cdb*@@;/some/file
9859 deny \*some further test involving*\ @$sender@_data
9861 \**Warning**\: This variable is set only when a lookup is used as an indexing
9862 method in the address list, using the semicolon syntax as in the example above.
9863 The variable is not set for a lookup that is used as part of the string
9864 expansion that all such lists undergo before being interpreted.
9868 \$sender@_fullhost$\: When a message is received from a remote host, this
9869 variable contains the host name and IP address in a single string. It ends
9870 with the IP address in square brackets, followed by a colon and a port number
9871 if the logging of ports is enabled. The format of the rest of the string
9872 depends on whether the host issued a \\HELO\\ or \\EHLO\\ SMTP command, and
9873 whether the host name was verified by looking up its IP address. (Looking up
9874 the IP address can be forced by the \host@_lookup\ option, independent of
9875 verification.) A plain host name at the start of the string is a verified host
9876 name; if this is not present, verification either failed or was not requested.
9877 A host name in parentheses is the argument of a \\HELO\\ or \\EHLO\\ command.
9878 This is omitted if it is identical to the verified host name or to the host's
9879 IP address in square brackets.
9882 \$sender@_helo@_name$\: When a message is received from a remote host that has
9883 issued a \\HELO\\ or \\EHLO\\ command, the argument of that command is placed
9884 in this variable. It is also set if \\HELO\\ or \\EHLO\\ is used when a message
9885 is received using SMTP locally via the \-bs-\ or \-bS-\ options.
9888 \$sender@_host@_address$\: When a message is received from a remote host, this
9889 variable contains that host's IP address. For locally submitted messages, it is
9893 \$sender@_host@_authenticated$\: This variable contains the name (not the
9894 public name) of the authenticator driver which successfully authenticated the
9895 client from which the message was received. It is empty if there was no
9896 successful authentication.
9899 \$sender@_host@_name$\: When a message is received from a remote host, this
9900 variable contains the host's name as obtained by looking up its IP address.
9901 For messages received by other means, this variable is empty.
9903 If the host name has not previously been looked up, a reference to
9904 \$sender@_host@_name$\ triggers a lookup (for messages from remote hosts).
9906 A looked up name is accepted only if it leads back to the original IP address
9907 via a forward lookup. If either the reverse or the forward lookup fails, or if
9908 the forward lookup does not yield the original IP address,
9909 \$sender@_host@_name$\ remains empty, and \$host@_lookup@_failed$\ is set to
9913 Exim does not automatically look up every calling host's name. If you want
9914 maximum efficiency, you should arrange your configuration so that it avoids
9915 these lookups altogether. The lookup happens only if one or more of the
9918 A string containing \$sender@_host@_name$\ is expanded.
9920 The calling host matches the list in \host@_lookup\. In the default
9921 configuration, this option is set to $*$, so it must be changed if lookups are
9922 to be avoided. (In the code, the default for \host@_lookup\ is unset.)
9924 Exim needs the host name in order to test an item in a host list. The items
9925 that require this are described in sections ~~SECThoslispatnam and
9926 ~~SECThoslispatnamsk.
9928 The calling host matches \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\.
9929 In this case, the host name is required to compare with the name quoted in any
9930 \\EHLO\\ or \\HELO\\ commands that the client issues.
9932 The remote host issues a \\EHLO\\ or \\HELO\\ command that quotes one of the
9933 domains in \helo@_lookup@_domains\. The default value of this option is
9935 helo_lookup_domains = @ : @[]
9937 which causes a lookup if a remote host (incorrectly) gives the server's name or
9938 IP address in an \\EHLO\\ or \\HELO\\ command.
9942 \$sender@_host@_port$\: When a message is received from a remote host, this
9943 variable contains the port number that was used on the remote host.
9946 \$sender@_ident$\: When a message is received from a remote host, this variable
9947 contains the identification received in response to an RFC 1413 request. When a
9948 message has been received locally, this variable contains the login name of the
9949 user that called Exim.
9952 \$sender@_rcvhost$\: This is provided specifically for use in ::Received::
9953 headers. It starts with either the verified host name (as obtained from a
9954 .index DNS||reverse lookup
9955 .index reverse DNS lookup
9956 reverse DNS lookup) or, if there is no verified host name, the IP address in
9957 square brackets. After that there may be text in parentheses. When the first
9958 item is a verified host name, the first thing in the parentheses is the IP
9959 address in square brackets, followed by a colon and a port number if port
9960 logging is enabled. When the first item is an IP address, the port is recorded
9961 as `port=$it{xxxx}' inside the parentheses.
9963 There may also be items of the form `helo=$it{xxxx}' if \\HELO\\ or \\EHLO\\
9964 was used and its argument was not identical to the real host name or IP
9965 address, and `ident=$it{xxxx}' if an RFC 1413 ident string is available. If all
9966 three items are present in the parentheses, a newline and tab are inserted into
9967 the string, to improve the formatting of the ::Received:: header.
9969 .index \\AUTH\\||argument
9970 .index \\EXPN\\||argument
9971 .index \\ETRN\\||argument
9972 .index \\VRFY\\||argument
9974 \$smtp@_command@_argument$\: While an ACL is running to check an \\AUTH\\,
9975 \\EHLO\\, \\EXPN\\, \\ETRN\\, \\HELO\\, or \\VRFY\\ command, this variable
9976 contains the argument for the SMTP command.
9979 \$sn0$\ -- \$sn9$\: These variables are copies of the values of the \$n0$\
9980 -- \$n9$\ accumulators that were current at the end of the system filter file.
9981 This allows a system filter file to set values that can be tested in users'
9982 filter files. For example, a system filter could set a value indicating how
9983 likely it is that a message is junk mail.
9986 \$spool@_directory$\: The name of Exim's spool directory.
9989 \$thisaddress$\: This variable is set only during the processing of the
9990 \foranyaddress\ command in a filter file. Its use is explained in the
9991 description of that command.
9994 \$tls@_certificate@_verified$\:
9995 This variable is set to `1' if a TLS certificate was verified when the message
9996 was received, and `0' otherwise.
9999 \$tls@_cipher$\: When a message is received from a remote host over an
10000 encrypted SMTP connection, this variable is set to the cipher suite that was
10001 negotiated, for example DES-CBC3-SHA.
10002 In other circumstances, in particular, for message received over unencrypted
10003 connections, the variable is empty.
10004 See chapter ~~CHAPTLS for details of TLS support.
10007 \$tls@_peerdn$\: When a message is received from a remote host over an
10008 encrypted SMTP connection,
10009 and Exim is configured to request a certificate from the client,
10010 the value of the Distinguished Name of the certificate is made available in the
10011 \$tls@_peerdn$\ during subsequent processing.
10014 \$tod@_bsdinbox$\: The time of day and date, in the format required for
10015 BSD-style mailbox files, for example: Thu Oct 17 17:14:09 1995.
10018 \$tod@_epoch$\: The time and date as a number of seconds since the start of the
10022 \$tod@_full$\: A full version of the time and date, for example: Wed, 16 Oct
10023 1995 09:51:40 +0100. The timezone is always given as a numerical offset from
10024 UTC, with positive values used for timezones that are ahead (east) of UTC, and
10025 negative values for those that are behind (west).
10028 \$tod@_log$\: The time and date in the format used for writing Exim's log
10029 files, for example: 1995-10-12 15:32:29,
10030 but without a timezone.
10034 This variable contains the date in the format yyyymmdd. This is the format that
10035 is used for datestamping log files when \log@_file@_path\ contains the \"%D"\
10039 \$tod@_zone$\: This variable contains the numerical value of the local
10040 timezone, for example: -0500.
10044 This variable contains the UTC date and time in `Zulu' format, as specified by
10045 ISO 8601, for example: 20030221154023Z.
10049 \$value$\: This variable contains the result of an expansion lookup, extraction
10050 operation, or external command, as described above.
10053 \$version@_number$\: The version number of Exim.
10056 \$warn@_message@_delay$\: This variable is set only during the creation of a
10057 message warning about a delivery delay. Details of its use are explained in
10058 section ~~SECTcustwarn.
10061 \$warn@_message@_recipients$\: This variable is set only during the creation of
10062 a message warning about a delivery delay. Details of its use are explained in
10063 section ~~SECTcustwarn.
10070 . ============================================================================
10071 .chapter Embedded Perl
10072 .set runningfoot "embedded Perl"
10073 .rset CHAPperl "~~chapter"
10074 .index Perl||calling from Exim
10076 Exim can be built to include an embedded Perl interpreter. When this is done,
10077 Perl subroutines can be called as part of the string expansion process. To make
10078 use of the Perl support, you need version 5.004 or later of Perl installed on
10079 your system. To include the embedded interpreter in the Exim binary, include
10084 in your \(Local/Makefile)\ and then build Exim in the normal way.
10086 Access to Perl subroutines is via a global configuration option called
10087 .index \perl@_startup\
10088 \perl@_startup\ and an expansion string operator \@$@{perl ...@}\. If there is
10089 no \perl@_startup\ option in the Exim configuration file then no Perl
10090 interpreter is started and there is almost no overhead for Exim (since none of
10091 the Perl library will be paged in unless used). If there is a \perl@_startup\
10092 option then the associated value is taken to be Perl code which is executed in
10093 a newly created Perl interpreter.
10095 The value of \perl@_startup\ is not expanded in the Exim sense, so you do not
10096 need backslashes before any characters to escape special meanings. The option
10097 should usually be something like
10099 perl_startup = do '/etc/exim.pl'
10101 where \(/etc/exim.pl)\ is Perl code which defines any subroutines you want to
10102 use from Exim. Exim can be configured either to start up a Perl interpreter as
10103 soon as it is entered, or to wait until the first time it is needed. Starting
10104 the interpreter at the beginning ensures that it is done while Exim still has
10105 its setuid privilege, but can impose an unnecessary overhead if Perl is not in
10106 fact used in a particular run. Also, note that this does not mean that Exim is
10107 necessarily running as root when Perl is called at a later time. By default,
10108 the interpreter is started only when it is needed, but this can be changed in
10111 .index \perl@_at@_start\
10112 Setting \perl@_at@_start\ (a boolean option) in the configuration requests
10113 a startup when Exim is entered.
10115 The command line option \-ps-\ also requests a startup when Exim is entered,
10116 overriding the setting of \perl@_at@_start\.
10118 There is also a command line option \-pd-\ (for delay) which suppresses the
10119 initial startup, even if \perl@_at@_start\ is set.
10121 When the configuration file includes a \perl@_startup\ option you can make use
10122 of the string expansion item to call the Perl subroutines that are defined
10123 by the \perl@_startup\ code. The operator is used in any of the following
10127 ${perl{foo}{argument}}
10128 ${perl{foo}{argument1}{argument2} ... }
10130 which calls the subroutine \foo\ with the given arguments. A maximum of eight
10131 arguments may be passed. Passing more than this results in an expansion failure
10132 with an error message of the form
10134 Too many arguments passed to Perl subroutine "foo" (max is 8)
10136 The return value of the Perl subroutine is evaluated in a scalar context before
10137 it is passed back to Exim to be inserted into the expanded string. If the
10138 return value is \*undef*\, the expansion fails in the same way as an explicit
10139 `fail' on an \@$@{if ...@}\ or \@$@{lookup...@}\ item.
10140 If the subroutine aborts by obeying Perl's \die\ function, the expansion fails
10141 with the error message that was passed to \die\.
10143 Within any Perl code called from Exim, the function \*Exim@:@:expand@_string*\
10144 is available to call back into Exim's string expansion function. For example,
10147 my $lp = Exim::expand_string('$local_part');
10149 makes the current Exim \$local@_part$\ available in the Perl variable \$lp$\.
10150 Note those are single quotes and not double quotes to protect against
10151 \$local@_part$\ being interpolated as a Perl variable.
10153 If the string expansion is forced to fail by a `fail' item, the result of
10154 \*Exim@:@:expand@_string*\ is \undef\. If there is a syntax error in the
10155 expansion string, the Perl call from the original expansion string fails with
10156 an appropriate error message, in the same way as if \die\ were used.
10158 .index debugging||from embedded Perl
10159 .index log||writing from embedded Perl
10160 Two other Exim functions are available for use from within Perl code.
10161 \*Exim@:@:debug@_write(<<string>>)*\ writes the string to the standard error
10162 stream if Exim's debugging is enabled. If you want a newline at the end, you
10163 must supply it. \*Exim@:@:log@_write(<<string>>)*\ writes the string to Exim's
10164 main log, adding a leading timestamp. In this case, you should not supply a
10165 terminating newline.
10173 . ============================================================================
10174 .chapter Starting the daemon and the use of network interfaces
10175 .set runningfoot "starting the daemon"
10176 .rset CHAPinterfaces "~~chapter"
10177 .index daemon||starting
10178 .index interface||listening
10179 .index network interface
10180 .index interface||network
10181 .index IP address||for listening
10182 .index daemon||listening IP addresses
10183 .index TCP/IP||setting listening interfaces
10184 .index TCP/IP||setting listening ports
10186 A host that is connected to a TCP/IP network may have one or more physical
10187 hardware network interfaces. Each of these interfaces may be configured as one
10188 or more `logical' interfaces, which are the entities that a program actually
10189 works with. Each of these logical interfaces is associated with an IP address.
10190 In addition, TCP/IP software supports `loopback' interfaces (127.0.0.1 in IPv4
10191 and @:@:1 in IPv6), which do not use any physical hardware. Exim requires
10192 knowledge about the host's interfaces for use in three different circumstances:
10194 When a listening daemon is started, Exim needs to know which interfaces
10195 and ports to listen on.
10197 When Exim is routing an address, it needs to know which IP addresses
10198 are associated with local interfaces. This is required for the correct
10199 processing of MX lists by removing the local host and others with the
10200 same or higher priority values. Also, Exim needs to detect cases
10201 when an address is routed to an IP address that in fact belongs to the
10202 local host. Unless the \self\ router option or the \allow@_localhost\
10203 option of the smtp transport is set (as appropriate), this is treated
10204 as an error situation.
10206 When Exim connects to a remote host, it may need to know which interface to use
10207 for the outgoing connection.
10210 Exim's default behaviour is likely to be appropriate in the vast majority
10211 of cases. If your host has only one interface, and you want all its IP
10212 addresses to be treated in the same way, and you are using only the
10213 standard SMTP port, you should not need to take any special action. The
10214 rest of this chapter does not apply to you.
10216 In a more complicated situation you may want to listen only on certain
10217 interfaces, or on different ports, and for this reason there are a number of
10218 options that can be used to influence Exim's behaviour. The rest of this
10219 chapter describes how they operate.
10221 When a message is received over TCP/IP, the interface and port that were
10222 actually used are set in \$interface@_address$\ and \$interface@_port$\.
10225 .section Starting a listening daemon
10226 When a listening daemon is started (by means of the \-bd-\ command line
10227 option), the interfaces and ports on which it listens are controlled by the
10230 \daemon@_smtp@_ports\ contains a list of default ports. (For backward
10231 compatibility, this option can also be specified in the singular.)
10233 \local@_interfaces\ contains list of interface IP addresses on which to
10234 listen. Each item may optionally also specify a port.
10236 The default list separator in both cases is a colon, but this can be changed as
10237 described in section ~~SECTlistconstruct. When IPv6 addresses are involved, it
10238 is usually best to change the separator to avoid having to double all the
10239 colons. For example:
10241 local_interfaces = <; 127.0.0.1 ; \
10244 3ffe:ffff:836f::fe86:a061
10246 There are two different formats for specifying a port along with an IP address
10247 in \local@_interfaces\:
10249 The port is added onto the address with a dot separator. For example, to listen
10250 on port 1234 on two different IP addresses:
10252 local_interfaces = <; 192.168.23.65.1234 ; \
10253 3ffe:ffff:836f::fe86:a061.1234
10256 The IP address is enclosed in square brackets, and the port is added
10257 with a colon separator, for example:
10259 local_interfaces = <; [192.168.23.65]:1234 ; \
10260 [3ffe:ffff:836f::fe86:a061]:1234
10263 When a port is not specified, the value of \daemon@_smtp@_ports\ is used. The
10264 default setting contains just one port:
10266 daemon_smtp_ports = smtp
10268 If more than one port is listed, each interface that does not have its own port
10269 specified listens on all of them. Ports that are listed in
10270 \daemon@_smtp@_ports\ can be identified either by name (defined in
10271 \(/etc/services)\) or by number. However, when ports are given with individual
10272 IP addresses in \local@_interfaces\, only numbers (not names) can be used.
10275 .section Special IP listening addresses
10276 The addresses 0.0.0.0 and @:@:0 are treated specially. They are interpreted
10277 as `all IPv4 interfaces' and `all IPv6 interfaces', respectively. In each
10278 case, Exim tells the TCP/IP stack to `listen on all IPv\*x*\ interfaces'
10279 instead of setting up separate listening sockets for each interface. The
10280 default value of \local@_interfaces\ is
10282 local_interfaces = 0.0.0.0
10284 when Exim is built without IPv6 support; otherwise it is:
10286 local_interfaces = <; ::0 ; 0.0.0.0
10288 Thus, by default, Exim listens on all available interfaces, on the SMTP port.
10291 .section Overriding local@_interfaces and daemon@_smtp@_ports
10292 The \-oX-\ command line option can be used to override the values of
10293 \daemon@_smtp@_ports\ and/or \local@_interfaces\ for a particular daemon
10294 instance. Another way of doing this would be to use macros and the \-D-\
10295 option. However, \-oX-\ can be used by any admin user, whereas modification of
10296 the runtime configuration by \-D-\ is allowed only when the caller is root or
10299 The value of \-oX-\ is a list of items. The default colon separator can be
10300 changed in the usual way if required. If there are any items that do not
10301 contain dots or colons (that is, are not IP addresses), the value of
10302 \daemon@_smtp@_ports\ is replaced by the list of those items. If there are any
10303 items that do contain dots or colons, the value of \local@_interfaces\ is
10304 replaced by those items. Thus, for example,
10308 overrides \daemon@_smtp@_ports\, but leaves \local@_interfaces\ unchanged,
10311 -oX 192.168.34.5.1125
10313 overrides \local@_interfaces\, leaving \daemon@_smtp@_ports\ unchanged.
10314 (However, since \local@_interfaces\ now contains no items without ports, the
10315 value of \daemon@_smtp@_ports\ is no longer relevant in this example.)
10318 .section IPv6 address scopes
10319 IPv6 addresses have `scopes', and a host with multiple hardware interfaces
10320 can, in principle, have the same link-local IPv6 address on different
10321 interfaces. Thus, additional information is needed, over and above the IP
10322 address, to distinguish individual interfaces. A convention of using a
10323 percent sign followed by something (often the interface name) has been
10324 adopted in some cases, leading to addresses like this:
10326 3ffe:2101:12:1:a00:20ff:fe86:a061%eth0
10328 To accommodate this usage, a percent sign followed by an arbitrary string is
10329 allowed at the end of an IPv6 address. By default, Exim calls \*getaddrinfo()*\
10330 to convert a textual IPv6 address for actual use. This function recognizes the
10331 percent convention in operating systems that support it, and it processes the
10332 address appropriately. Unfortunately, some older libraries have problems with
10333 \*getaddrinfo()*\. If
10335 IPV6_USE_INET_PTON=yes
10337 is set in \(Local/Makefile)\ (or an OS-dependent Makefile) when Exim is built,
10338 Exim uses \*inet@_pton()*\ to convert a textual IPv6 address for actual use,
10339 instead of \*getaddrinfo()*\. (Before version 4.14, it always used this
10340 function.) Of course, this means that the additional functionality of
10341 \*getaddrinfo()*\ -- recognizing scoped addresses -- is lost.
10344 .section Examples of starting a listening daemon
10345 The default case in an IPv6 environment is
10347 daemon_smtp_port = smtp
10348 local_interfaces = <; ::0 ; 0.0.0.0
10350 This specifies listening on the smtp port on all IPv6 and IPv4 interfaces.
10351 Either one or two sockets may be used, depending on the characteristics of
10352 the TCP/IP stack. (This is complicated and messy; for more information,
10353 read the comments in the \(daemon.c)\ source file.)
10355 To specify listening on ports 25 and 26 on all interfaces:
10357 daemon_smtp_ports = 25 : 26
10359 (leaving \local@_interfaces\ at the default setting) or, more explicitly:
10361 local_interfaces = <; ::0.25 ; ::0.26 \
10362 0.0.0.0.25 ; 0.0.0.0.26
10364 To listen on the default port on all IPv4 interfaces, and on port 26 on the
10365 IPv4 loopback address only:
10367 local_interfaces = 0.0.0.0 : 127.0.0.1.26
10369 To specify listening on the default port on specific interfaces only:
10371 local_interfaces = 192.168.34.67 : 192.168.34.67
10373 \**Note**\: such a setting excludes listening on the loopback interfaces.
10376 .section Recognising the local host
10377 .rset SECTreclocipadd "~~chapter.~~section"
10378 The \local@_interfaces\ option is also used when Exim needs to determine
10379 whether or not an IP address refers to the local host. That is, the IP
10380 addresses of all the interfaces on which a daemon is listening are always
10383 For this usage, port numbers in \local@_interfaces\ are ignored. If either of
10384 the items 0.0.0.0 or @:@:0 are encountered, Exim gets a complete list of
10385 available interfaces from the operating system, and extracts the relevant
10386 (that is, IPv4 or IPv6) addresses to use for checking.
10388 Some systems set up large numbers of virtual interfaces in order to provide
10389 many virtual web servers. In this situation, you may want to listen for
10390 email on only a few of the available interfaces, but nevertheless treat all
10391 interfaces as local when routing. You can do this by setting
10392 \extra@_local@_interfaces\ to a list of IP addresses, possibly including the
10393 `all' wildcard values. These addresses are recognized as local, but are not
10394 used for listening. Consider this example:
10396 local_interfaces = <; 127.0.0.1 ; ::1 ; \
10398 3ffe:2101:12:1:a00:20ff:fe86:a061
10400 extra_local_interfaces = <; ::0 ; 0.0.0.0
10402 The daemon listens on the loopback interfaces and just one IPv4 and one IPv6
10403 address, but all available interface addresses are treated as local when
10406 In some environments the local host name may be in an MX list, but with an IP
10407 address that is not assigned to any local interface. In other cases it may be
10408 desirable to treat other host names as if they referred to the local host. Both
10409 these cases can be handled by setting the \hosts@_treat@_as@_local\ option.
10410 This contains host names rather than IP addresses. When a host is referenced
10411 during routing, either via an MX record or directly, it is treated as the local
10412 host if its name matches \hosts@_treat@_as@_local\, or if any of its IP
10413 addresses match \local@_interfaces\ or \extra@_local@_interfaces\.
10416 .section Delivering to a remote host
10417 Delivery to a remote host is handled by the smtp transport. By default, it
10418 allows the system's TCP/IP functions to choose which interface to use (if
10419 there is more than one) when connecting to a remote host. However, the
10420 \interface\ option can be set to specify which interface is used. See the
10421 description of the smtp transport in chapter ~~CHAPsmtptrans for more details.
10431 . ============================================================================
10432 .chapter Main configuration
10433 .set runningfoot "main configuration"
10434 .rset CHAPmainconfig "~~chapter"
10435 .index configuration file||main section
10436 .index main configuration
10437 The first part of the run time configuration file contains three types of item:
10439 Macro definitions: These lines start with an upper case letter. See section
10440 ~~SECTmacrodefs for details of macro processing.
10442 Named list definitions: These lines start with one of the words `domainlist',
10443 `hostlist', `addresslist', or `localpartlist'. Their use is described in
10444 section ~~SECTnamedlists.
10446 Main configuration settings: Each setting occupies one line of the file
10447 (with possible continuations). If any setting is preceded by the word
10448 `hide', the \-bP-\ command line option displays its value to admin users only.
10449 See section ~~SECTcos for a description of the syntax of these option settings.
10451 This chapter specifies all the main configuration options, along with their
10452 types and default values. For ease of finding a particular option, they appear
10453 in alphabetical order in section ~~SECTalomo below. However, because there are
10454 now so many options, they are first listed briefly in functional groups, as an
10455 aid to finding the name of the option you are looking for.
10456 Some options are listed in more than one group.
10458 .set savedisplayflowcheck ~~displayflowcheck
10459 .set displayflowcheck 0
10461 .section Miscellaneous
10464 \bi@_command\ $t$rm{to run for \-bi-\ command line option}
10465 \keep@_malformed\ $t$rm{for broken files -- should not happen}
10466 \localhost@_number\ $t$rm{for unique message ids in clusters}
10467 \message@_body@_visible\ $t$rm{how much to show in \$message@_body$\}
10468 \print@_topbitchars\ $t$rm{top-bit characters are printing}
10469 \timezone\ $t$rm{force time zone}
10472 .section Exim parameters
10475 \exim@_group\ $t$rm{override compiled-in value}
10476 \exim@_path\ $t$rm{override compiled-in value}
10477 \exim@_user\ $t$rm{override compiled-in value}
10478 \primary@_hostname\ $t$rm{default from \*uname()*\}
10479 \split@_spool@_directory\ $t$rm{use multiple directories}
10480 \spool@_directory\ $t$rm{override compiled-in value}
10483 .section Privilege controls
10486 \admin@_groups\ $t$rm{groups that are Exim admin users}
10487 \deliver@_drop@_privilege\ $t$rm{drop root for delivery processes}
10488 \local@_from@_check\ $t$rm{insert ::Sender:: if necessary}
10489 \local@_from@_prefix\ $t$rm{for testing ::From:: for local sender}
10490 \local@_from@_suffix\ $t$rm{for testing ::From:: for local sender}
10491 \local@_sender@_retain\ $t$rm{keep ::Sender:: from untrusted user}
10492 \never@_users\ $t$rm{do not run deliveries as these}
10493 \prod@_requires@_admin\ $t$rm{forced delivery requires admin user}
10494 \queue@_list@_requires@_admin\ $t$rm{queue listing requires admin user}
10495 \trusted@_groups\ $t$rm{groups that are trusted}
10496 \trusted@_users\ $t$rm{users that are trusted}
10502 \log@_file@_path\ $t$rm{override compiled-in value}
10503 \log@_selector\ $t$rm{set/unset optional logging}
10504 \log@_timezone\ $t$rm{add timezone to log lines}
10505 \message@_logs\ $t$rm{create per-message logs}
10506 \preserve@_message@_logs\ $t$rm{in another directory after message completion}
10507 \process@_log@_path\ $t$rm{for SIGUSR1 and \*exiwhat*\}
10508 \syslog@_duplication\ $t$rm{controls duplicate log lines on syslog }
10509 \syslog@_facility\ $t$rm{set syslog `facility' field}
10510 \syslog@_processname\ $t$rm{set syslog `ident' field}
10511 \syslog@_timestamp\ $t$rm{timestamp syslog lines}
10514 \write@_rejectlog\ $t$rm{control use of message log}
10519 .section Frozen messages
10522 \auto@_thaw\ $t$rm{sets time for retrying frozen messages}
10523 \freeze@_tell\ $t$rm{send message when freezing}
10524 \move@_frozen@_messages\ $t$rm{to another directory}
10525 \timeout@_frozen@_after\ $t$rm{keep frozen messages only so long}
10528 .section Data lookups
10531 \ldap@_default@_servers\ $t$rm{used if no server in query}
10532 \ldap@_version\ $t$rm{set protocol version}
10533 \lookup@_open@_max\ $t$rm{lookup files held open}
10534 \mysql@_servers\ $t$rm{as it says}
10535 \oracle@_servers\ $t$rm{as it says}
10536 \pgsql@_servers\ $t$rm{as it says}
10539 .section Message ids
10542 \message@_id@_header@_domain\ $t$rm{used to build ::Message-ID:: header}
10543 \message@_id@_header@_text\ $t$rm{ditto}
10546 .section Embedded Perl Startup
10549 \perl@_at@_start\ $t$rm{always start the interpreter}
10550 \perl@_startup\ $t$rm{code to obey when starting Perl}
10556 \daemon@_smtp@_ports\ $t$rm{default ports}
10557 \extra@_local@_interfaces\ $t$rm{not necessarily listened on}
10558 \local@_interfaces\ $t$rm{on which to listen, with optional ports}
10559 \pid@_file@_path\ $t$rm{override compiled-in value}
10560 \queue@_run@_max\ $t$rm{maximum number of simultaneous queue runners}
10563 .section Resource control
10566 \check@_log@_inodes\ $t$rm{before accepting a message}
10567 \check@_log@_space\ $t$rm{before accepting a message}
10568 \check@_spool@_inodes\ $t$rm{before accepting a message}
10569 \check@_spool@_space\ $t$rm{before accepting a message}
10570 \deliver@_queue@_load@_max\ $t$rm{no queue deliveries if load high}
10571 \queue@_only@_load\ $t$rm{queue incoming if load high}
10572 \queue@_run@_max\ $t$rm{maximum number of simultaneous queue runners}
10573 \remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message}
10574 \smtp@_accept@_max\ $t$rm{simultaneous incoming connections}
10575 \smtp@_accept@_max@_nommail\ $t$rm{non-mail commands}
10576 \smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies}
10577 \smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection}
10578 \smtp@_accept@_max@_per@_host\ $t$rm{connections from one host}
10579 \smtp@_accept@_queue\ $t$rm{queue mail if more connections}
10580 \smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection}
10581 \smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections}
10582 \smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command}
10583 \smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack}
10584 \smtp@_load@_reserve\ $t$rm{SMTP from reserved hosts if load high}
10585 \smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts}
10588 .section Policy controls
10591 \acl@_not@_smtp\ $t$rm{set ACL for non-SMTP messages}
10592 \acl@_smtp@_auth\ $t$rm{set ACL for \\AUTH\\}
10593 \acl@_smtp@_connect\ $t$rm{set ACL for connection}
10594 \acl@_smtp@_data\ $t$rm{set ACL for \\DATA\\}
10595 \acl@_smtp@_etrn\ $t$rm{set ACL for \\ETRN\\}
10596 \acl@_smtp@_expn\ $t$rm{set ACL for \\EXPN\\}
10597 \acl@_smtp@_helo\ $t$rm{set ACL for \\EHLO\\ or \\HELO\\}
10598 \acl@_smtp@_mail\ $t$rm{set ACL for \\MAIL\\}
10599 \acl@_smtp@_mailauth\ $t$rm{set ACL for \\AUTH\\ on \\MAIL\\ command}
10600 \acl@_smtp@_rcpt\ $t$rm{set ACL for \\RCPT\\}
10601 \acl@_smtp@_starttls\ $t$rm{set ACL for \\STARTTLS\\}
10602 \acl@_smtp@_vrfy\ $t$rm{set ACL for \\VRFY\\}
10603 \header@_maxsize\ $t$rm{total size of message header}
10604 \header@_line@_maxsize\ $t$rm{individual header line limit}
10605 \helo@_accept@_junk@_hosts\ $t$rm{allow syntactic junk from these hosts}
10606 \helo@_allow@_chars\ $t$rm{allow illegal chars in \\HELO\\ names}
10607 \helo@_lookup@_domains\ $t$rm{lookup hostname for these \\HELO\\ names}
10608 \helo@_try@_verify@_hosts\ $t$rm{\\HELO\\ soft-checked for these hosts}
10609 \helo@_verify@_hosts\ $t$rm{\\HELO\\ hard-checked for these hosts}
10610 \host@_lookup\ $t$rm{host name looked up for these hosts}
10611 \host@_lookup@_order\ $t$rm{order of DNS and local name lookups}
10612 \host@_reject@_connection\ $t$rm{reject connection from these hosts}
10613 \hosts@_treat@_as@_local\ $t$rm{useful in some cluster configurations}
10614 \local@_scan@_timeout\ $t$rm{timeout for \*local@_scan()*\}
10615 \message@_size@_limit\ $t$rm{for all messages}
10616 \percent@_hack@_domains\ $t$rm{recognize %-hack for these domains}
10619 .section Callout cache
10622 \callout@_domain@_negative@_expire\ $t$rm{timeout for negative domain cache item}
10623 \callout@_domain@_positive@_expire\ $t$rm{timeout for positive domain cache item}
10624 \callout@_negative@_expire\ $t$rm{timeout for negative address cache item}
10625 \callout@_positive@_expire\ $t$rm{timeout for positive address cache item}
10626 \callout@_random@_local@_part\ $t$rm{string to use for `random' testing}
10632 \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts}
10633 \tls@_certificate\ $t$rm{location of server certificate}
10636 \tls@_crl\ $t$rm{certificate revocation list}
10639 \tls@_dhparam\ $t$rm{DH parameters for server}
10640 \tls@_privatekey\ $t$rm{location of server private key}
10641 \tls@_remember@_esmtp\ $t$rm{don't reset after starting TLS}
10644 \tls@_require@_ciphers\ $t$rm{specify acceptable cipers}
10647 \tls@_try@_verify@_hosts\ $t$rm{try to verify client certificate}
10648 \tls@_verify@_certificates\ $t$rm{expected client certificates}
10649 \tls@_verify@_hosts\ $t$rm{insist on client certificate verify}
10652 .section Local user handling
10655 \finduser@_retries\ $t$rm{useful in NIS environments}
10656 \gecos@_name\ $t$rm{used when creating ::Sender::}
10657 \gecos@_pattern\ $t$rm{ditto}
10658 \max@_username@_length\ $t$rm{for systems that truncate}
10659 \unknown@_login\ $t$rm{used when no login name found}
10660 \unknown@_username\ $t$rm{ditto}
10661 \uucp@_from@_pattern\ $t$rm{for recognizing `From ' lines}
10662 \uucp@_from@_sender\ $t$rm{ditto}
10665 .section All incoming messages (SMTP and non-SMTP)
10668 \header@_maxsize\ $t$rm{total size of message header}
10669 \header@_line@_maxsize\ $t$rm{individual header line limit}
10670 \message@_size@_limit\ $t$rm{applies to all messages}
10671 \percent@_hack@_domains\ $t$rm{recognize %-hack for these domains}
10672 \received@_header@_text\ $t$rm{expanded to make ::Received::}
10673 \received@_headers@_max\ $t$rm{for mail loop detection}
10674 \recipients@_max\ $t$rm{limit per message}
10675 \recipients@_max@_reject\ $t$rm{permanently reject excess}
10679 .section Non-SMTP incoming messages
10682 \receive@_timeout\ $t$rm{for non-SMTP messages}
10687 .section Incoming SMTP messages
10688 See also the \*Policy controls*\ section above.
10691 \host@_lookup\ $t$rm{host name looked up for these hosts}
10692 \host@_lookup@_order\ $t$rm{order of DNS and local name lookups}
10693 \recipient@_unqualified@_hosts\ $t$rm{may send unqualified recipients}
10694 \rfc1413@_hosts\ $t$rm{make ident calls to these hosts}
10695 \rfc1413@_query@_timeout\ $t$rm{zero disables ident calls}
10696 \sender@_unqualified@_hosts\ $t$rm{may send unqualified senders}
10697 \smtp@_accept@_keepalive\ $t$rm{some TCP/IP magic}
10698 \smtp@_accept@_max\ $t$rm{simultaneous incoming connections}
10699 \smtp@_accept@_max@_nommail\ $t$rm{non-mail commands}
10700 \smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies}
10701 \smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection}
10702 \smtp@_accept@_max@_per@_host\ $t$rm{connections from one host}
10703 \smtp@_accept@_queue\ $t$rm{queue mail if more connections}
10704 \smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection}
10705 \smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections}
10708 \smtp@_active@_hostname\ $t$rm{host name to use in messages}
10711 \smtp@_banner\ $t$rm{text for welcome banner}
10712 \smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command}
10713 \smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack}
10714 \smtp@_enforce@_sync\ $t$rm{of SMTP command/responses}
10715 \smtp@_etrn@_command\ $t$rm{what to run for \\ETRN\\}
10716 \smtp@_etrn@_serialize\ $t$rm{only one at once}
10717 \smtp@_load@_reserve\ $t$rm{only reserve hosts if this load}
10718 \smtp@_max@_unknown@_commands\ $t$rm{before dropping connection}
10719 \smtp@_ratelimit@_hosts\ $t$rm{apply ratelimiting to these hosts}
10720 \smtp@_ratelimit@_mail\ $t$rm{ratelimit for \\MAIL\\ commands}
10721 \smtp@_ratelimit@_rcpt\ $t$rm{ratelimit for \\RCPT\\ commands}
10722 \smtp@_receive@_timeout\ $t$rm{per command or data line}
10723 \smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts}
10724 \smtp@_return@_error@_details\ $t$rm{give detail on rejections}
10727 .section SMTP extensions
10730 \accept@_8bitmime\ $t$rm{advertise \\8BITMIME\\}
10731 \auth@_advertise@_hosts\ $t$rm{advertise \\AUTH\\ to these hosts}
10732 \ignore@_fromline@_hosts\ $t$rm{allow `From ' from these hosts}
10733 \ignore@_fromline@_local\ $t$rm{allow `From ' from local SMTP}
10734 \pipelining@_advertise@_hosts\ $t$rm{advertise pipelining to these hosts}
10735 \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts}
10738 .section Processing messages
10741 \allow@_domain@_literals\ $t$rm{recognize domain literal syntax}
10742 \allow@_mx@_to@_ip\ $t$rm{allow MX to point to IP address}
10743 \allow@_utf8@_domains\ $t$rm{in addresses}
10744 \delivery@_date@_remove\ $t$rm{from incoming messages}
10745 \envelope@_to@_remote\ $t$rm{from incoming messages}
10746 \extract@_addresses@_remove@_arguments\ $t$rm{affects \-t-\ processing}
10747 \headers@_charset\ $t$rm{default for translations}
10748 \qualify@_domain\ $t$rm{default for senders}
10749 \qualify@_recipient\ $t$rm{default for recipients}
10750 \return@_path@_remove\ $t$rm{from incoming messages}
10751 \strip@_excess@_angle@_brackets\ $t$rm{in addresses}
10752 \strip@_trailing@_dot\ $t$rm{at end of addresses}
10753 \untrusted@_set@_sender\ $t$rm{untrusted can set envelope sender}
10756 .section System filter
10759 \system@_filter\ $t$rm{locate system filter}
10760 \system@_filter@_directory@_transport\ $t$rm{transport for delivery to a directory}
10761 \system@_filter@_file@_transport\ $t$rm{transport for delivery to a file}
10762 \system@_filter@_group\ $t$rm{group for filter running}
10763 \system@_filter@_pipe@_transport\ $t$rm{transport for delivery to a pipe}
10764 \system@_filter@_reply@_transport\ $t$rm{transport for autoreply delivery}
10765 \system@_filter@_user\ $t$rm{user for filter running}
10768 .section Routing and delivery
10771 \dns@_again@_means@_nonexist\ $t$rm{for broken domains}
10772 \dns@_check@_names@_pattern\ $t$rm{pre-DNS syntax check}
10773 \dns@_ipv4@_lookup\ $t$rm{only v4 lookup for these domains}
10774 \dns@_retrans\ $t$rm{parameter for resolver}
10775 \dns@_retry\ $t$rm{parameter for resolver}
10776 \hold@_domains\ $t$rm{hold delivery for these domains}
10777 \local@_interfaces\ $t$rm{for routing checks}
10778 \queue@_domains\ $t$rm{no immediate delivery for these}
10779 \queue@_only\ $t$rm{no immediate delivery at all}
10780 \queue@_only@_file\ $t$rm{no immediate deliveryif file exists}
10781 \queue@_only@_load\ $t$rm{no immediate delivery if load is high}
10782 \queue@_only@_override\ $t$rm{allow command line to override}
10783 \queue@_run@_in@_order\ $t$rm{order of arrival}
10784 \queue@_run@_max\ $t$rm{of simultaneous queue runners}
10785 \queue@_smtp@_domains\ $t$rm{no immediate SMTP delivery for these}
10786 \remote@_max@_parallel\ $t$rm{parallel SMTP delivery (per message, not overall)}
10787 \remote@_sort@_domains\ $t$rm{order of remote deliveries}
10788 \retry@_data@_expire\ $t$rm{timeout for retry data}
10789 \retry@_interval@_max\ $t$rm{safety net for retry rules}
10792 .section Bounce and warning messages
10795 \bounce@_message@_file\ $t$rm{content of bounce}
10796 \bounce@_message@_text\ $t$rm{content of bounce}
10797 \bounce@_return@_body\ $t$rm{include body if returning message}
10798 \bounce@_return@_message\ $t$rm{include original message in bounce}
10799 \bounce@_return@_size@_limit\ $t$rm{limit on returned message}
10800 \bounce@_sender@_authentication\ $t$rm{send authenticated sender with bounce}
10801 \errors@_copy\ $t$rm{copy bounce messages}
10802 \errors@_reply@_to\ $t$rm{::Reply-to:: in bounces}
10803 \delay@_warning\ $t$rm{time schedule}
10804 \delay@_warning@_condition\ $t$rm{condition for warning messages}
10805 \ignore@_bounce@_errors@_after\ $t$rm{discard undeliverable bounces}
10806 \warn@_message@_file\ $t$rm{content of warning message}
10809 .set displayflowcheck ~~savedisplayflowcheck
10811 .section Alphabetical list of main options
10812 .rset SECTalomo "~~chapter.~~section"
10814 Those options that undergo string expansion before use are marked with $**$.
10819 .index \\8BITMIME\\
10820 .index 8-bit characters
10821 .conf accept@_8bitmime boolean false
10822 This option causes Exim to send \\8BITMIME\\ in its response to an SMTP
10823 \\EHLO\\ command, and to accept the \\BODY=\\ parameter on \\MAIL\\ commands.
10824 However, though Exim is 8-bit clean, it is not a protocol converter, and it
10825 takes no steps to do anything special with messages received by this route.
10826 Consequently, this option is turned off by default.
10828 .index ~~ACL||for non-SMTP messages
10829 .index non-SMTP messages, ACL for
10830 .conf acl@_not@_smtp string$**$ unset
10831 This option defines the ACL that is run when a non-SMTP message is on the point
10832 of being accepted. See chapter ~~CHAPACL for further details.
10834 .index ~~ACL||on SMTP connection
10835 .conf acl@_smtp@_connect string$**$ unset
10836 This option defines the ACL that is run when an SMTP connection is received.
10837 See chapter ~~CHAPACL for further details.
10839 .index ~~ACL||setting up for SMTP commands
10840 .index \\AUTH\\||ACL for
10841 .conf acl@_smtp@_auth string$**$ unset
10842 This option defines the ACL that is run when an SMTP \\AUTH\\ command is
10843 received. See chapter ~~CHAPACL for further details.
10845 .index \\DATA\\, ACL for
10846 .conf acl@_smtp@_data string$**$ unset
10847 This option defines the ACL that is run after an SMTP \\DATA\\ command has been
10848 processed and the message itself has been received, but before the final
10849 acknowledgement is sent. See chapter ~~CHAPACL for further details.
10851 .index \\ETRN\\||ACL for
10852 .conf acl@_smtp@_etrn string$**$ unset
10853 This option defines the ACL that is run when an SMTP \\ETRN\\ command is
10854 received. See chapter ~~CHAPACL for further details.
10856 .index \\EXPN\\||ACL for
10857 .conf acl@_smtp@_expn string$**$ unset
10858 This option defines the ACL that is run when an SMTP \\EXPN\\ command is
10859 received. See chapter ~~CHAPACL for further details.
10861 .index \\EHLO\\||ACL for
10862 .index \\HELO\\||ACL for
10863 .conf acl@_smtp@_helo string$**$ unset
10864 This option defines the ACL that is run when an SMTP \\EHLO\\ or \\HELO\\
10865 command is received. See chapter ~~CHAPACL for further details.
10867 .index \\MAIL\\||ACL for
10868 .conf acl@_smtp@_mail string$**$ unset
10869 This option defines the ACL that is run when an SMTP \\MAIL\\ command is
10870 received. See chapter ~~CHAPACL for further details.
10872 .index \\AUTH\\||on \\MAIL\\ command
10873 .conf acl@_smtp@_mailauth string$**$ unset
10874 This option defines the ACL that is run when there is an \\AUTH\\ parameter on
10875 a \\MAIL\\ command. See chapter ~~CHAPACL for details of ACLs, and chapter
10876 ~~CHAPSMTPAUTH for details of authentication.
10878 .index \\RCPT\\||ACL for
10879 .conf acl@_smtp@_rcpt string$**$ unset
10880 This option defines the ACL that is run when an SMTP \\RCPT\\ command is
10881 received. See chapter ~~CHAPACL for further details.
10883 .index \\STARTTLS\\, ACL for
10884 .conf acl@_smtp@_starttls string$**$ unset
10885 This option defines the ACL that is run when an SMTP \\STARTTLS\\ command is
10886 received. See chapter ~~CHAPACL for further details.
10888 .index \\VRFY\\||ACL for
10889 .conf acl@_smtp@_vrfy string$**$ unset
10890 This option defines the ACL that is run when an SMTP \\VRFY\\ command is
10891 received. See chapter ~~CHAPACL for further details.
10893 .conf admin@_groups "string list" unset
10895 If the current group or any of the supplementary groups of the caller is in
10896 this colon-separated list, the caller has admin privileges. If all your system
10897 programmers are in a specific group, for example, you can give them all Exim
10898 admin privileges by putting that group in \admin@_groups\. However, this does
10899 not permit them to read Exim's spool files (whose group owner is the Exim gid).
10900 To permit this, you have to add individuals to the Exim group.
10902 .conf allow@_domain@_literals boolean false
10903 .index domain literal
10904 If this option is set, the RFC 2822 domain literal format is permitted in
10905 email addresses. The option is not set by default, because the domain literal
10906 format is not normally required these days, and few people know about it. It
10907 has, however, been exploited by mail abusers.
10909 Unfortunately, it seems that some DNS black list maintainers are using this
10910 format to report black listing to postmasters. If you want to accept messages
10911 addressed to your hosts by IP address, you need to set
10912 \allow@_domain@_literals\ true, and also to add \"@@[]"\ to the list of local
10913 domains (defined in the named domain list \local@_domains\ in the default
10914 configuration). This `magic string' matches the domain literal form of all the
10915 local host's IP addresses.
10917 .conf allow@_mx@_to@_ip boolean false
10918 .index MX record||pointing to IP address
10919 It appears that more and more DNS zone administrators are breaking the rules
10920 and putting domain names that look like IP addresses on the right hand side of
10921 MX records. Exim follows the rules and rejects this, giving an error message
10922 that explains the mis-configuration. However, some other MTAs support this
10923 practice, so to avoid `Why can't Exim do this?' complaints, \allow@_mx@_to@_ip\
10924 exists, in order to enable this heinous activity. It is not recommended, except
10925 when you have no other choice.
10927 .index domain||UTF-8 characters in
10928 .index UTF-8||in domain name
10929 .conf allow@_utf8@_domains boolean false
10930 Lots of discussion is going on about internationalized domain names. One
10931 camp is strongly in favour of just using UTF-8 characters, and it seems
10932 that at least two other MTAs permit this. This option allows Exim users to
10933 experiment if they wish.
10935 If it is set true, Exim's domain parsing function allows valid
10936 UTF-8 multicharacters to appear in domain name components, in addition to
10937 letters, digits, and hyphens. However, just setting this option is not
10938 enough; if you want to look up these domain names in the DNS, you must also
10939 adjust the value of \dns@_check@_names@_pattern\ to match the extended form. A
10940 suitable setting is:
10942 dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\
10943 (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$
10945 Alternatively, you can just disable this feature by setting
10947 dns_check_names_pattern =
10949 That is, set the option to an empty string so that no check is done.
10951 .conf auth@_advertise@_hosts "host list$**$" $*$
10952 .index authentication||advertising
10953 .index \\AUTH\\||advertising
10954 If any server authentication mechanisms are configured, Exim advertises them in
10955 response to an \\EHLO\\ command only if the calling host matches this list.
10956 Otherwise, Exim does not advertise \\AUTH\\.
10957 Exim does not accept \\AUTH\\ commands from clients to which it has not
10958 advertised the availability of \\AUTH\\. The advertising of individual
10959 authentication mechanisms can be controlled by the use of the
10960 \server@_advertise@_condition\ generic authenticator option on the individual
10961 authenticators. See chapter ~~CHAPSMTPAUTH for further details.
10963 Certain mail clients (for example, Netscape) require the user to provide a name
10964 and password for authentication if \\AUTH\\ is advertised, even though it may
10965 not be needed (the host may accept messages from hosts on its local LAN without
10966 authentication, for example). The \auth@_advertise@_hosts\ option can be used
10967 to make these clients more friendly by excluding them from the set of hosts to
10968 which Exim advertises \\AUTH\\.
10970 .index \\AUTH\\||advertising when encrypted
10971 If you want to advertise the availability of \\AUTH\\ only when the connection
10972 is encrypted using TLS, you can make use of the fact that the value of this
10973 option is expanded, with a setting like this:
10975 auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}}
10977 If \$tls@_cipher$\ is empty, the session is not encrypted, and the result of
10978 the expansion is empty, thus matching no hosts. Otherwise, the result of the
10979 expansion is $*$, which matches all hosts.
10981 .conf auto@_thaw time 0s
10982 .index thawing messages
10983 .index unfreezing messages
10984 If this option is set to a time greater than zero, a queue runner will try a
10985 new delivery attempt on any frozen message if this much time has passed since
10986 it was frozen. This may result in the message being re-frozen if nothing has
10987 changed since the last attempt. It is a way of saying `keep on trying, even
10988 though there are big problems'. See also \timeout@_frozen@_after\ and
10989 \ignore@_bounce@_errors@_after\.
10991 .conf bi@_command string unset
10992 .index \-bi-\ option
10993 This option supplies the name of a command that is run when Exim is called with
10994 the \-bi-\ option (see chapter ~~CHAPcommandline). The string value is just the
10995 command name, it is not a complete command line. If an argument is required, it
10996 must come from the \-oA-\ command line option.
10998 .conf bounce@_message@_file string unset
10999 .index bounce message||customizing
11000 .index customizing||bounce message
11001 This option defines a template file containing paragraphs of text to be used
11002 for constructing bounce messages. Details of the file's contents are given in
11003 chapter ~~CHAPemsgcust. See also \warn@_message@_file\.
11005 .conf bounce@_message@_text string unset
11006 When this option is set, its contents are included in the default bounce
11007 message immediately after `This message was created automatically by mail
11008 delivery software.' It is not used if \bounce@_message@_file\ is set.
11010 .index bounce message||including body
11011 .conf bounce@_return@_body boolean true
11012 This option controls whether the body of an incoming message is included in a
11013 bounce message when \bounce@_return@_message\ is true. If it is not set, only
11014 the message header is included.
11016 .index bounce message||including original
11017 .conf bounce@_return@_message boolean true
11018 If this option is set false, the original message is not included in bounce
11019 messages generated by Exim. See also \bounce@_return@_size@_limit\.
11021 .conf bounce@_return@_size@_limit integer 100K
11022 .index size||of bounce, limit
11023 .index bounce message||size limit
11024 .index limit||bounce message size
11025 This option sets a limit in bytes on the size of messages that are returned to
11026 senders as part of bounce messages when \bounce@_return@_message\ is true. The
11027 limit should be less than the value of the global \message@_size@_limit\ and of
11028 any \message@_size@_limit\ settings on transports, to allow for the bounce text
11029 that Exim generates. If this option is set to zero there is no limit.
11031 When the body of any message that is to be included in a bounce message is
11032 greater than the limit, it is truncated, and a comment pointing this out is
11033 added at the top. The actual cutoff may be greater than the value given, owing
11034 to the use of buffering for transferring the message in chunks (typically 8K in
11035 size). The idea is to save bandwidth on those undeliverable 15-megabyte
11038 .index bounce message||sender authentication
11039 .index authentication||bounce message
11040 .index \\AUTH\\||on bounce message
11041 .conf bounce@_sender@_authentication string unset
11042 This option provides an authenticated sender address that is sent with any
11043 bounce messages generated by Exim that are sent over an authenticated SMTP
11044 connection. A typical setting might be:
11046 bounce_sender_authentication = mailer-daemon@my.domain.example
11048 which would cause bounce messages to be sent using the SMTP command:
11050 MAIL FROM:<> AUTH=mailer-daemon@my.domain.example
11052 The value of \bounce@_sender@_authentication\ must always be a complete email
11055 .index caching||callout, timeouts
11056 .index callout||caching timeouts
11057 .conf callout@_domain@_negative@_expire time 3h
11058 This option specifies the expiry time for negative callout cache data for a
11059 domain. See section ~~SECTcallver for details of callout verification, and
11060 section ~~SECTcallvercache for details of the caching.
11062 .conf callout@_domain@_positive@_expire time 7d
11063 This option specifies the expiry time for positive callout cache data for a
11064 domain. See section ~~SECTcallver for details of callout verification, and
11065 section ~~SECTcallvercache for details of the caching.
11067 .conf callout@_negative@_expire time 2h
11068 This option specifies the expiry time for negative callout cache data for an
11069 address. See section ~~SECTcallver for details of callout verification, and
11070 section ~~SECTcallvercache for details of the caching.
11072 .conf callout@_positive@_expire time 24h
11073 This option specifies the expiry time for positive callout cache data for an
11074 address. See section ~~SECTcallver for details of callout verification, and
11075 section ~~SECTcallvercache for details of the caching.
11077 .conf callout@_random@_local@_part string$**$ "see below"
11078 This option defines the `random' local part that can be used as part of callout
11079 verification. The default value is
11081 $primary_host_name-$tod_epoch-testing
11083 See section ~~CALLaddparcall for details of how this value is used.
11085 .conf check@_log@_inodes integer 0
11086 See \check@_spool@_space\ below.
11088 .conf check@_log@_space integer 0
11089 See \check@_spool@_space\ below.
11091 .conf check@_spool@_inodes integer 0
11092 See \check@_spool@_space\ below.
11094 .conf check@_spool@_space integer 0
11095 .index checking disk space
11096 .index disk space, checking
11097 .index spool directory||checking space
11098 The four \check@_...\ options allow for checking of disk resources before a
11099 message is accepted. \check@_spool@_space\ and \check@_spool@_inodes\ check the
11100 spool partition if either value is greater than zero, for example:
11102 check_spool_space = 10M
11103 check_spool_inodes = 100
11105 The spool partition is the one which contains the directory defined by
11106 \\SPOOL@_DIRECTORY\\ in \(Local/Makefile)\. It is used for holding messages in
11109 \check@_log@_space\ and \check@_log@_inodes\ check the partition in which log
11110 files are written if either is greater than zero. These should be set only if
11111 \log@_file@_path\ and \spool@_directory\ refer to different partitions.
11113 If there is less space or fewer inodes than requested, Exim refuses to accept
11114 incoming mail. In the case of SMTP input this is done by giving a 452 temporary
11115 error response to the \\MAIL\\ command. If ESMTP is in use and there was a
11116 \\SIZE\\ parameter on the \\MAIL\\ command, its value is added to the
11117 \check@_spool@_space\ value, and the check is performed even if
11118 \check@_spool@_space\ is zero, unless \no@_smtp@_check@_spool@_space\ is set.
11120 The values for \check@_spool@_space\ and \check@_log@_space\ are held as a
11121 number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up.
11123 For non-SMTP input and for batched SMTP input, the test is done at start-up; on
11124 failure a message is written to stderr and Exim exits with a non-zero code, as
11125 it obviously cannot send an error message of any kind.
11127 .index port||for daemon
11128 .index TCP/IP||setting listening ports
11129 .conf daemon@_smtp@_ports string "$tt{smtp}"
11130 This option specifies one or more default SMTP ports on which the Exim daemon
11131 listens. See chapter ~~CHAPinterfaces for details of how it is used. For
11132 backward compatibility, \daemon@_smtp@_port\ (singular) is a synonym.
11134 .conf delay@_warning "time list" 24h
11135 .index warning of delay
11136 .index delay warning, specifying
11137 When a message is delayed, Exim sends a warning message to the sender at
11138 intervals specified by this option. If it is set to a zero, no warnings are
11139 sent. The data is a colon-separated list of times after which to send warning
11140 messages. Up to 10 times may be given. If a message has been on the queue for
11141 longer than the last time, the last interval between the times is used to
11142 compute subsequent warning times. For example, with
11144 delay_warning = 4h:8h:24h
11146 the first message is sent after 4 hours, the second after 8 hours, and
11147 the third one after 24 hours. After that, messages are sent every 16 hours,
11148 because that is the interval between the last two times on the list. If you set
11149 just one time, it specifies the repeat interval. For example, with:
11153 messages are repeated every six hours. To stop warnings after a given time, set
11154 a very large time at the end of the list. For example:
11156 delay_warning = 2h:12h:99d
11159 .conf delay@_warning@_condition string$**$ "see below"
11160 The string is expanded at the time a warning message might be sent. If all the
11161 deferred addresses have the same domain, it is set in \$domain$\ during the
11162 expansion. Otherwise \$domain$\ is empty. If the result of the expansion is a
11163 forced failure, an empty string, or a string matching any of `0', `no' or
11164 `false' (the comparison being done caselessly) then the warning message is not
11165 sent. The default is
11167 delay_warning_condition = \
11168 ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}}
11170 which suppresses the sending of warnings about messages that have `bulk',
11171 `list' or `junk' in a ::Precedence:: header.
11173 .index unprivileged delivery
11174 .index delivery||unprivileged
11175 .conf deliver@_drop@_privilege boolean false
11176 If this option is set true, Exim drops its root privilege at the start of a
11177 delivery process, and runs as the Exim user throughout. This severely restricts
11178 the kinds of local delivery that are possible, but is viable in certain types
11179 of configuration. There is a discussion about the use of root privilege in
11180 chapter ~~CHAPsecurity.
11182 .index load average
11183 .index queue runner||abandoning
11184 .conf deliver@_queue@_load@_max fixed-point unset
11185 When this option is set, a queue run is abandoned if the system load average
11186 becomes greater than the value of the option. The option has no effect on
11187 ancient operating systems on which Exim cannot determine the load average.
11188 See also \queue@_only@_load\ and \smtp@_load@_reserve\.
11190 .conf delivery@_date@_remove boolean true
11191 .index ::Delivery-date:: header line
11192 Exim's transports have an option for adding a ::Delivery-date:: header to a
11193 message when it is delivered -- in exactly the same way as ::Return-path:: is
11194 handled. ::Delivery-date:: records the actual time of delivery. Such headers
11195 should not be present in incoming messages, and this option causes them to be
11196 removed at the time the message is received, to avoid any problems that might
11197 occur when a delivered message is subsequently sent on to some other recipient.
11199 .index DNS||`try again' response, overriding
11200 .conf dns@_again@_means@_nonexist "domain list$**$" unset
11201 DNS lookups give a `try again' response for the DNS errors `non-authoritative
11202 host not found' and `\\SERVERFAIL\\'. This can cause Exim to keep trying to
11203 deliver a message, or to give repeated temporary errors to incoming mail.
11204 Sometimes the effect is caused by a badly set up name server and may persist
11205 for a long time. If a domain which exhibits this problem matches anything in
11206 \dns__again__means__nonexist\, it is treated as if it did not exist. This
11207 option should be used with care.
11209 You can make it apply to reverse lookups by a setting such as this:
11211 dns_again_means_nonexist = *.in-addr.arpa
11215 .index DNS||pre-check of name syntax
11216 .conf dns@_check@_names@_pattern string "see below"
11217 When this option is set to a non-empty string, it causes Exim to check domain
11218 names for illegal characters before handing them to the DNS resolver, because
11219 some resolvers give temporary errors for malformed names. If a domain name
11220 contains any illegal characters, a `not found' result is forced, and the
11221 resolver is not called. The check is done by matching the domain name against a
11222 regular expression, which is the value of this option. The default pattern is
11224 dns_check_names_pattern = \
11225 (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$
11227 which permits only letters, digits, and hyphens in components, but they may not
11228 start or end with a hyphen.
11229 If you set \allow@_utf8@_domains\, you must modify this pattern, or set the
11230 option to an empty string.
11232 .conf dns@_ipv4@_lookup "domain list$**$" unset
11233 .index IPv6||DNS lookup for AAAA records
11234 .index DNS||IPv6 lookup for AAAA records
11235 When Exim is compiled with IPv6 support, it looks for IPv6 address records
11236 (AAAA and, if configured, A6) as well as IPv4 address records when trying to
11237 find IP addresses for hosts, unless the host's domain matches this list.
11239 This is a fudge to help with name servers that give big delays or otherwise do
11240 not work for the new IPv6 record types. If Exim is handed an IPv6 address
11241 record as a result of an MX lookup, it always recognizes it, and may as a
11242 result make an outgoing IPv6 connection. All this option does is to make Exim
11243 look only for IPv4-style A records when it needs to find an IP address for a
11244 host name. In due course, when the world's name servers have all been upgraded,
11245 there should be no need for this option.
11247 .conf dns@_retrans time 0s
11248 .index DNS||resolver options
11249 The options \dns@_retrans\ and \dns@_retry\ can be used to set the
11250 retransmission and retry parameters for DNS lookups. Values of zero (the
11251 defaults) leave the system default settings unchanged. The first value is the
11252 time between retries, and the second is the number of retries. It isn't
11253 totally clear exactly how these settings affect the total time a DNS lookup may
11254 take. I haven't found any documentation about timeouts on DNS lookups; these
11255 parameter values are available in the external resolver interface structure,
11256 but nowhere does it seem to describe how they are used or what you might want
11259 .conf dns@_retry integer 0
11260 See \dns@_retrans\ above.
11262 .conf drop@_cr boolean false
11263 This is an obsolete option that is now a no-op. It used to affect the way Exim
11264 handled CR and LF characters in incoming messages. What happens now is
11265 described in section ~~SECTlineendings.
11267 .conf envelope@_to@_remove boolean true
11268 .index ::Envelope-to:: header line
11269 Exim's transports have an option for adding an ::Envelope-to:: header to a
11270 message when it is delivered -- in exactly the same way as ::Return-path:: is
11271 handled. ::Envelope-to:: records the original recipient address from the
11272 messages's envelope that caused the delivery to happen. Such headers should not
11273 be present in incoming messages, and this option causes them to be removed at
11274 the time the message is received, to avoid any problems that might occur when a
11275 delivered message is subsequently sent on to some other recipient.
11277 .conf errors@_copy "string list$**$" unset
11278 .index bounce message||copy to other address
11279 .index copy of bounce message
11280 Setting this option causes Exim to send bcc copies of bounce messages that it
11281 generates to other addresses. \**Note**\: this does not apply to bounce messages
11282 coming from elsewhere. The value of the option is a colon-separated list of
11283 items. Each item consists of a pattern, terminated by white space, followed by
11284 a comma-separated list of email addresses. If a pattern contains spaces, it
11285 must be enclosed in double quotes.
11287 Each pattern is processed in the same way as a single item in an address list
11288 (see section ~~SECTaddresslist). When a pattern matches the recipient of the
11289 bounce message, the message is copied to the addresses on the list. The items
11290 are scanned in order, and once a matching one is found, no further items are
11291 examined. For example:
11293 errors_copy = spqr@mydomain postmaster@mydomain.example :\
11294 rqps@mydomain hostmaster@mydomain.example,\
11295 postmaster@mydomain.example
11297 The address list is expanded before use. The expansion variables
11298 \$local@_part$\ and \$domain$\ are set from the original recipient of the error
11299 message, and if there was any wildcard matching in the pattern, the expansion
11300 .index numerical variables (\$1$\, \$2$\, etc)||in \errors@_copy\
11301 variables \$0$\, \$1$\, etc. are set in the normal way.
11303 .conf errors@_reply@_to string unset
11304 .index bounce message||::Reply-to:: in
11305 Exim's bounce and delivery warning messages contain the header line
11307 From: Mail Delivery System @<Mailer-Daemon@@<<qualify-domain>>@>
11309 where <<qualify-domain>> is the value of the \qualify@_domain\ option.
11310 Experience shows that people reply to bounce messages. If the
11311 \errors@_reply@_to\ option is set, a ::Reply-To:: header is added to bounce and
11312 warning messages. For example:
11314 errors_reply_to = postmaster@my.domain.example
11316 The value of the option is not expanded. It must specify a valid RFC 2822
11319 .conf exim@_group string "compile-time configured"
11320 .index gid (group id)||Exim's own
11322 This option changes the gid under which Exim runs when it gives up root
11323 privilege. The default value is compiled into the binary. The value of this
11324 option is used only when \exim@_user\ is also set. Unless it consists entirely
11325 of digits, the string is looked up using \*getgrnam()*\, and failure causes a
11326 configuration error. See chapter ~~CHAPsecurity for a discussion of security
11329 .conf exim@_path string "see below"
11330 .index Exim binary, path name
11331 This option specifies the path name of the Exim binary, which is used when Exim
11332 needs to re-exec itself. The default is set up to point to the file \*exim*\ in
11333 the directory configured at compile time by the \\BIN@_DIRECTORY\\ setting. It
11334 is necessary to change \exim@_path\ if, exceptionally, Exim is run from some
11336 \**Warning**\: Do not use a macro to define the value of this option, because
11337 you will break those Exim utilities that scan the configuration file to find
11338 where the binary is. (They then use the \-bP-\ option to extract option
11339 settings such as the value of \spool@_directory\.)
11341 .conf exim@_user string "compile-time configured"
11342 .index uid (user id)||Exim's own
11344 This option changes the uid under which Exim runs when it gives up root
11345 privilege. The default value is compiled into the binary. Ownership of the run
11346 time configuration file and the use of the \-C-\ and \-D-\ command line options
11347 is checked against the values in the binary, not what is set here.
11349 Unless it consists entirely of digits, the string is looked up using
11350 \*getpwnam()*\, and failure causes a configuration error. If \exim@_group\ is
11351 not also supplied, the gid is taken from the result of \*getpwnam()*\ if it is
11352 used. See chapter ~~CHAPsecurity for a discussion of security issues.
11354 .conf extra@_local@_interfaces "string list" unset
11356 This option defines network interfaces that are to be considered local when
11357 routing, but which are not used for listening by the daemon. See section
11358 ~~SECTreclocipadd for details.
11360 .conf extract@_addresses@_remove@_arguments boolean true
11361 .index \-t-\ option
11362 .index command line||addresses with \-t-\
11363 .index Sendmail compatibility||\-t-\ option
11364 According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses
11365 are present on the command line when the \-t-\ option is used to build an
11366 envelope from a message's ::To::, ::Cc:: and ::Bcc:: headers, the command line
11367 addresses are removed from the recipients list. This is also how Smail behaves.
11368 However, other Sendmail documentation (the O'Reilly book) states that command
11369 line addresses are added to those obtained from the header lines. When
11370 \extract@_addresses@_remove@_arguments\ is true (the default), Exim subtracts
11371 argument headers. If it is set false, Exim adds rather than removes argument
11374 .conf finduser@_retries integer 0
11375 .index NIS, looking up users, retrying
11376 On systems running NIS or other schemes in which user and group information is
11377 distributed from a remote system, there can be times when \*getpwnam()*\ and
11378 related functions fail, even when given valid data, because things time out.
11379 Unfortunately these failures cannot be distinguished from genuine `not found'
11380 errors. If \finduser@_retries\ is set greater than zero, Exim will try that
11381 many extra times to find a user or a group, waiting for one second between
11384 .conf freeze@_tell "string list, comma separated" unset
11385 .index freezing messages||sending a message when freezing
11386 On encountering certain errors, or when configured to do so in a system filter,
11388 Exim freezes a message. This means that no further delivery attempts take place
11389 until an administrator (or the \auto@_thaw\ feature) thaws the message. If
11390 \freeze@_tell\ is set, Exim generates a warning message whenever it freezes
11391 something, unless the message it is freezing is a
11393 bounce message. (Without this exception there is the possibility of looping.)
11394 The warning message is sent to the addresses supplied as the comma-separated
11395 value of this option. If several of the message's addresses cause freezing,
11396 only a single message is sent.
11397 If the freezing was automatic, the reason(s) for freezing can be found in the
11398 message log. If you configure freezing in a filter or ACL, you must arrange for
11399 any logging that you require.
11401 .conf gecos@_name string$**$ unset
11403 .index `gecos' field, parsing
11404 Some operating systems, notably HP-UX, use the `gecos' field in the system
11405 password file to hold other information in addition to users' real names. Exim
11406 looks up this field for use when it is creating ::Sender:: or ::From:: headers.
11407 If either \gecos@_pattern\ or \gecos@_name\ are unset, the contents of the
11408 field are used unchanged, except that, if an ampersand is encountered, it is
11409 replaced by the user's login name with the first character forced to
11410 upper case, since this is a convention that is observed on many systems.
11412 When these options are set, \gecos@_pattern\ is treated as a regular expression
11413 that is to be applied to the field (again with & replaced by the login name),
11414 and if it matches, \gecos@_name\ is expanded and used as the user's name.
11415 .index numerical variables (\$1$\, \$2$\, etc)||in \gecos@_name\
11416 Numeric variables such as \$1$\, \$2$\, etc. can be used in the expansion to
11417 pick up sub-fields that were matched by the pattern. In HP-UX, where the user's
11418 name terminates at the first comma, the following can be used:
11420 gecos_pattern = ([^,]*)
11424 .conf gecos@_pattern string unset
11425 See \gecos@_name\ above.
11427 .conf headers@_charset string "see below"
11428 This option sets a default character set for translating from encoded MIME
11429 `words' in header lines, when referenced by an \$h@_xxx$\ expansion item. The
11430 default is the value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The
11431 ultimate default is ISO-8859-1. For more details see the description of header
11432 insertions in section ~~SECTexpansionitems.
11435 .conf header@_maxsize integer "see below"
11436 .index header section||maximum size of
11437 .index limit||size of message header section
11438 This option controls the overall maximum size of a message's header
11439 section. The default is the value of \\HEADER@_MAXSIZE\\ in
11440 \(Local/Makefile)\; the default for that is 1M. Messages with larger header
11441 sections are rejected.
11443 .conf header@_line@_maxsize integer 0
11444 .index header lines||maximum size of
11445 .index limit||size of one header line
11446 This option limits the length of any individual header line in a message, after
11447 all the continuations have been joined together. Messages with individual
11448 header lines that are longer than the limit are rejected. The default value of
11449 zero means `no limit'.
11453 .conf helo@_accept@_junk@_hosts "host list$**$" unset
11454 .index \\HELO\\||accepting junk data
11455 .index \\EHLO\\||accepting junk data
11456 Exim checks the syntax of \\HELO\\ and \\EHLO\\ commands for incoming SMTP
11457 mail, and gives an error response for invalid data. Unfortunately, there are
11458 some SMTP clients that send syntactic junk. They can be accommodated by setting
11459 this option. Note that this is a syntax check only. See \helo@_verify@_hosts\
11460 if you want to do semantic checking.
11461 See also \helo@_allow@_chars\ for a way of extending the permitted character
11464 .conf helo@_allow@_chars string unset
11465 .index \\HELO\\||underscores in
11466 .index \\EHLO\\||underscores in
11467 .index underscore in \\EHLO\\/\\HELO\\
11468 This option can be set to a string of rogue characters that are permitted in
11469 all \\EHLO\\ and \\HELO\\ names in addition to the standard letters, digits,
11470 hyphens, and dots. If you really must allow underscores, you can set
11472 helo_allow_chars = _
11474 Note that the value is one string, not a list.
11476 .conf helo@_lookup@_domains "domain list$**$" "$tt{@@:@@[]}"
11477 .index \\HELO\\||forcing reverse lookup
11478 .index \\EHLO\\||forcing reverse lookup
11479 If the domain given by a client in a \\HELO\\ or \\EHLO\\ command matches this
11480 list, a reverse lookup is done in order to establish the host's true name. The
11481 default forces a lookup if the client host gives the server's name or any of
11482 its IP addresses (in brackets), something that broken clients have been seen to
11485 .conf helo@_try@_verify@_hosts "host list$**$" unset
11486 .index \\HELO\\||verifying, optional
11487 .index \\EHLO\\||verifying, optional
11488 The RFCs mandate that a server must not reject a message because it doesn't
11489 like the \\HELO\\ or \\EHLO\\ command. By default, Exim just checks the syntax
11490 of these commands (see \helo__accept__junk__hosts\ and \helo@_allow@_chars\
11491 above). However, some sites like to be stricter. If the calling host matches
11492 \helo@_try@_verify@_hosts\, Exim checks that the host name given in the \\HELO\\
11493 or \\EHLO\\ command either:
11495 is an IP literal matching the calling address of the host (the RFCs
11496 specifically allow this), or
11498 .index DNS||reverse lookup
11499 .index reverse DNS lookup
11500 matches the host name that Exim obtains by doing a reverse lookup of the
11501 calling host address, or
11503 when looked up using \*gethostbyname()*\ (or \*getipnodebyname()*\ when
11504 available) yields the calling host address.
11506 However, the \\EHLO\\ or \\HELO\\ command is not rejected if any of the checks
11507 fail. Processing continues, but the result of the check is remembered, and can
11508 be detected later in an ACL by the \"verify = helo"\ condition. If you want
11509 verification failure to cause rejection of \\EHLO\\ or \\HELO\\, use
11510 \helo@_verify@_hosts\ instead.
11513 .conf helo@_verify@_hosts "host list$**$" unset
11514 .index \\HELO\\||verifying, mandatory
11515 .index \\EHLO\\||verifying, mandatory
11516 For hosts that match this option, Exim checks the host name given in the
11517 \\HELO\\ or \\EHLO\\ in the same way as for \helo@_try@_verify@_hosts\. If the
11518 check fails, the \\HELO\\ or \\EHLO\\ command is rejected with a 550 error, and
11519 entries are written to the main and reject logs. If a \\MAIL\\ command is
11520 received before \\EHLO\\ or \\HELO\\, it is rejected with a
11524 .conf hold@_domains "domain list$**$" unset
11525 .index domain||delaying delivery
11526 .index delivery||delaying certain domains
11527 This option allows mail for particular domains to be held on the queue
11528 manually. The option is overridden if a message delivery is forced with the
11529 \-M-\, \-qf-\, \-Rf-\ or \-Sf-\ options, and also while testing or verifying
11530 addresses using \-bt-\ or \-bv-\. Otherwise, if a domain matches an item in
11531 \hold@_domains\, no routing or delivery for that address is done, and it is
11532 deferred every time the message is looked at.
11534 This option is intended as a temporary operational measure for delaying the
11535 delivery of mail while some problem is being sorted out, or some new
11536 configuration tested. If you just want to delay the processing of some
11537 domains until a queue run occurs, you should use \queue@_domains\ or
11538 \queue@_smtp@_domains\, not \hold@_domains\.
11540 A setting of \hold@_domains\ does not override Exim's code for removing
11541 messages from the queue if they have been there longer than the longest retry
11542 time in any retry rule. If you want to hold messages for longer than the normal
11543 retry times, insert a dummy retry rule with a long retry time.
11545 .conf host@_lookup "host list$**$" unset
11546 .index host||name lookup, forcing
11547 Exim does not look up the name of a calling host from its IP address unless it
11548 is required to compare against some host list, or the host matches
11549 \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\, or the host matches this
11550 option (which normally contains IP addresses rather than host names). The
11551 default configuration file contains
11555 which causes a lookup to happen for all hosts. If the expense of these lookups
11556 is felt to be too great, the setting can be changed or removed.
11558 After a successful reverse lookup, Exim does a forward lookup on the name it
11559 has obtained, to verify that it yields the IP address that it started with. If
11560 this check fails, Exim behaves as if the name lookup failed.
11562 After any kind of failure, the host name (in \$sender@_host@_name$\) remains
11563 unset, and \$host@_lookup@_failed$\ is set to the string `1'. See also
11564 \dns@_again@_means@_nonexist\, \helo__lookup__domains\, and \"verify =
11565 reverse@_host@_lookup"\ in ACLs.
11567 .conf host@_lookup@_order "string list" $tt{bydns:byaddr}
11568 This option specifies the order of different lookup methods when Exim is trying
11569 to find a host name from an IP address. The default is to do a DNS lookup
11570 first, and then to try a local lookup (using \*gethostbyaddr()*\ or equivalent)
11571 if that fails. You can change the order of these lookups, or omit one entirely,
11574 \**Warning**\: the `byaddr' method does not always yield aliases when there are
11575 multiple PTR records in the DNS and the IP address is not listed in
11576 \(/etc/hosts)\. Different operating systems give different results in this
11577 case. That is why the default tries a DNS lookup first.
11580 .conf host@_reject@_connection "host list$**$" unset
11581 .index host||rejecting connections from
11582 If this option is set, incoming SMTP calls from the hosts listed are rejected
11583 as soon as the connection is made.
11584 This option is obsolete, and retained only for backward compatibility, because
11585 nowadays the ACL specified by \acl@_smtp@_connect\ can also reject incoming
11586 connections immediately.
11588 The ability to give an immediate rejection (either by this option or using an
11589 ACL) is provided for use in unusual cases. Many hosts will just try again,
11590 sometimes without much delay. Normally, it is better to use an ACL to reject
11591 incoming messages at a later stage, such as after \\RCPT\\ commands. See
11594 .conf hosts@_treat@_as@_local "domain list$**$" unset
11595 .index local host||domains treated as
11596 .index host||treated as local
11597 If this option is set, any host names that match the domain list are treated as
11598 if they were the local host when Exim is scanning host lists obtained from MX
11600 or other sources. Note that the value of this option is a domain list, not a
11601 host list, because it is always used to check host names, not IP addresses.
11603 This option also applies when Exim is matching the special items
11604 \"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\ in a domain list (see
11605 section ~~SECTdomainlist), and when checking the \hosts\ option in the \%smtp%\
11606 transport for the local host (see the \allow@_localhost\ option in that
11608 See also \local@_interfaces\, \extra@_local@_interfaces\, and chapter
11609 ~~CHAPinterfaces, which contains a discussion about local network interfaces
11610 and recognising the local host.
11612 .conf ignore@_bounce@_errors@_after time 10w
11613 .index bounce message||discarding
11614 .index discarding bounce message
11615 This option affects the processing of bounce messages that cannot be delivered,
11616 that is, those that suffer a permanent delivery failure. (Bounce messages that
11617 suffer temporary delivery failures are of course retried in the usual way.)
11619 After a permanent delivery failure, bounce messages are frozen,
11620 because there is no sender to whom they can be returned. When a frozen bounce
11621 message has been on the queue for more than the given time, it is unfrozen at
11622 the next queue run, and a further delivery is attempted. If delivery fails
11623 again, the bounce message is discarded. This makes it possible to keep failed
11624 bounce messages around for a shorter time than the normal maximum retry time
11625 for frozen messages. For example,
11627 ignore_bounce_errors_after = 12h
11629 retries failed bounce message deliveries after 12 hours, discarding any further
11630 failures. If the value of this option is set to a zero time period, bounce
11631 failures are discarded immediately. Setting a very long time (as in the default
11632 value) has the effect of disabling this option. For ways of automatically
11633 dealing with other kinds of frozen message, see \auto@_thaw\ and
11634 \timeout@_frozen@_after\.
11636 .conf ignore@_fromline@_hosts "host list$**$" unset
11638 .index UUCP||`From' line
11639 Some broken SMTP clients insist on sending a UUCP-like `From' line before the
11640 headers of a message. By default this is treated as the start of the message's
11641 body, which means that any following headers are not recognized as such. Exim
11642 can be made to ignore it by setting \ignore@_fromline@_hosts\ to match those
11643 hosts that insist on sending it. If the sender is actually a local process
11644 rather than a remote host, and is using \-bs-\ to inject the messages,
11645 \ignore__fromline__local\ must be set to achieve this effect.
11647 .conf ignore@_fromline@_local boolean false
11648 See \ignore@_fromline@_hosts\ above.
11650 .conf keep@_malformed time 4d
11651 This option specifies the length of time to keep messages whose spool files
11652 have been corrupted in some way. This should, of course, never happen. At the
11653 next attempt to deliver such a message, it gets removed. The incident is
11656 .conf ldap@_default@_servers "string list" unset
11657 .index LDAP||default servers
11658 This option provides a list of LDAP servers which are tried in turn when an
11659 LDAP query does not contain a server. See section ~~SECTforldaque for details
11660 of LDAP queries. This option is available only when Exim has been built with
11663 .conf ldap@_version integer unset
11664 .index LDAP||protocol version, forcing
11665 This option can be used to force Exim to set a specific protocol version for
11666 LDAP. If it option is unset, it is shown by the \-bP-\ command line option as
11667 -1. When this is the case, the default is 3 if \\LDAP@_VERSION3\\ is defined in
11668 the LDAP headers; otherwise it is 2. This option is available only when Exim
11669 has been built with LDAP support.
11672 .conf local@_from@_check boolean true
11673 .index ::Sender:: header line||disabling addition of
11674 .index ::From:: header line||disabling checking of
11675 When a message is submitted locally (that is, not over a TCP/IP connection) by
11676 an untrusted user, Exim removes any existing ::Sender:: header line, and checks
11677 that the ::From:: header line matches the login of the calling user. You can
11678 use \local@_from@_prefix\ and \local@_from@_suffix\ to permit affixes on the
11679 local part. If the ::From:: header line does not match, Exim adds a ::Sender::
11680 header with an address constructed from the calling user's login and the
11681 default qualify domain.
11683 If \local@_from@_check\ is set false, the ::From:: header check is disabled,
11684 and no ::Sender:: header is ever added. If, in addition, you want to retain
11685 ::Sender:: header lines supplied by untrusted users, you must also set
11686 \local@_sender@_retain\ to be true.
11688 .index envelope sender
11689 These options affect only the header lines in the message. The envelope sender
11690 is still forced to be the login id at the qualify domain unless
11691 \untrusted@_set@_sender\ permits the user to supply an envelope sender.
11692 Section ~~SECTthesenhea has more details about ::Sender:: processing.
11695 .conf local@_from@_prefix string unset
11696 When Exim checks the ::From:: header line of locally submitted messages for
11697 matching the login id (see \local@_from@_check\ above), it can be configured to
11698 ignore certain prefixes and suffixes in the local part of the address. This is
11699 done by setting \local@_from@_prefix\ and/or \local@_from@_suffix\ to
11700 appropriate lists, in the same form as the \local@_part@_prefix\ and
11701 \local@_part@_suffix\ router options (see chapter ~~CHAProutergeneric). For
11704 local_from_prefix = *-
11706 is set, a ::From:: line containing
11708 From: anything-user@your.domain.example
11710 will not cause a ::Sender:: header to be added if \*user@@your.domain.example*\
11711 matches the actual sender address that is constructed from the login name and
11714 .conf local@_from@_suffix string unset
11715 See \local@_from@_prefix\ above.
11717 .conf local@_interfaces "string list" "see below"
11718 This option controls which network interfaces are used by the daemon for
11719 listening; they are also used to identify the local host when routing. Chapter
11720 ~~CHAPinterfaces contains a full description of this option and the related
11721 options \extra@_local@_interfaces\ and \hosts@_treat@_as@_local\. The default
11722 value for \local@_interfaces\ is
11724 local_interfaces = 0.0.0.0
11726 when Exim is built without IPv6 support; otherwise it is
11728 local_interfaces = <; ::0 ; 0.0.0.0
11731 .conf local@_scan@_timeout time 5m
11732 .index timeout||for \*local@_scan()*\ function
11733 .index \*local@_scan()*\ function||timeout
11734 This timeout applies to the \*local@_scan()*\ function (see chapter
11735 ~~CHAPlocalscan). Zero means `no timeout'. If the timeout is exceeded, the
11736 incoming message is rejected with a temporary error if it is an SMTP message.
11737 For a non-SMTP message, the message is dropped and Exim ends with a non-zero
11738 code. The incident is logged on the main and reject logs.
11741 .conf local@_sender@_retain boolean false
11742 .index ::Sender:: header line||retaining from local submission
11743 When a message is submitted locally (that is, not over a TCP/IP connection) by
11744 an untrusted user, Exim removes any existing ::Sender:: header line. If you
11745 do not want this to happen, you must set \local@_sender@_retain\, and you must
11746 also set \local@_from@_check\ to be false (Exim will complain if you do not).
11747 Section ~~SECTthesenhea has more details about ::Sender:: processing.
11751 .conf localhost@_number string$**$ unset
11752 .index host||locally unique number for
11753 .index message||ids, with multiple hosts
11754 Exim's message ids are normally unique only within the local host. If
11755 uniqueness among a set of hosts is required, each host must set a different
11756 value for the \localhost@_number\ option. The string is expanded immediately
11757 after reading the configuration file (so that a number can be computed from the
11758 host name, for example) and the result of the expansion must be a number in the
11759 range 0--16 (or 0--10 on operating systems with case-insensitive file systems).
11760 This is available in subsequent string expansions via the variable
11761 \$localhost@_number$\. When \localhost@_number is set\, the final two
11762 characters of the message id, instead of just being a fractional part of the
11763 time, are computed from the time and the local host number as described in
11764 section ~~SECTmessiden.
11767 .conf log@_file@_path "string list$**$" "set at compile time"
11768 .index log||file path for
11769 This option sets the path which is used to determine the names of Exim's log
11770 files, or indicates that logging is to be to syslog, or both. It is expanded
11771 when Exim is entered, so it can, for example, contain a reference to the host
11772 name. If no specific path is set for the log files at compile or run time, they
11773 are written in a sub-directory called \(log)\ in Exim's spool directory.
11774 Chapter ~~CHAPlog contains further details about Exim's logging, and section
11775 ~~SECTwhelogwri describes how the contents of \log@_file@_path\ are used. If
11776 this string is fixed at your installation (contains no expansion variables) it
11777 is recommended that you do not set this option in the configuration file, but
11778 instead supply the path using \\LOG@_FILE@_PATH\\ in \(Local/Makefile)\ so that
11779 it is available to Exim for logging errors detected early on -- in particular,
11780 failure to read the configuration file.
11782 .conf log@_selector string unset
11783 .index log||selectors
11784 This option can be used to reduce or increase the number of things that Exim
11785 writes to its log files. Its argument is made up of names preceded by plus or
11786 minus characters. For example:
11788 log_selector = +arguments -retry_defer
11790 A list of possible names and what they control is given in the chapter on
11791 logging, in section ~~SECTlogselector.
11793 .conf log@_timezone boolean false
11794 .index log||timezone for entries
11795 By default, the timestamps on log lines are in local time without the
11796 timezone. This means that if your timezone changes twice a year, the timestamps
11797 in log lines are ambiguous for an hour when the clocks go back. One way of
11798 avoiding this problem is to set the timezone to UTC. An alternative is to set
11799 \log@_timezone\ true. This turns on the addition of the timezone offset to
11800 timestamps in log lines. Turning on this option can add quite a lot to the size
11801 of log files because each line is extended by 6 characters. Note that the
11802 \$tod@_log$\ variable contains the log timestamp without the zone, but there is
11803 another variable called \$tod@_zone$\ that contains just the timezone offset.
11805 .conf lookup@_open@_max integer 25
11806 .index too many open files
11807 .index open files, too many
11808 .index file||too many open
11809 .index lookup||maximum open files
11810 .index limit||open files for lookups
11811 This option limits the number of simultaneously open files for single-key
11812 lookups that use regular files (that is, \%lsearch%\, \%dbm%\, and \%cdb%\). Exim
11813 normally keeps these files open during routing, because often the same file is
11814 required several times. If the limit is reached, Exim closes the least recently
11815 used file. Note that if you are using the \*ndbm*\ library, it actually opens
11816 two files for each logical DBM database, though it still counts as one for the
11817 purposes of \lookup@_open@_max\. If you are getting `too many open files'
11818 errors with NDBM, you need to reduce the value of \lookup@_open@_max\.
11820 .conf max@_username@_length integer 0
11821 .index length of login name
11822 .index user name||maximum length
11823 .index limit||user name length
11824 Some operating systems are broken in that they truncate long arguments to
11825 \*getpwnam()*\ to eight characters, instead of returning `no such user'. If
11826 this option is set greater than zero, any attempt to call \*getpwnam()*\ with
11827 an argument that is longer behaves as if \*getpwnam()*\ failed.
11830 .conf message@_body@_visible integer 500
11831 .index body of message||visible size
11832 .index message||body, visible size
11833 This option specifies how much of a message's body is to be included in the
11834 \$message@_body$\ and \$message@_body@_end$\ expansion variables.
11836 .conf message@_id@_header@_domain string$**$ unset
11837 .index ::Message-ID:: header line
11838 If this option is set, the string is expanded and used as the right hand side
11839 (domain) of the ::Message-ID:: header that Exim creates if a
11840 locally-originated incoming message does not have one. `Locally-originated'
11841 means `not received over TCP/IP.'
11842 Otherwise, the primary host name is used.
11843 Only letters, digits, dot and hyphen are accepted; any other characters are
11844 replaced by hyphens. If the expansion is forced to fail, or if the result is an
11845 empty string, the option is ignored.
11847 .conf message@_id@_header@_text string$**$ unset
11848 If this variable is set, the string is expanded and used to augment the text of
11849 the ::Message-id:: header that Exim creates if a
11851 incoming message does not have one. The text of this header is required by RFC
11852 2822 to take the form of an address. By default, Exim uses its internal message
11853 id as the local part, and the primary host name as the domain. If this option
11854 is set, it is expanded, and provided the expansion is not forced to fail, and
11855 does not yield an empty string, the result is inserted into the header
11856 immediately before the @@, separated from the internal message id by a dot. Any
11857 characters that are illegal in an address are automatically converted into
11858 hyphens. This means that variables such as \$tod@_log$\ can be used, because
11859 the spaces and colons will become hyphens.
11861 .conf message@_logs boolean true
11862 .index message||log, disabling
11863 .index log||message log, disabling
11864 If this option is turned off, per-message log files are not created in the
11865 \(msglog)\ spool sub-directory. This reduces the amount of disk I/O required by
11866 Exim, by reducing the number of files involved in handling a message from a
11867 minimum of four (header spool file, body spool file, delivery journal, and
11868 per-message log) to three. The other major I/O activity is Exim's main log,
11869 which is not affected by this option.
11871 .conf message@_size@_limit string$**$ 50M
11872 .index message||size limit
11873 .index limit||message size
11874 .index size||of message, limit
11875 This option limits the maximum size of message that Exim will process. The
11876 value is expanded for each incoming
11877 connection so, for example, it can be made to depend on the IP address of the
11878 remote host for messages arriving via TCP/IP. \**Note**\: This limit cannot be
11879 made to depend on a message's sender or any other properties of an individual
11880 message, because it has to be advertised in the server's response to \\EHLO\\.
11881 String expansion failure causes a temporary error. A value of zero means no
11882 limit, but its use is not recommended. See also \bounce@_return@_size@_limit\.
11884 Incoming SMTP messages are failed with a 552 error if the limit is
11885 exceeded; locally-generated messages either get a stderr message or a delivery
11886 failure message to the sender, depending on the \-oe-\ setting. Rejection of an
11887 oversized message is logged in both the main and the reject logs. See also the
11888 generic transport option \message@_size@_limit\, which limits the size of
11889 message that an individual transport can process.
11891 .conf move@_frozen@_messages boolean false
11892 .index frozen messages||moving
11893 This option, which is available only if Exim has been built with the setting
11895 SUPPORT_MOVE_FROZEN_MESSAGES=yes
11897 in \(Local/Makefile)\, causes frozen messages and their message logs to be
11898 moved from the \(input)\ and \(msglog)\ directories on the spool to \(Finput)\
11899 and \(Fmsglog)\, respectively. There is currently no support in Exim or the
11900 standard utilities for handling such moved messages, and they do not show up in
11901 lists generated by \-bp-\ or by the Exim monitor.
11903 .conf mysql@_servers "string list" unset
11904 .index MySQL||server list
11905 This option provides a list of MySQL servers and associated connection data, to
11906 be used in conjunction with \%mysql%\ lookups (see section ~~SECTsql). The
11907 option is available only if Exim has been built with MySQL support.
11909 .conf never@_users "string list" unset
11910 Local message deliveries are normally run in processes that are setuid to the
11911 recipient, and remote deliveries are normally run under Exim's own uid and gid.
11912 It is usually desirable to prevent any deliveries from running as root, as a
11915 When Exim is built, an option called \\FIXED@_NEVER@_USERS\\ can be set to a
11916 list of users that must not be used for local deliveries. This list is fixed in
11917 the binary and cannot be overridden by the configuration file. By default, it
11918 contains just the single user name `root'. The \never@_users\ runtime option
11919 can be used to add more users to the fixed list.
11921 If a message is to be delivered as one of the users on the fixed list or the
11922 \never@_users\ list, an error occurs, and delivery is deferred. A common
11925 never@_users = root:daemon:bin
11927 Including root is redundant if it is also on the fixed list, but it does no
11929 This option overrides the \pipe@_as@_creator\ option of the \%pipe%\ transport
11932 .conf oracle@_servers "string list" unset
11933 .index Oracle||server list
11934 This option provides a list of Oracle servers and associated connection data,
11935 to be used in conjunction with \%oracle%\ lookups (see section ~~SECTsql). The
11936 option is available only if Exim has been built with Oracle support.
11938 .conf percent@_hack@_domains "domain list$**$" unset
11939 .index `percent hack'
11940 .index source routing||in email address
11941 .index address||source-routed
11942 The `percent hack' is the convention whereby a local part containing a percent
11943 sign is re-interpreted as a new email address, with the percent replaced by @@.
11944 This is sometimes called `source routing', though that term is also applied to
11945 RFC 2822 addresses that begin with an @@ character. If this option is set, Exim
11946 implements the percent facility for those domains listed, but no others. This
11947 happens before an incoming SMTP address is tested against an ACL.
11949 \**Warning**\: The `percent hack' has often been abused by people who are
11950 trying to get round relaying restrictions. For this reason, it is best avoided
11951 if at all possible. Unfortunately, a number of less security-conscious MTAs
11952 implement it unconditionally. If you are running Exim on a gateway host, and
11953 routing mail through to internal MTAs without processing the local parts, it is
11954 a good idea to reject recipient addresses with percent characters in their
11955 local parts. Exim's default configuration does this.
11957 .conf perl@_at@_start boolean false
11958 This option is available only when Exim is built with an embedded Perl
11959 interpreter. See chapter ~~CHAPperl for details of its use.
11961 .conf perl@_startup string unset
11962 This option is available only when Exim is built with an embedded Perl
11963 interpreter. See chapter ~~CHAPperl for details of its use.
11965 .conf pgsql@_servers "string list" unset
11966 .index PostgreSQL lookup type||server list
11967 This option provides a list of PostgreSQL servers and associated connection
11968 data, to be used in conjunction with \%pgsql%\ lookups (see section ~~SECTsql).
11969 The option is available only if Exim has been built with PostgreSQL support.
11971 .conf pid@_file@_path string$**$ "set at compile time"
11972 .index daemon||pid file path
11973 .index pid file, path for
11974 This option sets the name of the file to which the Exim daemon writes its
11975 process id. The string is expanded, so it can contain, for example, references
11978 pid_file_path = /var/log/$primary_hostname/exim.pid
11980 If no path is set, the pid is written to the file \(exim-daemon.pid)\ in Exim's
11982 The value set by the option can be overridden by the \-oP-\ command line
11983 option. A pid file is not written if a `non-standard' daemon is run by means of
11984 the \-oX-\ option, unless a path is explicitly supplied by \-oP-\.
11986 .conf pipelining@_advertise@_hosts "host list$**$" $*$
11987 .index \\PIPELINING\\||advertising, suppressing
11988 This option can be used to suppress the advertisement of the SMTP
11989 \\PIPELINING\\ extension to specific hosts. When \\PIPELINING\\ is not
11990 advertised and \smtp@_enforce@_sync\ is true, an Exim server enforces strict
11991 synchronization for each SMTP command and response.
11993 When \\PIPELINING\\ is advertised, Exim assumes that clients will use it; `out
11994 of order' commands that are `expected' do not count as protocol errors (see
11995 \smtp@_max@_synprot@_errors\).
11998 .conf preserve@_message@_logs boolean false
11999 .index message logs, preserving
12000 If this option is set, message log files are not deleted when messages are
12001 completed. Instead, they are moved to a sub-directory of the spool directory
12002 called \(msglog.OLD)\, where they remain available for statistical or debugging
12003 purposes. This is a dangerous option to set on systems with any appreciable
12004 volume of mail. Use with care!
12006 .conf primary@_hostname string "see below"
12007 .index name||of local host
12008 .index host||name of local
12009 .index local host||name of
12011 This specifies the name of the current host. It is used in the default \\EHLO\\
12012 or \\HELO\\ command for outgoing SMTP messages (changeable via the \helo@_data\
12013 option in the \%smtp%\ transport),
12015 and as the default for \qualify@_domain\. If it is not set, Exim calls
12016 \*uname()*\ to find it. If this fails, Exim panics and dies. If the name
12017 returned by \*uname()*\ contains only one component, Exim passes it to
12018 \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) in order to
12019 obtain the fully qualified version.
12022 The value of \$primary@_hostname$\ is also used by default in some SMTP
12023 response messages from an Exim server. This can be changed dynamically by
12024 setting \smtp@_active@_hostname\.
12027 .conf print@_topbitchars boolean false
12028 .index printing characters
12029 .index 8-bit characters
12030 By default, Exim considers only those characters whose codes lie in the range
12031 32--126 to be printing characters. In a number of circumstances (for example,
12032 when writing log entries) non-printing characters are converted into escape
12033 sequences, primarily to avoid messing up the layout. If \print@_topbitchars\ is
12034 set, code values of 128 and above are also considered to be printing
12037 .conf process@_log@_path string unset
12038 .index process log path
12039 .index log||process log
12041 This option sets the name of the file to which an Exim process writes its
12042 `process log' when sent a USR1 signal. This is used by the \*exiwhat*\ utility
12043 script. If this option is unset, the file called \(exim-process.info)\ in
12044 Exim's spool directory is used. The ability to specify the name explicitly can
12045 be useful in environments where two different Exims are running, using
12046 different spool directories.
12048 .conf prod@_requires@_admin boolean true
12049 .index \-M-\ option
12050 .index \-R-\ option
12051 .index \-q-\ option
12052 The \-M-\, \-R-\, and \-q-\ command-line options require the caller to be an
12053 admin user unless \prod@_requires@_admin\ is set false. See also
12054 \queue@_list@_requires@_admin\.
12056 .conf qualify@_domain string "see below"
12057 .index domain||for qualifying addresses
12058 .index address||qualification
12059 This option specifies the domain name that is added to any sender addresses
12060 that do not have a domain qualification. It also applies to recipient addresses
12061 if \qualify@_recipient\ is not set. Such addresses are accepted by default only
12062 for locally-generated messages. Messages from external sources must always
12063 contain fully qualified addresses, unless the sending host matches
12064 \sender@_unqualified@_hosts\ or \recipient@_unqualified@_hosts\ (as
12065 appropriate), in which case incoming addresses are qualified with
12066 \qualify@_domain\ or \qualify@_recipient\ as necessary. Internally, Exim always
12067 works with fully qualified addresses.
12068 If \qualify@_domain\ is not set, it defaults to the \primary@_hostname\ value.
12070 .conf qualify@_recipient string "see below"
12071 This specifies the domain name that is added to any recipient addresses that do
12072 not have a domain qualification. Such addresses are accepted by default only
12073 for locally-generated messages. Messages from external sources must always
12074 contain fully qualified recipient addresses, unless the sending host matches
12075 \recipient@_unqualified@_hosts\,
12076 in which case incoming recipient addresses are qualified with
12077 \qualify@_recipient\.
12078 If \qualify@_recipient\ is not set, it defaults to the \qualify@_domain\ value.
12080 .conf queue@_domains "domain list$**$" unset
12081 .index domain||specifying non-immediate delivery
12082 .index queueing incoming messages
12083 .index message||queueing certain domains
12084 This option lists domains for which immediate delivery is not required.
12085 A delivery process is started whenever a message is received, but only those
12086 domains that do not match are processed. All other deliveries wait until the
12087 next queue run. See also \hold@_domains\ and \queue@_smtp@_domains\.
12089 .conf queue@_list@_requires@_admin boolean true
12090 .index \-bp-\ option
12091 The \-bp-\ command-line option, which lists the messages that are on the queue,
12092 requires the caller to be an admin user unless \queue__list__requires__admin\
12093 is set false. See also \prod@_requires@_admin\.
12095 .conf queue@_only boolean false
12096 .index queueing incoming messages
12097 .index message||queueing unconditionally
12098 If \queue@_only\ is set, a delivery process is not automatically started
12099 whenever a message is received. Instead, the message waits on the queue for the
12100 next queue run. Even if \queue@_only\ is false, incoming messages may not get
12101 delivered immediately when certain conditions (such as heavy load) occur.
12103 The \-odq-\ command line has the same effect as \queue@_only\. The \-odb-\ and
12104 \-odi-\ command line options override \queue@_only\ unless
12105 \queue@_only@_override\ is set false. See also \queue@_only@_file\,
12106 \queue@_only@_load\, and \smtp@_accept@_queue\.
12108 .conf queue@_only@_file string unset
12109 .index queueing incoming messages
12110 .index message||queueing by file existence
12111 This option can be set to a colon-separated list of absolute path names, each
12112 one optionally preceded by `smtp'. When Exim is receiving a message,
12113 it tests for the existence of each listed path using a call to \*stat()*\. For
12114 each path that exists, the corresponding queuing option is set.
12115 For paths with no prefix, \queue@_only\ is set; for paths prefixed by `smtp',
12116 \queue@_smtp@_domains\ is set to match all domains. So, for example,
12118 queue_only_file = smtp/some/file
12120 causes Exim to behave as if \queue@_smtp@_domains\ were set to `$*$' whenever
12121 \(/some/file)\ exists.
12123 .conf queue@_only@_load fixed-point unset
12124 .index load average
12125 .index queueing incoming messages
12126 .index message||queueing by load
12127 If the system load average is higher than this value, incoming messages from
12128 all sources are queued, and no automatic deliveries are started. If this
12129 happens during local or remote SMTP input, all subsequent messages on the same
12130 connection are queued. Deliveries will subsequently be performed by queue
12131 runner processes. This option has no effect on ancient operating systems on
12132 which Exim cannot determine the load average. See also
12133 \deliver@_queue@_load@_max\ and \smtp@_load@_reserve\.
12135 .conf queue@_only@_override boolean true
12136 .index queueing incoming messages
12137 When this option is true, the \-od\*x*\-\ command line options override the
12138 setting of \queue@_only\ or \queue@_only@_file\ in the configuration file. If
12139 \queue@_only@_override\ is set false, the \-od\*x*\-\ options cannot be used to
12140 override; they are accepted, but ignored.
12142 .conf queue@_run@_in@_order boolean false
12143 .index queue runner||processing messages in order
12144 If this option is set, queue runs happen in order of message arrival instead of
12145 in an arbitrary order. For this to happen, a complete list of the entire queue
12146 must be set up before the deliveries start. When the queue is all in a single
12147 directory (the default), this happens anyway, but if \split@_spool@_directory\
12148 is set it does not -- for delivery in random order, the sub-directories are
12149 processed one at a time (in random order), to avoid setting up one huge list.
12150 Thus, setting \queue@_run@_in@_order\ with \split@_spool@_directory\ may
12151 degrade performance when the queue is large. In most situations,
12152 \queue@_run@_in@_order\ should not be set.
12154 .conf queue@_run@_max integer 5
12155 .index queue runner||maximum number of
12156 This controls the maximum number of queue runner processes that an Exim daemon
12157 can run simultaneously. This does not mean that it starts them all at once,
12158 but rather that if the maximum number are still running when the time comes to
12159 start another one, it refrains from starting another one. This can happen with
12160 very large queues and/or very sluggish deliveries. This option does not,
12161 however, interlock with other processes, so additional queue runners can be
12162 started by other means, or by killing and restarting the daemon.
12164 .conf queue@_smtp@_domains "domain list$**$" unset
12165 .index queueing incoming messages
12166 .index message||queueing remote deliveries
12167 When this option is set, a delivery process is started whenever a message is
12168 received, routing is performed, and local deliveries take place.
12169 However, if any SMTP deliveries are required for domains that match
12170 \queue@_smtp@_domains\, they are not immediately delivered, but instead the
12171 message waits on the queue for the next queue run. Since routing of the message
12172 has taken place, Exim knows to which remote hosts it must be delivered, and so
12173 when the queue run happens, multiple messages for the same host are delivered
12174 over a single SMTP connection. The \-odqs-\ command line option causes all SMTP
12175 deliveries to be queued in this way, and is equivalent to setting
12176 \queue@_smtp@_domains\ to `$*$'. See also \hold@_domains\ and \queue@_domains\.
12178 .conf receive@_timeout time 0s
12179 .index timeout||for non-SMTP input
12180 This option sets the timeout for accepting a non-SMTP message, that is, the
12181 maximum time that Exim waits when reading a message on the standard input. If
12182 the value is zero, it will wait for ever. This setting is overridden by the
12183 \-or-\ command line option. The timeout for incoming SMTP messages is
12184 controlled by \smtp@_receive@_timeout\.
12186 .index customizing|| ::Received:: header
12187 .index ::Received:: header line||customizing
12188 .conf received@_header@_text string$**$ "see below"
12189 This string defines the contents of the ::Received:: message header that is
12190 added to each message, except for the timestamp, which is automatically added
12191 on at the end (preceded by a semicolon). The string is expanded each time it is
12192 used. If the expansion yields an empty string, no ::Received:: header line is
12193 added to the message. Otherwise, the string should start with the text
12194 `Received:' and conform to the RFC 2822 specification for ::Received:: header
12195 lines. The default setting is:
12197 received_header_text = Received: \
12198 ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\
12199 {${if def:sender_ident {from $sender_ident }}\
12200 ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
12201 by $primary_hostname \
12202 ${if def:received_protocol {with $received_protocol}} \
12203 ${if def:tls_cipher {($tls_cipher)\n\t}}\
12204 (Exim $version_number)\n\t\
12206 ${if def:received_for {\n\tfor $received_for}}
12208 Note the use of quotes, to allow the sequences \"@\n"\ and \"@\t"\ to be used
12209 for newlines and tabs, respectively. The reference to the TLS cipher is omitted
12210 when Exim is built without TLS support. The use of conditional expansions
12211 ensures that this works for both locally generated messages and messages
12212 received from remote hosts, giving header lines such as the following:
12214 Received: from scrooge.carol.example ([192.168.12.25] ident=root)
12215 by marley.carol.example with esmtp (Exim 4.00)
12216 id 16IOWa-00019l-00
12217 for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000
12218 Received: by scrooge.carol.example with local (Exim 4.00)
12219 id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000
12222 Until the body of the message has been received, the timestamp is the time when
12223 the message started to be received. Once the body has arrived, and all policy
12224 checks have taken place, the timestamp is updated to the time at which the
12225 message was accepted.
12228 .conf received@_headers@_max integer 30
12229 .index loop||prevention
12230 .index mail loop prevention
12231 .index ::Received:: header line||counting
12232 When a message is to be delivered, the number of ::Received:: headers is
12233 counted, and if it is greater than this parameter, a mail loop is assumed to
12234 have occurred, the delivery is abandoned, and an error message is generated.
12235 This applies to both local and remote deliveries.
12237 .conf recipient@_unqualified@_hosts "host list$**$" unset
12238 .index unqualified addresses
12239 .index host||unqualified addresses from
12240 This option lists those hosts from which Exim is prepared to accept unqualified
12241 recipient addresses in message envelopes. The addresses are made fully
12242 qualified by the addition of the \qualify@_recipient\ value. This option also
12243 affects message header lines. Exim does not reject unqualified recipient
12244 addresses in headers, but it qualifies them only if the message came from a
12245 host that matches \recipient@_unqualified@_hosts\,
12247 or if the message was submitted locally (not using TCP/IP), and the \-bnq-\
12248 option was not set.
12251 .conf recipients@_max integer 0
12252 .index limit||number of recipients
12253 .index recipient||maximum number
12254 If this option is set greater than zero, it specifies the maximum number of
12255 original recipients for any message. Additional recipients that are generated
12256 by aliasing or forwarding do not count. SMTP messages get a 452 response for
12257 all recipients over the limit; earlier recipients are delivered as normal.
12258 Non-SMTP messages with too many recipients are failed, and no deliveries are
12260 .index \\RCPT\\||maximum number of incoming
12261 Note that the RFCs specify that an SMTP server should accept at least 100
12262 \\RCPT\\ commands in a single message.
12264 .conf recipients@_max@_reject boolean false
12265 If this option is set true, Exim rejects SMTP messages containing too many
12266 recipients by giving 552 errors to the surplus \\RCPT\\ commands, and a 554
12267 error to the eventual \\DATA\\ command. Otherwise (the default) it gives a 452
12268 error to the surplus \\RCPT\\ commands and accepts the message on behalf of the
12269 initial set of recipients. The remote server should then re-send the message
12270 for the remaining recipients at a later time.
12272 .conf remote@_max@_parallel integer 2
12273 .index delivery||parallelism for remote
12274 This option controls parallel delivery of one message to a number of remote
12275 hosts. If the value is less than 2, parallel delivery is disabled, and Exim
12276 does all the remote deliveries for a message one by one. Otherwise, if a single
12277 message has to be delivered to more than one remote host, or if several copies
12278 have to be sent to the same remote host, up to \remote@_max@_parallel\
12279 deliveries are done simultaneously. If more than \remote@_max@_parallel\
12280 deliveries are required, the maximum number of processes are started, and as
12281 each one finishes, another is begun. The order of starting processes is the
12282 same as if sequential delivery were being done, and can be controlled by the
12283 \remote@_sort@_domains\ option. If parallel delivery takes place while running
12284 with debugging turned on, the debugging output from each delivery process is
12285 tagged with its process id.
12287 This option controls only the maximum number of parallel deliveries for one
12288 message in one Exim delivery process. Because Exim has no central queue
12289 manager, there is no way of controlling the total number of simultaneous
12290 deliveries if the configuration allows a delivery attempt as soon as a message
12292 .index number of deliveries
12293 .index delivery||maximum number of
12294 If you want to control the total number of deliveries on the system, you
12295 need to set the \queue@_only\ option. This ensures that all incoming messages
12296 are added to the queue without starting a delivery process. Then set up an Exim
12297 daemon to start queue runner processes at appropriate intervals (probably
12298 fairly often, for example, every minute), and limit the total number of queue
12299 runners by setting the \queue__run__max\ parameter. Because each queue runner
12300 delivers only one message at a time, the maximum number of deliveries that can
12301 then take place at once is \queue@_run@_max\ multiplied by
12302 \remote@_max@_parallel\.
12304 If it is purely remote deliveries you want to control, use \queue@_smtp\
12305 instead of \queue@_only\. This has the added benefit of doing the SMTP routing
12306 before queuing, so that several messages for the same host will eventually get
12307 delivered down the same connection.
12309 .conf remote@_sort@_domains "domain list$**$" unset
12310 .index sorting remote deliveries
12311 .index delivery||sorting remote
12312 When there are a number of remote deliveries for a message, they are sorted by
12313 domain into the order given by this list. For example,
12315 remote_sort_domains = *.cam.ac.uk:*.uk
12317 would attempt to deliver to all addresses in the \*cam.ac.uk*\ domain first, then
12318 to those in the \uk\ domain, then to any others.
12320 .conf retry@_data@_expire time 7d
12321 .index hints database||data expiry
12322 This option sets a `use before' time on retry information in Exim's hints
12323 database. Any older retry data is ignored. This means that, for example, once a
12324 host has not been tried for 7 days, Exim behaves as if it has no knowledge of
12327 .conf retry@_interval@_max time 24h
12328 .index retry||limit on interval
12329 .index limit||on retry interval
12330 Chapter ~~CHAPretry describes Exim's mechanisms for controlling the intervals
12331 between delivery attempts for messages that cannot be delivered straight away.
12332 This option sets an overall limit to the length of time between retries.
12334 .conf return@_path@_remove boolean true
12335 .index ::Return-path:: header line||removing
12336 RFC 2821, section 4.4, states that an SMTP server must insert a ::Return-path::
12337 header line into a message when it makes a `final delivery'. The ::Return-path::
12338 header preserves the sender address as received in the \\MAIL\\ command. This
12339 description implies that this header should not be present in an incoming
12340 message. If \return@_path@_remove\ is true, any existing ::Return-path::
12341 headers are removed from messages at the time they are received. Exim's
12342 transports have options for adding ::Return-path:: headers at the time of
12343 delivery. They are normally used only for final local deliveries.
12345 .conf return@_size@_limit integer 100K
12346 This option is an obsolete synonym for \bounce@_return@_size@_limit\.
12348 .conf rfc1413@_hosts "host list$**$" $*$
12350 .index host||for RFC 1413 calls
12351 RFC 1413 identification calls are made to any client host which matches an item
12354 .conf rfc1413@_query@_timeout time 30s
12355 .index RFC 1413||query timeout
12356 .index timeout||for RFC 1413 call
12357 This sets the timeout on RFC 1413 identification calls. If it is set to zero,
12358 no RFC 1413 calls are ever made.
12360 .conf sender@_unqualified@_hosts "host list$**$" unset
12361 .index unqualified addresses
12362 .index host||unqualified addresses from
12363 This option lists those hosts from which Exim is prepared to accept unqualified
12364 sender addresses. The addresses are made fully qualified by the addition of
12365 \qualify@_domain\. This option also affects message header lines. Exim does not
12366 reject unqualified addresses in headers that contain sender addresses, but it
12367 qualifies them only if the message came from a host that matches
12368 \sender@_unqualified@_hosts\,
12370 or if the message was submitted locally (not using TCP/IP), and the \-bnq-\
12371 option was not set.
12374 .conf smtp@_accept@_keepalive boolean true
12375 .index keepalive||on incoming connection
12376 This option controls the setting of the \\SO@_KEEPALIVE\\ option on incoming
12377 TCP/IP socket connections. When set, it causes the kernel to probe idle
12378 connections periodically, by sending packets with `old' sequence numbers. The
12379 other end of the connection should send an acknowledgement if the connection is
12380 still okay or a reset if the connection has been aborted. The reason for doing
12381 this is that it has the beneficial effect of freeing up certain types of
12382 connection that can get stuck when the remote host is disconnected without
12383 tidying up the TCP/IP call properly. The keepalive mechanism takes several
12384 hours to detect unreachable hosts.
12387 .conf smtp@_accept@_max integer 20
12388 .index limit||incoming SMTP connections
12389 .index SMTP||incoming connection count
12391 This option specifies the maximum number of simultaneous incoming SMTP calls
12392 that Exim will accept. It applies only to the listening daemon; there is no
12393 control (in Exim) when incoming SMTP is being handled by \*inetd*\. If the value
12394 is set to zero, no limit is applied. However, it is required to be non-zero if
12395 either \smtp@_accept@_max@_per@_host\ or \smtp@_accept@_queue\ is set. See also
12396 \smtp@_accept@_reserve\.
12399 .conf smtp@_accept@_max@_nonmail integer 10
12400 .index limit||non-mail SMTP commands
12401 .index SMTP||limiting non-mail commands
12402 Exim counts the number of `non-mail' commands in an SMTP session, and drops the
12403 connection if there are too many. This option defines `too many'. The check
12404 catches some denial-of-service attacks, repeated failing \\AUTH\\s, or a mad
12405 client looping sending \\EHLO\\, for example. The check is applied only if the
12406 client host matches \smtp@_accept@_max@_nonmail@_hosts\.
12408 When a new message is expected, one occurrence of \\RSET\\ is not counted. This
12409 allows a client to send one \\RSET\\ between messages (this is not necessary,
12410 but some clients do it). Exim also allows one uncounted occurence of \\HELO\\
12411 or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After
12412 starting up a TLS session, another \\EHLO\\ is expected, and so it too is not
12413 counted. The first occurrence of \\AUTH\\ in a connection, or immediately
12414 following \\STARTTLS\\ is not counted. Otherwise, all commands other than
12415 \\MAIL\\, \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted.
12417 .conf smtp@_accept@_max@_nonmail@_hosts "host list$**$" $*$
12418 You can control which hosts are subject to the \smtp@_accept@_max@_nonmail\
12419 check by setting this option. The default value makes it apply to all hosts. By
12420 changing the value, you can exclude any badly-behaved hosts that you have to
12424 .conf smtp@_accept@_max@_per@_connection integer 1000
12425 .index SMTP||incoming message count, limiting
12426 .index limit||messages per SMTP connection
12427 The value of this option limits the number of \\MAIL\\ commands that Exim is
12428 prepared to accept over a single SMTP connection, whether or not each command
12429 results in the transfer of a message. After the limit is reached, a 421
12430 response is given to subsequent \\MAIL\\ commands. This limit is a safety
12431 precaution against a client that goes mad (incidents of this type have been
12434 .conf smtp@_accept@_max@_per@_host string$**$ unset
12435 .index limit||SMTP connections from one host
12436 .index host||limiting SMTP connections from
12437 This option restricts the number of simultaneous IP connections from a single
12438 host (strictly, from a single IP address) to the Exim daemon. The option is
12439 expanded, to enable different limits to be applied to different hosts by
12440 reference to \$sender@_host@_address$\. Once the limit is reached, additional
12441 connection attempts from the same host are rejected with error code 421. The
12442 default value of zero imposes no limit. If this option is set, it is required
12443 that \smtp@_accept@_max\ be non-zero.
12445 \**Warning**\: When setting this option you should not use any expansion
12446 constructions that take an appreciable amount of time. The expansion and test
12447 happen in the main daemon loop, in order to reject additional connections
12448 without forking additional processes (otherwise a denial-of-service attack
12449 could cause a vast number or processes to be created). While the daemon is
12450 doing this processing, it cannot accept any other incoming connections.
12453 .conf smtp@_accept@_queue integer 0
12454 .index SMTP||incoming connection count
12455 .index queueing incoming messages
12456 .index message||queueing by SMTP connection count
12457 If the number of simultaneous incoming SMTP calls handled via the listening
12458 daemon exceeds this value, messages received by SMTP are just placed on the
12459 queue; no delivery processes are started automatically. A value of zero implies
12460 no limit, and clearly any non-zero value is useful only if it is less than the
12461 \smtp@_accept@_max\ value (unless that is zero). See also \queue@_only\,
12462 \queue@_only@_load\, \queue@_smtp@_domains\, and the various \-od-\ command
12465 .conf smtp@_accept@_queue@_per@_connection integer 10
12466 .index queueing incoming messages
12467 .index message||queueing by message count
12468 This option limits the number of delivery processes that Exim starts
12469 automatically when receiving messages via SMTP, whether via the daemon or by
12470 the use of \-bs-\ or \-bS-\. If the value of the option is greater than zero,
12471 and the number of messages received in a single SMTP session exceeds this
12472 number, subsequent messages are placed on the queue, but no delivery processes
12473 are started. This helps to limit the number of Exim processes when a server
12474 restarts after downtime and there is a lot of mail waiting for it on other
12475 systems. On large systems, the default should probably be increased, and on
12476 dial-in client systems it should probably be set to zero (that is, disabled).
12478 .conf smtp@_accept@_reserve integer 0
12479 .index SMTP||incoming call count
12480 .index host||reserved
12481 When \smtp@_accept@_max\ is set greater than zero, this option specifies a
12482 number of SMTP connections that are reserved for connections from the hosts
12483 that are specified in \smtp@_reserve@_hosts\. The value set in
12484 \smtp@_accept@_max\ includes this reserve pool. The specified hosts are not
12485 restricted to this number of connections; the option specifies a minimum number
12486 of connection slots for them, not a maximum. It is a guarantee that that group
12487 of hosts can always get at least \smtp@_accept@_reserve\ connections.
12489 For example, if \smtp@_accept@_max\ is set to 50 and \smtp@_accept@_reserve\ is
12490 set to 5, once there are 45 active connections (from any hosts), new
12491 connections are accepted only from hosts listed in \smtp@_reserve@_hosts\.
12492 See also \smtp@_accept@_max@_per@_host\.
12495 .conf smtp@_active@_hostname string$**$ unset
12496 .index host||name in SMTP responses
12497 .index SMTP||host name in responses
12498 This option is provided for multi-homed servers that want to masquerade as
12499 several different hosts. At the start of an SMTP connection, its value is
12500 expanded and used instead of the value of \$primary@_hostname$\ in SMTP
12501 responses. For example, it is used as domain name in the response to an
12502 incoming \\HELO\\ or \\EHLO\\ command. If this option is unset, or if its
12503 expansion is forced to fail, or if the expansion results in an empty string,
12504 the value of \$primary@_hostname$\ is used. Other expansion failures cause a
12505 message to be written to the main and panic logs, and the SMTP command receives
12506 a temporary error. Typically, the value of \smtp@_active@_hostname\ depends on
12507 the incoming interface address. For example:
12509 smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\
12510 {cox.mydomain}{box.mydomain}}
12512 If you set \smtp@_active@_hostname\, you probably also want to set
12513 \smtp@_banner\, since its default value references \$primary@_hostname$\.
12516 .conf smtp@_banner string$**$ "see below"
12517 .index SMTP||welcome banner
12518 .index banner for SMTP
12519 .index welcome banner for SMTP
12520 .index customizing||SMTP banner
12521 This string, which is expanded every time it is used, is output as the initial
12522 positive response to an SMTP connection. The default setting is:
12524 smtp_banner = $primary_hostname ESMTP Exim $version_number \
12527 Failure to expand the string causes a panic error. If you want to create a
12528 multiline response to the initial SMTP connection, use `@\n' in the string at
12529 appropriate points, but not at the end. Note that the 220 code is not included
12530 in this string. Exim adds it automatically (several times in the case of a
12531 multiline response).
12533 .conf smtp@_check@_spool@_space boolean true
12534 .index checking disk space
12535 .index disk space, checking
12536 .index spool directory||checking space
12537 When this option is set, if an incoming SMTP session encounters the \\SIZE\\
12538 option on a \\MAIL\\ command, it checks that there is enough space in the
12539 spool directory's partition to accept a message of that size, while still
12540 leaving free the amount specified by \check@_spool@_space\ (even if that value
12541 is zero). If there isn't enough space, a temporary error code is returned.
12543 .conf smtp@_connect@_backlog integer 20
12544 .index connection backlog
12545 .index SMTP||connection backlog
12546 .index backlog of connections
12547 This option specifies a maximum number of waiting SMTP connections. Exim passes
12548 this value to the TCP/IP system when it sets up its listener. Once this number
12549 of connections are waiting for the daemon's attention, subsequent connection
12550 attempts are refused at the TCP/IP level. At least, that is what the manuals
12551 say; in some circumstances such connection attempts have been observed to time
12552 out instead. For large systems it is probably a good idea to increase the
12553 value (to 50, say). It also gives some protection against denial-of-service
12554 attacks by SYN flooding.
12556 .conf smtp@_enforce@_sync boolean true
12557 .index SMTP||synchronization checking
12558 .index synchronization checking in SMTP
12559 The SMTP protocol specification requires the client to wait for a response from
12560 the server at certain points in the dialogue. Without \\PIPELINING\\ these
12561 synchronization points are after every command; with \\PIPELINING\\ they are
12562 fewer, but they still exist. Some spamming sites send out a complete set of
12563 SMTP commands without waiting for any response. Exim protects against this by
12564 rejecting a message if the client has sent further input when it should not
12565 have. The error response `554 SMTP synchronization error' is sent, and the
12566 connection is dropped. Testing for this error cannot be perfect because of
12567 transmission delays (unexpected input may be on its way but not yet received
12568 when Exim checks). However, it does detect many instances. The check can be
12569 disabled by setting \smtp@_enforce@_sync\ false.
12571 See also \pipelining@_advertise@_hosts\.
12574 .conf smtp@_etrn@_command string$**$ unset
12575 .index \\ETRN\\||command to be run
12576 If this option is set, the given command is run whenever an SMTP \\ETRN\\
12577 command is received from a host that is permitted to issue such commands (see
12578 chapter ~~CHAPACL). The string is split up into separate arguments which are
12579 independently expanded. The expansion variable \$domain$\ is set to the
12580 argument of the \\ETRN\\ command, and no syntax checking is done on it. For
12583 smtp_etrn_command = /etc/etrn_command $domain $sender_host_address
12585 A new process is created to run the command, but Exim does not wait for it to
12586 complete. Consequently, its status cannot be checked. If the command cannot be
12587 run, a line is written to the panic log, but the \\ETRN\\ caller still receives
12588 a 250 success response. Exim is normally running under its own uid when
12589 receiving SMTP, so it is not possible for it to change the uid before running
12592 .conf smtp@_etrn@_serialize boolean true
12593 .index \\ETRN\\||serializing
12594 When this option is set, it prevents the simultaneous execution of more than
12595 one identical command as a result of \\ETRN\\ in an SMTP connection. See
12596 section ~~SECTETRN for details.
12598 .conf smtp@_load@_reserve fixed-point unset
12599 .index load average
12600 If the system load average ever gets higher than this, incoming SMTP calls are
12601 accepted only from those hosts that match an entry in \smtp@_reserve@_hosts\.
12602 If \smtp@_reserve@_hosts\ is not set, no incoming SMTP calls are accepted when
12603 the load is over the limit. The option has no effect on ancient operating
12604 systems on which Exim cannot determine the load average. See also
12605 \deliver@_queue@_load@_max\ and \queue@_only@_load\.
12608 .conf smtp@_max@_synprot@_errors integer 3
12609 .index SMTP||limiting syntax and protocol errors
12610 .index limit||SMTP syntax and protocol errors
12611 Exim rejects SMTP commands that contain syntax or protocol errors. In
12612 particular, a syntactically invalid email address, as in this command:
12614 RCPT TO:<abc xyz@a.b.c>
12616 causes immediate rejection of the command, before any other tests are done.
12617 (The ACL cannot be run if there is no valid address to set up for it.) An
12618 example of a protocol error is receiving \\RCPT\\ before \\MAIL\\. If there are
12619 too many syntax or protocol errors in one SMTP session, the connection is
12620 dropped. The limit is set by this option.
12623 .index \\PIPELINING\\||expected errors
12624 When the \\PIPELINING\\ extension to SMTP is in use, some protocol errors are
12625 `expected', for instance, a \\RCPT\\ command after a rejected \\MAIL\\ command.
12626 Exim assumes that \\PIPELINING\\ will be used if it advertises it (see
12627 \pipelining@_advertise@_hosts\), and in this situation, `expected' errors do
12628 not count towards the limit.
12632 .conf smtp@_max@_unknown@_commands integer 3
12633 .index SMTP||limiting unknown commands
12634 .index limit||unknown SMTP commands
12635 If there are too many unrecognized commands in an incoming SMTP session, an
12636 Exim server drops the connection. This is a defence against some kinds of abuse
12641 into making connections to SMTP ports; in these circumstances, a number of
12642 non-SMTP command lines are sent first.
12645 .conf smtp@_ratelimit@_hosts "host list$**$" unset
12646 .index SMTP||rate limiting
12647 .index limit||rate of message arrival
12648 .index \\RCPT\\||rate limiting
12649 Some sites find it helpful to be able to limit the rate at which certain hosts
12650 can send them messages, and the rate at which an individual message can specify
12651 recipients. When a host matches \smtp@_ratelimit@_hosts\, the values of
12652 \smtp@_ratelimit@_mail\ and \smtp@_ratelimit@_rcpt\ are used to control the
12653 rate of acceptance of \\MAIL\\ and \\RCPT\\ commands in a single SMTP session,
12654 respectively. Each option, if set, must contain a set of four comma-separated
12657 A threshold, before which there is no rate limiting.
12659 An initial time delay. Unlike other times in Exim, numbers with decimal
12660 fractional parts are allowed here.
12662 A factor by which to increase the delay each time.
12664 A maximum value for the delay. This should normally be less than 5 minutes,
12665 because after that time, the client is liable to timeout the SMTP command.
12667 For example, these settings have been used successfully at the site which
12668 first suggested this feature, for controlling mail from their customers:
12670 smtp_ratelimit_mail = 2,0.5s,1.05,4m
12671 smtp_ratelimit_rcpt = 4,0.25s,1.015,4m
12673 The first setting specifies delays that are applied to \\MAIL\\ commands after
12674 two have been received over a single connection. The initial delay is 0.5
12675 seconds, increasing by a factor of 1.05 each time. The second setting applies
12676 delays to \\RCPT\\ commands when more than four occur in a single message.
12678 It is also possible to configure delays explicitly in ACLs. See section
12679 ~~SECTACLmodi for details.
12682 .conf smtp@_ratelimit@_mail string unset
12683 See \smtp@_ratelimit@_hosts\ above.
12685 .conf smtp@_ratelimit@_rcpt string unset
12686 See \smtp@_ratelimit@_hosts\ above.
12688 .conf smtp@_receive@_timeout time 5m
12689 .index timeout||for SMTP input
12690 .index SMTP||timeout, input
12691 This sets a timeout value for SMTP reception. It applies to all forms of SMTP
12692 input, including batch SMTP. If a line of input (either an SMTP command or a
12693 data line) is not received within this time, the SMTP connection is dropped and
12694 the message is abandoned.
12695 A line is written to the log containing one of the following messages:
12697 SMTP command timeout on connection from...
12698 SMTP data timeout on connection from...
12700 The former means that Exim was expecting to read an SMTP command; the latter
12701 means that it was in the \\DATA\\ phase, reading the contents of a message.
12704 .index \-os-\ option
12705 The value set by this option can be overridden by the
12706 \-os-\ command-line option. A setting of zero time disables the timeout, but
12707 this should never be used for SMTP over TCP/IP. (It can be useful in some cases
12708 of local input using \-bs-\ or \-bS-\.) For non-SMTP input, the reception
12709 timeout is controlled by \receive@_timeout\ and \-or-\.
12711 .conf smtp@_reserve@_hosts "host list$**$" unset
12712 This option defines hosts for which SMTP connections are reserved; see
12713 \smtp@_accept@_reserve\ and \smtp@_load@_reserve\ above.
12715 .conf smtp@_return@_error@_details boolean false
12716 .index SMTP||details policy failures
12717 .index policy control||rejection, returning details
12718 In the default state, Exim uses bland messages such as
12719 `Administrative prohibition' when it rejects SMTP commands for policy
12720 reasons. Many sysadmins like this because it gives away little information
12721 to spammers. However, some other syadmins who are applying strict checking
12722 policies want to give out much fuller information about failures. Setting
12723 \smtp@_return@_error@_details\ true causes Exim to be more forthcoming. For
12724 example, instead of `Administrative prohibition', it might give:
12726 550-Rejected after DATA: '>' missing at end of address:
12727 550 failing address in "From" header is: <user@dom.ain
12730 .conf split@_spool@_directory boolean false
12731 .index multiple spool directories
12732 .index spool directory||split
12733 .index directories, multiple
12734 If this option is set, it causes Exim to split its input directory into 62
12735 subdirectories, each with a single alphanumeric character as its name. The
12736 sixth character of the message id is used to allocate messages to
12737 subdirectories; this is the least significant base-62 digit of the time of
12738 arrival of the message.
12740 Splitting up the spool in this way may provide better performance on systems
12741 where there are long mail queues, by reducing the number of files in any one
12742 directory. The msglog directory is also split up in a similar way to the input
12743 directory; however, if \preserve@_message@_logs\ is set, all old msglog files
12744 are still placed in the single directory \(msglog.OLD)\.
12746 It is not necessary to take any special action for existing messages when
12747 changing \split@_spool@_directory\. Exim notices messages that are in the
12748 `wrong' place, and continues to process them. If the option is turned off after
12749 a period of being on, the subdirectories will eventually empty and be
12750 automatically deleted.
12752 When \split@_spool@_directory\ is set, the behaviour of queue runner processes
12753 changes. Instead of creating a list of all messages in the queue, and then
12754 trying to deliver each one in turn, it constructs a list of those in one
12755 sub-directory and tries to deliver them, before moving on to the next
12756 sub-directory. The sub-directories are processed in a random order. This
12757 spreads out the scanning of the input directories, and uses less memory. It is
12758 particularly beneficial when there are lots of messages on the queue. However,
12759 if \queue@_run@_in@_order\ is set, none of this new processing happens. The
12760 entire queue has to be scanned and sorted before any deliveries can start.
12762 .conf spool@_directory string$**$ "set at compile time"
12763 .index spool directory||path to
12764 This defines the directory in which Exim keeps its spool, that is, the messages
12765 it is waiting to deliver. The default value is taken from the compile-time
12766 configuration setting, if there is one. If not, this option must be set. The
12767 string is expanded, so it can contain, for example, a reference to
12768 \$primary@_hostname$\.
12770 If the spool directory name is fixed on your installation, it is recommended
12771 that you set it at build time rather than from this option, particularly if the
12772 log files are being written to the spool directory (see \log@_file@_path\).
12773 Otherwise log files cannot be used for errors that are detected early on, such
12774 as failures in the configuration file.
12776 By using this option to override the compiled-in path, it is possible to run
12777 tests of Exim without using the standard spool.
12779 .conf strip@_excess@_angle@_brackets boolean false
12780 .index angle brackets, excess
12781 If this option is set, redundant pairs of angle brackets round `route-addr'
12782 items in addresses are stripped. For example, \*@<@<xxx@@a.b.c.d@>@>*\ is treated
12783 as \*@<xxx@@a.b.c.d@>*\. If this is in the envelope and the message is passed on
12784 to another MTA, the excess angle brackets are not passed on. If this option is
12785 not set, multiple pairs of angle brackets cause a syntax error.
12787 .conf strip@_trailing@_dot boolean false
12788 .index trailing dot on domain
12789 .index dot||trailing on domain
12790 If this option is set, a trailing dot at the end of a domain in an address is
12791 ignored. If this is in the envelope and the message is passed on to another
12792 MTA, the dot is not passed on. If this option is not set, a dot at the end of a
12793 domain causes a syntax error.
12795 However, addresses in header lines are checked only when an ACL requests header
12799 .conf syslog@_duplication boolean true
12800 .index syslog||duplicate log lines, suppressing
12801 When Exim is logging to syslog, it writes the log lines for its three
12802 separate logs at different syslog priorities so that they can in principle
12803 be separated on the logging hosts. Some installations do not require this
12804 separation, and in those cases, the duplication of certain log lines is a
12805 nuisance. If \syslog@_duplication\ is set false, only one copy of any
12806 particular log line is written to syslog. For lines that normally go to
12807 both the main log and the reject log, the reject log version (possibly
12808 containing message header lines) is written, at \\LOG@_NOTICE\\ priority.
12809 Lines that normally go to both the main and the panic log are written at
12810 the \\LOG@_ALERT\\ priority.
12812 .conf syslog@_facility string unset
12813 .index syslog||facility, setting
12814 This option sets the syslog `facility' name, used when Exim is logging to
12815 syslog. The value must be one of the strings `mail', `user', `news', `uucp',
12816 `daemon', or `local\*x*\' where \*x*\ is a digit between 0 and 7. If this
12817 option is unset, `mail' is used. See chapter ~~CHAPlog for details of Exim's
12821 .conf syslog@_processname string "$tt{exim}"
12822 .index syslog||process name, setting
12823 This option sets the syslog `ident' name, used when Exim is logging to syslog.
12824 The value must be no longer than 32 characters. See chapter ~~CHAPlog for
12825 details of Exim's logging.
12828 .conf syslog@_timestamp boolean true
12829 .index syslog||timestamps
12830 If \syslog@_timestamp\ is set false, the timestamps on Exim's log lines are
12831 omitted when these lines are sent to syslog. See chapter ~~CHAPlog for
12832 details of Exim's logging.
12834 .conf system@_filter string$**$ unset
12835 .index filter||system filter
12836 .index system filter||specifying
12837 .index Sieve filter||not available for system filter
12838 This option specifies an Exim filter file that is applied to all messages at
12839 the start of each delivery attempt, before any routing is done. System filters
12840 must be Exim filters; they cannot be Sieve filters. If the system filter
12841 generates any deliveries to files or pipes, or any new mail messages, the
12842 appropriate \system@_filter@_...@_transport\ option(s) must be set, to define
12843 which transports are to be used. Details of this facility are given in chapter
12844 ~~CHAPsystemfilter.
12846 .conf system@_filter@_directory@_transport string$**$ unset
12847 This sets the name of the transport driver that is to be used when the
12848 \save\ command in a system message filter specifies a path ending in `/',
12849 implying delivery of each message into a separate file in some directory.
12850 During the delivery, the variable \$address@_file$\ contains the path name.
12852 .conf system@_filter@_file@_transport string$**$ unset
12853 .index file||transport for system filter
12854 This sets the name of the transport driver that is to be used when the \save\
12855 command in a system message filter specifies a path not ending in `/'. During
12856 the delivery, the variable \$address@_file$\ contains the path name.
12858 .index gid (group id)||system filter
12859 .conf system@_filter@_group string unset
12860 This option is used only when \system@_filter@_user\ is also set. It sets the
12861 gid under which the system filter is run, overriding any gid that is associated
12862 with the user. The value may be numerical or symbolic.
12864 .conf system@_filter@_pipe@_transport string$**$ unset 7
12865 .index \%pipe%\ transport||for system filter
12866 This specifies the transport driver that is to be used when a \pipe\ command is
12867 used in a system filter. During the delivery, the variable \$address@_pipe$\
12868 contains the pipe command.
12870 .conf system@_filter@_reply@_transport string$**$ unset
12871 .index \%autoreply%\ transport||for system filter
12872 This specifies the transport driver that is to be used when a \mail\ command is
12873 used in a system filter.
12875 .index uid (user id)||system filter
12876 .conf system@_filter@_user string unset
12877 If this option is not set, the system filter is run in the main Exim delivery
12878 process, as root. When the option is set, the system filter runs in a separate
12879 process, as the given user. Unless the string consists entirely of digits, it
12880 is looked up in the password data. Failure to find the named user causes a
12881 configuration error. The gid is either taken from the password data, or
12882 specified by \system@_filter@_group\. When the uid is specified numerically,
12883 \system@_filter@_group\ is required to be set.
12885 If the system filter generates any pipe, file, or reply deliveries, the uid
12886 under which the filter is run is used when transporting them, unless a
12887 transport option overrides.
12888 Normally you should set \system@_filter@_user\ if your system filter generates
12889 these kinds of delivery.
12891 .conf tcp@_nodelay boolean true
12892 .index daemon||\\TCP@_NODELAY\\ on sockets
12893 .index Nagle algorithm
12894 .index \\TCP@_NODELAY\\ on listening sockets
12895 If this option is set false, it stops the Exim daemon setting the
12896 \\TCP@_NODELAY\\ option on its listening sockets. Setting \\TCP@_NODELAY\\
12897 turns off the `Nagle algorithm', which is a way of improving network
12898 performance in interactive (character-by-character) situations. Turning it off
12899 should improve Exim's performance a bit, so that is what happens by default.
12900 However, it appears that some broken clients cannot cope, and time out. Hence
12901 this option. It affects only those sockets that are set up for listening by the
12902 daemon. Sockets created by the smtp transport for delivering mail always set
12905 .conf timeout@_frozen@_after time 0s
12906 .index frozen messages||timing out
12907 .index timeout||frozen messages
12908 If \timeout@_frozen@_after\ is set to a time greater than zero, a frozen
12909 message of any kind that has been on the queue for longer than the given
12910 time is automatically cancelled at the next queue run. If it is a bounce
12911 message, it is just discarded; otherwise, a bounce is sent to the sender, in a
12912 similar manner to cancellation by the \-Mg-\ command line option. If you want
12913 to timeout frozen bounce messages earlier than other kinds of frozen message,
12914 see \ignore@_bounce@_errors@_after\.
12916 .conf timezone string unset
12917 .index timezone, setting
12918 The value of \timezone\ is used to set the environment variable \\TZ\\ while
12919 running Exim (if it is different on entry). This ensures that all timestamps
12920 created by Exim are in the required timezone. If you want all your timestamps
12921 to be in UTC (aka GMT) you should set
12925 The default value is taken from \\TIMEZONE@_DEFAULT\\ in \(Local/Makefile)\,
12926 or, if that is not set, from the value of the TZ environment variable when Exim
12927 is built. If \timezone\ is set to the empty string, either at build or run
12928 time, any existing \\TZ\\ variable is removed from the environment when Exim
12929 runs. This is appropriate behaviour for obtaining wall-clock time on some, but
12930 unfortunately not all, operating systems.
12932 .conf tls@_advertise@_hosts "host list$**$" unset
12933 .index TLS||advertising
12934 .index encryption||on SMTP connection
12935 .index SMTP||encrypted connection
12936 When Exim is built with support for TLS encrypted connections, the availability
12937 of the \\STARTTLS\\ command to set up an encrypted session is advertised in
12938 response to \\EHLO\\ only to those client hosts that match this option. See
12939 chapter ~~CHAPTLS for details of Exim's support for TLS.
12941 .conf tls@_certificate string$**$ unset
12942 .index TLS||server certificate, location of
12943 .index certificate||for server, location of
12944 The value of this option is expanded, and must then be the absolute path to a
12945 file which contains the server's certificates. The server's private key is also
12946 assumed to be in this file if \tls@_privatekey\ is unset. See chapter ~~CHAPTLS
12947 for further details.
12949 \**Note**\: The certificates defined by this option are used only when Exim is
12950 receiving incoming messages as a server. If you want to supply certificates for
12951 use when sending messages as a client, you must set the \tls@_certificate\
12952 option in the relevant \%smtp%\ transport.
12955 .conf tls@_crl string$**$ unset
12956 .index TLS||server certificate revocation list
12957 .index certificate||revocation list for server
12958 This option specifies a certificate revocation list. The expanded value must
12959 be the name of a file that contains a CRL in PEM format.
12962 .conf tls@_dhparam string$**$ unset
12963 .index TLS||D-H parameters for server
12964 The value of this option is expanded, and must then be the absolute path to
12965 a file which contains the server's DH parameter values.
12966 This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is
12967 ignored. See section ~~SECTopenvsgnu for further details.
12969 .conf tls@_privatekey string$**$ unset
12970 .index TLS||server private key, location of
12971 The value of this option is expanded, and must then be the absolute path to
12972 a file which contains the server's private key.
12973 If this option is unset, the private key is assumed to be in the same file as
12974 the server's certificates. See chapter ~~CHAPTLS for further details.
12976 .conf tls@_remember@_esmtp boolean false
12977 .index TLS||esmtp state, remembering
12978 .index TLS||broken clients
12979 If this option is set true, Exim violates the RFCs by remembering that it is in
12980 `esmtp' state after successfully negotiating a TLS session. This provides
12981 support for broken clients that fail to send a new \\EHLO\\ after starting a
12985 .conf tls@_require@_ciphers string$**$ unset
12986 .index TLS||requiring specific ciphers
12987 .index cipher||requiring specific
12988 This option controls which ciphers can be used for incoming TLS connections.
12989 (The \%smtp%\ transport has an option of the same name for controlling outgoing
12990 connections.) This option is expanded for each connection, so can be varied for
12991 different clients if required. The value of this option must be a list of
12992 permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
12993 in somewhat different ways. Details are given in section ~~SECTreqciphsslgnu.
12996 .conf tls@_try@_verify@_hosts "host list$**$" unset
12997 .index TLS||client certificate verification
12998 .index certificate||verification of client
12999 See \tls@_verify@_hosts\ below.
13001 .conf tls@_verify@_certificates string$**$ unset
13002 .index TLS||client certificate verification
13003 .index certificate||verification of client
13004 The value of this option is expanded, and must then be the absolute path to
13005 a file containing permitted certificates for clients that
13006 match \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\. Alternatively, if you
13007 are using OpenSSL, you can set \tls@_verify@_certificates\ to the name of a
13008 directory containing certificate files. This does not work with GnuTLS; the
13009 option must be set to the name of a single file if you are using GnuTLS.
13011 .conf tls@_verify@_hosts "host list$**$" unset
13012 .index TLS||client certificate verification
13013 .index certificate||verification of client
13014 This option, along with \tls@_try@_verify@_hosts\, controls the checking of
13015 certificates from clients.
13016 The expected certificates are defined by \tls@_verify@_certificates\, which
13017 must be set. A configuration error occurs if either \tls@_verify@_hosts\ or
13018 \tls@_try@_verify@_hosts\ is set and \tls@_verify@_certificates\ is not set.
13020 Any client that matches \tls@_verify@_hosts\ is constrained by
13021 \tls@_verify@_certificates\. The client must present one of the listed
13022 certificates. If it does not, the connection is aborted.
13024 A weaker form of checking is provided by \tls@_try@_verify@_hosts\. If a client
13025 matches this option (but not \tls@_verify@_hosts\), Exim requests a
13026 certificate and checks it against \tls@_verify@_certificates\, but does not
13027 abort the connection if there is no certificate or if it does not match. This
13028 state can be detected in an ACL, which makes it possible to implement policies
13029 such as `accept for relay only if a verified certificate has been received, but
13030 accept for local delivery if encrypted, even without a verified certificate'.
13032 Client hosts that match neither of these lists are not asked to present
13035 .conf trusted@_groups "string list" unset
13036 .index trusted group
13037 .index group||trusted
13038 If this option is set, any process that is running in one of the listed groups,
13039 or which has one of them as a supplementary group, is trusted.
13040 The groups can be specified numerically or by name.
13041 See section ~~SECTtrustedadmin for details of what trusted callers are
13042 permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only
13043 root and the Exim user are trusted.
13045 .conf trusted@_users "string list" unset
13046 .index trusted user
13047 .index user||trusted
13048 If this option is set, any process that is running as one of the listed users
13050 The users can be specified numerically or by name.
13051 See section ~~SECTtrustedadmin for details of what trusted callers are
13052 permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only
13053 root and the Exim user are trusted.
13055 .index uid (user id)||unknown caller
13056 .conf unknown@_login string$**$ unset
13057 This is a specialized feature for use in unusual configurations. By default, if
13058 the uid of the caller of Exim cannot be looked up using \*getpwuid()*\, Exim
13059 gives up. The \unknown@_login\ option can be used to set a login name to be
13060 used in this circumstance. It is expanded, so values like \user@$caller@_uid\
13061 can be set. When \unknown@_login\ is used, the value of \unknown@_username\ is
13062 used for the user's real name (gecos field), unless this has been set by the
13065 .conf unknown@_username string unset
13066 See \unknown@_login\.
13068 .conf untrusted@_set@_sender "address list$**$" unset
13069 .index trusted user
13070 .index sender||setting by untrusted user
13071 .index untrusted user, setting sender
13072 .index user||untrusted setting sender
13073 .index envelope sender
13074 When an untrusted user submits a message to Exim using the standard input, Exim
13075 normally creates an envelope sender address from the user's login and the
13076 default qualification domain. Data from the \-f-\ option (for setting envelope
13077 senders on non-SMTP messages) or the SMTP \\MAIL\\ command (if \-bs-\ or \-bS-\
13078 is used) is ignored.
13080 However, untrusted users are permitted to set an empty envelope sender address,
13081 to declare that a message should never generate any bounces. For example:
13083 exim -f '<>' user@domain.example
13085 The \untrusted@_set@_sender\ option allows you to permit untrusted users to set
13086 other envelope sender addresses in a controlled way. When it is set, untrusted
13087 users are allowed to set envelope sender addresses that match any of the
13088 patterns in the list. Like all address lists, the string is expanded. The
13089 identity of the user is in \$sender@_ident$\, so you can, for example, restrict
13090 users to setting senders that start with their login ids
13091 followed by a hyphen
13092 by a setting like this:
13094 untrusted_set_sender = ^$sender_ident-
13096 If you want to allow untrusted users to set envelope sender addresses without
13097 restriction, you can use
13099 untrusted_set_sender = *
13101 The \untrusted@_set@_sender\ option applies to all forms of local input, but
13102 only to the setting of the envelope sender. It does not permit untrusted users
13103 to use the other options which trusted user can use to override message
13104 parameters. Furthermore, it does not stop Exim from removing an existing
13105 ::Sender:: header in the message, or from adding a ::Sender:: header if
13106 necessary. See \local__sender__retain\ and \local@_from@_check\ for ways of
13107 overriding these actions. The handling of the ::Sender:: header is also
13108 described in section ~~SECTthesenhea.
13110 The log line for a message's arrival shows the envelope sender following `<='.
13111 For local messages, the user's login always follows, after `U='. In \-bp-\
13112 displays, and in the Exim monitor, if an untrusted user sets an envelope sender
13113 address, the user's login is shown in parentheses after the sender address.
13115 .conf uucp@_from@_pattern string "see below"
13117 .index UUCP||`From' line
13118 Some applications that pass messages to an MTA via a command line interface use
13119 an initial line starting with `From' to pass the envelope sender. In
13120 particular, this is used by UUCP software. Exim recognizes such a line by means
13121 of a regular expression that is set in \uucp@_from@_pattern\. When the pattern
13122 matches, the sender address is constructed by expanding the contents of
13123 \uucp@_from@_sender\, provided that the caller of Exim is a trusted user. The
13124 default pattern recognizes lines in the following two forms:
13126 From ph10 Fri Jan 5 12:35 GMT 1996
13127 From ph10 Fri, 7 Jan 97 14:00:00 GMT
13129 The pattern can be seen by running
13131 exim -bP uucp_from_pattern
13133 It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit
13134 year in the second case. The first word after `From' is matched in the regular
13135 expression by a parenthesized subpattern. The default value for
13136 \uucp@_from@_sender\ is `$1', which therefore just uses this first word (`ph10'
13137 in the example above) as the message's sender. See also
13138 \ignore@_fromline@_hosts\.
13140 .conf uucp@_from@_sender string$**$ "$tt{@$1}"
13141 See \uucp@_from@_pattern\ above.
13143 .conf warn@_message@_file string unset
13144 .index warning of delay||customizing the message
13145 .index customizing||warning message
13146 This option defines a template file containing paragraphs of text to be used
13147 for constructing the warning message which is sent by Exim when a message has
13148 been on the queue for a specified amount of time, as specified by
13149 \delay@_warning\. Details of the file's contents are given in chapter
13150 ~~CHAPemsgcust. See also \bounce@_message@_file\.
13153 .conf write@_rejectlog boolean true
13154 .index reject log||disabling
13155 If this option is set false, Exim no longer writes anything to the reject log.
13156 See chapter ~~CHAPlog for details of what Exim writes to its logs.
13167 . ============================================================================
13168 .chapter Generic options for routers
13169 .rset CHAProutergeneric "~~chapter"
13170 .set runningfoot "generic router options"
13171 .index options||generic, for routers
13172 .index generic options||router
13174 This chapter describes the generic options that apply to all routers,
13175 identifying those that are preconditions. For a general description of how a
13176 router operates, see sections ~~SECTrunindrou and ~~SECTrouprecon. The second
13177 of these sections specifies the order in which the preconditions are tested.
13178 The order of expansion of the options that provide data for a transport is:
13179 \errors@_to\, \headers@_add\, \headers@_remove\, \transport\.
13183 .conf address@_data string$**$ unset
13184 .index router||data attached to address
13185 The string is expanded just before the router is run, that is, after all the
13186 precondition tests have succeeded. If the expansion is forced to fail, the
13187 router declines. Other expansion failures cause delivery of the address to be
13190 When the expansion succeeds, the value is retained with the address, and can be
13191 accessed using the variable \$address@_data$\ in the current router, subsequent
13192 routers, and the eventual transport.
13194 \**Warning**\: if the current or any subsequent router is a \%redirect%\ router
13195 that runs a user's filter file, the contents of \$address@_data$\ are
13196 accessible in the filter. This is not normally a problem, because such data is
13197 usually either not confidential or it `belongs' to the current user, but if you
13198 do put confidential data into \$address@_data$\ you need to remember this
13201 Even if the router declines or passes, the value of \$address@_data$\ remains
13202 with the address, though it can be changed by another \address@_data\ setting
13203 on a subsequent router. If a router generates child addresses, the value of
13204 \$address@_data$\ propagates to them. This also applies to the special kind of
13205 `child' that is generated by a router with the \unseen\ option.
13207 The idea of \address@_data\ is that you can use it to look up a lot of data for
13208 the address once, and then pick out parts of the data later. For example, you
13209 could use a single LDAP lookup to return a string of the form
13211 uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
13213 In the transport you could pick out the mailbox by a setting such as
13215 file = ${extract{mailbox}{$address_data}}
13217 This makes the configuration file less messy, and also reduces the number of
13218 lookups. (Exim does cache the most recent lookup, but there may be several
13219 addresses in a message which cause lookups to occur.)
13221 The \address@_data\ facility is also useful as a means of passing information
13222 from one router to another,
13223 and from a router to a transport. In addition, if \address@_data\ is set by a
13224 router when verifying an address from an ACL, its value is available for use in
13225 the rest of the ACL statement.
13228 .conf address@_test "boolean (precondition)" true
13229 .index \-bt-\ option
13230 .index router||skipping when address testing
13231 If this option is set false, the router is skipped when routing is being tested
13232 by means of the \-bt-\ command line option. This can be a convenience when your
13233 first router sends messages to an external scanner, because it saves you
13234 having to set the `already scanned' indicator when testing real address
13238 .conf cannot@_route@_message string$**$ unset
13239 .index router||customizing `cannot route' message
13240 .index customizing||`cannot route' message
13241 This option specifies a text message that is used when an address cannot be
13242 routed because Exim has run out of routers. The default message is `Unrouteable
13243 address'. This option is useful only on routers that have \more\ set false, or
13244 on the very last router in a configuration, because the value that is used is
13245 taken from the last router that inspects an address. For example, using the
13246 default configuration, you could put:
13248 cannot_route_message = Remote domain not found in DNS
13250 on the first (\%dnslookup%\) router, and
13252 cannot_route_message = Unknown local user
13254 on the final router that checks for local users. If string expansion fails, the
13255 default message is used.
13256 Unless the expansion failure was explicitly forced, a message about the failure
13257 is written to the main and panic logs, in addition to the normal message about
13258 the routing failure.
13260 .conf caseful@_local@_part boolean false
13261 .index case of local parts
13262 .index router||case of local parts
13263 By default, routers handle the local parts of addresses in a case-insensitive
13264 manner, though the actual case is preserved for transmission with the message.
13265 If you want the case of letters to be significant in a router, you must set
13266 this option true. For individual router options that contain address or local
13267 part lists (for example, \local@_parts\), case-sensitive matching can be turned
13268 on by `+caseful' as a list item. See section ~~SECTcasletadd for more details.
13271 .conf check@_local@_user "boolean (precondition)" false
13272 .index local user, checking in router
13273 .index router||checking for local user
13274 When this option is true, Exim checks that the local part of the recipient
13275 address (with affixes removed if relevant) is the name of an account on the
13276 local system. The check is done by calling the \*getpwnam()*\ function rather
13277 than trying to read \(/etc/passwd)\ directly. This means that other methods of
13278 holding password data (such as NIS) are supported. If the local part is a local
13279 user, \$home$\ is set from the password data, and can be tested in other
13280 preconditions that are evaluated after this one
13281 (the order of evaluation is given in section ~~SECTrouprecon). However, the
13282 value of \$home$\ can be overridden by \router@_home@_directory\.
13283 If the local part is not a local user, the router is skipped.
13285 If you want to check that the local part is either the name of a local user
13286 or matches something else, you cannot combine \check@_local@_user\ with a
13287 setting of \local@_parts\, because that specifies the logical \*and*\ of the
13288 two conditions. However, you can use a \%passwd%\ lookup in a \local@_parts\
13289 setting to achieve this. For example:
13291 local_parts = passwd;$local_part : lsearch;/etc/other/users
13293 Note, however, that the side effects of \check@_local@_user\ (such as setting
13294 up a home directory) do not occur when a \%passwd%\ lookup is used in a
13295 \local@_parts\ (or any other) precondition.
13297 .conf condition "string$**$ (precondition)" unset
13298 .index router||customized precondition
13299 This option specifies a general precondition test that has to succeed for the
13300 router to be called. The string is expanded, and if the result is a forced
13301 failure or an empty string or one of the strings `0' or `no' or `false'
13302 (checked without regard to the case of the letters), the router is skipped, and
13303 the address is offered to the next one. This provides a means of applying
13304 special-purpose conditions to the running of routers.
13306 If the expansion fails (other than forced failure) delivery is deferred. Some
13307 of the other options below are common special cases that could in fact be
13308 specified using \condition\.
13309 Note that \condition\ is the last precondition to be evaluated (see
13310 section ~~SECTrouprecon).
13313 .conf debug@_print string$**$ unset
13314 .index testing||variables in drivers
13315 If this option is set and debugging is enabled (see the \-d-\ command line
13316 option), the string is expanded and included in the debugging output.
13317 If expansion of the string fails, the error message is written to the debugging
13318 output, and Exim carries on processing.
13319 This option is provided to help with checking out the values of variables and
13320 so on when debugging router configurations. For example, if a \condition\
13321 option appears not to be working, \debug@_print\ can be used to output the
13322 variables it references. The output happens after checks for \domains\,
13323 \local@_parts\, and \check@_local@_user\ but before any other preconditions are
13324 tested. A newline is added to the text if it does not end with one.
13327 .conf disable@_logging boolean false
13328 If this option is set true, nothing is logged for any routing errors
13330 or for any deliveries caused by this router. You should not set this option
13331 unless you really, really know what you are doing. See also the generic
13332 transport option of the same name.
13335 .conf domains "domain list$**$ (precondition)" unset
13336 .index router||restricting to specific domains
13337 If this option is set, the router is skipped unless the current domain matches
13338 the list. If the match is achieved by means of a file lookup, the data that the
13339 lookup returned for the domain is placed in \$domain@_data$\ for use in string
13340 expansions of the driver's private options.
13341 See section ~~SECTrouprecon for a list of the order in which preconditions
13345 .conf driver string unset
13346 This option must always be set. It specifies which of the available routers is
13350 .conf errors@_to string$**$ unset
13351 .index envelope sender
13352 .index router||changing address for errors
13353 If a router successfully handles an address, it may queue the address for
13354 delivery or it may generate child addresses. In both cases, if there is a
13355 delivery problem during later processing, the resulting bounce message is sent
13356 to the address that results from expanding this string, provided that the
13357 address verifies successfully.
13358 \errors@_to\ is expanded before \headers@_add\, \headers@_remove\, and
13361 If the option is unset, or the expansion is forced to fail, or the result of
13362 the expansion fails to verify, the errors address associated with the incoming
13363 address is used. At top level, this is the envelope sender. A non-forced
13364 expansion failure causes delivery to be deferred.
13366 If an address for which \errors@_to\ has been set ends up being delivered over
13367 SMTP, the envelope sender for that delivery is the \errors@_to\ value, so that
13368 any bounces that are generated by other MTAs on the delivery route are also
13369 sent there. The most common use of \errors@_to\ is probably to direct mailing
13370 list bounces to the manager of the list, as described in section
13371 ~~SECTmailinglists.
13373 The \errors@_to\ setting associated with an address can be overridden if it
13374 subsequently passes through other routers that have their own \errors@_to\
13376 or if it is delivered by a transport with a \return@_path\ setting.
13378 You can set \errors@_to\ to the empty string by either of these settings:
13383 An expansion item that yields an empty string has the same effect. If you do
13384 this, a locally detected delivery error for addresses processed by this router
13385 no longer gives rise to a bounce message; the error is discarded. If the
13386 address is delivered to a remote host, the return path is set to \"<>"\, unless
13387 overridden by the \return@_path\ option on the transport.
13389 If for some reason you want to discard local errors, but use a non-empty
13390 \\MAIL\\ command for remote delivery, you can preserve the original return
13391 path in \$address@_data$\ in the router, and reinstate it in the transport by
13392 setting \return@_path\.
13395 .conf expn "boolean (precondition)" true
13396 .index address||testing
13397 .index testing||addresses
13398 .index \\EXPN\\||router skipping
13399 .index router||skipping for \\EXPN\\
13400 If this option is turned off, the router is skipped when testing an address
13401 as a result of processing an SMTP \\EXPN\\ command. You might, for example,
13402 want to turn it off on a router for users' \(.forward)\ files, while leaving it
13403 on for the system alias file.
13404 See section ~~SECTrouprecon for a list of the order in which preconditions
13407 The use of the SMTP \\EXPN\\ command is controlled by an ACL (see chapter
13408 ~~CHAPACL). When Exim is running an \\EXPN\\ command, it is similar to testing
13409 an address with \-bt-\. Compare \\VRFY\\, whose counterpart is \-bv-\.
13412 .conf fail@_verify boolean false
13413 .index router||forcing verification failure
13414 Setting this option has the effect of setting both \fail@_verify@_sender\ and
13415 \fail@_verify@_recipient\ to the same value.
13418 .conf fail@_verify@_recipient boolean false
13419 If this option is true and an address is accepted by this router when
13420 verifying a recipient, verification fails.
13423 .conf fail@_verify@_sender boolean false
13424 If this option is true and an address is accepted by this router when
13425 verifying a sender, verification fails.
13428 .conf fallback@_hosts "string list" unset
13429 .index router||fallback hosts
13430 .index fallback||hosts specified on router
13431 String expansion is not applied to this option. The argument must be a
13432 colon-separated list of host names or IP addresses. If a router queues an
13433 address for a remote transport, this host list is associated with the address,
13434 and used instead of the transport's fallback host list. If \hosts@_randomize\
13435 is set on the transport, the order of the list is randomized for each use. See
13436 the \fallback@_hosts\ option of the \%smtp%\ transport for further details.
13438 .conf group string$**$ "see below"
13439 .index gid (group id)||local delivery
13440 .index local transports||uid and gid
13441 .index transport||local
13442 .index router||setting group
13443 When a router queues an address for a transport, and the transport does not
13444 specify a group, the group given here is used when running the delivery
13446 The group may be specified numerically or by name. If expansion fails, the
13447 error is logged and delivery is deferred.
13448 The default is unset, unless \check@_local@_user\ is set, when the default
13449 is taken from the password information. See also \initgroups\ and \user\ and
13450 the discussion in chapter ~~CHAPenvironment.
13453 .conf headers@_add string$**$ unset
13454 .index header lines||adding
13455 .index router||adding header lines
13456 This option specifies a string of text that is expanded at routing time, and
13457 associated with any addresses that are processed by the router
13458 when delivering a message. This option has no effect when an address is just
13461 The \headers@_add\ option is expanded after \errors@_to\, but before
13462 \headers@_remove\ and \transport\.
13463 If the expanded string is empty, or if the expansion is forced to fail, the
13464 option has no effect. Other expansion failures are treated as configuration
13465 errors. The expanded string must be in the form of one or more RFC 2822 header
13466 lines, separated by newlines (coded as `@\n'). For example:
13468 headers_add = X-added-header: added by $primary_hostname\n\
13469 X-added-second: another added header line
13471 Exim does not check the syntax of these added header lines. If an address
13472 passes through several routers as a result of aliasing or forwarding
13473 operations, any \headers@_add\ or \headers@_remove\ specifications are
13474 cumulative. This does not apply for multiple routers that result from the use
13477 At transport time, all the original headers listed in \headers__remove\ are
13478 removed. If there are multiple instances of any listed header, they are all
13480 Then the new headers specified by \headers@_add\ are added, in the order in
13481 which they were attached to the address. Finally, any additional headers
13482 specified by the transport are added. It is not possible to remove headers
13483 added to an address by \headers@_add\.
13485 Because the addition does not happen until transport time, header lines that
13486 are added by \headers@_add\ are not accessible by means of the \$header@_xxx$\
13487 expansion syntax. Conversely, header lines that are removed by
13488 \headers@_remove\ remain visible.
13490 Addresses with different \headers@_add\ or \headers@_remove\ settings cannot be
13491 delivered together in a batch. The \headers@_add\ option cannot be used for a
13492 \%redirect%\ router that has the \one@_time\ option set.
13495 .conf headers@_remove string$**$ unset
13496 .index header lines||removing
13497 .index router||removing header lines
13498 The string is expanded at routing time and is then associated with any
13499 addresses that are processed by the router when delivering a message. This
13500 option has no effect when an address is being verified. The \headers@_remove\
13501 option is expanded after \errors@_to\ and \headers@_add\, but before
13502 \transport\. If the expansion is forced to fail, the option has no effect.
13503 Other expansion failures are treated as configuration errors.
13506 After expansion, the string must consist of a colon-separated list of header
13507 names. This is confusing, because header names themselves are often terminated
13508 by colons. In this case, the colons are the list separators, not part of the
13513 headers_remove = return-receipt-to:acknowledge-to
13515 The list is used at transport time as described under \headers@_add\ above. The
13516 \headers@_remove\ option cannot be used for a \%redirect%\ router that has the
13517 \one@_time\ option set.
13519 .conf ignore@_target@_hosts "host list$**$" unset
13520 .index IP address||discarding
13521 .index router||discarding IP addresses
13522 Although this option is a host list, it should normally contain IP address
13523 entries rather than names. If any host that is looked up by the router has an
13524 IP address that matches an item in this list, Exim behaves as if that IP
13525 address did not exist. This option allows you to cope with rogue DNS entries
13528 remote.domain.example. A 127.0.0.1
13532 ignore_target_hosts = 127.0.0.1
13534 on the relevant router.
13536 If all the hosts found by a \%dnslookup%\ router are discarded in this way, the
13537 router declines. In a conventional configuration, an attempt to mail to such a
13538 domain would then normally provoke the `unrouteable domain' error, and an
13539 attempt to verify an address in the domain would fail.
13541 Similarly, if \ignore@_target@_hosts\ is set on an \%ipliteral%\ router, the
13542 router declines if presented with one of the listed addresses.
13545 This option may also be useful for ignoring link-local and site-local IPv6
13546 addresses. Because, like all host lists, the value of \ignore@_target@_hosts\
13547 is expanded before use as a list, it is possible to make it dependent on the
13548 domain that is being routed.
13552 .index additional groups
13553 .index groups, additional
13554 .index local transports||uid and gid
13555 .index transport||local
13556 .conf initgroups boolean false
13557 If the router queues an address for a transport, and this option is true, and
13558 the uid supplied by the router is not overridden by the transport, the
13559 \*initgroups()*\ function is called when running the transport to ensure that
13560 any additional groups associated with the uid are set up. See also \group\ and
13561 \user\ and the discussion in chapter ~~CHAPenvironment.
13564 .conf local@_part@_prefix "string list (precondition)" unset
13565 .index router||prefix for local part
13566 .index prefix||for local part, used in router
13567 If this option is set, the router is skipped unless the local part
13568 starts with one of the given strings, or \local@_part@_prefix@_optional\ is
13570 See section ~~SECTrouprecon for a list of the order in which preconditions
13573 The list is scanned from left to right, and the first prefix that matches is
13574 used. A limited form of wildcard is available; if the prefix begins with an
13575 asterisk, it matches the longest possible sequence of arbitrary characters at
13576 the start of the local part. An asterisk should therefore always be followed by
13577 some character that does not occur in normal local parts.
13578 .index multiple mailboxes
13579 .index mailbox||multiple
13580 Wildcarding can be used to set up multiple user mailboxes, as described in
13581 section ~~SECTmulbox.
13583 During the testing of the \local@_parts\ option, and while the router is
13584 running, the prefix is removed from the local part, and is available in the
13585 expansion variable \$local@_part@_prefix$\. If the router accepts the address,
13586 this remains true during subsequent delivery.
13587 In particular, the local part that is transmitted in the \\RCPT\\ command
13588 for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. This
13589 behaviour can be overridden by setting \rcpt@_include@_affixes\ true on the
13590 relevant transport.
13592 The prefix facility is commonly used to handle local parts of the form
13593 \owner-something\. Another common use is to support local parts of the form
13594 \real-username\ to bypass a user's \(.forward)\ file -- helpful when trying to
13595 tell a user their forwarding is broken -- by placing a router like this one
13596 immediately before the router that handles \(.forward)\ files:
13600 local_part_prefix = real-
13602 transport = local_delivery
13604 If both \local@_part@_prefix\ and \local@_part@_suffix\ are set for a router,
13605 both conditions must be met if not optional. Care must be taken if wildcards
13606 are used in both a prefix and a suffix on the same router. Different
13607 separator characters must be used to avoid ambiguity.
13609 .conf local@_part@_prefix@_optional boolean false
13610 See \local@_part@_prefix\ above.
13613 .conf local@_part@_suffix "string list (precondition)" unset
13614 .index router||suffix for local part
13615 .index suffix for local part, used in router
13616 This option operates in the same way as \local@_part@_prefix\, except that the
13617 local part must end (rather than start) with the given string, the
13618 \local@_part@_suffix@_optional\ option determines whether the suffix is
13619 mandatory, and the wildcard $*$ character, if present, must be the last
13620 character of the suffix. This option facility is commonly used to handle local
13621 parts of the form \something-request\ and multiple user mailboxes of the form
13624 .conf local@_part@_suffix@_optional boolean false
13625 See \local@_part@_suffix\ above.
13628 .conf local@_parts "local part list$**$ (precondition)" unset
13629 .index router||restricting to specific local parts
13630 .index local part||checking in router
13631 The router is run only if the local part of the address matches the list.
13632 See section ~~SECTrouprecon for a list of the order in which preconditions
13634 section ~~SECTlocparlis for a discussion of local part lists. Because the
13635 string is expanded, it is possible to make it depend on the domain, for
13638 local_parts = dbm;/usr/local/specials/$domain
13640 If the match is achieved by a lookup, the data that the lookup returned
13641 for the local part is placed in the variable \$local@_part@_data$\ for use in
13642 expansions of the router's private options. You might use this option, for
13643 example, if you have a large number of local virtual domains, and you want to
13644 send all postmaster mail to the same place without having to set up an alias in
13645 each virtual domain:
13649 local_parts = postmaster
13650 data = postmaster@real.domain.example
13654 .conf log@_as@_local boolean "see below"
13655 .index log||delivery line
13656 .index delivery||log line format
13657 Exim has two logging styles for delivery, the idea being to make local
13658 deliveries stand out more visibly from remote ones. In the `local' style, the
13659 recipient address is given just as the local part, without a domain. The use of
13660 this style is controlled by this option. It defaults to true for the \%accept%\
13661 router, and false for all the others.
13664 .conf more boolean$**$ true
13665 The result of string expansion for this option must be a valid boolean value,
13666 that is, one of the strings `yes', `no', `true', or `false'. Any other result
13667 causes an error, and delivery is deferred. If the expansion is forced to fail,
13668 the default value for the option (true) is used. Other failures cause delivery
13671 If this option is set false, and the router is run, but declines to handle the
13672 address, no further routers are tried, routing fails, and the address is
13674 .index \self\ option
13675 However, if the router explicitly passes an address to the following router by
13676 means of the setting
13680 or otherwise, the setting of \more\ is ignored. Also, the setting of \more\
13681 does not affect the behaviour if one of the precondition tests fails. In that
13682 case, the address is always passed to the next router.
13685 .conf pass@_on@_timeout boolean false
13686 .index timeout||of router
13687 .index router||timeout
13688 If a router times out during a host lookup, it normally causes deferral of the
13689 address. If \pass@_on@_timeout\ is set, the address is passed on to the next
13690 router, overriding \no@_more\. This may be helpful for systems that are
13691 intermittently connected to the Internet, or those that want to pass to a smart
13692 host any messages that cannot immediately be delivered.
13694 There are occasional other temporary errors that can occur while doing DNS
13695 lookups. They are treated in the same way as a timeout, and this option
13696 applies to all of them.
13699 .conf pass@_router string unset
13700 .index router||go to after `pass'
13701 When a router returns `pass', the address is normally handed on to the next
13702 router in sequence. This can be changed by setting \pass@_router\ to the name
13703 of another router. However (unlike \redirect@_router\) the named router must be
13704 below the current router, to avoid loops. Note that this option applies only to
13705 the special case of `pass'. It does not apply when a router returns `decline'.
13708 .conf redirect@_router string unset
13709 .index router||start at after redirection
13710 Sometimes an administrator knows that it is pointless to reprocess addresses
13711 generated from alias or forward files with the same router again. For
13712 example, if an alias file translates real names into login ids there is no
13713 point searching the alias file a second time, especially if it is a large file.
13715 The \redirect@_router\ option can be set to the name of any router instance. It
13716 causes the routing of any generated addresses to start at the named router
13717 instead of at the first router. This option has no effect if the router in
13718 which it is set does not generate new addresses.
13721 .conf require@_files "string list$**$ (precondition)" unset
13722 .index file||requiring for router
13723 .index router||requiring file existence
13724 This option provides a general mechanism for predicating the running of a
13725 router on the existence or non-existence of certain files or directories.
13726 Before running a router, as one of its precondition tests, Exim works its way
13727 through the \require@_files\ list, expanding each item separately.
13729 Because the list is split before expansion, any colons in expansion items must
13730 be doubled, or the facility for using a different list separator must be used.
13731 If any expansion is forced to fail, the item is ignored. Other expansion
13732 failures cause routing of the address to be deferred.
13734 If any expanded string is empty, it is ignored. Otherwise, except as described
13735 below, each string must be a fully qualified file path, optionally preceded by
13736 `!'. The paths are passed to the \*stat()*\ function to test for the existence
13737 of the files or directories. The router is skipped if any paths not preceded by
13738 `!' do not exist, or if any paths preceded by `!' do exist.
13741 If \*stat()*\ cannot determine whether a file exists or not, delivery of
13742 the message is deferred. This can happen when NFS-mounted filesystems are
13745 This option is checked after the \domains\, \local@_parts\, and \senders\
13746 options, so you cannot use it to check for the existence of a file in which to
13747 look up a domain, local part, or sender. (See section ~~SECTrouprecon for a
13748 full list of the order in which preconditions are evaluated.) However, as
13749 these options are all expanded, you can use the \exists\ expansion condition to
13750 make such tests. The \require@_files\ option is intended for checking files
13751 that the router may be going to use internally, or which are needed by a
13752 transport (for example \(.procmailrc)\).
13754 During delivery, the \*stat()*\ function is run as root, but there is a
13755 facility for some checking of the accessibility of a file by another user.
13756 This is not a proper permissions check, but just a `rough' check that
13757 operates as follows:
13759 If an item in a \require@_files\ list does not contain any forward slash
13760 characters, it is taken to be the user (and optional group, separated by a
13761 comma) to be checked for subsequent files in the list. If no group is specified
13762 but the user is specified symbolically, the gid associated with the uid is
13765 require_files = mail:/some/file
13766 require_files = $local_part:$home/.procmailrc
13768 If a user or group name in a \require@_files\ list does not exist, the
13769 \require@_files\ condition fails.
13771 Exim performs the check by scanning along the components of the file path, and
13772 checking the access for the given uid and gid. It checks for `x' access on
13773 directories, and `r' access on the final file. Note that this means that file
13774 access control lists, if the operating system has them, are ignored.
13776 \**Warning 1**\: When the router is being run to verify addresses for an
13777 incoming SMTP message, Exim is not running as root, but under its own uid. This
13778 may affect the result of a \require@_files\ check. In particular, \*stat()*\
13779 may yield the error \\EACCES\\ (`Permission denied'). This means that the Exim
13780 user is not permitted to read one of the directories on the file's path.
13782 \**Warning 2**\: Even when Exim is running as root while delivering a message,
13783 \*stat()*\ can yield \\EACCES\\ for a file on an NFS directory that is mounted
13784 without root access.
13787 the default action is to consider this a configuration error, and routing is
13788 deferred because the existence or non-existence of the file cannot be
13789 determined. However, in some circumstances it may be desirable to treat this
13790 condition as if the file did not exist. If the file name (or the exclamation
13791 mark that precedes the file name for non-existence) is preceded by a plus sign,
13792 the \\EACCES\\ error is treated as if the file did not exist. For example:
13794 require_files = +/some/file
13796 If the router is not an essential part of verification (for example, it
13797 handles users' \(.forward)\ files), another solution is to set the \verify\
13798 option false so that the router is skipped when verifying.
13801 .conf retry@_use@_local@_part boolean "see below"
13802 .index hints database||retry keys
13803 .index local part||in retry keys
13804 When a delivery suffers a temporary routing failure, a retry record is created
13805 in Exim's hints database. For addresses whose routing depends only on the
13806 domain, the key for the retry record should not involve the local part, but for
13807 other addresses, both the domain and the local part should be included.
13808 Usually, remote routing is of the former kind, and local routing is of the
13811 This option controls whether the local part is used to form the key for retry
13812 hints for addresses that suffer temporary errors while being handled by this
13813 router. The default value is true for any router that has \check@_local@_user\
13814 set, and false otherwise. Note that this option does not apply to hints keys
13815 for transport delays; they are controlled by a generic transport option of the
13819 The setting of \retry@_use@_local@_part\ applies only to the router on which it
13820 appears. If the router generates child addresses, they are routed
13821 independently; this setting does not become attached to them.
13825 .conf router@_home@_directory string$**$ unset
13826 .index router||home directory for
13827 .index home directory||for router
13828 This option sets a home directory for use while the router is running. (Compare
13829 \transport__home@_directory\, which sets a home directory for later
13830 transporting.) In particular, if used on a \%redirect%\ router, this option
13831 sets a value for \$home$\ while a filter is running. The value is expanded;
13832 forced expansion failure causes the option to be ignored -- other failures
13833 cause the router to defer.
13835 Expansion of \router@_home@_directory\ happens immediately after the
13836 \check@_local@_user\ test (if configured), before any further expansions take
13838 (See section ~~SECTrouprecon for a list of the order in which preconditions
13840 While the router is running, \router__home@_directory\ overrides the value of
13841 \$home$\ that came from \check@_local@_user\.
13843 When a router accepts an address and routes it to a transport (including the
13844 cases when a redirect router generates a pipe, file, or autoreply delivery),
13845 the home directory setting for the transport is taken from the first of these
13846 values that is set:
13848 The \home@_directory\ option on the transport;
13850 The \transport@_home@_directory\ option on the router;
13852 The password data if \check@_local@_user\ is set on the router;
13854 The \router@_home@_directory\ option on the router.
13856 In other words, \router@_home@_directory\ overrides the password data for the
13857 router, but not for the transport.
13860 .conf self string "freeze"
13861 .index MX record||pointing to local host
13862 .index local host||MX pointing to
13863 This option applies to those routers that use a recipient address to find a
13864 list of remote hosts. Currently, these are the \%dnslookup%\, \%ipliteral%\,
13865 and \%manualroute%\ routers.
13866 Certain configurations of the \%queryprogram%\ router can also specify a list
13868 Usually such routers are configured to send the message to a remote host via an
13869 \%smtp%\ transport. The \self\ option specifies what happens when the first
13870 host on the list turns out to be the local host.
13871 The way in which Exim checks for the local host is described in section
13874 Normally this situation indicates either an error in Exim's configuration (for
13875 example, the router should be configured not to process this domain), or an
13876 error in the DNS (for example, the MX should not point to this host). For this
13877 reason, the default action is to log the incident, defer the address, and
13878 freeze the message. The following alternatives are provided for use in special
13883 Delivery of the message is tried again later, but the message is not frozen.
13885 \reroute: <<domain>>\
13887 The domain is changed to the given domain, and the address is passed back to
13888 be reprocessed by the routers. No rewriting of headers takes place. This
13889 behaviour is essentially a redirection.
13891 \reroute: rewrite: <<domain>>\
13893 The domain is changed to the given domain, and the address is passed back to be
13894 reprocessed by the routers. Any headers that contain the original domain are
13899 The router passes the address to the next router, or to the router named in the
13900 \pass@_router\ option if it is set.
13901 .index \more\ option
13902 This overrides \no@_more\.
13904 During subsequent routing and delivery, the variable
13905 \$self@_hostname$\ contains the name of the local host that the router
13906 encountered. This can be used to distinguish between different cases for hosts
13907 with multiple names. The combination
13912 ensures that only those addresses that routed to the local host are passed on.
13913 Without \no@_more\, addresses that were declined for other reasons would also
13914 be passed to the next router.
13918 Delivery fails and an error report is generated.
13922 .index local host||sending to
13923 The anomaly is ignored and the address is queued for the transport. This
13924 setting should be used with extreme caution. For an \%smtp%\ transport, it makes
13925 sense only in cases where the program that is listening on the SMTP port is not
13926 this version of Exim. That is, it must be some other MTA, or Exim with a
13927 different configuration file that handles the domain in another way.
13930 .conf senders "address list$**$ (precondition)" unset
13931 .index router||checking senders
13932 If this option is set, the router is skipped unless the message's sender
13933 address matches something on the list.
13934 See section ~~SECTrouprecon for a list of the order in which preconditions
13937 There are issues concerning verification when the running of routers is
13938 dependent on the sender. When Exim is verifying the address in an \errors@_to\
13939 setting, it sets the sender to the null string. When using the \-bt-\ option to
13940 check a configuration file, it is necessary also to use the \-f-\ option to set
13941 an appropriate sender. For incoming mail, the sender is unset when verifying
13942 the sender, but is available when verifying any recipients. If the SMTP
13943 \\VRFY\\ command is enabled, it must be used after \\MAIL\\ if the sender
13946 .conf translate@_ip@_address string$**$ unset
13947 .index IP address||translating
13948 .index packet radio
13949 .index router||IP address translation
13950 There exist some rare networking situations (for example, packet radio) where
13951 it is helpful to be able to translate IP addresses generated by normal routing
13952 mechanisms into other IP addresses, thus performing a kind of manual IP
13953 routing. This should be done only if the normal IP routing of the TCP/IP stack
13954 is inadequate or broken. Because this is an extremely uncommon requirement, the
13955 code to support this option is not included in the Exim binary unless
13956 \\SUPPORT__TRANSLATE__IP__ADDRESS\\=yes is set in \(Local/Makefile)\.
13958 The \translate@_ip@_address\ string is expanded for every IP address generated
13959 by the router, with the generated address set in \$host@_address$\. If the
13960 expansion is forced to fail, no action is taken.
13961 For any other expansion error, delivery of the message is deferred.
13962 If the result of the expansion is an IP address, that replaces the original
13963 address; otherwise the result is assumed to be a host name -- this is looked up
13964 using \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) to produce
13965 one or more replacement IP addresses. For example, to subvert all IP addresses
13966 in some specific networks, this could be added to a router:
13968 $smc{translate@_ip@_address = @\
13969 @$@{lookup@{@$@{mask:@$host@_address/26@}@}lsearch@{/some/file@}@{@$value@}fail@}}
13971 The file would contain lines like
13973 10.2.3.128/26 some.host
13974 10.8.4.34/26 10.44.8.15
13976 You should not make use of this facility unless you really understand what you
13980 .conf transport string$**$ unset
13981 This option specifies the transport to be used when a router accepts an address
13982 and sets it up for delivery. A transport is never needed if a router is used
13983 only for verification. The value of the option is expanded at routing time,
13984 after the expansion of \errors@_to\,
13985 \headers@_add\, and \headers@_remove\,
13986 and result must be the name of one of the configured transports. If it is
13987 not, delivery is deferred.
13989 The \transport\ option is not used by the \%redirect%\ router, but it does have
13990 some private options that set up transports for pipe and file deliveries (see
13991 chapter ~~CHAPredirect).
13994 .conf transport@_current@_directory string$**$ unset
13995 .index current directory for local transport
13996 This option associates a current directory with any address that is routed
13997 to a local transport. This can happen either because a transport is
13998 explicitly configured for the router, or because it generates a delivery to a
13999 file or a pipe. During the delivery process (that is, at transport time), this
14000 option string is expanded and is set as the current directory, unless
14001 overridden by a setting on the transport.
14002 If the expansion fails for any reason, including forced failure, an error is
14003 logged, and delivery is deferred.
14004 See chapter ~~CHAPenvironment for details of the local delivery environment.
14008 .conf transport@_home@_directory string$**$ "see below"
14009 .index home directory||for local transport
14010 This option associates a home directory with any address that is routed to a
14011 local transport. This can happen either because a transport is explicitly
14012 configured for the router, or because it generates a delivery to a file or a
14013 pipe. During the delivery process (that is, at transport time), the option
14014 string is expanded and is set as the home directory, unless overridden by a
14015 setting of \home@_directory\ on the transport.
14016 If the expansion fails for any reason, including forced failure, an error is
14017 logged, and delivery is deferred.
14019 If the transport does not specify a home directory, and
14020 \transport@_home@_directory\ is not set for the router, the home directory for
14021 the tranport is taken from the password data if \check@_local@_user\ is set for
14022 the router. Otherwise it is taken from \router@_home@_directory\ if that option
14023 is set; if not, no home directory is set for the transport.
14025 See chapter ~~CHAPenvironment for further details of the local delivery
14030 .conf unseen boolean$**$ false
14031 .index router||carrying on after success
14032 The result of string expansion for this option must be a valid boolean value,
14033 that is, one of the strings `yes', `no', `true', or `false'. Any other result
14034 causes an error, and delivery is deferred. If the expansion is forced to fail,
14035 the default value for the option (false) is used. Other failures cause delivery
14038 When this option is set true, routing does not cease if the router accepts the
14039 address. Instead, a copy of the incoming address is passed to the next router,
14040 overriding a false setting of \more\. There is little point in setting \more\
14041 false if \unseen\ is always true, but it may be useful in cases when the value
14042 of \unseen\ contains expansion items (and therefore, presumably, is sometimes
14043 true and sometimes false).
14045 The \unseen\ option can be used to cause
14046 .index copy of message (\unseen\ option)
14047 copies of messages to be delivered to some other destination, while also
14048 carrying out a normal delivery. In effect, the current address is made into a
14049 `parent' that has two children -- one that is delivered as specified by this
14050 router, and a clone that goes on to be routed further.
14052 Header lines added to the address (or specified for removal) by this router or
14053 by previous routers affect the `unseen' copy of the message only. The clone
14054 that continues to be processed by further routers starts with no added headers
14055 and none specified for removal.
14057 However, any data that was set by the \address@_data\ option in the current or
14058 previous routers is passed on. Setting this option has a similar effect to the
14059 \unseen\ command qualifier in filter files.
14062 .conf user string$**$ "see below"
14063 .index uid (user id)||local delivery
14064 .index local transports||uid and gid
14065 .index transport||local
14066 .index router||user for filter processing
14067 .index filter||user for processing
14068 When a router queues an address for a transport, and the transport does not
14069 specify a user, the user given here is used when running the delivery process.
14070 The user may be specified numerically or by name. If expansion fails, the
14071 error is logged and delivery is deferred.
14072 This user is also used by the \%redirect%\ router when running a filter file.
14073 The default is unset, except when \check@_local@_user\ is set. In this case,
14074 the default is taken from the password information. If the user is specified as
14075 a name, and \group\ is not set, the group associated with the user is used. See
14076 also \initgroups\ and \group\ and the discussion in chapter ~~CHAPenvironment.
14079 .conf verify "boolean (precondition)" true
14080 Setting this option has the effect of setting \verify@_sender\ and
14081 \verify@_recipient\ to the same value.
14083 .conf verify@_only "boolean (precondition)" false
14084 .index \\EXPN\\||with \verify@_only\
14085 .index \-bv-\ option
14086 .index router||used only when verifying
14087 If this option is set, the router is used only when verifying an address or
14088 testing with the \-bv-\ option, not when actually doing a delivery, testing
14089 with the \-bt-\ option, or running the SMTP \\EXPN\\ command. It can be further
14090 restricted to verifying only senders or recipients by means of \verify@_sender\
14091 and \verify@_recipient\.
14093 \**Warning**\: When the router is being run to verify addresses for an incoming
14094 SMTP message, Exim is not running as root, but under its own uid. If the router
14095 accesses any files, you need to make sure that they are accessible to the Exim
14098 .conf verify@_recipient "boolean (precondition)" true
14099 If this option is false, the router is skipped when verifying recipient
14101 or testing recipient verification using \-bv-\.
14102 See section ~~SECTrouprecon for a list of the order in which preconditions
14105 .conf verify@_sender "boolean (precondition)" true
14106 If this option is false, the router is skipped when verifying sender addresses
14107 or testing sender verification using \-bvs-\.
14108 See section ~~SECTrouprecon for a list of the order in which preconditions
14121 . ============================================================================
14122 .chapter The accept router
14123 .set runningfoot "accept router"
14124 .index \%accept%\ router
14125 .index routers||\%accept%\
14126 The \%accept%\ router has no private options of its own. Unless it is being used
14127 purely for verification (see \verify@_only\) a transport is required to be
14128 defined by the generic \transport\ option. If the preconditions that are
14129 specified by generic options are met, the router accepts the address and queues
14130 it for the given transport. The most common use of this router is for setting
14131 up deliveries to local mailboxes. For example:
14135 domains = mydomain.example
14137 transport = local_delivery
14139 The \domains\ condition in this example checks the domain of the address, and
14140 \check@_local@_user\ checks that the local part is the login of a local user.
14141 When both preconditions are met, the \%accept%\ router runs, and queues the
14142 address for the \%local@_delivery%\ transport.
14153 . ============================================================================
14154 .chapter The dnslookup router
14155 .rset CHAPdnslookup "~~chapter"
14156 .set runningfoot "dnslookup router"
14157 .index \%dnslookup%\ router
14158 .index routers||\%dnslookup%\
14159 The \%dnslookup%\ router looks up the hosts that handle mail for the given
14160 domain in the DNS. A transport must always be set for this router, unless
14161 \verify@_only\ is set.
14164 If SRV support is configured (see \check@_srv\ below), Exim first searches for
14165 SRV records. If none are found, or if SRV support is not configured,
14166 MX records are looked up. If no MX records exist, address records are sought.
14167 However, \mx@_domains\ can be set to disable the direct use of address records.
14169 MX records of equal priority are sorted by Exim into a random order. Exim then
14170 looks for address records for the host names obtained from MX or SRV records.
14171 When a host has more than one IP address, they are sorted into a random order,
14172 except that IPv6 addresses are always sorted before IPv4 addresses. If all the
14173 IP addresses found are discarded by a setting of the \ignore@_target@_hosts\
14174 generic option, the router declines.
14176 Unless they have the highest priority (lowest MX value), MX records that point
14177 to the local host, or to any host name that matches \hosts__treat__as__local\,
14178 are discarded, together with any other MX records of equal or lower priority.
14181 .index MX record||pointing to local host
14182 .index local host||MX pointing to
14183 .index \self\ option||in \%dnslookup%\ router
14184 If the host pointed to by the highest priority MX record, or looked up as an
14185 address record, is the local host, or matches \hosts__treat__as__local\, what
14186 happens is controlled by the generic \self\ option.
14188 There are a number of private options that can be used to vary the way the DNS
14193 .index options||\%dnslookup%\ router
14194 .conf check@_secondary@_mx boolean false
14195 .index MX record||checking for secondary
14196 If this option is set, the router declines unless the local host is found in
14197 (and removed from) the list of hosts obtained by MX lookup. This can be used to
14198 process domains for which the local host is a secondary mail exchanger
14199 differently to other domains. The way in which Exim decides whether a host is
14200 the local host is described in section ~~SECTreclocipadd.
14203 .conf check@_srv string$**$ unset
14204 .index SRV record||enabling use of
14205 The dnslookup router supports the use of SRV records (see RFC 2782) in
14206 addition to MX and address records. The support is disabled by default. To
14207 enable SRV support, set the \check@_srv\ option to the name of the service
14208 required. For example,
14212 looks for SRV records that refer to the normal smtp service. The option is
14213 expanded, so the service name can vary from message to message or address
14214 to address. This might be helpful if SRV records are being used for a
14215 submission service. If the expansion is forced to fail, the \check@_srv\
14216 option is ignored, and the router proceeds to look for MX records in the
14219 When the expansion succeeds, the router searches first for SRV records for
14220 the given service (it assumes TCP protocol). A single SRV record with the
14221 host name \"."\ indicates `no such service for this domain'; if this is
14222 encountered, the router declines. If other kinds of SRV record are found,
14223 they are used to construct a host list for delivery according to the rules
14224 of RFC 2782. MX records are not sought in this case.
14226 However, when no SRV records are found, MX records (and address records)
14227 are sought in the traditional way. In other words, SRV records take
14228 precedence over MX records, just as MX records take precedence over address
14229 records. Note that this behaviour is not sanctioned by RFC 2782, though a
14230 previous draft RFC defined it. It is apparently believed that MX records
14231 are sufficient for email and that SRV records should not be used for this
14232 purpose. However, SRV records have an additional `weight' feature which
14233 some people might find useful when trying to split an SMTP load between
14234 hosts of different power.
14237 .conf mx@_domains "domain list$**$" unset
14238 .index MX record||required to exist
14239 .index SRV record||required to exist
14241 A domain that matches \mx@_domains\ is required to have either an MX or an SRV
14242 record in order to be recognised. (The name of this option could be improved.)
14244 For example, if all the mail hosts in \*fict.example*\ are known to have MX
14245 records, except for those in \*discworld.fict.example*\, you could use this
14248 mx_domains = ! *.discworld.fict.example : *.fict.example
14250 This specifies that messages addressed to a domain that matches the list but
14251 has no MX record should be bounced immediately instead of being routed using
14252 the address record.
14254 .conf qualify@_single boolean true
14255 .index DNS||resolver options
14256 .index DNS||qualifying single-component names
14257 When this option is true, the resolver option \\RES@_DEFNAMES\\ is set for DNS
14258 lookups. Typically, but not standardly, this causes the resolver to qualify
14259 single-component names with the default domain. For example, on a machine
14260 called \*dictionary.ref.example*\, the domain \*thesaurus*\ would be changed to
14261 \*thesaurus.ref.example*\ inside the resolver. For details of what your resolver
14262 actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\.
14265 .conf rewrite@_headers boolean true
14266 .index rewriting||header lines
14267 .index header lines||rewriting
14268 If the domain name in the address that is being processed is not fully
14269 qualified, it may be expanded to its full form by a DNS lookup. For example, if
14270 an address is specified as \*dormouse@@teaparty*\, the domain might be
14271 expanded to \*teaparty.wonderland.fict.example*\. Domain expansion can also
14272 occur as a result of setting the \widen@_domains\ option. If \rewrite@_headers\
14273 is true, all occurrences of the abbreviated domain name in any ::Bcc::, ::Cc::,
14274 ::From::, ::Reply-to::, ::Sender::, and ::To:: header lines of the message are
14275 rewritten with the full domain name.
14277 This option should be turned off only when it is known that no message is
14278 ever going to be sent outside an environment where the abbreviation makes
14281 When an MX record is looked up in the DNS and matches a wildcard record, name
14282 servers normally return a record containing the name that has been looked up,
14283 making it impossible to detect whether a wildcard was present or not. However,
14284 some name servers have recently been seen to return the wildcard entry. If the
14285 name returned by a DNS lookup begins with an asterisk, it is not used for
14288 .conf same@_domain@_copy@_routing boolean false
14289 .index address||copying routing
14290 Addresses with the same domain are normally routed by the \%dnslookup%\ router
14291 to the same list of hosts. However, this cannot be presumed, because the router
14292 options and preconditions may refer to the local part of the address. By
14293 default, therefore, Exim routes each address in a message independently. DNS
14294 servers run caches, so repeated DNS lookups are not normally expensive, and in
14295 any case, personal messages rarely have more than a few recipients.
14297 If you are running mailing lists with large numbers of subscribers at the same
14298 domain, and you are using a \%dnslookup%\ router which is independent of the
14299 local part, you can set \same__domain__copy@_routing\ to bypass repeated DNS
14300 lookups for identical domains in one message. In this case, when \%dnslookup%\
14301 routes an address to a remote transport, any other unrouted addresses in the
14302 message that have the same domain are automatically given the same routing
14303 without processing them independently,
14304 provided the following conditions are met:
14306 No router that processed the address specified \headers@_add\ or
14309 The router did not change the address in any way, for example, by `widening'
14314 .conf search@_parents boolean false
14315 .index DNS||resolver options
14316 When this option is true, the resolver option \\RES@_DNSRCH\\ is set for DNS
14317 lookups. This is different from the \qualify@_single\ option in that it applies
14318 to domains containing dots. Typically, but not standardly, it causes the
14319 resolver to search for the name in the current domain and in parent domains.
14320 For example, on a machine in the \*fict.example*\ domain, if looking up
14321 \*teaparty.wonderland*\ failed, the resolver would try
14322 \*teaparty.wonderland.fict.example*\. For details of what your resolver
14323 actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\.
14325 Setting this option true can cause problems in domains that have a wildcard MX
14326 record, because any domain that does not have its own MX record matches the
14329 .conf widen@_domains "string list" unset
14330 .index domain||partial, widening
14331 If a DNS lookup fails and this option is set, each of its strings in turn is
14332 added onto the end of the domain, and the lookup is tried again. For example,
14335 widen_domains = fict.example:ref.example
14337 is set and a lookup of \*klingon.dictionary*\ fails,
14338 \*klingon.dictionary.fict.example*\ is looked up, and if this fails,
14339 \*klingon.dictionary.ref.example*\ is tried. Note that the \qualify@_single\
14340 and \search@_parents\ options can cause some widening to be undertaken inside
14346 .section Effect of qualify@_single and search@_parents
14347 When a domain from an envelope recipient is changed by the resolver as a result
14348 of the \qualify@_single\ or \search@_parents\ options, Exim rewrites the
14349 corresponding address in the message's header lines unless \rewrite@_headers\
14350 is set false. Exim then re-routes the address, using the full domain.
14352 These two options affect only the DNS lookup that takes place inside the router
14353 for the domain of the address that is being routed. They do not affect lookups
14354 such as that implied by
14358 that may happen while processing a router precondition before the router is
14359 entered. No widening ever takes place for these lookups.
14374 . ============================================================================
14375 .chapter The ipliteral router
14376 .set runningfoot "ipliteral router"
14377 .index \%ipliteral%\ router
14378 .index domain literal||routing
14379 .index routers||\%ipliteral%\
14380 This router has no private options. Unless it is being used purely for
14381 verification (see \verify@_only\) a transport is required to be defined by the
14382 generic \transport\ option. The router accepts the address if its domain part
14383 takes the form of an RFC 2822 domain literal, that is, an IP address enclosed
14384 in square brackets. For example, this router handles the address
14388 by setting up delivery to the host with that IP address.
14391 If the IP address matches something in \ignore@_target@_hosts\, the router
14394 .index \self\ option||in \%ipliteral%\ router
14395 If an IP literal turns out to refer to the local host, the generic \self\
14396 option determines what happens.
14398 The RFCs require support for domain literals; however, their use is
14399 controversial in today's Internet. If you want to use this router, you must
14400 also set the main configuration option \allow@_domain@_literals\. Otherwise,
14401 Exim will not recognize the domain literal syntax in addresses.
14409 . ============================================================================
14410 .chapter The iplookup router
14411 .set runningfoot "iplookup router"
14412 .index \%iplookup%\ router
14413 .index routers||\%iplookup%\
14414 The \%iplookup%\ router was written to fulfil a specific requirement in
14415 Cambridge University. For this reason, it is not included in the binary of Exim
14416 by default. If you want to include it, you must set
14418 ROUTER_IPLOOKUP=yes
14420 in your \(Local/Makefile)\ configuration file.
14422 The \%iplookup%\ router routes an address by sending it over a TCP or UDP
14423 connection to one or more specific hosts. The host can then return the same or
14424 a different address -- in effect rewriting the recipient address in the
14425 message's envelope. The new address is then passed on to subsequent routers.
14428 If this process fails, the address can be passed on to
14429 other routers, or delivery can be deferred.
14431 Background, for those that are interested: We have an Oracle database of all
14432 Cambridge users, and one of the items of data it maintains for each user is
14433 where to send mail addressed to \*user@@cam.ac.uk*\. The MX records for
14434 \*cam.ac.uk*\ point to a central machine that has a large alias list that is
14435 abstracted from the database. Mail from outside is switched by this system, and
14436 originally internal mail was also done this way. However, this resulted in a
14437 fair number of messages travelling from some of our larger systems to the
14438 switch and back again. The Oracle machine now runs a UDP service that can be
14439 called by the \%iplookup%\ router in Exim to find out where \*user@@cam.ac.uk*\
14440 addresses really have to go; this saves passing through the central switch, and
14441 in many cases saves doing any remote delivery at all.
14443 Since \%iplookup%\ is just a rewriting router, a transport must not be
14447 .index options||\%iplookup%\ router
14449 .conf hosts string unset
14450 This option must be supplied. Its value is a colon-separated list of host
14451 names. The hosts are looked up using \*gethostbyname()*\
14452 (or \*getipnodebyname()*\ when available)
14453 and are tried in order until one responds to the query. If none respond, what
14454 happens is controlled by \optional\.
14456 .conf optional boolean false
14457 If \optional\ is true, if no response is obtained from any host, the address is
14458 passed to the next router, overriding \no@_more\. If \optional\ is false,
14459 delivery to the address is deferred.
14461 .conf port integer 0
14462 .index port||\%iplookup%\ router
14463 This option must be supplied. It specifies the port number for the TCP or UDP
14466 .conf protocol string "udp"
14467 This option can be set to `udp' or `tcp' to specify which of the two protocols
14470 .conf query string$**$ "$tt{@$local@_part@@@$domain @$local@_part@@@$domain}"
14471 This defines the content of the query that is sent to the remote hosts. The
14472 repetition serves as a way of checking that a response is to the correct query
14473 in the default case (see \response@_pattern\ below).
14475 .conf reroute string$**$ unset
14476 If this option is not set, the rerouted address is precisely the byte string
14477 returned by the remote host, up to the first white space, if any. If set, the
14478 string is expanded to form the rerouted address. It can include parts matched
14479 in the response by \response@_pattern\ by means of numeric variables such as
14480 \$1$\, \$2$\, etc. The variable \$0$\ refers to the entire input string,
14481 whether or not a pattern is in use. In all cases, the rerouted address must end
14482 up in the form \*local@_part@@domain*\.
14484 .conf response@_pattern string unset
14485 This option can be set to a regular expression that is applied to the string
14486 returned from the remote host. If the pattern does not match the response, the
14487 router declines. If \response@_pattern\ is not set, no checking of the response
14488 is done, unless the query was defaulted, in which case there is a check that
14489 the text returned after the first white space is the original address. This
14490 checks that the answer that has been received is in response to the correct
14491 question. For example, if the response is just a new domain, the following
14494 response_pattern = ^([^@]+)$
14495 reroute = $local_part@$1
14498 .conf timeout time 5s
14499 This specifies the amount of time to wait for a response from the remote
14500 machine. The same timeout is used for the \*connect()*\ function for a TCP
14501 call. It does not apply to UDP.
14512 . ============================================================================
14513 .chapter The manualroute router
14514 .set runningfoot "manualroute router"
14515 .index \%manualroute%\ router
14516 .index routers||\%manualroute%\
14517 .index domain||manually routing
14518 The \%manualroute%\ router is so-called because it provides a way of manually
14519 routing an address according to its domain. It is mainly used when you want to
14520 route addresses to remote hosts according to your own rules, bypassing the
14521 normal DNS routing that looks up MX records. However, \%manualroute%\ can also
14522 route to local transports, a facility that may be useful if you want to save
14523 messages for dial-in hosts in local files.
14525 The \%manualroute%\ router compares a list of domain patterns with the domain it
14526 is trying to route. If there is no match, the router declines. Each pattern has
14527 associated with it a list of hosts and some other optional data, which may
14528 include a transport. The combination of a pattern and its data is called a
14529 `routing rule'. For patterns that do not have an associated transport, the
14530 generic \transport\ option must specify a transport, unless the router is being
14531 used purely for verification (see \verify@_only\).
14533 In the case of verification, matching the domain pattern is sufficient for the
14534 router to accept the address. When actually routing an address for delivery,
14535 an address that matches a domain pattern is queued for the associated
14536 transport. If the transport is not a local one, a host list must be associated
14537 with the pattern; IP addresses are looked up for the hosts, and these are
14538 passed to the transport along with the mail address. For local transports, a
14539 host list is optional. If it is present, it is passed in \$host$\ as a single
14542 The list of routing rules can be provided as an inline string in \route@_list\,
14543 or the data can be obtained by looking up the domain in a file or database by
14544 setting \route@_data\. Only one of these settings may appear in any one
14545 instance of \%manualroute%\. The format of routing rules is described below,
14546 following the list of private options.
14548 .section Private options for manualroute
14549 .rset SECTprioptman "~~chapter.~~section"
14551 The private options for the \%manualroute%\ router are as follows:
14554 .index options||\%manualroute%\ router
14556 .conf host@_find@_failed string "freeze"
14557 This option controls what happens when \%manualroute%\ tries to find an IP
14558 address for a host, and the host does not exist. The option can be set to one
14567 The default assumes that this state is a serious configuration error. The
14568 difference between `pass' and `decline' is that the former forces the address
14569 to be passed to the next router (or the router defined by \pass@_router\),
14570 .index \more\ option
14571 overriding \no@_more\, whereas the latter passes the address to the next router
14572 only if \more\ is true.
14574 This option applies only to a definite `does not exist' state; if a host lookup
14575 gets a temporary error, delivery is deferred unless the generic
14576 \pass@_on@_timeout\ option is set.
14578 .conf hosts@_randomize boolean false
14579 .index randomized host list
14580 .index host||list of, randomized
14581 If this option is set, the order of the items in a host list in a routing rule
14582 is randomized each time the list is used, unless an option in the routing rule
14583 overrides (see below). Randomizing the order of a host list can be used to do
14584 crude load sharing. However, if more than one mail address is routed by the
14585 same router to the same host list, the host lists are considered to be the same
14586 (even though they may be randomized into different orders) for the purpose of
14587 deciding whether to batch the deliveries into a single SMTP transaction.
14589 When \hosts@_randomize\ is true, a host list may be split
14590 into groups whose order is separately randomized. This makes it possible to
14591 set up MX-like behaviour. The boundaries between groups are indicated by an
14592 item that is just \"+"\ in the host list. For example:
14594 route_list = * host1:host2:host3:+:host4:host5
14596 The order of the first three hosts and the order of the last two hosts is
14597 randomized for each use, but the first three always end up before the last two.
14598 If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. If a
14599 randomized host list is passed to an \%smtp%\ transport that also has
14600 \hosts@_randomize set\, the list is not re-randomized.
14602 .conf route@_data string$**$ unset
14603 If this option is set, it must expand to yield the data part of a routing rule.
14604 Typically, the expansion string includes a lookup based on the domain. For
14607 route_data = ${lookup{$domain}dbm{/etc/routes}}
14609 If the expansion is forced to fail, or the result is an empty string, the
14610 router declines. Other kinds of expansion failure cause delivery to be
14613 .conf route@_list "string list, semicolon-separated" unset
14614 This string is a list of routing rules, in the form defined below. Note that,
14615 unlike most string lists, the items are separated by semicolons. This is so
14616 that they may contain colon-separated host lists.
14618 .conf same@_domain@_copy@_routing boolean false
14619 .index address||copying routing
14620 Addresses with the same domain are normally routed by the \%manualroute%\ router
14621 to the same list of hosts. However, this cannot be presumed, because the router
14622 options and preconditions may refer to the local part of the address. By
14623 default, therefore, Exim routes each address in a message independently. DNS
14624 servers run caches, so repeated DNS lookups are not normally expensive, and in
14625 any case, personal messages rarely have more than a few recipients.
14627 If you are running mailing lists with large numbers of subscribers at the same
14628 domain, and you are using a \%manualroute%\ router which is independent of the
14629 local part, you can set \same@_domain@_copy@_routing\ to bypass repeated DNS
14630 lookups for identical domains in one message. In this case, when \%manualroute%\
14631 routes an address to a remote transport, any other unrouted addresses in the
14632 message that have the same domain are automatically given the same routing
14633 without processing them independently. However, this is only done if
14634 \headers@_add\ and \headers@_remove\ are unset.
14639 .section Routing rules in route@_list
14640 The value of \route@_list\ is a string consisting of a sequence of routing
14641 rules, separated by semicolons. If a semicolon is needed in a rule, it can be
14642 entered as two semicolons. Empty rules are ignored. The format of each rule is
14644 <<domain pattern>> <<list of hosts>> <<options>>
14646 The following example contains two rules, each with a simple domain pattern and
14650 dict.ref.example mail-1.ref.example:mail-2.ref.example ; \
14651 thes.ref.example mail-3.ref.example:mail-4.ref.example
14653 The three parts of a rule are separated by white space. The pattern and the
14654 list of hosts can be enclosed in quotes if necessary, and if they are, the
14655 usual quoting rules apply. Each rule in a \route@_list\ must start with a
14656 single domain pattern, which is the only mandatory item in the rule. The
14657 pattern is in the same format as one item in a domain list (see section
14659 except that it may not be the name of an interpolated file.
14660 That is, it may be wildcarded, or a regular expression, or a file or database
14661 lookup (with semicolons doubled, because of the use of semicolon as a separator
14662 in a \route@_list\).
14664 The rules in \route@_list\ are searched in order until one of the patterns
14665 matches the domain that is being routed. The list of hosts and then options are
14666 then used as described below. If there is no match, the router declines. When
14667 \route@_list\ is set, \route@_data\ must not be set.
14670 .section Routing rules in route@_data
14671 The use of \route@_list\ is convenient when there are only a small number of
14672 routing rules. For larger numbers, it is easier to use a file or database to
14673 hold the routing information, and use the \route@_data\ option instead.
14674 The value of \route@_data\ is a list of hosts, followed by (optional) options.
14675 Most commonly, \route@_data\ is set as a string that contains an
14676 expansion lookup. For example, suppose we place two routing rules in a file
14679 dict.ref.example: mail-1.ref.example:mail-2.ref.example
14680 thes.ref.example: mail-3.ref.example:mail-4.ref.example
14682 This data can be accessed by setting
14684 route_data = ${lookup{$domain}lsearch{/the/file/name}}
14686 Failure of the lookup results in an empty string, causing the router to
14687 decline. However, you do not have to use a lookup in \route@_data\. The only
14688 requirement is that the result of expanding the string is a list of hosts,
14689 possibly followed by options, separated by white space. The list of hosts must
14690 be enclosed in quotes if it contains white space.
14694 .section Format of the list of hosts
14695 A list of hosts, whether obtained via \route@_data\ or \route@_list\, is always
14696 separately expanded before use. If the expansion fails, the router declines.
14697 The result of the expansion must be a colon-separated list of names and/or
14698 IP addresses. IP addresses are not enclosed in brackets.
14700 If the list of hosts was obtained from a \route@_list\ item, the following
14701 variables are set during its expansion:
14702 .index numerical variables (\$1$\, \$2$\, etc)||in \%manualroute%\ router
14704 If the domain was matched against a regular expression, the numeric variables
14705 \$1$\, \$2$\, etc. may be set.
14707 \$0$\ is always set to the entire domain.
14709 \$1$\ is also set when partial matching is done in a file lookup.
14712 If the pattern that matched the domain was a lookup item, the data that was
14713 looked up is available in the expansion variable \$value$\.
14718 .section How the list of hosts is used
14719 When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of
14720 the hosts is tried, in the order specified, when carrying out the SMTP
14721 delivery. However, the order can be changed by setting the \hosts@_randomize\
14722 option, either on the router (see section ~~SECTprioptman above), or on the
14725 Hosts may be listed by name or by IP address. An unadorned name in the list of
14726 hosts is interpreted as a host name. A name that is followed by \"/MX"\ is
14727 interpreted as an indirection to a sublist of hosts obtained by looking up MX
14728 records in the DNS. For example:
14730 route_list = * x.y.z:p.q.r/MX:e.f.g
14732 If the \hosts@_randomize\ option is set, the order of the items in the list is
14733 randomized before any lookups are done. Exim then scans the list; for any name
14734 that is not followed by \"/MX"\ it looks up an IP address. If this turns out to
14735 be an interface on the local host and the item is not the first in the list,
14736 Exim discards it and any subsequent items. If it is the first item, what
14737 happens is controlled by the
14738 .index \self\ option||in \%manualroute%\ router
14739 \self\ option of the router.
14741 A name on the list that is followed by \"/MX"\ is replaced with the list of
14742 hosts obtained by looking up MX records for the name. This is always a DNS
14743 lookup; the \bydns\ and \byname\ options (see section ~~SECThowoptused below)
14744 are not relevant here. The order of these hosts is determined by the preference
14745 values in the MX records, according to the usual rules. Because randomizing
14746 happens before the MX lookup, it does not affect the order that is defined by
14750 If the local host is present in the sublist obtained from MX records, but is
14751 not the most preferred host in that list, it and any equally or less
14752 preferred hosts are removed before the sublist is inserted into the main list.
14754 If the local host is the most preferred host in the MX list, what happens
14755 depends on where in the original list of hosts the \"/MX"\ item appears. If it
14756 is not the first item (that is, there are previous hosts in the main list),
14757 Exim discards this name and any subsequent items in the main list.
14759 If the MX item is first in the list of hosts, and the local host is the
14760 most preferred host, what happens is controlled by the \self\ option of the
14763 DNS failures when lookup up the MX records are treated in the same way as DNS
14764 failures when looking up IP addresses: \pass@_on@_timeout\ and
14765 \host@_find@_failed\ are used when relevant.
14768 The generic \ignore@_target@_hosts\ option applies to all hosts in the list,
14769 whether obtained from an MX lookup or not.
14773 .section How the options are used
14774 .rset SECThowoptused "~~chapter.~~section"
14775 The options are a sequence of words; in practice no more than three are ever
14776 present. One of the words can be the name of a transport; this overrides the
14777 \transport\ option on the router for this particular routing rule only. The
14778 other words (if present) control randomization of the list of hosts on a
14779 per-rule basis, and how the IP addresses of the hosts are to be found when
14780 routing to a remote transport. These options are as follows:
14782 \randomize\: randomize the order of the hosts in this list, overriding the
14783 setting of \hosts@_randomize\ for this routing rule only.
14785 \no@_randomize\: do not randomize the order of the hosts in this list,
14786 overriding the setting of \hosts@_randomize\ for this routing rule only.
14788 \byname\: use \*getipnodebyname()*\ (\*gethostbyname()*\ on older systems) to
14789 find IP addresses. This function may ultimately cause a DNS lookup, but it may
14790 also look in \(/etc/hosts)\ or other sources of information.
14792 \bydns\: look up address records for the hosts directly in the DNS; fail if
14793 no address records are found. If there is a temporary DNS error (such as a
14794 timeout), delivery is deferred.
14798 route_list = domain1 host1:host2:host3 randomize bydns;\
14799 domain2 host4:host5
14801 If neither \byname\ nor \bydns\ is given, Exim behaves as follows: First, a DNS
14802 lookup is done. If this yields anything other than \\HOST@_NOT@_FOUND\\, that
14803 result is used. Otherwise, Exim goes on to try a call to \*getipnodebyname()*\
14804 or \*gethostbyname()*\, and the result of the lookup is the result of that
14807 \**Warning**\: It has been discovered that on some systems, if a DNS lookup
14808 called via \*getipnodebyname()*\ times out, \\HOST@_NOT@_FOUND\\ is returned
14809 instead of \\TRY@_AGAIN\\. That is why the default action is to try a DNS
14810 lookup first. Only if that gives a definite `no such host' is the local
14815 If no IP address for a host can be found, what happens is controlled by the
14816 \host@_find@_failed\ option.
14818 When an address is routed to a local transport, IP addresses are not looked up.
14819 The host list is passed to the transport in the \$host$\ variable.
14822 .section Manualroute examples
14823 In some of the examples that follow, the presence of the \remote@_smtp\
14824 transport, as defined in the default configuration file, is assumed:
14827 .index smart host||example router
14828 The \%manualroute%\ router can be used to forward all external mail to a
14829 \*smart host*\. If you have set up, in the main part of the configuration, a
14830 named domain list that contains your local domains, for example,
14832 domainlist local_domains = my.domain.example
14834 you can arrange for all other domains to be routed to a smart host by making
14835 your first router something like this:
14838 driver = manualroute
14839 domains = !+local_domains
14840 transport = remote_smtp
14841 route_list = * smarthost.ref.example
14843 This causes all non-local addresses to be sent to the single host
14844 \*smarthost.ref.example*\. If a colon-separated list of smart hosts is given,
14845 they are tried in order
14846 (but you can use \hosts@_randomize\ to vary the order each time).
14847 Another way of configuring the same thing is this:
14850 driver = manualroute
14851 transport = remote_smtp
14852 route_list = !+local_domains smarthost.ref.example
14854 There is no difference in behaviour between these two routers as they stand.
14855 However, they behave differently if \no@_more\ is added to them. In the first
14856 example, the router is skipped if the domain does not match the \domains\
14857 precondition; the following router is always tried. If the router runs, it
14858 always matches the domain and so can never decline. Therefore, \no@_more\ would
14859 have no effect. In the second case, the router is never skipped; it always
14860 runs. However, if it doesn't match the domain, it declines. In this case
14861 \no@_more\ would prevent subsequent routers from running.
14864 .index mail hub example
14865 A \*mail hub*\ is a host which receives mail for a number of domains via MX
14866 records in the DNS and delivers it via its own private routing mechanism. Often
14867 the final destinations are behind a firewall, with the mail hub being the one
14868 machine that can connect to machines both inside and outside the firewall. The
14869 \%manualroute%\ router is usually used on a mail hub to route incoming messages
14870 to the correct hosts. For a small number of domains, the routing can be inline,
14871 using the \route@_list\ option, but for a larger number a file or database
14872 lookup is easier to manage.
14874 If the domain names are in fact the names of the machines to which the mail is
14875 to be sent by the mail hub, the configuration can be quite simple. For
14879 driver = manualroute
14880 transport = remote_smtp
14881 route_list = *.rhodes.tvs.example $domain
14883 This configuration routes domains that match \"*.rhodes.tvs.example"\ to hosts
14884 whose names are the same as the mail domains. A similar approach can be taken
14885 if the host name can be obtained from the domain name by a string manipulation
14886 that the expansion facilities can handle. Otherwise, a lookup based on the
14887 domain can be used to find the host:
14890 driver = manualroute
14891 transport = remote_smtp
14892 route_data = ${lookup {$domain} cdb {/internal/host/routes}}
14894 The result of the lookup must be the name or IP address of the host (or
14895 hosts) to which the address is to be routed. If the lookup fails, the route
14896 data is empty, causing the router to decline. The address then passes to the
14900 .index batched SMTP output example
14901 .index SMTP||batched outgoing, example
14902 You can use \%manualroute%\ to deliver messages to pipes or files in batched
14903 SMTP format for onward transportation by some other means. This is one way of
14904 storing mail for a dial-up host when it is not connected. The route list entry
14905 can be as simple as a single domain name in a configuration like this:
14908 driver = manualroute
14909 transport = batchsmtp_appendfile
14910 route_list = saved.domain.example
14912 though often a pattern is used to pick up more than one domain. If there are
14913 several domains or groups of domains with different transport requirements,
14914 different transports can be listed in the routing information:
14917 driver = manualroute
14919 *.saved.domain1.example $domain batch_appendfile; \
14920 *.saved.domain2.example \
14921 ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \
14924 The first of these just passes the domain in the \$host$\ variable, which
14925 doesn't achieve much (since it is also in \$domain$\), but the second does a
14926 file lookup to find a value to pass, causing the router to decline to handle
14927 the address if the lookup fails.
14929 .index UUCP||example of router for
14930 Routing mail directly to UUCP software is a specific case of the use of
14931 \%manualroute%\ in a gateway to another mail environment. This is an example of
14932 one way it can be done:
14938 command = /usr/local/bin/uux -r - \
14939 ${substr_-5:$host}!rmail ${local_part}
14940 return_fail_output = true
14946 driver = manualroute
14948 ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}}
14950 The file \(/usr/local/exim/uucphosts)\ contains entries like
14952 darksite.ethereal.example: darksite.UUCP
14954 It can be set up more simply without adding and removing `.UUCP' but this way
14955 makes clear the distinction between the domain name
14956 \*darksite.ethereal.example*\ and the UUCP host name \*darksite*\.
14968 . ============================================================================
14969 .chapter The queryprogram router
14970 .set runningfoot "queryprogram router"
14971 .rset CHAPdriverlast "~~chapter"
14972 .index \%queryprogram%\ router
14973 .index routers||\%queryprogram%\
14974 .index routing||by external program
14975 The \%queryprogram%\ router routes an address by running an external command and
14976 acting on its output. This is an expensive way to route, and is intended mainly
14977 for use in lightly-loaded systems, or for performing experiments. However, if
14978 it is possible to use the precondition options (\domains\, \local@_parts\,
14979 etc) to skip this router for most addresses, it could sensibly be used in
14980 special cases, even on a busy host. There are the following private options:
14983 .index options||\%queryprogram%\ router
14984 .conf command string$**$ unset
14985 This option must be set. It specifies the command that is to be run. The
14986 command is split up into a command name and arguments, and then each is
14987 expanded separately (exactly as for a \%pipe%\ transport, described in chapter
14988 ~~CHAPpipetransport).
14990 .conf command@_group string unset
14991 .index gid (group id)||in \%queryprogram%\ router
14992 This option specifies a gid to be set when running the command. It must be set
14993 if \command@_user\ specifies a numerical uid. If it begins with a digit, it is
14994 interpreted as the numerical value of the gid. Otherwise it is looked up using
14997 .conf command@_user string unset
14998 .index uid (user id)||for \%queryprogram%\
14999 This option must be set. It specifies the uid which is set when running the
15000 command. If it begins with a digit it is interpreted as the numerical value of
15001 the uid. Otherwise, it is looked up using \*getpwnam()*\ to obtain a value for
15002 the uid and, if \command@_group\ is not set, a value for the gid also.
15004 .conf current@_directory string /
15005 This option specifies an absolute path which is made the current directory
15006 before running the command.
15008 .conf timeout time 1h
15009 If the command does not complete within the timeout period, its process group
15010 is killed and the message is frozen. A value of zero time specifies no
15015 The standard output of the command is connected to a pipe, which is read when
15016 the command terminates. It should consist of a single line of output,
15017 containing up to five fields, separated by white space. The first field is one
15018 of the following words (case-insensitive):
15020 \*Accept*\: routing succeeded; the remaining fields specify what to do (see
15023 \*Decline*\: the router declines; pass the address to the next router, unless
15026 \*Fail*\: routing failed; do not pass the address to any more routers. Any
15027 subsequent text on the line is an error message. If the router is run as part
15028 of address verification during an incoming SMTP message, the message is
15029 included in the SMTP response.
15031 \*Defer*\: routing could not be completed at this time; try again later. Any
15032 subsequent text on the line is an error message which is logged. It is not
15033 included in any SMTP response.
15035 \*Freeze*\: the same as \*defer*\, except that the message is frozen.
15037 \*Pass*\: pass the address to the next router (or the router specified by
15038 \pass@_router\), overriding \no@_more\.
15040 \*Redirect*\: the message is redirected. The remainder of the line is a list of
15041 new addresses, which are routed independently, starting with the first router,
15042 or the router specified by \redirect@_router\, if set.
15044 When the first word is \*accept*\, the remainder of the line consists of a
15045 number of keyed data values, as follows (split into two lines here, to fit on
15048 ACCEPT TRANSPORT=<<transport>> HOSTS=<<list of hosts>>
15049 LOOKUP=byname|bydns DATA=<<text>>
15051 The data items can be given in any order, and all are optional. If no transport
15052 is included, the transport specified by the generic \transport\ option is used.
15053 The list of hosts and the lookup type are needed only if the transport is an
15054 \%smtp%\ transport that does not itself supply a list of hosts.
15056 The format of the list of hosts is the same as for the \%manualroute%\ router.
15057 As well as host names and IP addresses, it may contain names followed by
15058 \"/MX"\ to specify sublists of hosts that are obtained by looking up MX
15061 If the lookup type is not specified, Exim behaves as follows when trying to
15062 find an IP address for each host: First, a DNS lookup is done. If this yields
15063 anything other than \\HOST@_NOT@_FOUND\\, that result is used. Otherwise, Exim
15064 goes on to try a call to \*getipnodebyname()*\ or \*gethostbyname()*\, and the
15065 result of the lookup is the result of that call.
15067 If the DATA field is set, its value is placed in the \$address@_data$\
15068 variable. For example, this return line
15070 accept hosts=x1.y.example:x2.y.example data="rule1"
15072 routes the address to the default transport, with a host list containing two
15073 hosts. When the transport runs, the string `rule1' is in \$address@_data$\.
15081 . ============================================================================
15082 .chapter The redirect router
15083 .set runningfoot "redirect router"
15084 .rset CHAPredirect "~~chapter"
15085 .index \%redirect%\ router
15086 .index routers||\%redirect%\
15087 .index alias file||in a \%redirect%\ router
15088 .index address redirection||\%redirect%\ router
15089 The \%redirect%\ router handles several kinds of address redirection. Its most
15090 common uses are for resolving local part aliases from a central alias file
15091 (usually called \(/etc/aliases)\) and for handling users' personal \(.forward)\
15092 files, but it has many other potential uses. The incoming address can be
15093 redirected in several different ways:
15095 It can be replaced by one or more new addresses which are themselves routed
15098 It can be routed to be delivered to a given file or directory.
15100 It can be routed to be delivered to a specified pipe command.
15102 It can cause an automatic reply to be generated.
15104 It can be forced to fail, with a custom error message.
15106 It can be temporarily deferred.
15108 It can be discarded.
15110 The generic \transport\ option must not be set for \%redirect%\ routers.
15111 However, there are some private options which define transports for delivery to
15112 files and pipes, and for generating autoreplies. See the \file@_transport\,
15113 \pipe@_transport\ and \reply@_transport\ descriptions below.
15116 .section Redirection data
15117 The router operates by interpreting a text string which it obtains either by
15118 expanding the contents of the \data\ option, or by reading the entire contents
15119 of a file whose name is given in the \file\ option. These two options are
15120 mutually exclusive. The first is commonly used for handling system aliases, in
15121 a configuration like this:
15125 data = ${lookup{$local_part}lsearch{/etc/aliases}}
15128 If the lookup fails, the expanded string in this example is empty. When the
15129 expansion of \data\ results in an empty string, the router declines. A forced
15130 expansion failure also causes the router to decline; other expansion failures
15131 cause delivery to be deferred.
15134 A configuration using \file\ is commonly used for handling users' \(.forward)\
15140 file = $home/.forward
15143 If the file does not exist, or causes no action to be taken (for example, it is
15144 empty or consists only of comments), the router declines. \**Warning**\: This
15145 is not the case when the file contains syntactically valid items that happen to
15146 yield empty addresses, for example, items containing only RFC 2822 address
15150 .section Forward files and address verification
15151 .index address redirection||while verifying
15152 It is usual to set \no@_verify\ on \%redirect%\ routers which handle users'
15153 \(.forward)\ files, as in the example above. There are two reasons for this:
15155 When Exim is receiving an incoming SMTP message from a remote host, it is
15156 running under the Exim uid, not as root.
15157 No additional groups are set up, even if the Exim uid is a member of other
15158 groups (that is, the \*initgroups()*\ function is not run).
15159 Exim is unable to change uid to read the file as the user, and it may not be
15160 able to read it as the Exim user. So in practice the router may not be able to
15163 However, even when the router can operate, the existence of a \(.forward)\ file
15164 is unimportant when verifying an address. What should be checked is whether the
15165 local part is a valid user name or not. Cutting out the redirection processing
15166 saves some resources.
15172 .section Interpreting redirection data
15173 .index Sieve filter||specifying in redirection data
15174 .index filter||specifying in redirection data
15175 The contents of the data string, whether obtained from \data\ or \file\, can be
15176 interpreted in two different ways:
15178 If the \allow@_filter\ option is set true, and the data begins with the text
15179 `@#Exim filter' or `@#Sieve filter', it is interpreted as a list of
15180 \*filtering*\ instructions in the form of an Exim or Sieve filter file,
15181 respectively. Details of the syntax and semantics of filter files are described
15182 in a separate document entitled \*Exim's interfaces to mail filtering*\; this
15183 document is intended for use by end users.
15185 Otherwise, the data must be a comma-separated list of redirection items, as
15186 described in the next section.
15188 When a message is redirected to a file (a `mail folder'), the file name given
15189 in a non-filter redirection list must always be an absolute path. A filter may
15190 generate a relative path -- how this is handled depends on the transport's
15191 configuration. See section ~~SECTfildiropt for a discussion of this issue for
15192 the \%appendfile%\ transport.
15195 .section Items in a non-filter redirection list
15196 .rset SECTitenonfilred "~~chapter.~~section"
15197 .index address redirection||non-filter list items
15198 When the redirection data is not an Exim or Sieve filter, for example, if it
15199 comes from a conventional alias or forward file, it consists of a list of
15200 addresses, file names, pipe commands, or certain special items (see section
15201 ~~SECTspecitredli below). The special items can be individually enabled or
15202 disabled by means of options whose names begin with \allow@_\ or \forbid@_\,
15203 depending on their default values. The items in the list are separated by
15204 commas or newlines.
15205 If a comma is required in an item, the entire item must be enclosed in double
15208 Lines starting with a @# character are comments, and are ignored, and @# may
15209 also appear following a comma, in which case everything between the @# and the
15210 next newline character is ignored.
15212 If an item is entirely enclosed in double quotes, these are removed. Otherwise
15213 double quotes are retained because some forms of mail address require their use
15214 (but never to enclose the entire address). In the following description, `item'
15215 refers to what remains after any surrounding double quotes have been removed.
15217 \**Warning**\: If you use an Exim expansion to construct a redirection address,
15218 and the expansion contains a reference to \$local@_part$\, you should make use
15219 of the \quote\ expansion operator, in case the local part contains special
15220 characters. For example, to redirect all mail for the domain
15221 \*obsolete.example*\, retaining the existing local part, you could use this
15224 data = ${quote:$local_part}@newdomain.example
15228 .section Redirecting to a local mailbox
15229 .rset SECTredlocmai "~~chapter.~~section"
15230 .index routing||loops in
15231 .index loop||while routing, avoidance of
15232 .index address redirection||to local mailbox
15233 A redirection item may safely be the same as the address currently under
15234 consideration. This does not cause a routing loop, because a router is
15235 automatically skipped if any ancestor of the address that is being processed
15237 is the same as the current address and was processed by the current router.
15239 Such an address is therefore passed to the following routers, so it is handled
15240 as if there were no redirection. When making this loop-avoidance test, the
15241 complete local part, including any prefix or suffix, is used.
15243 .index address redirection||local part without domain
15244 Specifying the same local part without a domain is a common usage in personal
15245 filter files when the user wants to have messages delivered to the local
15246 mailbox and also forwarded elsewhere. For example, the user whose login is
15247 \*cleo*\ might have a \(.forward)\ file containing this:
15249 cleo, cleopatra@egypt.example
15251 .index backslash in alias file
15252 .index alias file||backslash in
15253 For compatibility with other MTAs, such unqualified local parts may be
15254 preceeded by `@\', but this is not a requirement for loop prevention. However,
15255 it does make a difference if more than one domain is being handled
15258 If an item begins with `@\' and the rest of the item parses as a valid RFC 2822
15259 address that does not include a domain, the item is qualified using the domain
15260 of the incoming address. In the absence of a leading `@\', unqualified
15261 addresses are qualified using the value in \qualify@_recipient\, but you can
15262 force the incoming domain to be used by setting \qualify__preserve@_domain\.
15264 Care must be taken if there are alias names for local users.
15266 Consider an MTA handling a single local domain where the system alias file
15271 Now suppose that Sam (whose login id is \*spqr*\) wants to save copies of
15272 messages in the local mailbox, and also forward copies elsewhere. He creates
15275 Sam.Reman, spqr@reme.elsewhere.example
15277 With these settings, an incoming message addressed to \*Sam.Reman*\ fails. The
15278 \%redirect%\ router for system aliases does not process \*Sam.Reman*\ the
15279 second time round, because it has previously routed it,
15281 and the following routers presumably cannot handle the alias. The forward file
15282 should really contain
15284 spqr, spqr@reme.elsewhere.example
15286 but because this is such a common error, the \check@_ancestor\ option (see
15287 below) exists to provide a way to get round it. This is normally set on a
15288 \%redirect%\ router that is handling users' \(.forward)\ files.
15291 .section Special items in redirection lists
15292 .rset SECTspecitredli "~~chapter.~~section"
15293 In addition to addresses, the following types of item may appear in redirection
15294 lists (that is, in non-filter redirection data):
15297 .index pipe||in redirection list
15298 .index address redirection||to pipe
15299 An item is treated as a pipe command if it begins with `|' and does not parse
15300 as a valid RFC 2822 address that includes a domain. A transport for running the
15301 command must be specified by the \pipe@_transport\ option.
15303 Normally, either the router or the transport specifies a user and a group under
15304 which to run the delivery. The default is to use the Exim user and group.
15307 Single or double quotes can be used for enclosing the individual arguments of
15308 the pipe command; no interpretation of escapes is done for single quotes. If
15309 the command contains a comma character, it is necessary to put the whole item
15310 in double quotes, for example:
15312 "|/some/command ready,steady,go"
15314 since items in redirection lists are terminated by commas. Do not, however,
15315 quote just the command. An item such as
15317 |"/some/command ready,steady,go"
15319 is interpreted as a pipe with a rather strange command name, and no arguments.
15321 .index file||in redirection list
15322 .index address redirection||to file
15323 An item is interpreted as a path name if it begins with `/' and does not parse
15324 as a valid RFC 2822 address that includes a domain. For example,
15326 /home/world/minbari
15328 is treated as a file name, but
15330 /s=molari/o=babylon/@x400gate.way
15332 is treated as an address. For a file name, a transport must be specified using
15333 the \file@_transport\ option. However, if the generated path name ends with a
15334 forward slash character, it is interpreted as a directory name rather than a
15335 file name, and \directory@_transport\ is used instead.
15338 Normally, either the router or the transport specifies a user and a group under
15339 which to run the delivery. The default is to use the Exim user and group.
15340 .index \(/dev/null)\
15341 However, if a redirection item is the path \(/dev/null)\, delivery to it is
15342 bypassed at a high level, and the log entry shows `$*$$*$bypassed$*$$*$'
15343 instead of a transport name. In this case the user and group are not used.
15346 .index included address list
15347 .index address redirection||included external list
15348 If an item is of the form
15350 :include:<<path name>>
15352 a list of further items is taken from the given file and included at that
15354 \**Note**\: such a file can not be a filter file; it is just an out-of-line
15355 addition to the list.
15356 The items in the included list are separated by commas or newlines and are not
15357 subject to expansion. If this is the first item in an alias list in an
15358 \%lsearch%\ file, a colon must be used to terminate the alias name. This
15359 example is incorrect:
15361 list1 :include:/opt/lists/list1
15363 It must be given as
15365 list1: :include:/opt/lists/list1
15368 .index address redirection||to black hole
15369 Sometimes you want to throw away mail to a particular local part. Making the
15370 \data\ option expand to an empty string does not work, because that causes the
15371 router to decline. Instead, the alias item
15373 .index abandoning mail
15377 can be used. It does what its name implies. No delivery is done, and no error
15378 message is generated. This has the same effect as specifing \(/dev/null)\, but
15379 can be independently disabled.
15381 \**Warning**\: If \":blackhole:"\ appears anywhere in a redirection list, no
15382 delivery is done for the original local part, even if other redirection items
15383 are present. If you are generating a multi-item list (for example, by reading a
15384 database) and need the ability to provide a no-op item, you must use
15388 .index delivery||forcing failure
15389 .index delivery||forcing deferral
15390 .index failing delivery||forcing
15391 .index deferred delivery, forcing
15392 .index customizing||failure message
15393 An attempt to deliver a particular address can be deferred or forced to fail by
15394 redirection items of the form
15400 respectively. When a redirection list contains such an item, it applies to the
15401 entire redirection; any other items in the list are ignored (:::blackhole:: is
15402 different). Any text following :::fail:: or :::defer:: is placed in the error
15403 text associated with the failure. For example, an alias file might contain:
15405 X.Employee: :fail: Gone away, no forwarding address
15407 In the case of an address that is being verified from an ACL or as the subject
15408 of a \\VRFY\\ command, the text is included in the SMTP error response by
15409 default. In an ACL, an explicitly provided message overrides the default, but
15410 the default message is available in the variable \$acl@_verify@_message$\ and
15411 can therefore be included in a custom message if this is desired. Exim sends a
15412 451 SMTP code for a :::defer::, and 550 for :::fail::. In non-SMTP cases the
15413 text is included in the error message that Exim generates.
15417 Normally the error text is the rest of the redirection list -- a comma does not
15418 terminate it -- but a newline does act as a terminator. Newlines are not
15419 normally present in alias expansions. In \%lsearch%\ lookups they are removed as
15420 part of the continuation process, but they may exist in other kinds of lookup
15421 and in :::include:: files.
15423 During routing for message delivery (as opposed to verification), a redirection
15424 containing :::fail:: causes an immediate failure of the incoming address,
15425 whereas :::defer:: causes the message to remain on the queue so that a
15426 subsequent delivery attempt can happen at a later time. If an address is
15427 deferred for too long, it will ultimately fail, because the normal retry
15430 .index alias file||exception to default
15431 Sometimes it is useful to use a single-key search type with a default (see
15432 chapter ~~CHAPfdlookup) to look up aliases. However, there may be a need for
15433 exceptions to the default. These can be handled by aliasing them to
15437 This differs from :::fail:: in that it causes the \%redirect%\ router to decline,
15438 whereas :::fail:: forces routing to fail. A lookup which results in an empty
15439 redirection list has the same effect.
15442 .section Duplicate addresses
15443 .index duplicate addresses
15444 .index address||duplicate, discarding
15445 .index pipe||duplicated
15446 Exim removes duplicate addresses from the list to which it is delivering, so as
15447 to deliver just one copy to each address. This does not apply to deliveries
15448 routed to pipes by different immediate parent addresses, but an indirect
15449 aliasing scheme of the type
15451 pipe: |/some/command $local_part
15455 does not work with a message that is addressed to both local parts, because
15456 when the second is aliased to the intermediate local part `pipe' it gets
15457 discarded as being the same as a previously handled address. However, a scheme
15460 localpart1: |/some/command $local_part
15461 localpart2: |/some/command $local_part
15463 does result in two different pipe deliveries, because the immediate parents of
15464 the pipes are distinct.
15467 .section Repeated redirection expansion
15468 .index repeated redirection expansion
15469 .index address redirection||repeated for each delivery attempt
15470 When a message cannot be delivered to all of its recipients immediately,
15471 leading to two or more delivery attempts, redirection expansion is carried out
15472 afresh each time for those addresses whose children were not all previously
15473 delivered. If redirection is being used as a mailing list, this can lead to new
15474 members of the list receiving copies of old messages. The \one@_time\ option
15475 can be used to avoid this.
15477 .section Errors in redirection lists
15478 .index address redirection||errors
15479 If \skip@_syntax@_errors\ is set, a malformed address that causes a parsing
15480 error is skipped, and an entry is written to the main log. This may be useful
15481 for mailing lists that are automatically managed. Otherwise, if an error is
15482 detected while generating the list of new addresses, the original address is
15483 deferred. See also \syntax@_errors@_to\.
15486 .section Private options for the redirect router
15488 The private options for the \%redirect%\ router are as follows:
15491 .index options||\%redirect%\ router
15493 .conf allow@_defer boolean false
15494 Setting this option allows the use of :::defer:: in non-filter redirection
15496 or the \defer\ command in an Exim filter file.
15498 .conf allow@_fail boolean false
15499 .index failing delivery||from filter
15500 If this option is true, the :::fail:: item can be used in a redirection list,
15501 and the \fail\ command may be used in a filter file.
15503 .conf allow@_filter boolean false
15504 .index filter||enabling use of
15505 .index Sieve filter||enabling use of
15506 Setting this option allows Exim to interpret redirection data that starts with
15507 `@#Exim filter' or `@#Sieve filter' as a set of filtering instructions. There
15508 are some features of Exim filter files that some administrators may wish to
15509 lock out; see the \forbid@_filter@_xxx\ options below. The filter is run using
15510 the uid and gid set by the generic \user\ and \group\ options. These take their
15511 defaults from the password data if \check@_local@_user\ is set, so in the
15512 normal case of users' personal filter files, the filter is run as the relevant
15513 user. When \allow@_filter\ is set true, Exim insists that either
15514 \check@_local@_user\ or \user\ is set.
15517 .conf allow@_freeze boolean false
15518 .index freezing messages||allowing in filter
15519 Setting this option allows the use of the \freeze\ command in an Exim filter.
15520 This command is more normally encountered in system filters, and is disabled by
15521 default for redirection filters because it isn't something you usually want to
15522 let ordinary users do.
15525 .conf check@_ancestor boolean false
15526 This option is concerned with handling generated addresses that are the same
15527 as some address in the list of redirection ancestors of the current address.
15528 Although it is turned off by default in the code, it is set in the default
15529 configuration file for handling users' \(.forward)\ files. It is recommended
15530 for this use of the \%redirect%\ router.
15533 When \check@_ancestor\ is set, if a generated address (including the domain) is
15534 the same as any ancestor of the current address, it is replaced by a copy of
15535 the current address. This helps in the case where local part A is aliased to B,
15536 and B has a \(.forward)\ file pointing back to A. For example, within a single
15537 domain, the local part `Joe.Bloggs' is aliased to `jb' and \(@~jb/.forward)\
15541 @\Joe.Bloggs, <<other item(s)>>
15543 Without the \check@_ancestor\ setting, either local part (`jb' or `joe.bloggs')
15544 gets processed once by each router and so ends up as it was originally. If `jb'
15545 is the real mailbox name, mail to `jb' gets delivered (having been turned into
15546 `joe.bloggs' by the \(.forward)\ file and back to `jb' by the alias), but mail
15547 to `joe.bloggs' fails. Setting \check@_ancestor\ on the \%redirect%\ router that
15548 handles the \(.forward)\ file prevents it from turning `jb' back into
15549 `joe.bloggs' when that was the original address. See also the \repeat@_use\
15552 .conf check@_group boolean "see below"
15553 When the \file\ option is used, the group owner of the file is checked only
15554 when this option is set. The permitted groups are those listed in the
15555 \owngroups\ option, together with the user's default group if
15556 \check@_local@_user\ is set. If the file has the wrong group, routing is
15557 deferred. The default setting for this option is true if \check@_local@_user\
15558 is set and the \modemask\ option permits the group write bit, or if the
15559 \owngroups\ option is set. Otherwise it is false, and no group check occurs.
15562 .conf check@_owner boolean "see below"
15563 When the \file\ option is used, the owner of the file is checked only when this
15564 option is set. If \check@_local@_user\ is set, the local user is permitted;
15565 otherwise the owner must be one of those listed in the \owners\ option. The
15566 default value for this option is true if \check@_local@_user\ or \owners\ is
15567 set. Otherwise the default is false, and no owner check occurs.
15569 .conf data string$**$ unset
15570 This option is mutually exclusive with \file\. One or other of them must be
15571 set, but not both. The contents of \data\ are expanded, and then used as the
15572 list of forwarding items, or as a set of filtering instructions. If the
15573 expansion is forced to fail, or the result is an empty string or a string that
15574 has no effect (consists entirely of comments), the router declines.
15576 When filtering instructions are used, the string must begin with `@#Exim
15577 filter', and all comments in the string, including this initial one, must be
15578 terminated with newline characters. For example:
15580 data = #Exim filter\n\
15581 if $h_to: contains Exim then save $home/mail/exim endif
15583 If you are reading the data from a database where newlines cannot be included,
15584 you can use the \$@{sg@}$\ expansion item to turn the escape string of your
15585 choice into a newline.
15587 .conf directory@_transport string$**$ unset
15588 A \%redirect%\ router sets up a direct delivery to a directory when a path name
15589 ending with a slash is specified as a new `address'. The transport used is
15590 specified by this option, which, after expansion, must be the name of a
15591 configured transport. This should normally be an \%appendfile%\ transport.
15593 .conf file string$**$ unset
15594 This option specifies the name of a file that contains the redirection data. It
15595 is mutually exclusive with the \data\ option. The string is expanded before
15596 use; if the expansion is forced to fail, the router declines. Other expansion
15597 failures cause delivery to be deferred. The result of a successful expansion
15598 must be an absolute path. The entire file is read and used as the redirection
15599 data. If the data is an empty string or a string that has no effect (consists
15600 entirely of comments), the router declines.
15602 .index NFS||checking for file existence
15603 If the attempt to open the file fails with a `does not exist' error, Exim
15604 runs a check on the containing directory,
15605 unless \ignore@_enotdir\ is true (see below).
15606 If the directory does not appear to exist, delivery is deferred. This can
15607 happen when users' \(.forward)\ files are in NFS-mounted directories, and there
15608 is a mount problem. If the containing directory does exist, but the file does
15609 not, the router declines.
15611 .conf file@_transport string$**$ unset
15612 A \%redirect%\ router sets up a direct delivery to a file when a path name not
15613 ending in a slash is specified as a new `address'. The transport used is
15614 specified by this option, which, after expansion, must be the name of a
15615 configured transport.
15616 This should normally be an \%appendfile%\ transport.
15617 When it is running, the file name is in \$address@_file$\.
15619 .conf forbid@_blackhole boolean false
15620 If this option is true, the :::blackhole:: item may not appear in a redirection
15623 .conf forbid@_file boolean false
15624 .index delivery||to file, forbidding
15625 .index Sieve filter||forbidding delivery to a file
15626 .index Sieve filter||`keep' facility, disabling
15627 If this option is true, this router may not generate a new address that
15628 specifies delivery to a local file or directory, either from a filter or from a
15629 conventional forward file. This option is forced to be true if \one@_time\ is
15630 set. It applies to Sieve filters as well as to Exim filters, but if true, it
15631 locks out the Sieve's `keep' facility.
15633 .conf forbid@_filter@_existstest boolean false
15634 .index filter||locking out certain features
15635 If this option is true, string expansions in Exim filters are not allowed to
15636 make use of the \exists\ condition.
15638 .conf forbid@_filter@_logwrite boolean false
15639 If this option is true, use of the logging facility in Exim filters is not
15640 permitted. Logging is in any case available only if the filter is being run
15641 under some unprivileged uid (which is normally the case for ordinary users'
15642 \(.forward)\ files).
15644 .conf forbid@_filter@_lookup boolean false
15645 If this option is true, string expansions in Exim filter files are not allowed
15646 to make use of \lookup\ items.
15648 .conf forbid@_filter@_perl boolean false
15649 This option is available only if Exim is built with embedded Perl support. If
15650 it is true, string expansions in Exim filter files are not allowed to make use
15651 of the embedded Perl support.
15653 .conf forbid@_filter@_readfile boolean false
15654 If this option is true, string expansions in Exim filter files are not allowed
15655 to make use of \readfile\ items.
15657 .conf forbid@_filter@_readsocket boolean false
15658 If this option is true, string expansions in Exim filter files are not allowed
15659 to make use of \readsocket\ items.
15661 .conf forbid@_filter@_reply boolean false
15662 If this option is true, this router may not generate an automatic reply
15663 message. Automatic replies can be generated only from Exim filter files, not
15664 from traditional forward files or Sieve filters. This option is forced to be
15665 true if \one@_time\ is set.
15667 .conf forbid@_filter@_run boolean false
15668 If this option is true, string expansions in Exim filter files are not allowed
15669 to make use of \run\ items.
15671 .conf forbid@_include boolean false
15672 If this option is true, items of the form
15674 :include:<<path name>>
15676 are not permitted in non-filter redirection lists.
15678 .conf forbid@_pipe boolean false
15679 .index delivery||to pipe, forbidding
15680 If this option is true, this router may not generate a new address which
15681 specifies delivery to a pipe, either from an Exim filter or from a conventional
15682 forward file. This option is forced to be true if \one@_time\ is set.
15684 .conf hide@_child@_in@_errmsg boolean false
15685 .index bounce message||redirection details, suppressing
15686 If this option is true, it prevents Exim from quoting a child address if it
15687 generates a bounce or delay message for it. Instead it says `an address
15688 generated from <<the top level address>>'. Of course, this applies only to
15689 bounces generated locally. If a message is forwarded to another host, $it{its}
15690 bounce may well quote the generated address.
15692 .conf ignore@_eacces boolean false
15694 If this option is set and an attempt to open a redirection file yields the
15695 \\EACCES\\ error (permission denied), the \%redirect%\ router behaves as if the
15696 file did not exist.
15698 .conf ignore@_enotdir boolean false
15700 If this option is set and an attempt to open a redirection file yields the
15701 \\ENOTDIR\\ error (something on the path is not a directory), the \%redirect%\
15702 router behaves as if the file did not exist.
15704 Setting \ignore@_enotdir\ has another effect as well: When a \%redirect%\
15705 router that has the \file\ option set discovers that the file does not exist
15706 (the \\ENOENT\\ error), it tries to \*stat()*\ the parent directory, as a check
15707 against unmounted NFS directories. If the parent can not be statted, delivery
15708 is deferred. However, it seems wrong to do this check when \ignore@_enotdir\ is
15709 set, because that option tells Exim to ignore `something on the path is not a
15710 directory' (the \\ENOTDIR\\ error). This is a confusing area, because it seems
15711 that some operating systems give \\ENOENT\\ where others give \\ENOTDIR\\.
15714 .conf include@_directory string unset
15715 If this option is set, the path names of any :::include:: items in a redirection
15716 list must start with this directory.
15718 .conf modemask "octal integer" 022
15719 This specifies mode bits which must not be set for a file specified by the
15720 \file\ option. If any of the forbidden bits are set, delivery is deferred.
15722 .conf one@_time boolean false
15723 .index one-time aliasing/forwarding expansion
15724 .index alias file||one-time expansion
15725 .index forward file||one-time expansion
15726 .index mailing lists||one-time expansion
15727 .index address redirection||one-time expansion
15728 Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
15729 files each time it tries to deliver a message causes a problem
15730 when one or more of the generated addresses fails be delivered at the first
15731 attempt. The problem is not one of duplicate delivery -- Exim is clever enough
15732 to handle that -- but of what happens when the redirection list changes during
15733 the time that the message is on Exim's queue. This is particularly true in the
15734 case of mailing lists, where new subscribers might receive copies of messages
15735 that were posted before they subscribed.
15737 If \one@_time\ is set and any addresses generated by the router fail to
15738 deliver at the first attempt, the failing addresses are added to the message as
15739 `top level' addresses, and the parent address that generated them is marked
15740 `delivered'. Thus, redirection does not happen again at the next
15743 \**Warning 1**\: This means that any header line addition or removal that is
15744 specified by this router would be lost if delivery did not succeed at the
15745 first attempt. For this reason, the \headers@_add\ and \headers@_remove\
15746 generic options are not permitted when \one@_time\ is set.
15748 \**Warning 2**\: To ensure that the router generates only addresses (as opposed
15749 to pipe or file deliveries or auto-replies) \forbid@_file\, \forbid@_pipe\,
15750 and \forbid@_filter@_reply\ are forced to be true when \one@_time\ is set.
15752 The original top-level address is remembered with each of the generated
15753 addresses, and is output in any log messages. However, any intermediate parent
15754 addresses are not recorded. This makes a difference to the log only if
15755 \all__parents\ log selector is set. It is expected that \one@_time\ will
15756 typically be used for mailing lists, where there is normally just one level of
15759 .conf owners "string list" unset
15760 .index ownership||alias file
15761 .index ownership||forward file
15762 .index alias file||ownership
15763 .index forward file||ownership
15764 This specifies a list of permitted owners for the file specified by \file\.
15765 This list is in addition to the local user when \check@_local@_user\ is set.
15766 See \check@_owner\ above.
15768 .conf owngroups "string list" unset
15769 This specifies a list of permitted groups for the file specified by \file\. The
15770 list is in addition to the local user's primary group when \check@_local@_user\
15771 is set. See \check@_group\ above.
15774 .conf qualify@_domain string$**$ unset
15775 If this option is set and an unqualified address (one without a domain) is
15776 generated, it is qualified with the domain specified by expanding this string,
15777 instead of the global setting in \qualify@_recipient\. If the expansion fails,
15778 the router declines. If you want to revert to the default, you can have the
15779 expansion generate \$qualify@_recipient$\.
15782 .conf pipe@_transport string$**$ unset
15783 A \%redirect%\ router sets up a direct delivery to a pipe when a string starting
15784 with a vertical bar character is specified as a new `address'. The transport
15785 used is specified by this option, which, after expansion, must be the name of a
15786 configured transport.
15787 This should normally be a \%pipe%\ transport.
15788 When the transport is run, the pipe command is in \$address@_pipe$\.
15790 .conf qualify@_preserve@_domain boolean false
15791 .index domain||in redirection, preserving
15792 .index preserving domain in redirection
15793 .index address redirection||domain, preserving
15794 If this is set and an unqualified address (one without a domain) is generated,
15795 it is qualified with the domain of the
15797 parent address (the immediately preceding ancestor) instead of the local
15798 \qualify@_domain\ or global \qualify@_recipient\ value.
15801 .conf repeat@_use boolean true
15802 If this option is set false, the router is skipped for a child address that has
15803 any ancestor that was routed by this router. This test happens before any of
15804 the other preconditions are tested. Exim's default anti-looping rules skip
15805 only when the ancestor is the same as the current address. See also
15806 \check@_ancestor\ above and the generic \redirect@_router\ option.
15808 .conf reply@_transport string$**$ unset
15809 A \%redirect%\ router sets up an automatic reply when a \mail\ or \vacation\
15810 command is used in a filter file. The transport used is specified by this
15811 option, which, after expansion, must be the name of a configured transport.
15812 This should normally be an \%autoreply%\ transport. Other transports are
15813 unlikely to do anything sensible or useful.
15815 .conf rewrite boolean true
15816 .index address redirection||disabling rewriting
15817 If this option is set false, addresses generated by the router are not
15818 subject to address rewriting. Otherwise, they are treated like new addresses
15819 and are rewritten according to the global rewriting rules.
15821 .conf skip@_syntax@_errors boolean false
15822 .index forward file||broken
15823 .index address redirection||broken files
15824 .index alias file||broken
15825 .index broken alias or forward files
15826 .index ignoring faulty addresses
15827 .index skipping faulty addresses
15828 .index error||skipping bad syntax
15829 If \skip@_syntax@_errors\ is set, syntactically malformed addresses in
15830 non-filter redirection data are skipped, and each failing address is logged. If
15831 \syntax@_errors@_to\ is set, a message is sent to the address it defines,
15832 giving details of the failures. If \syntax@_errors@_text\ is set, its contents
15833 are expanded and placed at the head of the error message generated by
15834 \syntax@_errors@_to\. Usually it is appropriate to set \syntax@_errors@_to\ to
15835 be the same address as the generic \errors@_to\ option. The
15836 \skip@_syntax@_errors\ option is often used when handling mailing lists.
15838 If all the addresses in a redirection list are skipped because of syntax
15839 errors, the router declines to handle the original address, and it is passed to
15840 the following routers.
15842 If \skip@_syntax@_errors\ is set when an Exim filter is interpreted, any syntax
15843 error in the filter causes filtering to be abandoned without any action being
15844 taken. The incident is logged, and the router declines to handle the address,
15845 so it is passed to the following routers.
15847 .index Sieve filter||syntax errors in
15848 Currently, any syntax errors in a Sieve filter file cause the `keep' action to
15849 occur. The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and
15850 \syntax@_errors@_text\ are not used.
15852 \skip@_syntax@_errors\ can be used to specify that errors in users' forward
15853 lists or filter files should not prevent delivery. The \syntax@_errors@_to\
15854 option, used with an address that does not get redirected, can be used to
15855 notify users of these errors, by means of a router like this:
15861 file = $home/.forward
15862 file_transport = address_file
15863 pipe_transport = address_pipe
15864 reply_transport = address_reply
15867 syntax_errors_to = real-$local_part@$domain
15868 syntax_errors_text = \
15869 This is an automatically generated message. An error has\n\
15870 been found in your .forward file. Details of the error are\n\
15871 reported below. While this error persists, you will receive\n\
15872 a copy of this message for every message that is addressed\n\
15873 to you. If your .forward file is a filter file, or if it is\n\
15874 a non-filter file containing no valid forwarding addresses,\n\
15875 a copy of each incoming message will be put in your normal\n\
15876 mailbox. If a non-filter file contains at least one valid\n\
15877 forwarding address, forwarding to the valid addresses will\n\
15878 happen, and those will be the only deliveries that occur.
15880 You also need a router to ensure that local addresses that are prefixed by
15881 \"real-"\ are recognized, but not forwarded or filtered. For example, you could
15882 put this immediately before the \%userforward%\ router:
15887 local_part_prefix = real-
15888 transport = local_delivery
15891 .conf syntax@_errors@_text string$**$ unset
15892 See \skip@_syntax@_errors\ above.
15894 .conf syntax@_errors@_to string unset
15895 See \skip@_syntax@_errors\ above.
15906 . ============================================================================
15907 .chapter Environment for running local transports
15908 .rset CHAPenvironment "~~chapter"
15909 .set runningfoot "local transport environment"
15910 .index local transports||environment for
15911 .index environment for local transports
15912 .index transport||local, environment for
15913 Local transports handle deliveries to files and pipes. (The \%autoreply%\
15914 transport can be thought of as similar to a pipe.) Exim always runs transports
15915 in subprocesses, under specified uids and gids. Typical deliveries to local
15916 mailboxes run under the uid and gid of the local user.
15918 Exim also sets a specific current directory while running the transport; for
15919 some transports a home directory setting is also relevant. The \%pipe%\
15920 transport is the only one which sets up environment variables; see section
15921 ~~SECTpipeenv for details.
15923 The values used for the uid, gid, and the directories may come from several
15924 different places. In many cases, the router that handles the address associates
15925 settings with that address as a result of its \check@_local@_user\, \group\, or
15926 \user\ options. However, values may also be given in the transport's own
15927 configuration, and these override anything that comes from the router.
15929 .section Uids and gids
15930 .rset SECTenvuidgid "~~chapter.~~section"
15931 .index local transports||uid and gid
15932 .index transport||local, uid and gid
15933 All transports have the options \group\ and \user\. If \group\ is set, it
15934 overrides any group that the router set in the address, even if \user\ is not
15935 set for the transport. This makes it possible, for example, to run local mail
15936 delivery under the uid of the recipient (set by the router), but in a special
15937 group (set by the transport). For example:
15940 # User/group are set by check_local_user in this router
15944 transport = group_delivery
15947 # This transport overrides the group
15949 driver = appendfile
15950 file = /var/spool/mail/$local_part
15953 If \user\ is set for a transport, its value overrides what is set in the
15954 address. If \user\ is non-numeric and \group\ is not set, the gid associated
15955 with the user is used. If \user\ is numeric, \group\ must be set.
15957 .index \initgroups\ option
15958 When the uid is taken from the transport's configuration, the \*initgroups()*\
15959 function is called for the groups associated with that uid if the \initgroups\
15960 option is set for the transport. When the uid is not specified by the
15961 transport, but is associated with the address by a router, the option for
15962 calling \*initgroups()*\ is taken from the router configuration.
15964 .index \%pipe%\ transport||uid for
15965 The \%pipe%\ transport contains the special option \pipe@_as@_creator\. If this
15966 is set and \user\ is not set, the uid of the process that called Exim to
15967 receive the message is used, and if \group\ is not set, the corresponding
15968 original gid is also used.
15971 .section Current and home directories
15972 .index current directory for local transport
15973 .index home directory||for local transport
15974 .index transport||local, home directory for
15975 .index transport||local, current directory for
15976 Routers may set current and home directories for local transports by means of
15977 the \transport__current@_directory\ and \transport@_home@_directory\ options.
15978 However, if the transport's \current__directory\ or \home@_directory\ options
15979 are set, they override the router's values. In detail, the home directory
15980 for a local transport is taken from the first of these values that is set:
15982 The \home@_directory\ option on the transport;
15984 The \transport@_home@_directory\ option on the router;
15986 The password data if \check@_local@_user\ is set on the router;
15988 The \router@_home@_directory\ option on the router.
15990 The current directory is taken from the first of these values that is set:
15992 The \current@_directory\ option on the transport;
15994 The \transport@_current@_directory\ option on the router.
15997 If neither the router nor the transport sets a current directory, Exim uses the
15998 value of the home directory, if it is set. Otherwise it sets the current
15999 directory to \(/)\ before running a local transport.
16002 .section Expansion variables derived from the address
16003 Normally a local delivery is handling a single address, and in that case the
16004 variables such as \$domain$\ and \$local@_part$\ are set during local
16005 deliveries. However, in some circumstances more than one address may be handled
16006 at once (for example, while writing batch SMTP for onward transmission by some
16007 other means). In this case, the variables associated with the local part are
16008 never set, \$domain$\ is set only if all the addresses have the same
16009 domain, and \$original@_domain$\ is never set.
16020 . ============================================================================
16021 .chapter Generic options for transports
16022 .rset CHAPtransportgeneric "~~chapter"
16023 .set runningfoot "generic transport options"
16025 .index generic options||transport
16026 .index options||generic, for transports
16027 .index transport||generic options for
16028 The following generic options apply to all transports:
16031 .conf body@_only boolean false
16032 .index transport||body only
16033 .index message||transporting body only
16034 .index body of message||transporting
16035 If this option is set, the message's headers are not transported. It is
16036 mutually exclusive with \headers@_only\. If it is used with the \%appendfile%\ or
16037 \%pipe%\ transports, the settings of \message@_prefix\ and \message@_suffix\
16038 should be checked, because this option does not automatically suppress them.
16040 .conf current@_directory string$**$ unset
16041 .index transport||current directory for
16042 This specifies the current directory that is to be set while running the
16043 transport, overriding any value that may have been set by the router.
16044 If the expansion fails for any reason, including forced failure, an error is
16045 logged, and delivery is deferred.
16047 .conf disable@_logging boolean false
16048 If this option is set true, nothing is logged for any
16050 deliveries by the transport or for any
16052 transport errors. You should not set this option unless you really, really know
16053 what you are doing.
16055 .conf debug@_print string$**$ unset
16056 .index testing||variables in drivers
16057 If this option is set and debugging is enabled (see the \-d-\ command line
16058 option), the string is expanded and included in the debugging output when the
16060 If expansion of the string fails, the error message is written to the debugging
16061 output, and Exim carries on processing.
16062 This facility is provided to help with checking out the values of variables and
16063 so on when debugging driver configurations. For example, if a \headers@_add\
16064 option is not working properly, \debug@_print\ could be used to output the
16065 variables it references. A newline is added to the text if it does not end with
16068 .conf delivery@_date@_add boolean false
16069 .index ::Delivery-date:: header line
16070 If this option is true, a ::Delivery-date:: header is added to the message. This
16071 gives the actual time the delivery was made. As this is not a standard header,
16072 Exim has a configuration option (\delivery@_date@_remove\) which requests its
16073 removal from incoming messages, so that delivered messages can safely be resent
16074 to other recipients.
16076 .conf driver string unset
16077 This specifies which of the available transport drivers is to be used.
16078 There is no default, and this option must be set for every transport.
16080 .conf envelope@_to@_add boolean false
16081 .index ::Envelope-to:: header line
16082 If this option is true, an ::Envelope-to:: header is added to the message. This
16083 gives the original address(es) in the incoming envelope that caused this
16084 delivery to happen. More than one address may be present if the transport is
16085 configured to handle several addresses at once, or if more than one original
16086 address was redirected to the same final address. As this is not a standard
16087 header, Exim has a configuration option (\envelope@_to@_remove\) which requests
16088 its removal from incoming messages, so that delivered messages can safely be
16089 resent to other recipients.
16091 .conf group string$**$ "Exim group"
16092 .index transport||group, specifying
16093 This option specifies a gid for running the transport process, overriding any
16094 value that the router supplies, and also overriding any value associated with
16095 \user\ (see below).
16097 .conf headers@_add string$**$ unset
16098 .index header lines||adding in transport
16099 .index transport||header lines, adding
16100 This option specifies a string of text which is expanded and added to the
16101 header portion of a message as it is transported. If the result of the
16102 expansion is an empty string, or if the expansion is forced to fail, no action
16103 is taken. Other expansion failures are treated as errors and cause the delivery
16104 to be deferred. The expanded string should be in the form of one or more RFC
16105 2822 header lines, separated by newlines (coded as `@\n'), for example:
16107 headers_add = X-added: this is a header added at $tod_log\n\
16108 X-added: this is another
16110 Exim does not check the syntax of these added header lines. They are added at
16111 the end of the existing header lines. If you include a blank line within the
16112 string, you can subvert this facility into adding text at the start of the
16113 message's body. This is not recommended. Additional header lines can also be
16114 specified by routers. See chapter ~~CHAProutergeneric and section
16115 ~~SECTheadersaddrem.
16117 .conf headers@_only boolean false
16118 .index transport||header lines only
16119 .index message||transporting headers only
16120 .index header lines||transporting
16121 If this option is set, the message's body is not transported. It is mutually
16122 exclusive with \body@_only\. If it is used with the \%appendfile%\ or \%pipe%\
16123 transports, the settings of \message@_prefix\ and \message__suffix\ should be
16124 checked, since this option does not automatically suppress them.
16126 .conf headers@_remove string$**$ unset
16127 .index header lines||removing
16128 .index transport||header lines, removing
16129 This option is expanded; the result must consist of a colon-separated list of
16130 header names, not including the terminating colon, for example:
16132 headers_remove = return-receipt-to:acknowledge-to
16134 Any existing headers matching those names are not included in any message that
16135 is transmitted by the transport.
16136 If the result of the expansion is an empty string, or if the expansion is
16137 forced to fail, no action is taken. Other expansion failures are treated as
16138 errors and cause the delivery to be deferred.
16140 If there are multiple instances of a header, they are all removed. However,
16141 added headers may have these names. Thus it is possible to replace a header by
16142 specifying it in \headers@_remove\ and supplying the replacement in
16143 \headers@_add\. Headers to be removed can also be specified by routers. See
16144 chapter ~~CHAProutergeneric and section ~~SECTheadersaddrem.
16146 .conf headers@_rewrite string unset
16147 .index transport||header lines, rewriting
16148 .index rewriting||at transport time
16149 This option allows addresses in header lines to be rewritten at transport time,
16150 that is, as the message is being copied to its destination. The contents of the
16151 option are a colon-separated list of rewriting rules. Each rule is in exactly
16152 the same form as one of the general rewriting rules that are applied when a
16153 message is received. These are described in chapter ~~CHAPrewrite. For example,
16155 headers_rewrite = a@b c@d f : \
16158 changes \a@@b\ into \c@@d\ in ::From:: header lines, and \x@@y\ into \w@@z\ in
16159 all address-bearing header lines. The rules are applied to the header lines
16160 just before they are written out at transport time, so they affect only those
16161 copies of the message that pass through the transport. However, only the
16162 message's original header lines, and any that were added by a system filter,
16163 are rewritten. If a router or transport adds header lines, they are
16164 not affected by this option. These rewriting rules are $it{not} applied to the
16165 envelope. You can change the return path using \return@_path\, but you cannot
16166 change envelope recipients at this time.
16168 .conf home@_directory string$**$ unset
16169 .index transport||home directory for
16170 This option specifies a home directory setting for the transport, overriding
16171 any value that may be set by the router. The home directory is placed in
16172 \$home$\ while expanding the transport's private options. It is also used as
16173 the current directory if no current directory is set by the
16174 \current__directory\ option on the transport or the
16175 \transport__current__directory\ option on the router.
16176 If the expansion fails for any reason, including forced failure, an error is
16177 logged, and delivery is deferred.
16180 .index additional groups
16181 .index groups, additional
16182 .index transport||group, additional
16183 .conf initgroups boolean false
16184 If this option is true and the uid for the delivery process is provided by the
16185 transport, the \*initgroups()*\ function is called when running the transport
16186 to ensure that any additional groups associated with the uid are set up.
16188 .conf message@_size@_limit string$**$ 0
16189 .index limit||message size per transport
16190 .index size||of message, limit
16191 .index transport||message size, limiting
16192 This option controls the size of messages passed through the transport. It is
16193 expanded before use; the result of the expansion must be a sequence of digits,
16194 optionally followed by K or M.
16195 If the expansion fails for any reason, including forced failure, or if the
16196 result is not of the required form, delivery is deferred.
16197 If the value is greater than zero and the size of a message exceeds this
16198 limit, the address is failed. If there is any chance that the resulting bounce
16199 message could be routed to the same transport, you should ensure that
16200 \return@_size@_limit\ is less than the transport's \message@_size@_limit\, as
16201 otherwise the bounce message will fail to get delivered.
16204 .conf rcpt@_include@_affixes boolean false
16205 .index prefix||for local part, including in envelope
16206 .index suffix||for local part, including in envelope
16207 .index local part||prefix
16208 .index local part||suffix
16209 When this option is false (the default), and an address that has had any
16210 affixes (prefixes or suffixes) removed from the local part is delivered by any
16211 form of SMTP or LMTP, the affixes are not included. For example, if a router
16214 local_part_prefix = *-
16216 routes the address \*abc-xyz@@some.domain*\ to an SMTP transport, the envelope
16219 RCPT TO:<xyz@some.domain>
16221 If \rcpt@_include@_affixes\ is set true, the whole local part is included in
16222 the \\RCPT\\ command. This option applies to BSMTP deliveries by the
16223 \%appendfile%\ and \%pipe%\ transports as well as to the \%lmtp%\ and \%smtp%\
16226 .conf retry@_use@_local@_part boolean "see below"
16227 .index hints database||retry keys
16228 When a delivery suffers a temporary failure, a retry record is created
16229 in Exim's hints database. For remote deliveries, the key for the retry record
16230 is based on the name and/or IP address of the failing remote host. For local
16231 deliveries, the key is normally the entire address, including both the local
16232 part and the domain. This is suitable for most common cases of local delivery
16233 temporary failure -- for example, exceeding a mailbox quota should delay only
16234 deliveries to that mailbox, not to the whole domain.
16236 However, in some special cases you may want to treat a temporary local delivery
16237 as a failure associated with the domain, and not with a particular local part.
16238 (For example, if you are storing all mail for some domain in files.) You can do
16239 this by setting \retry@_use@_local@_part\ false.
16241 For all the local transports, its default value is true. For remote transports,
16242 the default value is false for tidiness, but changing the value has no effect
16243 on a remote transport in the current implementation.
16245 .conf return@_path string$**$ unset
16246 .index envelope sender
16247 .index transport||return path, changing
16248 .index return path||changing in transport
16249 If this option is set, the string is expanded at transport time and replaces
16250 the existing return path (envelope sender) value in the copy of the message
16251 that is being delivered. An empty return path is permitted. This feature is
16252 designed for remote deliveries, where the value of this option is used in the
16253 SMTP \\MAIL\\ command. If you set \return@_path\ for a local transport, the
16254 only effect is to change the address that is placed in the ::Return-path::
16255 header line, if one is added to the message (see the next option).
16257 The expansion can refer to the existing value via \$return@_path$\. This is
16258 either the message's envelope sender, or an address set by the
16259 \errors@_to\ option on a router. If the expansion is forced to fail, no
16260 replacement occurs; if it fails for another reason, delivery is deferred. This
16261 option can be used to support VERP (Variable Envelope Return Paths) -- see
16262 chapter ~~CHAPSMTP.
16264 \**Note**\: If a delivery error is detected locally,
16266 including the case when a remote server rejects a message at SMTP time,
16267 the bounce message is not sent to the value of this option, but to the
16268 previously set errors address (which defaults to the incoming sender address).
16272 .conf return@_path@_add boolean false
16273 .index ::Return-path:: header line
16274 If this option is true, a ::Return-path:: header is added to the message.
16275 Although the return path is normally available in the prefix line of BSD
16276 mailboxes, this is commonly not displayed by MUAs, and so the user does not
16277 have easy access to it.
16279 RFC 2821 states that the ::Return-path:: header is added to a message `when the
16280 delivery SMTP server makes the final delivery'. This implies that this header
16281 should not be present in incoming messages. Exim has a configuration option,
16282 \return@_path@_remove\, which requests removal of this header from incoming
16283 messages, so that delivered messages can safely be resent to other recipients.
16285 .conf shadow@_condition string$**$ unset
16286 See \shadow@_transport\ below.
16288 .conf shadow@_transport string unset
16289 .index shadow transport
16290 .index transport||shadow
16291 A local transport may set the \shadow@_transport\ option to the name of another
16292 local transport. Shadow remote transports are not supported.
16294 Whenever a delivery to the main transport succeeds, and either
16295 \shadow@_condition\ is unset, or its expansion does not result in the empty
16296 string or one of the strings `0' or `no' or `false', the message is also passed
16297 to the shadow transport, with the same delivery address or addresses.
16298 If expansion fails, no action is taken except that non-forced expansion
16299 failures cause a log line to be written.
16301 The result of the shadow transport is discarded and does not affect the
16302 subsequent processing of the message. Only a single level of shadowing is
16303 provided; the \shadow@_transport\ option is ignored on any transport when it is
16304 running as a shadow. Options concerned with output from pipes are also ignored.
16306 The log line for the successful delivery has an item added on the end, of the
16309 ST=<<shadow transport name>>
16311 If the shadow transport did not succeed, the error message is put in
16312 parentheses afterwards.
16314 Shadow transports can be used for a number of different purposes, including
16315 keeping more detailed log information than Exim normally provides, and
16316 implementing automatic acknowledgement policies based on message headers that
16317 some sites insist on.
16319 .conf transport@_filter string$**$ unset
16320 .index transport||filter
16321 .index filter||transport filter
16322 This option sets up a filtering (in the Unix shell sense) process for messages
16323 at transport time. It should not be confused with mail filtering as set up by
16324 individual users or via a system filter.
16326 When the message is about to be written out, the command specified by
16327 \transport@_filter\ is started up in a separate process, and the entire
16328 message, including the header lines, is passed to it on its standard input
16329 (this in fact is done from a third process, to avoid deadlock).
16330 The command must be specified as an absolute path.
16332 The message is passed to the filter before any SMTP-specific processing, such
16333 as turning `@\n' into `@\r@\n' and escaping lines beginning with a dot, and
16334 also before any processing implied by the settings of \check@_string\ and
16335 \escape@_string\ in the \%appendfile%\ or \%pipe%\ transports.
16337 The filter's standard output is read and written to the message's destination.
16338 The filter can perform any transformations it likes, but of course should take
16339 care not to break RFC 2822 syntax. A demonstration Perl script is provided in
16340 \(util/transport-filter.pl)\; this makes a few arbitrary modifications just to
16341 show the possibilities. Exim does not check the result, except to test for a
16342 final newline when SMTP is in use. All messages transmitted over SMTP must end
16343 with a newline, so Exim supplies one if it is missing.
16345 .index SMTP||\\SIZE\\
16346 A problem might arise if the filter increases the size of a message that is
16347 being sent down an SMTP connection. If the receiving SMTP server has indicated
16348 support for the \\SIZE\\ parameter, Exim will have sent the size of the message
16349 at the start of the SMTP session. If what is actually sent is substantially
16350 more, the server might reject the message. This can be worked round by setting
16351 the \size@_addition\ option on the \%smtp%\ transport, either to allow for
16352 additions to the message, or to disable the use of \\SIZE\\ altogether.
16354 The value of the option is the command string for starting up the filter, which
16355 is run directly from Exim, not under a shell. The string is parsed by Exim in
16356 the same way as a command string for the \%pipe%\ transport: Exim breaks it up
16357 into arguments and then expands each argument separately. The special argument
16358 \$pipe@_addresses$\ is replaced by a number of arguments, one for each address
16359 that applies to this delivery. (This isn't an ideal name for this feature here,
16360 but as it was already implemented for the \%pipe%\ transport, it seemed sensible
16364 .index \$host@_address$\
16365 The expansion variables \$host$\ and \$host@_address$\ are available when the
16366 transport is a remote one. They contain the name and IP address of the host to
16367 which the message is being sent. For example:
16369 transport_filter = /some/directory/transport-filter.pl \
16370 $host $host_address $sender_address $pipe_addresses
16372 The filter process is run under the same uid and gid as the normal delivery.
16373 For remote deliveries this is the Exim uid/gid by default.
16375 If a transport filter is set on an autoreply transport, the original message is
16376 passed through the filter as it is being copied into the newly generated
16377 message, which happens if the \return@_message\ option is set.
16379 .conf transport@_filter@_timeout time 5m
16380 .index transport||filter, timeout
16381 When Exim is reading the output of a transport filter, it a applies a timeout
16382 that can be set by this option. Exceeding the timeout is treated as a
16383 temporary delivery failure.
16386 .conf user string$**$ "Exim user"
16387 .index uid (user id)||local delivery
16388 .index transport||user, specifying
16389 This option specifies the user under whose uid the delivery process is to be
16390 run, overriding any uid that may have been set by the router. If the user is
16391 given as a name, the uid is looked up from the password data, and the
16392 associated group is taken as the value of the gid to be used if the \group\
16396 For deliveries that use local transports, a user and group are normally
16397 specified explicitly or implicitly (for example, as a result of
16398 \check@_local@_user\) by the router or transport.
16401 .index hints database||access by remote transport
16402 For remote transports, you should leave this option unset unless you really are
16403 sure you know what you are doing. When a remote transport is running, it needs
16404 to be able to access Exim's hints databases, because each host may have its own
16416 . ============================================================================
16417 .chapter Address batching in local transports
16418 .set runningfoot "address batching"
16419 .rset CHAPbatching ~~chapter
16420 .index transport||local, address batching in
16421 The only remote transport (\%smtp%\) is normally configured to handle more than
16422 one address at a time, so that when several addresses are routed to the same
16423 remote host, just one copy of the message is sent. Local transports, however,
16424 normally handle one address at a time. That is, a separate instance of the
16425 transport is run for each address that is routed to the transport. A separate
16426 copy of the message is delivered each time.
16428 .index batched local delivery
16429 .index \batch@_max\
16431 In special cases, it may be desirable to handle several addresses at once in a
16432 local transport, for example:
16434 In an \%appendfile%\ transport, when storing messages in files for later
16435 delivery by some other means, a single copy of the message with multiple
16436 recipients saves space.
16438 In an \%lmtp%\ transport, when delivering over `local SMTP' to some process,
16439 a single copy saves time, and is the normal way LMTP is expected to work.
16441 In a \%pipe%\ transport, when passing the message
16442 to a scanner program or
16443 to some other delivery mechanism such as UUCP, multiple recipients may be
16446 The three local transports (\%appendfile%\, \%lmtp%\, and \%pipe%\) all have
16447 the same options for controlling multiple (`batched') deliveries, namely
16448 \batch@_max\ and \batch@_id\. To save repeating the information for each
16449 transport, these options are described here.
16451 The \batch@_max\ option specifies the maximum number of addresses that can be
16452 delivered together in a single run of the transport. Its default value is one.
16453 When more than one address is routed to a transport that has a \batch@_max\
16454 value greater than one, the addresses are delivered in a batch (that is, in a
16455 single run of the transport), subject to certain conditions:
16457 If any of the transport's options contain a reference to \$local@_part$\, no
16458 batching is possible.
16460 If any of the transport's options contain a reference to \$domain$\, only
16461 addresses with the same domain are batched.
16463 .index customizing||batching condition
16464 If \batch@_id\ is set, it is expanded for each address, and only those
16465 addresses with the same expanded value are batched. This allows you to specify
16466 customized batching conditions.
16467 Failure of the expansion for any reason, including forced failure, disables
16468 batching, but it does not stop the delivery from taking place.
16470 Batched addresses must also have the same errors address (where to send
16471 delivery errors), the same header additions and removals, the same user and
16472 group for the transport, and if a host list is present, the first host must
16475 .index ::Envelope-to:: header line
16476 If the generic \envelope@_to@_add\ option is set for the transport, the
16477 ::Envelope-to:: header that is added to the message contains all the addresses
16478 that are batched together.
16480 The \%appendfile%\ and \%pipe%\ transports have an option called \use@_bsmtp\,
16481 which causes them to deliver the message in `batched SMTP' format, with the
16482 envelope represented as SMTP commands. The \check@_string\ and \escape@_string\
16483 options are forced to the values
16486 escape_string = ".."
16488 when batched SMTP is in use. A full description of the batch SMTP mechanism is
16489 given in section ~~SECTbatchSMTP. The \%lmtp%\ transport does not have a
16490 \use@_bsmtp\ option, because it always delivers using the SMTP protocol.
16492 .index \%pipe%\ transport||with multiple addresses
16493 If you are not using BSMTP, but are using a \%pipe%\ transport, you can include
16494 \$pipe@_addresses$\ as part of the command. This is not a true variable; it is
16495 a bit of magic that causes each of the recipient addresses to be inserted into
16496 the command as a separate argument. This provides a way of accessing all the
16497 addresses that are being delivered in the batch.
16499 If you are using a batching \%appendfile%\ transport without \use@_bsmtp\, the
16500 only way to preserve the recipient addresses is to set the \envelope@_to@_add\
16501 option. This causes an ::Envelope-to:: header line to be added to the message,
16502 containing all the recipients.
16509 . ============================================================================
16510 .chapter The appendfile transport
16511 .set runningfoot "appendfile transport"
16512 .rset CHAPappendfile ~~chapter
16513 .index \%appendfile%\ transport
16514 .index transports||\%appendfile%\
16515 .index directory creation
16516 .index creating directories
16517 The \%appendfile%\ transport delivers a message by appending it to an existing
16518 file, or by creating an entirely new file in a specified directory. Single
16519 files to which messages are appended can be in the traditional Unix mailbox
16520 format, or optionally in the MBX format supported by the Pine MUA and
16521 University of Washington IMAP daemon, $it{inter alia}. When each message is
16522 being delivered as a separate file, `maildir' format can optionally be used to
16523 give added protection against failures that happen part-way through the
16524 delivery. A third form of separate-file delivery known as `mailstore' is also
16525 supported. For all file formats, Exim attempts to create as many levels of
16526 directory as necessary, provided that \create@_directory\ is set.
16528 The code for the optional formats is not included in the Exim binary by
16529 default. It is necessary to set \\SUPPORT@_MBX\\, \\SUPPORT@_MAILDIR\\ and/or
16530 \\SUPPORT@_MAILSTORE\\ in \(Local/Makefile)\ to have the appropriate code
16533 .index quota||system
16534 Exim recognises system quota errors, and generates an appropriate message. Exim
16535 also supports its own quota control within the transport, for use when the
16536 system facility is unavailable or cannot be used for some reason.
16538 If there is an error while appending to a file (for example, quota exceeded or
16539 partition filled), Exim attempts to reset the file's length and last
16540 modification time back to what they were before. If there is an error while
16541 creating an entirely new file, the new file is removed.
16543 Before appending to a file, a number of security checks are made, and the
16544 file is locked. A detailed description is given below, after the list of
16547 \%appendfile%\ is most commonly used for local deliveries to users' mailboxes.
16548 However, it can also be used as a pseudo-remote transport for putting messages
16549 into files for remote delivery by some means other than Exim. `Batch SMTP'
16550 format is often used in this case (see the \use@_bsmtp\ option).
16553 .section The file and directory options
16554 .rset SECTfildiropt "~~chapter.~~section"
16555 The \file\ option specifies a single file, to which the message is appended;
16556 the \directory\ option specifies a directory, in which a new file containing
16557 the message is created. Only one of these two options can be set, and for
16558 normal deliveries to mailboxes, one of them \*must*\ be set.
16560 However, \%appendfile%\ is also used for delivering messages to files or
16561 directories whose names (or parts of names) are obtained from alias,
16562 forwarding, or filtering operations (for example, a \save\ command in a user's
16563 Exim filter). When such a transport is running, \$local@_part$\ contains the
16564 local part that was aliased or forwarded, and \$address@_file$\ contains the
16565 name (or partial name) of the file or directory generated by the redirection
16566 operation. There are two cases:
16568 If neither \file\ nor \directory\ is set, the redirection operation
16569 must specify an absolute path (one that begins with \"/"\). This is the most
16570 common case when users with local accounts use filtering to sort mail into
16571 different folders. See for example, the \%address@_file%\ transport in the
16572 default configuration. If the path ends with a slash, it is assumed to be the
16573 name of a directory. A delivery to a directory can also be forced by setting
16574 \maildir@_format\ or \mailstore@_format\.
16576 If \file\ or \directory\ is set for a delivery from a redirection, it is used
16577 to determine the file or directory name for the delivery. Normally, the
16578 contents of \$address@_file$\ are used in some way in the string expansion.
16581 .index Sieve filter||configuring \%appendfile%\
16582 .index Sieve filter||relative mailbox path handling
16583 As an example of the second case, consider an environment where users do not
16584 have home directories. They may be permitted to use Exim filter commands of the
16589 or Sieve filter commands of the form:
16591 require "fileinto";
16592 fileinto "folder23";
16594 In this situation, the expansion of \file\ or \directory\ in the transport must
16595 transform the relative path into an appropriate absolute file name. In the case
16596 of Sieve filters, the name \*inbox*\ must be handled. It is the name that is
16597 used as a result of a `keep' action in the filter. This example shows one way
16598 of handling this requirement:
16600 file = ${if eq{$address_file}{inbox} \
16601 {/var/mail/$local_part} \
16602 {${if eq{${substr_0_1:$address_file}}{/} \
16604 {$home/mail/$address_file} \
16608 With this setting of \file\, \*inbox*\ refers to the standard mailbox location,
16609 absolute paths are used without change, and other folders are in the \(mail)\
16610 directory within the home directory.
16612 \**Note 1**\: While processing an Exim filter, a relative path such as
16613 \(folder23)\ is turned into an absolute path if a home directory is known to
16614 the router. In particular, this is the case if \check@_local@_user\ is set. If
16615 you want to prevent this happening at routing time, you can set
16616 \router@_home@_directory\ empty. This forces the router to pass the relative
16617 path to the transport.
16619 \**Note 2**\: An absolute path in \$address@_file$\ is not treated specially;
16620 the \file\ or \directory\ option is still used if it is set.
16624 .section Private options for appendfile
16625 .index options||\%appendfile%\ transport
16629 .conf allow@_fifo boolean false
16630 .index fifo (named pipe)
16631 .index named pipe (fifo)
16632 .index pipe||named (fifo)
16633 Setting this option permits delivery to named pipes (FIFOs) as well as to
16634 regular files. If no process is reading the named pipe at delivery time, the
16635 delivery is deferred.
16637 .conf allow@_symlink boolean false
16638 .index symbolic link||to mailbox
16639 .index mailbox||symbolic link
16640 By default, \%appendfile%\ will not deliver if the path name for the file is
16641 that of a symbolic link. Setting this option relaxes that constraint, but there
16642 are security issues involved in the use of symbolic links. Be sure you know
16643 what you are doing if you set this. Details of exactly what this option affects
16644 are included in the discussion which follows this list of options.
16646 .conf batch@_id string$**$ unset
16647 See the description of local delivery batching in chapter ~~CHAPbatching.
16648 However, batching is automatically disabled for \%appendfile%\ deliveries that
16649 happen as a result of forwarding or aliasing or other redirection directly to a
16652 .conf batch@_max integer 1
16653 See the description of local delivery batching in chapter ~~CHAPbatching.
16655 .conf check@_group boolean false
16656 When this option is set, the group owner of the file defined by the \file\
16657 option is checked to see that it is the same as the group under which the
16658 delivery process is running. The default setting is false because the default
16659 file mode is 0600, which means that the group is irrelevant.
16661 .conf check@_owner boolean true
16662 When this option is set, the owner of the file defined by the \file\ option is
16663 checked to ensure that it is the same as the user under which the delivery
16664 process is running.
16666 .conf check@_string string "see below"
16668 As \%appendfile%\ writes the message, the start of each line is tested for
16669 matching \check@_string\, and if it does, the initial matching characters are
16670 replaced by the contents of \escape@_string\. The value of \check@_string\ is a
16671 literal string, not a regular expression, and the case of any letters it
16672 contains is significant.
16674 If \use@_bsmtp\ is set the values of \check@_string\ and \escape@_string\ are
16675 forced to `.' and `..' respectively, and any settings in the configuration are
16676 ignored. Otherwise, they default to `From ' and `>From ' when the \file\ option
16677 is set, and unset when
16678 any of the \directory\, \maildir\, or \mailstore\ options are set.
16680 The default settings, along with \message@_prefix\ and \message@_suffix\, are
16681 suitable for traditional `BSD' mailboxes, where a line beginning with `From '
16682 indicates the start of a new message. All four options need changing if another
16683 format is used. For example, to deliver to mailboxes in MMDF format:
16684 .index MMDF format mailbox
16685 .index mailbox||MMDF format
16687 check_string = "\1\1\1\1\n"
16688 escape_string = "\1\1\1\1 \n"
16689 message_prefix = "\1\1\1\1\n"
16690 message_suffix = "\1\1\1\1\n"
16693 .index directory creation
16694 .conf create@_directory boolean true
16695 When this option is true, Exim attempts to create any missing superior
16696 directories for the file that it is about to write. A created directory's mode
16697 is given by the \directory@_mode\ option.
16699 .conf create@_file string "anywhere"
16700 This option constrains the location of files and directories that are created
16701 by this transport. It applies to files defined by the \file\ option and
16702 directories defined by the \directory\ option. In the case of maildir delivery,
16703 it applies to the top level directory, not the maildir directories beneath.
16705 The option must be set to one of the words `anywhere', `inhome', or
16706 `belowhome'. In the second and third cases, a home directory must have been set
16707 for the transport. This option is not useful when an explicit file name is
16708 given for normal mailbox deliveries. It is intended for the case when file
16709 names are generated from users' \(.forward)\ files. These are usually handled
16710 by an \%appendfile%\ transport called \address@_file\. See also
16711 \file@_must@_exist\.
16713 .conf directory string$**$ unset
16714 This option is mutually exclusive with the \file\ option, but one of \file\ or
16715 \directory\ must be set, unless the delivery is the direct result of a
16716 redirection (see section ~~SECTfildiropt).
16718 When \directory\ is set, the string is expanded, and the message is delivered
16719 into a new file or files in or below the given directory, instead of being
16720 appended to a single mailbox file. A number of different formats are provided
16721 (see \maildir@_format\ and \mailstore@_format\), and see section ~~SECTopdir
16722 for further details of this form of delivery.
16724 .conf directory@_file string$**$ "$tt{q@$@{base62:@$tod@_epoch@}-@$inode}"
16726 When \directory\ is set, but neither \maildir@_format\ nor \mailstore@_format\
16727 is set, \%appendfile%\ delivers each message into a file whose name is obtained
16728 by expanding this string. The default value generates a unique name from the
16729 current time, in base 62 form, and the inode of the file. The variable
16730 \$inode$\ is available only when expanding this option.
16732 .conf directory@_mode "octal integer" 0700
16733 If \%appendfile%\ creates any directories as a result of the \create@_directory\
16734 option, their mode is specified by this option.
16736 .conf escape@_string string "see description"
16737 See \check@_string\ above.
16739 .conf file string$**$ unset
16740 This option is mutually exclusive with the \directory\ option, but one of
16741 \file\ or \directory\ must be set, unless the delivery is the direct result of
16742 a redirection (see section ~~SECTfildiropt). The \file\ option specifies a
16743 single file, to which the message is appended. One or more of
16744 \use@_fcntl@_lock\, \use@_flock@_lock\, or \use@_lockfile\ must be set with
16746 .index NFS||lock file
16747 .index locking files
16749 If you are using more than one host to deliver over NFS into the same
16750 mailboxes, you should always use lock files.
16752 The string value is expanded for each delivery, and must yield an absolute
16753 path. The most common settings of this option are variations on one of these
16756 file = /var/spool/mail/$local_part
16757 file = /home/$local_part/inbox
16760 .index `sticky' bit
16761 In the first example, all deliveries are done into the same directory. If Exim
16762 is configured to use lock files (see \use@_lockfile\ below) it must be able to
16763 create a file in the directory, so the `sticky' bit must be turned on for
16764 deliveries to be possible, or alternatively the \group\ option can be used to
16765 run the delivery under a group id which has write access to the directory.
16768 .conf file@_format string unset
16769 .index file||mailbox, checking existing format
16770 This option requests the transport to check the format of an existing file
16771 before adding to it. The check consists of matching a specific string at the
16772 start of the file. The value of the option consists of an even number of
16773 colon-separated strings. The first of each pair is the test string, and the
16774 second is the name of a transport. If the transport associated with a matched
16775 string is not the current transport, control is passed over to the other
16776 transport. For example, suppose the standard \%local@_delivery%\ transport has
16779 file_format = "From : local_delivery :\
16780 \1\1\1\1\n : local_mmdf_delivery"
16782 Mailboxes that begin with `From' are still handled by this transport, but if a
16783 mailbox begins with four binary ones followed by a newline, control is passed
16784 to a transport called \local__mmdf__delivery\, which presumably is configured
16785 to do the delivery in MMDF format. If a mailbox does not exist or is empty, it
16786 is assumed to match the current transport. If the start of a mailbox doesn't
16787 match any string, or if the transport named for a given string is not defined,
16788 delivery is deferred.
16790 .conf file@_must@_exist boolean false
16791 If this option is true, the file specified by the \file\ option must exist, and
16792 an error occurs if it does not. Otherwise, it is created if it does not exist.
16794 .conf lock@_fcntl@_timeout time 0s
16795 .index timeout||mailbox locking
16796 .index mailbox locking||blocking and non-blocking
16797 .index locking files
16798 By default, the \%appendfile%\ transport uses non-blocking calls to \*fcntl()*\
16799 when locking an open mailbox file. If the call fails, the delivery process
16800 sleeps for \lock@_interval\ and tries again, up to \lock@_retries\ times.
16801 Non-blocking calls are used so that the file is not kept open during the wait
16802 for the lock; the reason for this is to make it as safe as possible for
16803 deliveries over NFS in the case when processes might be accessing an NFS
16804 mailbox without using a lock file. This should not be done, but
16805 misunderstandings and hence misconfigurations are not unknown.
16807 On a busy system, however, the performance of a non-blocking lock approach is
16808 not as good as using a blocking lock with a timeout. In this case, the waiting
16809 is done inside the system call, and Exim's delivery process acquires the lock
16810 and can proceed as soon as the previous lock holder releases it.
16812 If \lock@_fcntl@_timeout\ is set to a non-zero time, blocking locks, with that
16813 timeout, are used. There may still be some retrying: the maximum number of
16816 (lock_retries * lock_interval) / lock_fcntl_timeout
16818 rounded up to the next whole number. In other words, the total time during
16819 which \%appendfile%\ is trying to get a lock is roughly the same, unless
16820 \lock@_fcntl@_timeout\ is set very large.
16822 You should consider setting this option if you are getting a lot of delayed
16823 local deliveries because of errors of the form
16825 failed to lock mailbox /some/file (fcntl)
16828 .conf lock@_flock@_timeout time 0s
16829 This timeout applies to file locking when using \*flock()*\ (see \use@_flock\);
16830 the timeout operates in a similar manner to \lock@_fcntl@_timeout\.
16832 .conf lock@_interval time 3s
16833 This specifies the time to wait between attempts to lock the file. See below
16834 for details of locking.
16836 .conf lock@_retries integer 10
16837 This specifies the maximum number of attempts to lock the file. A value of zero
16838 is treated as 1. See below for details of locking.
16840 .conf lockfile@_mode "octal integer" 0600
16841 This specifies the mode of the created lock file, when a lock file is being
16842 used (see \use@_lockfile\).
16844 .conf lockfile@_timeout time 30m
16845 .index timeout||mailbox locking
16846 When a lock file is being used (see \use@_lockfile\), if a lock file already
16847 exists and is older than this value, it is assumed to have been left behind by
16848 accident, and Exim attempts to remove it.
16850 .conf maildir@_format boolean false
16851 .index maildir format||specifying
16852 If this option is set with the \directory\ option, the delivery is into a new
16853 file, in the `maildir' format that is used by other mail software. When the
16854 transport is activated directly from a \%redirect%\ router (for example, the
16855 \%address@_file%\ transport in the default configuration), setting
16856 \maildir@_format\ causes the path received from the router to be treated as a
16857 directory, whether or not it ends with \"/"\. This option is available only if
16858 \\SUPPORT@_MAILDIR\\ is present in \(Local/Makefile)\. See section
16859 ~~SECTmaildirdelivery below for further details.
16862 .conf maildir@_quota@_directory@_regex string "See below"
16863 .index maildir format||quota, directories included in
16864 .index quota||maildir, directories included in
16865 This option is relevant only when \maildir@_use@_size@_file\ is set. It defines
16866 a regular expression for specifying directories that should be included in the
16867 quota calculation. The default value is
16869 maildir_quota_directory_regex = ^(?:cur|new|\..*)$
16871 which includes the \(cur)\ and \(new)\ directories, and any maildir++ folders
16872 (directories whose names begin with a dot). If you want to exclude the
16874 folder from the count (as some sites do), you need to change this setting to
16876 maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
16878 This uses a negative lookahead in the regular expression to exclude the
16879 directory whose name is \(.Trash)\.
16882 .conf maildir@_retries integer 10
16883 This option specifies the number of times to retry when writing a file in
16884 `maildir' format. See section ~~SECTmaildirdelivery below.
16886 .conf maildir@_tag string$**$ unset
16887 This option applies only to deliveries in maildir format, and is described in
16888 section ~~SECTmaildirdelivery below.
16890 .conf maildir@_use@_size@_file boolean false
16891 .index maildir format||\(maildirsize)\ file
16892 Setting this option true enables support for \(maildirsize)\ files. Exim
16893 creates a \(maildirsize)\ file in a maildir if one does not exist, taking the
16894 quota from the \quota\ option of the transport. If \quota\ is unset, the value
16895 is zero. See section ~~SECTmaildirdelivery below for further details.
16897 .conf mailstore@_format boolean false
16898 .index mailstore format||specifying
16899 If this option is set with the \directory\ option, the delivery is into two new
16900 files in `mailstore' format. The option is available only if
16901 \\SUPPORT@_MAILSTORE\\ is present in \(Local/Makefile)\. See section
16902 ~~SECTopdir below for further details.
16904 .conf mailstore@_prefix string$**$ unset
16905 This option applies only to deliveries in mailstore format, and is described in
16906 section ~~SECTopdir below.
16908 .conf mailstore@_suffix string$**$ unset
16909 This option applies only to deliveries in mailstore format, and is described in
16910 section ~~SECTopdir below.
16912 .conf mbx@_format boolean false
16913 .index locking files
16914 .index file||locking
16915 .index file||MBX format
16916 .index MBX format, specifying
16917 This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\
16918 set in \(Local/Makefile)\. If \mbx@_format\ is set with the \file\ option,
16919 the message is appended to the mailbox file in MBX format instead of
16920 traditional Unix format. This format is supported by Pine4 and its associated
16921 IMAP and POP daemons, by means of the \*c-client*\ library that they all use.
16923 \**Note**\: The \message@_prefix\ and \message@_suffix\ options are not
16924 automatically changed by the use of \mbx@_format\. They should normally be set
16925 empty when using MBX format, so this option almost always appears in this
16933 If none of the locking options are mentioned in the configuration,
16934 \use@_mbx@_lock\ is assumed and the other locking options default to false. It
16935 is possible to specify the other kinds of locking with \mbx@_format\, but
16936 \use@_fcntl@_lock\ and \use@_mbx@_lock\ are mutually exclusive. MBX locking
16937 interworks with \*c-client*\, providing for shared access to the mailbox. It
16938 should not be used if any program that does not use this form of locking is
16939 going to access the mailbox, nor should it be used if the mailbox file is NFS
16940 mounted, because it works only when the mailbox is accessed from a single host.
16942 If you set \use@_fcntl@_lock\ with an MBX-format mailbox, you cannot use
16943 the standard version of \*c-client*\, because as long as it has a mailbox open
16944 (this means for the whole of a Pine or IMAP session), Exim will not be able to
16945 append messages to it.
16947 .conf message@_prefix string$**$ "see below"
16949 The string specified here is expanded and output at the start of every message.
16950 The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in
16953 message_prefix = "From ${if def:return_path{$return_path}\
16954 {MAILER-DAEMON}} $tod_bsdinbox\n"
16957 .conf message@_suffix string$**$ "see below"
16958 The string specified here is expanded and output at the end of every message.
16959 The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in
16960 which case it is a single newline character. The suffix can be suppressed by
16966 .conf mode "octal integer" 0600
16967 If the output file is created, it is given this mode. If it already exists and
16968 has wider permissions, they are reduced to this mode. If it has narrower
16969 permissions, an error occurs unless \mode__fail__narrower\ is false. However,
16970 if the delivery is the result of a \save\ command in a filter file specifing a
16971 particular mode, the mode of the output file is always forced to take that
16972 value, and this option is ignored.
16974 .conf mode@_fail@_narrower boolean true
16975 This option applies in the case when an existing mailbox file has a narrower
16976 mode than that specified by the \mode\ option. If \mode@_fail@_narrower\ is
16977 true, the delivery is deferred (`mailbox has the wrong mode'); otherwise Exim
16978 continues with the delivery attempt, using the existing mode of the file.
16980 .conf notify@_comsat boolean false
16981 If this option is true, the \*comsat*\ daemon is notified after every successful
16982 delivery to a user mailbox. This is the daemon that notifies logged on users
16983 about incoming mail.
16985 .conf quota string$**$ unset
16986 .index quota||imposed by Exim
16987 This option imposes a limit on the size of the file to which Exim is appending,
16988 or to the total space used in the directory tree when the \directory\ option is
16989 set. In the latter case, computation of the space used is expensive, because
16990 all the files in the directory (and any sub-directories) have to be
16991 individually inspected and their sizes summed.
16993 (See \quota@_size@_regex\ and \maildir@_use@_size@_file\ for ways to avoid this
16994 in environments where users have no shell access to their mailboxes).
16996 As there is no interlock against two simultaneous deliveries into a
16997 multi-file mailbox, it is possible for the quota to be overrun in this case.
16998 For single-file mailboxes, of course, an interlock is a necessity.
17001 A file's size is taken as its \*used*\ value. Because of blocking effects, this
17002 may be a lot less than the actual amount of disk space allocated to the file.
17003 If the sizes of a number of files are being added up, the rounding effect can
17004 become quite noticeable, especially on systems that have large block sizes.
17005 Nevertheless, it seems best to stick to the \*used*\ figure, because this is
17006 the obvious value which users understand most easily.
17008 The value of the option is expanded, and must then be a numerical value
17009 (decimal point allowed), optionally followed by one of the letters K or M. The
17010 expansion happens while Exim is running as root, before it changes uid for the
17011 delivery. This means that files which are inaccessible to the end user can be
17012 used to hold quota values that are looked up in the expansion. When delivery
17013 fails because this quota is exceeded, the handling of the error is as for
17014 system quota failures.
17017 \**Note**\: A value of zero is interpreted as `no quota'.
17020 By default, Exim's quota checking mimics system quotas, and restricts the
17021 mailbox to the specified maximum size, though the value is not accurate to the
17022 last byte, owing to separator lines and additional headers that may get added
17023 during message delivery. When a mailbox is nearly full, large messages may get
17024 refused even though small ones are accepted, because the size of the current
17025 message is added to the quota when the check is made. This behaviour can be
17026 changed by setting \quota@_is@_inclusive\ false. When this is done, the check
17027 for exceeding the quota does not include the current message. Thus, deliveries
17028 continue until the quota has been exceeded; thereafter, no further messages are
17029 delivered. See also \quota@_warn@_threshold\.
17031 .conf quota@_directory string$**$ unset
17032 This option defines the directory to check for quota purposes when delivering
17033 into individual files. The default is the delivery directory, or, if a file
17034 called \(maildirfolder)\ exists in a maildir directory, the parent of the
17035 delivery directory.
17037 .conf quota@_filecount string$**$ 0
17038 This option applies when the \directory\ option is set. It limits the total
17039 number of files in the directory (compare the inode limit in system quotas). It
17040 can only be used if \quota\ is also set. The value is expanded; an expansion
17041 failure causes delivery to be deferred.
17043 .conf quota@_is@_inclusive boolean true
17046 .conf quota@_size@_regex string unset
17047 This option applies when one of the delivery modes that writes a separate file
17048 for each message is being used. When Exim wants to find the size of one of
17049 these files in order to test the quota, it first checks \quota@_size@_regex\.
17050 If this is set to a regular expression that matches the file name, and it
17051 captures one string, that string is interpreted as a representation of the
17052 file's size. The value of \quota@_size@_regex\ is not expanded.
17054 This feature is useful only when users have no shell access to their mailboxes
17055 -- otherwise they could defeat the quota simply by renaming the files. This
17056 facility can be used with maildir deliveries, by setting \maildir@_tag\ to add
17057 the file length to the file name. For example:
17059 maildir_tag = ,S=$message_size
17060 quota_size_regex = ,S=(\d+)
17062 The regular expression should not assume that the length is at the end of the
17063 file name (even though \maildir@_tag\ puts it there) because maildir MUAs
17064 sometimes add other information onto the ends of message file names.
17066 .conf quota@_warn@_message string$**$ "see below"
17067 See below for the use of this option. If it is not set when
17068 \quota@_warn@_threshold\ is set, it defaults to
17070 quota_warn_message = "\
17071 To: $local_part@$domain\n\
17072 Subject: Your mailbox\n\n\
17073 This message is automatically created \
17074 by mail delivery software.\n\n\
17075 The size of your mailbox has exceeded \
17076 a warning threshold that is\n\
17077 set by the system administrator.\n"
17080 .conf quota@_warn@_threshold string$**$ 0
17081 .index quota||warning threshold
17082 .index mailbox||size warning
17083 .index size||of mailbox
17084 This option is expanded in the same way as \quota\ (see above). If the
17085 resulting value is greater than zero, and delivery of the message causes the
17086 size of the file or total space in the directory tree to cross the given
17087 threshold, a warning message is sent. If \quota\ is also set, the threshold may
17088 be specified as a percentage of it by following the value with a percent sign.
17092 quota_warn_threshold = 75%
17094 If \quota\ is not set, a setting of \quota@_warn@_threshold\ that ends with a
17095 percent sign is ignored.
17097 The warning message itself is specified by the \quota@_warn@_message\ option,
17098 and it must start with a ::To:: header line containing the recipient(s). A
17099 ::Subject:: line should also normally be supplied. The \quota\ option does not
17100 have to be set in order to use this option; they are independent of one
17101 another except when the threshold is specified as a percentage.
17103 .conf use@_bsmtp boolean false
17104 .index envelope sender
17105 If this option is set true, \%appendfile%\ writes messages in `batch SMTP'
17106 format, with the envelope sender and recipient(s) included as SMTP commands. If
17107 you want to include a leading \\HELO\\ command with such messages, you can do
17108 so by setting the \message@_prefix\ option. See section ~~SECTbatchSMTP for
17109 details of batch SMTP.
17111 .conf use@_crlf boolean false
17112 .index carriage return
17114 This option causes lines to be terminated with the two-character CRLF sequence
17115 (carriage return, linefeed) instead of just a linefeed character. In the case
17116 of batched SMTP, the byte sequence written to the file is then an exact image
17117 of what would be sent down a real SMTP connection.
17119 The contents of the \message@_prefix\ and \message@_suffix\ options are written
17120 verbatim, so must contain their own carriage return characters if these are
17121 needed. In cases where these options have non-empty defaults, the values end
17122 with a single linefeed, so they
17124 be changed to end with \"@\r@\n"\ if \use@_crlf\ is set.
17126 .conf use@_fcntl@_lock boolean "see below"
17127 This option controls the use of the \*fcntl()*\ function to lock a file for
17128 exclusive use when a message is being appended. It is set by default unless
17129 \use@_flock@_lock\ is set. Otherwise, it should be turned off only if you know
17130 that all your MUAs use lock file locking. When both \use@_fcntl@_lock\ and
17131 \use@_flock@_lock\ are unset, \use@_lockfile\ must be set.
17133 .conf use@_flock@_lock boolean false
17134 This option is provided to support the use of \*flock()*\ for file locking, for
17135 the few situations where it is needed. Most modern operating systems support
17136 \*fcntl()*\ and \*lockf()*\ locking, and these two functions interwork with
17137 each other. Exim uses \*fcntl()*\ locking by default.
17139 This option is required only if you are using an operating system where
17140 \*flock()*\ is used by programs that access mailboxes (typically MUAs), and
17141 where \*flock()*\ does not correctly interwork with \*fcntl()*\. You can use
17142 both \*fcntl()*\ and \*flock()*\ locking simultaneously if you want.
17144 .index Solaris||\*flock()*\ support
17145 Not all operating systems provide \*flock()*\. Some versions of Solaris do not
17146 have it (and some, I think, provide a not quite right version built on top of
17147 \*lockf()*\). If the OS does not have \*flock()*\, Exim will be built without
17148 the ability to use it, and any attempt to do so will cause a configuration
17151 \**Warning**\: \*flock()*\ locks do not work on NFS files (unless \*flock()*\
17152 is just being mapped onto \*fcntl()*\ by the OS).
17154 .conf use@_lockfile boolean "see below"
17155 If this option is turned off, Exim does not attempt to create a lock file when
17156 appending to a mailbox file. In this situation, the only locking is by
17157 \*fcntl()*\. You should only turn \use@_lockfile\ off if you are absolutely
17158 sure that every MUA that is ever going to look at your users' mailboxes uses
17159 \*fcntl()*\ rather than a lock file, and even then only when you are not
17160 delivering over NFS from more than one host.
17162 .index NFS||lock file
17163 In order to append to an NFS file safely from more than one host, it is
17164 necessary to take out a lock $it{before} opening the file, and the lock file
17165 achieves this. Otherwise, even with \*fcntl()*\ locking, there is a risk of
17168 The \use@_lockfile\ option is set by default unless \use@_mbx@_lock\ is set. It
17169 is not possible to turn both \use@_lockfile\ and \use@_fcntl@_lock\ off, except
17170 when \mbx@_format\ is set.
17172 .conf use@_mbx@_lock boolean "see below"
17173 This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\
17174 set in \(Local/Makefile)\. Setting the option specifies that special MBX
17175 locking rules be used. It is set by default if \mbx@_format\ is set and none of
17176 the locking options are mentioned in the configuration. The locking rules are
17177 the same as are used by the \*c-client*\ library that underlies Pine and the
17178 IMAP4 and POP daemons that come with it (see the discussion below). The rules
17179 allow for shared access to the mailbox. However, this kind of locking does not
17180 work when the mailbox is NFS mounted.
17182 You can set \use@_mbx@_lock\ with either (or both) of \use@_fcntl@_lock\ and
17183 \use@_flock@_lock\ to control what kind of locking is used in implementing the
17184 MBX locking rules. The default is to use \*fcntl()*\ if \use@_mbx@_lock\ is set
17185 without \use@_fcntl@_lock\ or \use@_flock@_lock\.
17189 .section Operational details for appending
17190 .rset SECTopappend "~~chapter.~~section"
17191 .index appending to a file
17192 .index file||appending
17193 Before appending to a file, the following preparations are made:
17195 If the name of the file is \(/dev/null)\, no action is taken, and a success
17198 .index directory creation
17199 If any directories on the file's path are missing, Exim creates them if the
17200 \create@_directory\ option is set. A created directory's mode is given by the
17201 \directory@_mode\ option.
17203 If \file@_format\ is set, the format of an existing file is checked. If this
17204 indicates that a different transport should be used, control is passed to that
17207 .index file||locking
17208 .index locking files
17209 .index NFS||lock file
17210 If \use@_lockfile\ is set, a lock file is built in a way that will work
17211 reliably over NFS, as follows:
17213 Create a `hitching post' file whose name is that of the lock file with the
17214 current time, primary host name, and process id added, by opening for writing
17215 as a new file. If this fails with an access error, delivery is deferred.
17217 Close the hitching post file, and hard link it to the lock file name.
17219 If the call to \*link()*\ succeeds, creation of the lock file has succeeded.
17220 Unlink the hitching post name.
17222 Otherwise, use \*stat()*\ to get information about the hitching post file, and
17223 then unlink hitching post name. If the number of links is exactly two, creation
17224 of the lock file succeeded but something (for example, an NFS server crash and
17225 restart) caused this fact not to be communicated to the \*link()*\ call.
17227 If creation of the lock file failed, wait for \lock@_interval\ and try again,
17228 up to \lock@_retries\ times. However, since any program that writes to a
17229 mailbox should complete its task very quickly, it is reasonable to time out old
17230 lock files that are normally the result of user agent and system crashes. If an
17231 existing lock file is older than \lockfile@_timeout\ Exim attempts to unlink it
17232 before trying again.
17235 A call is made to \*lstat()*\ to discover whether the main file exists, and if
17236 so, what its characteristics are. If \*lstat()*\ fails for any reason other
17237 than non-existence, delivery is deferred.
17239 .index symbolic link||to mailbox
17240 .index mailbox||symbolic link
17241 If the file does exist and is a symbolic link, delivery is deferred, unless the
17242 \allow@_symlink\ option is set, in which case the ownership of the link is
17243 checked, and then \*stat()*\ is called to find out about the real file, which
17244 is then subjected to the checks below. The check on the top-level link
17245 ownership prevents one user creating a link for another's mailbox in a sticky
17246 directory, though allowing symbolic links in this case is definitely not a good
17247 idea. If there is a chain of symbolic links, the intermediate ones are not
17250 If the file already exists but is not a regular file, or if the file's owner
17251 and group (if the group is being checked -- see \check@_group\ above) are
17252 different from the user and group under which the delivery is running,
17253 delivery is deferred.
17255 If the file's permissions are more generous than specified, they are reduced.
17256 If they are insufficient, delivery is deferred, unless \mode@_fail@_narrower\
17257 is set false, in which case the delivery is tried using the existing
17260 The file's inode number is saved, and the file is then opened for appending. If
17261 this fails because the file has vanished, \%appendfile%\ behaves as if it hadn't
17262 existed (see below). For any other failures, delivery is deferred.
17264 If the file is opened successfully, check that the inode number hasn't
17265 changed, that it is still a regular file, and that the owner and permissions
17266 have not changed. If anything is wrong, defer delivery and freeze the message.
17268 If the file did not exist originally, defer delivery if the \file@_must@_exist\
17269 option is set. Otherwise, check that the file is being created in a permitted
17270 directory if the \create@_file\ option is set (deferring on failure), and then
17271 open for writing as a new file, with the \\O@_EXCL\\ and \\O@_CREAT\\ options,
17272 except when dealing with a symbolic link (the \allow@_symlink\ option must be
17273 set). In this case, which can happen if the link points to a non-existent file,
17274 the file is opened for writing using \\O@_CREAT\\ but not \\O@_EXCL\\, because
17275 that prevents link following.
17277 .index loop||while file testing
17278 If opening fails because the file exists, obey the tests given above for
17279 existing files. However, to avoid looping in a situation where the file is
17280 being continuously created and destroyed, the exists/not-exists loop is broken
17281 after 10 repetitions, and the message is then frozen.
17283 If opening fails with any other error, defer delivery.
17285 .index file||locking
17286 .index locking files
17287 Once the file is open, unless both \use@_fcntl@_lock\ and \use@_flock@_lock\
17288 are false, it is locked using \*fcntl()*\ or \*flock()*\ or both. If
17289 \use@_mbx@_lock\ is false, an exclusive lock is requested in each case.
17290 However, if \use@_mbx@_lock\ is true,
17291 Exim takes out a shared lock on the open file,
17292 and an exclusive lock on the file whose name is
17294 /tmp/.<<device-number>>.<<inode-number>>
17296 using the device and inode numbers of the open mailbox file, in accordance with
17297 the MBX locking rules.
17299 If Exim fails to lock the file, there are two possible courses of action,
17300 depending on the value of the locking timeout. This is obtained from
17301 \lock@_fcntl@_timeout\ or \lock@_flock@_timeout\, as appropriate.
17303 If the timeout value is zero, the file is closed, Exim waits for
17304 \lock@_interval\, and then goes back and re-opens the file as above and tries
17305 to lock it again. This happens up to \lock@_retries\ times, after which the
17306 delivery is deferred.
17308 If the timeout has a value greater than zero, blocking calls to \*fcntl()*\ or
17309 \*flock()*\ are used (with the given timeout), so there has already been some
17310 waiting involved by the time locking fails. Nevertheless, Exim does not give up
17311 immediately. It retries up to
17313 (lock@_retries * lock@_interval) / <<timeout>>
17315 times (rounded up).
17318 At the end of delivery, Exim closes the file (which releases the \*fcntl()*\
17319 and/or \*flock()*\ locks) and then deletes the lock file if one was created.
17321 .section Operational details for delivery to a new file
17322 .rset SECTopdir "~~chapter.~~section"
17323 .index delivery||to single file
17325 When the \directory\ option is set instead of \file\, each message is delivered
17326 into a newly-created file or set of files. When \%appendfile%\ is activated
17327 directly from a \%redirect%\ router, neither \file\ nor \directory\ is normally
17328 set, because the path for delivery is supplied by the router. (See for example,
17329 the \%address@_file%\ transport in the default configuration.) In this case,
17330 delivery is to a new file if either the path name ends in \"/"\, or the
17331 \maildir@_format\ or \mailstore@_format\ option is set.
17333 No locking is required while writing the message to a new file, so the various
17334 locking options of the transport are ignored. The `From' line that by default
17335 separates messages in a single file is not normally needed, nor is the escaping
17336 of message lines that start with `From', and there is no need to ensure a
17337 newline at the end of each message. Consequently, the default values for
17338 \check@_string\, \message@_prefix\, and \message@_suffix\ are all unset when
17339 any of \directory\, \maildir@_format\, or \mailstore@_format\ is set.
17341 If Exim is required to check a \quota\ setting, it adds up the sizes of all the
17342 files in the delivery directory by default. However, you can specify a
17343 different directory by setting \quota@_directory\. Also, for maildir deliveries
17344 (see below) the \(maildirfolder)\ convention is honoured.
17347 .index maildir format
17348 .index mailstore format
17349 There are three different ways in which delivery to individual files can be
17350 done, controlled by the settings of the \maildir@_format\ and
17351 \mailstore@_format\ options. Note that code to support maildir or mailstore
17352 formats is not included in the binary unless \\SUPPORT@_MAILDIR\\ or
17353 \\SUPPORT@_MAILSTORE\\, respectively, is set in \(Local/Makefile)\.
17355 .index directory creation
17356 In all three cases an attempt is made to create the directory and any necessary
17357 sub-directories if they do not exist, provided that the \create@_directory\
17358 option is set (the default). The location of a created directory can be
17359 constrained by setting \create@_file\. A created directory's mode is given by
17360 the \directory@_mode\ option. If creation fails, or if the \create@_directory\
17361 option is not set when creation is required, delivery is deferred.
17364 .section Maildir delivery
17365 .rset SECTmaildirdelivery "~~chapter.~~section"
17366 .index maildir format||description of
17367 If the \maildir@_format\ option is true, Exim delivers each message by writing
17368 it to a file whose name is \(tmp/<<stime>>.H<<mtime>>P<<pid>>.<<host>>)\ in the
17369 given directory. If the delivery is successful, the file is renamed into the
17370 \(new)\ subdirectory.
17372 In the file name, <<stime>> is the current time of day in seconds, and
17373 <<mtime>> is the microsecond fraction of the time. After a maildir delivery,
17374 Exim checks that the time-of-day clock has moved on by at least one microsecond
17375 before terminating the delivery process. This guarantees uniqueness for the
17376 file name. However, as a precaution, Exim calls \*stat()*\ for the file before
17377 opening it. If any response other than \\ENOENT\\ (does not exist) is given,
17378 Exim waits 2 seconds and tries again, up to \maildir@_retries\ times.
17380 .index quota||in maildir delivery
17382 If Exim is required to check a \quota\ setting before a maildir delivery, and
17383 \quota@_directory\ is not set, it looks for a file called \(maildirfolder)\ in
17384 the maildir directory (alongside \(new)\, \(cur)\, \(tmp)\). If this exists,
17385 Exim assumes the directory is a maildir++ folder directory, which is one level
17386 down from the user's top level mailbox directory. This causes it to start at
17387 the parent directory instead of the current directory when calculating the
17388 amount of space used.
17391 .section Using tags to record message sizes
17392 If \maildir@_tag\ is set, the string is expanded for each delivery.
17393 When the maildir file is renamed into the \(new)\ sub-directory, the
17394 tag is added to its name. However, if adding the tag takes the length of the
17395 name to the point where the test \*stat()*\ call fails with \\ENAMETOOLONG\\,
17396 the tag is dropped and the maildir file is created with no tag.
17398 Tags can be used to encode the size of files in their names; see
17399 \quota@_size@_regex\ above for an example. The expansion of \maildir@_tag\
17400 happens after the message has been written. The value of the \$message@_size$\
17401 variable is set to the number of bytes actually written. If the expansion is
17402 forced to fail, the tag is ignored, but a non-forced failure causes delivery to
17403 be deferred. The expanded tag may contain any printing characters except `/'.
17404 Non-printing characters in the string are ignored; if the resulting string is
17405 empty, it is ignored. If it starts with an alphanumeric character, a leading
17410 .section Using a maildirsize file
17411 .index quota||in maildir delivery
17412 .index maildir format||\(maildirsize)\ file
17413 If \maildir@_use@_size@_file\ is true, Exim implements the maildir++ rules for
17414 storing quota and message size information in a file called \(maildirsize)\
17415 within the maildir directory. If this file does not exist, Exim creates it,
17416 setting the quota from the \quota\ option of the transport. If the maildir
17417 directory itself does not exist, it is created before any attempt to write a
17418 \(maildirsize)\ file.
17420 The \(maildirsize)\ file is used to hold information about the sizes of
17421 messages in the maildir, thus speeding up quota calculations. The quota value
17422 in the file is just a cache; if the quota is changed in the transport, the new
17423 value overrides the cached value when the next message is delivered. The cache
17424 is maintained for the benefit of other programs that access the maildir and
17425 need to know the quota.
17427 If the \quota\ option in the transport is unset or zero, the \(maildirsize)\
17428 file is maintained (with a zero quota setting), but no quota is imposed.
17430 A regular expression is available for controlling which directories in the
17431 maildir participate in quota calculations. See the description of the
17432 \maildir@_quota@_directory@_regex\ option above for details.
17436 .section Mailstore delivery
17437 .index mailstore format||description of
17438 If the \mailstore@_format\ option is true, each message is written as two files
17439 in the given directory. A unique base name is constructed from the message id
17440 and the current delivery process, and the files that are written use this base
17441 name plus the suffixes \(.env)\ and \(.msg)\. The \(.env)\ file contains the
17442 message's envelope, and the \(.msg)\ file contains the message itself.
17444 During delivery, the envelope is first written to a file with the suffix
17445 \(.tmp)\. The \(.msg)\ file is then written, and when it is complete, the
17446 \(.tmp)\ file is renamed as the \(.env)\ file. Programs that access messages in
17447 mailstore format should wait for the presence of both a \(.msg)\ and a \(.env)\
17448 file before accessing either of them. An alternative approach is to wait for
17449 the absence of a \(.tmp)\ file.
17451 The envelope file starts with any text defined by the \mailstore@_prefix\
17452 option, expanded and terminated by a newline if there isn't one. Then follows
17453 the sender address on one line, then all the recipient addresses, one per line.
17454 There can be more than one recipient only if the \batch@_max\ option is set
17455 greater than one. Finally, \mailstore@_suffix\ is expanded and the result
17456 appended to the file, followed by a newline if it does not end with one.
17458 If expansion of \mailstore@_prefix\ or \mailstore@_suffix\ ends with a forced
17459 failure, it is ignored. Other expansion errors are treated as serious
17460 configuration errors, and delivery is deferred.
17463 .section Non-special new file delivery
17464 If neither \maildir@_format\ nor \mailstore@_format\ is set, a single new file
17465 is created directly in the named directory. For example, when delivering
17466 messages into files in batched SMTP format for later delivery to some host (see
17467 section ~~SECTbatchSMTP), a setting such as
17469 directory = /var/bsmtp/$host
17471 might be used. A message is written to a file with a temporary name, which is
17472 then renamed when the delivery is complete. The final name is obtained by
17473 expanding the contents of the \directory@_file\ option.
17483 . ============================================================================
17484 .chapter The autoreply transport
17485 .set runningfoot "autoreply transport"
17486 .index transports||\%autoreply%\
17487 .index \%autoreply%\ transport
17488 The \%autoreply%\ transport is not a true transport in that it does not cause
17489 the message to be transmitted. Instead, it generates another mail message. It
17490 is usually run as the result of mail filtering, a `vacation' message being the
17491 standard example. However, it can also be run directly from a router like any
17492 other transport. To reduce the possibility of message cascades, messages
17493 created by the \%autoreply%\ transport always have empty envelope sender
17494 addresses, like bounce messages.
17496 The parameters of the message to be sent can be specified in the configuration
17497 by options described below. However, these are used only when the address
17498 passed to the transport does not contain its own reply information. When the
17499 transport is run as a consequence of a
17501 or \vacation\ command in a filter file, the parameters of the message are
17502 supplied by the filter, and passed with the address. The transport's options
17503 that define the message are then ignored (so they are not usually set in this
17504 case). The message is specified entirely by the filter or by the transport; it
17505 is never built from a mixture of options. However, the \file@_optional\,
17506 \mode\, and \return@_message\ options apply in all cases.
17508 \%Autoreply%\ is implemented as a local transport. When used as a result of a
17509 command in a user's filter file, \%autoreply%\ normally runs under the uid and
17510 gid of the user, and with appropriate current and home directories (see chapter
17511 ~~CHAPenvironment).
17513 There is a subtle difference between routing a message to a \%pipe%\ transport
17514 that generates some text to be returned to the sender, and routing it to an
17515 \%autoreply%\ transport. This difference is noticeable only if more than one
17516 address from the same message is so handled. In the case of a pipe, the
17517 separate outputs from the different addresses are gathered up and returned to
17518 the sender in a single message, whereas if \%autoreply%\ is used, a separate
17519 message is generated for each address that is passed to it.
17521 Non-printing characters are not permitted in the header lines generated for the
17522 message that \%autoreply%\ creates, with the exception of newlines that are
17523 immediately followed by whitespace. If any non-printing characters are found,
17524 the transport defers.
17525 Whether characters with the top bit set count as printing characters or not is
17526 controlled by the \print@_topbitchars\ global option.
17528 If any of the generic options for manipulating headers (for example,
17529 \headers@_add\) are set on an \%autoreply%\ transport, they apply to the copy of
17530 the original message that is included in the generated message when
17531 \return@_message\ is set. They do not apply to the generated message itself.
17533 If the \%autoreply%\ transport receives return code 2 from Exim when it submits
17534 the message, indicating that there were no recipients, it does not treat this
17535 as an error. This means that autoreplies sent to \$sender@_address$\ when this
17536 is empty (because the incoming message is a bounce message) do not cause
17537 problems. They are just discarded.
17540 .section Private options for autoreply
17543 .index options||\%autoreply%\ transport
17544 .conf bcc string$**$ unset
17545 This specifies the addresses that are to receive `blind carbon copies' of the
17546 message when the message is specified by the transport.
17548 .conf cc string$**$ unset
17549 This specifies recipients of the message and the contents of the ::Cc:: header
17550 when the message is specified by the transport.
17552 .conf file string$**$ unset
17553 The contents of the file are sent as the body of the message when the message
17554 is specified by the transport. If both \file\ and \text\ are set, the text
17555 string comes first.
17557 .conf file@_expand boolean false
17558 If this is set, the contents of the file named by the \file\ option are
17559 subjected to string expansion as they are added to the message.
17561 .conf file@_optional boolean false
17562 If this option is true, no error is generated if the file named by the \file\
17563 option or passed with the address does not exist or cannot be read.
17565 .conf from string$**$ unset
17566 This specifies the contents of the ::From:: header when the message is specified
17569 .conf headers string$**$ unset
17570 This specifies additional RFC 2822 headers that are to be added to the message when
17571 the message is specified by the transport. Several can be given by using `@\n'
17572 to separate them. There is no check on the format.
17574 .conf log string$**$ unset
17575 This option names a file in which a record of every message sent is logged when
17576 the message is specified by the transport.
17578 .conf mode "octal integer" 0600
17579 If either the log file or the `once' file has to be created, this mode is used.
17581 .conf once string$**$ unset
17582 This option names a file or DBM database in which a record of each
17583 ::To:: recipient is kept when the message is specified by the transport.
17584 \**Note**\: This does not apply to ::Cc:: or ::Bcc:: recipients.
17585 If \once@_file@_size\ is not set, a DBM database is used, and it is allowed to
17586 grow as large as necessary. If a potential recipient is already in the
17587 database, no message is sent by default. However, if \once@_repeat\ specifies a
17588 time greater than zero, the message is sent if that much time has elapsed since
17589 a message was last sent to this recipient. If \once\ is unset, the message is
17592 If \once@_file@_size\ is set greater than zero, it changes the way Exim
17593 implements the \once\ option. Instead of using a DBM file to record every
17594 recipient it sends to, it uses a regular file, whose size will never get larger
17595 than the given value. In the file, it keeps a linear list of recipient
17596 addresses and times at which they were sent messages. If the file is full when
17597 a new address needs to be added, the oldest address is dropped. If
17598 \once@_repeat\ is not set, this means that a given recipient may receive
17599 multiple messages, but at unpredictable intervals that depend on the rate of
17600 turnover of addresses in the file. If \once@_repeat\ is set, it specifies a
17601 maximum time between repeats.
17603 .conf once@_file@_size integer 0
17606 .conf once@_repeat time$**$ 0s
17608 After expansion, the value of this option must be a valid time value.
17610 .conf reply@_to string$**$ unset
17611 This specifies the contents of the ::Reply-To:: header when the message is
17612 specified by the transport.
17614 .conf return@_message boolean false
17615 If this is set, a copy of the original message is returned with the new
17616 message, subject to the maximum size set in the \return@_size@_limit\ global
17617 configuration option.
17619 .conf subject string$**$ unset
17620 This specifies the contents of the ::Subject:: header when the message is
17621 specified by the transport.
17623 .conf text string$**$ unset
17624 This specifies a single string to be used as the body of the message when the
17625 message is specified by the transport. If both \text\ and \file\ are set, the
17628 .conf to string$**$ unset
17629 This specifies recipients of the message and the contents of the ::To:: header
17630 when the message is specified by the transport.
17640 . ============================================================================
17641 .chapter The lmtp transport
17642 .set runningfoot "lmtp transport"
17643 .index transports||\%lmtp%\
17644 .index \%lmtp%\ transport
17645 .index LMTP||over a pipe
17646 .index LMTP||over a socket
17647 .rset CHAPLMTP "~~chapter"
17648 The \%lmtp%\ transport runs the LMTP protocol (RFC 2033) over a pipe to a
17650 or by interacting with a Unix domain socket.
17651 This transport is something of a cross between the \%pipe%\ and \%smtp%\
17652 transports. Exim also has support for using LMTP over TCP/IP; this is
17653 implemented as an option for the \%smtp%\ transport. Because LMTP is expected
17654 to be of minority interest, the default build-time configure in \(src/EDITME)\
17655 has it commented out. You need to ensure that
17659 is present in your \(Local/Makefile)\ in order to have the \%lmtp%\ transport
17660 included in the Exim binary.
17662 The private options of the \%lmtp%\ transport are as follows:
17665 .index options||\%lmtp%\ transport
17667 .conf batch@_id string$**$ unset
17668 See the description of local delivery batching in chapter ~~CHAPbatching.
17670 .conf batch@_max integer 1
17671 This limits the number of addresses that can be handled in a single delivery.
17672 Most LMTP servers can handle several addresses at once, so it is normally a
17673 good idea to increase this value. See the description of local delivery
17674 batching in chapter ~~CHAPbatching.
17676 .conf command string$**$ unset
17677 This option must be set if \socket\ is not set.
17678 The string is a command which is run in a separate process. It is split up into
17679 a command name and list of arguments, each of which is separately expanded (so
17680 expansion cannot change the number of arguments). The command is run directly,
17681 not via a shell. The message is passed to the new process using the standard
17682 input and output to operate the LMTP protocol.
17684 .conf socket string$**$ unset
17685 This option must be set if \command\ is not set. The result of expansion must
17686 be the name of a Unix domain socket. The transport connects to the socket and
17687 delivers the message to it using the LMTP protocol.
17689 .conf timeout time 5m
17690 The transport is aborted if the created process
17691 or Unix domain socket
17692 does not respond to LMTP commands or message input within this timeout.
17696 Here is an example of a typical LMTP transport:
17700 command = /some/local/lmtp/delivery/program
17704 This delivers up to 20 addresses at a time, in a mixture of domains if
17705 necessary, running as the user \*exim*\.
17713 . ============================================================================
17714 .chapter The pipe transport
17715 .rset CHAPpipetransport "~~chapter"
17716 .set runningfoot "pipe transport"
17717 .index transports||\%pipe%\
17718 .index \%pipe%\ transport
17719 The \%pipe%\ transport is used to deliver messages via a pipe to a command
17720 running in another process. This can happen in one of two ways:
17722 A router routes an address to a transport in the normal way, and the transport
17723 is configured as a \%pipe%\ transport. In this case, \$local@_part$\ contains
17724 the address (as usual), and the command which is run is specified by the
17725 \command\ option on the transport. An example of this is the use of \%pipe%\ as
17726 a pseudo-remote transport for passing messages to some other delivery mechanism
17729 A router redirects an address directly to a pipe command (for example, from an
17730 alias or forward file). In this case, \$local@_part$\ contains the local part
17731 that was redirected, and \$address@_pipe$\ contains the text of the pipe
17732 command itself. The \command\ option on the transport is ignored.
17735 The \%pipe%\ transport is a non-interactive delivery method. Exim can also
17736 deliver messages over pipes using the LMTP interactive protocol. This is
17737 implemented by the \%lmtp%\ transport.
17739 In the case when \%pipe%\ is run as a consequence of an entry in a local user's
17740 \(.forward)\ file, the command runs under the uid and gid of that user. In
17741 other cases, the uid and gid have to be specified explicitly, either on the
17742 transport or on the router that handles the address. Current and `home'
17743 directories are also controllable. See chapter ~~CHAPenvironment for details of
17744 the local delivery environment.
17746 .section Returned status and data
17747 .index \%pipe%\ transport||returned data
17748 If the command exits with a non-zero return code, the delivery is deemed to
17749 have failed, unless either the \ignore@_status\ option is set (in which case
17750 the return code is treated as zero), or the return code is one of those listed
17751 in the \temp@_errors\ option, which are interpreted as meaning `try again
17752 later'. In this case, delivery is deferred. Details of a permanent failure are
17753 logged, but are not included in the bounce message, which merely contains
17754 `local delivery failed'.
17756 If the return code is greater than 128 and the command being run is a shell
17757 script, it normally means that the script was terminated by a signal whose
17758 value is the return code minus 128.
17760 If Exim is unable to run the command (that is, if \*execve()*\ fails), the
17761 return code is set to 127. This is the value that a shell returns if it is
17762 asked to run a non-existent command. The wording for the log line suggests that
17763 a non-existent command may be the problem.
17765 The \return@_output\ option can affect the result of a pipe delivery. If it is
17766 set and the command produces any output on its standard output or standard
17767 error streams, the command is considered to have failed, even if it gave a zero
17768 return code or if \ignore@_status\ is set. The output from the command is
17769 included as part of the bounce message. The \return@_fail@_output\ option is
17770 similar, except that output is returned only when the command exits with a
17771 failure return code, that is, a value other than zero or a code that matches
17775 .section How the command is run
17776 .rset SECThowcommandrun "~~chapter.~~section"
17777 .index \%pipe%\ transport||path for command
17778 The command line is (by default) broken down into a command name and arguments
17779 by the \%pipe%\ transport itself. The \allow@_commands\ and \restrict@_to@_path\
17780 options can be used to restrict the commands that may be run.
17781 .index quoting||in pipe command
17782 Unquoted arguments are delimited by white space. If an argument appears in
17783 double quotes, backslash is interpreted as an escape character in the usual
17784 way. If an argument appears in single quotes, no escaping is done.
17786 String expansion is applied to the command line except when it comes from a
17787 traditional \(.forward)\ file (commands from a filter file are expanded). The
17788 expansion is applied to each argument in turn rather than to the whole line.
17789 For this reason, any string expansion item that contains white space must be
17790 quoted so as to be contained within a single argument. A setting such as
17792 command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}}
17794 will not work, because the expansion item gets split between several
17795 arguments. You have to write
17797 command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}"
17799 to ensure that it is all in one argument. The expansion is done in this way,
17800 argument by argument, so that the number of arguments cannot be changed as a
17801 result of expansion, and quotes or backslashes in inserted variables do not
17802 interact with external quoting.
17804 .index transport||filter
17805 .index filter||transport filter
17806 Special handling takes place when an argument consists of precisely the text
17807 `$tt{@$pipe@_addresses}'. This is not a general expansion variable; the only
17808 place this string is recognized is when it appears as an argument for a pipe or
17809 transport filter command. It causes each address that is being handled to be
17810 inserted in the argument list at that point $it{as a separate argument}. This
17811 avoids any problems with spaces or shell metacharacters, and is of use when a
17812 \%pipe%\ transport is handling groups of addresses in a batch.
17814 After splitting up into arguments and expansion, the resulting command is run
17815 in a subprocess directly from the transport, $it{not} under a shell. The
17816 message that is being delivered is supplied on the standard input, and the
17817 standard output and standard error are both connected to a single pipe that is
17818 read by Exim. The \max@_output\ option controls how much output the command may
17819 produce, and the \return@_output\ and \return@_fail@_output\ options control
17820 what is done with it.
17822 Not running the command under a shell (by default) lessens the security risks
17823 in cases when a command from a user's filter file is built out of data that was
17824 taken from an incoming message. If a shell is required, it can of course be
17825 explicitly specified as the command to be run. However, there are circumstances
17826 where existing commands (for example, in \(.forward)\ files) expect to be run
17827 under a shell and cannot easily be modified. To allow for these cases, there is
17828 an option called \use@_shell\, which changes the way the \%pipe%\ transport
17829 works. Instead of breaking up the command line as just described, it expands it
17830 as a single string and passes the result to \(/bin/sh)\. The
17831 \restrict@_to@_path\ option and the \$pipe@_addresses$\ facility cannot be used
17832 with \use@_shell\, and the whole mechanism is inherently less secure.
17835 .section Environment variables
17836 .rset SECTpipeenv "~~chapter.~~section"
17837 .index \%pipe%\ transport||environment for command
17838 .index environment for pipe transport
17839 The environment variables listed below are set up when the command is invoked.
17840 This list is a compromise for maximum compatibility with other MTAs. Note that
17841 the \environment\ option can be used to add additional variables to this
17845 DOMAIN $t $rm{the domain of the address}
17846 HOME $t $rm{the home directory, if set}
17847 HOST $t $rm{the host name when called from a router (see below)}
17848 LOCAL@_PART $t $rm{see below}
17849 LOCAL@_PART@_PREFIX $t $rm{see below}
17850 LOCAL@_PART@_SUFFIX $t $rm{see below}
17851 LOGNAME $t $rm{see below}
17852 MESSAGE@_ID $t $rm{the message's id}
17853 PATH $t $rm{as specified by the \path\ option below}
17854 QUALIFY@_DOMAIN $t $rm{the sender qualification domain}
17855 RECIPIENT $t $rm{the complete recipient address}
17856 SENDER $t $rm{the sender of the message (empty if a bounce)}
17857 SHELL $t `$tt{/bin/sh}'
17858 TZ $t $rm{the value of the \timezone\ option, if set}
17859 USER $t $rm{see below}
17862 When a \%pipe%\ transport is called directly from (for example) an \%accept%\
17863 router, \\LOCAL@_PART\\ is set to the local part of the address. When it is
17864 called as a result of a forward or alias expansion, \\LOCAL@_PART\\ is set to
17865 the local part of the address that was expanded. In both cases, any affixes are
17866 removed from the local part, and made available in \\LOCAL@_PART@_PREFIX\\ and
17867 \\LOCAL@_PART@_SUFFIX\\, respectively. \\LOGNAME\\ and \\USER\\ are set to the
17868 same value as \\LOCAL@_PART\\ for compatibility with other MTAs.
17871 \\HOST\\ is set only when a \%pipe%\ transport is called from a router that
17872 associates hosts with an address, typically when using \%pipe%\ as a
17873 pseudo-remote transport. \\HOST\\ is set to the first host name specified by
17877 If the transport's generic \home@_directory\ option is set, its value is used
17878 for the \\HOME\\ environment variable. Otherwise, a home directory may be set
17879 by the router's \transport@_home@_directory\ option, which defaults to the
17880 user's home directory if \check@_local@_user\ is set.
17882 .section Private options for pipe
17883 .index options||\%pipe%\ transport
17886 .conf allow@_commands "string list$**$" unset
17887 .index \%pipe%\ transport||permitted commands
17888 The string is expanded, and is then interpreted as a colon-separated list of
17889 permitted commands. If \restrict@_to@_path\ is not set, the only commands
17890 permitted are those in the \allow@_commands\ list. They need not be absolute
17891 paths; the \path\ option is still used for relative paths. If
17892 \restrict@_to@_path\ is set with \allow@_commands\, the command must either be
17893 in the \allow@_commands\ list, or a name without any slashes that is found on
17894 the path. In other words, if neither \allow@_commands\ nor \restrict@_to@_path\
17895 is set, there is no restriction on the command, but otherwise only commands
17896 that are permitted by one or the other are allowed. For example, if
17898 allow_commands = /usr/bin/vacation
17900 and \restrict@_to@_path\ is not set, the only permitted command is
17901 \(/usr/bin/vacation)\. The \allow@_commands\ option may not be set if
17902 \use@_shell\ is set.
17904 .conf batch@_id string$**$ unset
17905 See the description of local delivery batching in chapter ~~CHAPbatching.
17907 .conf batch@_max integer 1
17908 This limits the number of addresses that can be handled in a single delivery.
17909 See the description of local delivery batching in chapter ~~CHAPbatching.
17911 .conf check@_string string unset
17912 As \%pipe%\ writes the message, the start of each line is tested for matching
17913 \check@_string\, and if it does, the initial matching characters are replaced
17914 by the contents of \escape@_string\, provided both are set. The value of
17915 \check@_string\ is a literal string, not a regular expression, and the case of
17916 any letters it contains is significant. When \use@_bsmtp\ is set, the contents
17917 of \check@_string\ and \escape@_string\ are forced to values that implement the
17918 SMTP escaping protocol. Any settings made in the configuration file are
17921 .conf command string$**$ unset
17922 This option need not be set when \%pipe%\ is being used to deliver to pipes
17923 obtained directly from address redirections. In other cases, the option must be
17924 set, to provide a command to be run. It need not yield an absolute path (see
17925 the \path\ option below). The command is split up into separate arguments by
17926 Exim, and each argument is separately expanded, as described in section
17927 ~~SECThowcommandrun above.
17929 .conf environment string$**$ unset
17930 .index \%pipe%\ transport||environment for command
17931 .index environment for \%pipe%\ transport
17932 This option is used to add additional variables to the environment in which the
17933 command runs (see section ~~SECTpipeenv for the default list). Its value is a
17934 string which is expanded, and then interpreted as a colon-separated list of
17935 environment settings of the form `<<name>>=<<value>>'.
17937 .conf escape@_string string unset
17938 See \check@_string\ above.
17940 .conf freeze@_exec@_fail boolean false
17941 .index exec failure
17942 .index failure of exec
17943 .index \%pipe%\ transport||failure of exec
17944 Failure to exec the command in a pipe transport is by default treated like
17945 any other failure while running the command. However, if \freeze@_exec@_fail\
17946 is set, failure to exec is treated specially, and causes the message to be
17947 frozen, whatever the setting of \ignore@_status\.
17949 .conf ignore@_status boolean false
17950 If this option is true, the status returned by the subprocess that is set up to
17951 run the command is ignored, and Exim behaves as if zero had been returned.
17952 Otherwise, a non-zero status
17953 or termination by signal
17954 causes an error return from the transport unless the status value is one of
17955 those listed in \temp@_errors\; these cause the delivery to be deferred and
17958 .conf log@_defer@_output boolean false
17959 .index \%pipe%\ transport||logging output
17960 If this option is set, and the status returned by the command is
17961 one of the codes listed in \temp@_errors\ (that is, delivery was deferred),
17962 and any output was produced, the first line of it is written to the main log.
17964 .conf log@_fail@_output boolean false
17965 If this option is set, and the command returns any output, and also ends with a
17966 return code that is neither zero nor one of the return codes listed in
17967 \temp@_errors\ (that is, the delivery failed), the first line of output is
17968 written to the main log.
17970 .conf log@_output boolean false
17971 If this option is set and the command returns any output, the first line of
17972 output is written to the main log, whatever the return code.
17974 .conf max@_output integer 20K
17975 This specifies the maximum amount of output that the command may produce on its
17976 standard output and standard error file combined. If the limit is exceeded, the
17977 process running the command is killed. This is intended as a safety measure to
17978 catch runaway processes. The limit is applied independently of the settings of
17979 the options that control what is done with such output (for example,
17980 \return@_output\). Because of buffering effects, the amount of output may
17981 exceed the limit by a small amount before Exim notices.
17983 .conf message@_prefix string$**$ "see below"
17984 The string specified here is expanded and output at the start of every message.
17985 The default is unset if \use@_bsmtp\ is set. Otherwise it is
17988 From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
17994 This is required by the commonly used \(/usr/bin/vacation)\ program.
17995 However, it must $it{not} be present if delivery is to the Cyrus IMAP server,
17996 or to the \tmail\ local delivery agent. The prefix can be suppressed by setting
18001 .conf message@_suffix string$**$ "see below"
18002 The string specified here is expanded and output at the end of every message.
18003 The default is unset if \use@_bsmtp\ is set. Otherwise it is a single newline.
18004 The suffix can be suppressed by setting
18009 .conf path string $tt{/usr/bin}
18010 This option specifies the string that is set up in the \\PATH\\ environment
18011 variable of the subprocess. If the \command\ option does not yield an absolute
18012 path name, the command is sought in the \\PATH\\ directories, in the usual way.
18013 \**Warning**\: This does not apply to a command specified as a transport
18016 .conf pipe@_as@_creator boolean false
18017 .index uid (user id)||local delivery
18018 If the generic \user\ option is not set and this option is true, the delivery
18019 process is run under the uid that was in force when Exim was originally called
18020 to accept the message. If the group id is not otherwise set (via the generic
18021 \group\ option), the gid that was in force when Exim was originally called to
18022 accept the message is used.
18024 .conf restrict@_to@_path boolean false
18025 When this option is set, any command name not listed in \allow@_commands\ must
18026 contain no slashes. The command is searched for only in the directories listed
18027 in the \path\ option. This option is intended for use in the case when a pipe
18028 command has been generated from a user's \(.forward)\ file. This is usually
18029 handled by a \%pipe%\ transport called \address@_pipe\.
18031 .conf return@_fail@_output boolean false
18032 If this option is true, and the command produced any output and ended with a
18033 return code other than zero or one of the codes listed in \temp@_errors\ (that
18034 is, the delivery failed), the output is returned in the bounce message.
18035 However, if the message has a null sender (that is, it is itself a bounce
18036 message), output from the command is discarded.
18038 .conf return@_output boolean false
18039 If this option is true, and the command produced any output, the delivery is
18040 deemed to have failed whatever the return code from the command, and the output
18041 is returned in the bounce message. Otherwise, the output is just discarded.
18042 However, if the message has a null sender (that is, it is a bounce message),
18043 output from the command is always discarded, whatever the setting of this
18046 .conf temp@_errors "string list" "see below"
18047 .index \%pipe%\ transport||temporary failure
18048 This option contains either a colon-separated list of numbers, or a single
18049 asterisk. If \ignore@_status\ is false
18051 and \return@_output\ is not set,
18053 and the command exits with a non-zero return code, the failure is treated as
18054 temporary and the delivery is deferred if the return code matches one of the
18055 numbers, or if the setting is a single asterisk. Otherwise, non-zero return
18056 codes are treated as permanent errors. The default setting contains the codes
18057 defined by \\EX@_TEMPFAIL\\ and \\EX@_CANTCREAT\\ in \(sysexits.h)\. If Exim is
18058 compiled on a system that does not define these macros, it assumes values of 75
18059 and 73, respectively.
18061 .conf timeout time 1h
18062 If the command fails to complete within this time, it is killed. This normally
18063 causes the delivery to fail. A zero time interval specifies no timeout. In
18064 order to ensure that any subprocesses created by the command are also killed,
18065 Exim makes the initial process a process group leader, and kills the whole
18066 process group on a timeout. However, this can be defeated if one of the
18067 processes starts a new process group.
18069 .conf umask "octal integer" 022
18070 This specifies the umask setting for the subprocess that runs the command.
18072 .conf use@_bsmtp boolean false
18073 .index envelope sender
18074 If this option is set true, the \%pipe%\ transport writes messages in `batch
18075 SMTP' format, with the envelope sender and recipient(s) included as SMTP
18076 commands. If you want to include a leading \\HELO\\ command with such messages,
18077 you can do so by setting the \message@_prefix\ option. See section
18078 ~~SECTbatchSMTP for details of batch SMTP.
18080 .conf use@_crlf boolean false
18081 .index carriage return
18083 This option causes lines to be terminated with the two-character CRLF sequence
18084 (carriage return, linefeed) instead of just a linefeed character. In the case
18085 of batched SMTP, the byte sequence written to the pipe is then an exact image
18086 of what would be sent down a real SMTP connection.
18088 The contents of the \message@_prefix\ and \message@_suffix\ options are written
18089 verbatim, so must contain their own carriage return characters if these are
18090 needed. Since the default values for both \message@_prefix\ and
18091 \message@_suffix\ end with a single linefeed, their values
18093 be changed to end with \"@\r@\n"\ if \use@_crlf\ is set.
18095 .conf use@_shell boolean false
18096 If this option is set, it causes the command to be passed to \(/bin/sh)\
18097 instead of being run directly from the transport, as described in section
18098 ~~SECThowcommandrun. This is less secure, but is needed in some situations
18099 where the command is expected to be run under a shell and cannot easily be
18100 modified. The \allow@_commands\ and \restrict@_to@_path\ options, and the
18101 `$tt{@$pipe@_addresses}' facility are incompatible with \use@_shell\. The
18102 command is expanded as a single string, and handed to \(/bin/sh)\ as data for
18107 .section Using an external local delivery agent
18108 .index local delivery||using an external agent
18109 .index \*procmail*\
18110 .index external local delivery
18111 .index delivery||\*procmail*\
18112 .index delivery||by external agent
18113 The \%pipe%\ transport can be used to pass all messages that require local
18114 delivery to a separate local delivery agent such as \procmail\. When doing
18115 this, care must be taken to ensure that the pipe is run under an appropriate
18116 uid and gid. In some configurations one wants this to be a uid that is trusted
18117 by the delivery agent to supply the correct sender of the message. It may be
18118 necessary to recompile or reconfigure the delivery agent so that it trusts an
18119 appropriate user. The following is an example transport and router
18120 configuration for \procmail\:
18125 command = /usr/local/bin/procmail -d $local_part
18129 check_string = "From "
18130 escape_string = ">From "
18139 transport = procmail_pipe
18142 In this example, the pipe is run as the local user, but with the group set to
18143 \*mail*\. An alternative is to run the pipe as a specific user such as \*mail*\
18144 or \*exim*\, but in this case you must arrange for \procmail\ to trust that
18145 user to supply a correct sender address. If you do not specify either a \group\
18146 or a \user\ option, the pipe command is run as the local user. The home
18147 directory is the user's home directory by default.
18149 Note that the command that the pipe transport runs does $it{not} begin with
18153 as shown in the \procmail\ documentation, because Exim does not by default use
18154 a shell to run pipe commands.
18157 The next example shows a transport and a router for a system where local
18158 deliveries are handled by the Cyrus IMAP server.
18161 local_delivery_cyrus:
18163 command = /usr/cyrus/bin/deliver \
18164 -m ${substr_1:$local_part_suffix} -- $local_part
18177 local_part_suffix = .*
18178 transport = local_delivery_cyrus
18180 Note the unsetting of \message@_prefix\ and \message@_suffix\, and the use of
18181 \return@_output\ to cause any text written by Cyrus to be returned to the
18189 . ============================================================================
18190 .chapter The smtp transport
18191 .rset CHAPsmtptrans "~~chapter"
18192 .set runningfoot "smtp transport"
18193 .index transports||\%smtp%\
18194 .index \%smtp%\ transport
18195 The \%smtp%\ transport delivers messages over TCP/IP connections using the SMTP
18196 or LMTP protocol. The list of hosts to try can either be taken from the address
18197 that is being processed (having been set up by the router), or specified
18198 explicitly for the transport. Timeout and retry processing (see chapter
18199 ~~CHAPretry) is applied to each IP address independently.
18201 .section Multiple messages on a single connection
18202 The sending of multiple messages over a single TCP/IP connection can arise in
18205 If a message contains more than \max@_rcpt\ (see below) addresses that are
18206 routed to the same host, more than one copy of the message has to be sent to
18207 that host. In this situation, multiple copies may be sent in a single run of
18208 the \%smtp%\ transport over a single TCP/IP connection. (What Exim actually does
18209 when it has too many addresses to send in one message also depends on the value
18210 of the global \remote@_max@_parallel\ option. Details are given in section
18213 .index hints database||remembering routing
18214 When a message has been successfully delivered over a TCP/IP connection, Exim
18215 looks in its hints database to see if there are any other messages awaiting a
18216 connection to the same host. If there are, a new delivery process is started
18217 for one of them, and the current TCP/IP connection is passed on to it. The new
18218 process may in turn send multiple copies and possibly create yet another
18222 For each copy sent over the same TCP/IP connection, a sequence counter is
18223 incremented, and if it ever gets to the value of \connection@_max@_messages\,
18224 no further messages are sent over that connection.
18227 .section Use of the @$host variable
18229 .index \$host@_address$\
18230 At the start of a run of the \%smtp%\ transport, the values of \$host$\ and
18231 \$host@_address$\ are the name and IP address of the first host on the host list
18232 passed by the router. However, when the transport is about to connect to a
18233 specific host, and while it is connected to that host, \$host$\ and
18234 \$host@_address$\ are set to the values for that host. These are the values
18235 that are in force when the \helo@_data\, \hosts@_try@_auth\, \interface\,
18236 \serialize@_hosts\, and the various TLS options are expanded.
18239 .section Private options for smtp
18240 The private options of the \%smtp%\ transport are as follows:
18242 .index options||\%smtp%\ transport
18244 .conf allow@_localhost boolean false
18245 .index local host||sending to
18246 .index fallback||hosts specified on transport
18247 When a host specified in \hosts\ or \fallback@_hosts\ (see below) turns out to
18248 be the local host, or is listed in \hosts@_treat@_as@_local\, delivery is
18249 deferred by default. However, if \allow@_localhost\ is set, Exim goes on to do
18250 the delivery anyway. This should be used only in special cases when the
18251 configuration ensures that no looping will result (for example, a differently
18252 configured Exim is listening on the port to which the message is sent).
18254 .conf authenticated@_sender string$**$ unset
18256 When Exim has authenticated as a client, this option sets a value for the
18257 \\AUTH=\\ item on outgoing \\MAIL\\ commands, overriding any existing
18258 authenticated sender value. If the string expansion is forced to fail, the
18259 option is ignored. Other expansion failures cause delivery to be deferred. If
18260 the result of expansion is an empty string, that is also ignored.
18262 If the SMTP session is not authenticated, the expansion of
18263 \authenticated@_sender\ still happens (and can cause the delivery to be
18264 deferred if it fails), but no \\AUTH=\\ item is added to \\MAIL\\ commands.
18266 This option allows you to use the \%smtp%\ transport in LMTP mode to
18267 deliver mail to Cyrus IMAP and provide the proper local part as the
18268 `authenticated sender', via a setting such as:
18270 authenticated_sender = $local_part
18272 This removes the need for IMAP subfolders to be assigned special ACLs to
18273 allow direct delivery to those subfolders.
18275 Because of expected uses such as that just described for Cyrus (when no
18276 domain is involved), there is no checking on the syntax of the provided
18279 .conf command@_timeout time 5m
18280 This sets a timeout for receiving a response to an SMTP command that has been
18281 sent out. It is also used when waiting for the initial banner line from the
18282 remote host. Its value must not be zero.
18284 .conf connect@_timeout time 5m
18285 This sets a timeout for the \*connect()*\ function, which sets up a TCP/IP call
18286 to a remote host. A setting of zero allows the system timeout (typically
18287 several minutes) to act. To have any effect, the value of this option must be
18288 less than the system timeout. However, it has been observed that on some
18289 systems there is no system timeout, which is why the default value for this
18290 option is 5 minutes, a value recommended by RFC 1123.
18292 .index SMTP||passed connection
18293 .index SMTP||multiple deliveries
18294 .index multiple SMTP deliveries
18295 .conf connection@_max@_messages integer 500
18296 This controls the maximum number of separate message deliveries that are sent
18297 over a single TCP/IP connection. If the value is zero, there is no limit.
18298 For testing purposes, this value can be overridden by the \-oB-\ command line
18301 .conf data@_timeout time 5m
18302 This sets a timeout for the transmission of each block in the data portion of
18303 the message. As a result, the overall timeout for a message depends on the size
18304 of the message. Its value must not be zero. See also \final@_timeout\.
18306 .conf delay@_after@_cutoff boolean true
18307 This option controls what happens when all remote IP addresses for a given
18308 domain have been inaccessible for so long that they have passed their retry
18311 In the default state, if the next retry time has not been reached for any of
18312 them, the address is bounced without trying any deliveries. In other words,
18313 Exim delays retrying an IP address after the final cutoff time until a new
18314 retry time is reached, and can therefore bounce an address without ever trying
18315 a delivery, when machines have been down for a long time. Some people are
18316 unhappy at this prospect, so...
18318 If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP
18319 addresses are past their final cutoff time, Exim tries to deliver to those
18320 IP addresses that have not been tried since the message arrived. If there are
18321 none, of if they all fail, the address is bounced. In other words, it does not
18322 delay when a new message arrives, but immediately tries those expired IP
18323 addresses that haven't been tried since the message arrived. If there is a
18324 continuous stream of messages for the dead hosts, unsetting
18325 \delay@_after@_cutoff\ means that there will be many more attempts to deliver
18328 .conf dns@_qualify@_single boolean true
18329 If the \hosts\ or \fallback@_hosts\ option is being used,
18330 and the \gethostbyname\ option is false,
18331 the \\RES@_DEFNAMES\\ resolver option is set. See the \qualify@_single\ option
18332 in chapter ~~CHAPdnslookup for more details.
18334 .conf dns@_search@_parents boolean false
18335 .index \search@_parents\
18336 If the \hosts\ or \fallback@_hosts\ option is being used, and the
18337 \gethostbyname\ option is false, the \\RES@_DNSRCH\\ resolver option is set.
18338 See the \search@_parents\ option in chapter ~~CHAPdnslookup for more details.
18341 .conf fallback@_hosts "string list" unset
18342 .index fallback||hosts specified on transport
18343 String expansion is not applied to this option. The argument must be a
18344 colon-separated list of host names or IP addresses. Fallback hosts can also be
18345 specified on routers, which associate them with the addresses they process. As
18346 for the \hosts\ option without \hosts@_override\, \fallback@_hosts\ specified
18347 on the transport is used only if the address does not have its own associated
18348 fallback host list. Unlike \hosts\, a setting of \fallback@_hosts\ on an
18349 address is not overridden by \hosts@_override\. However, \hosts@_randomize\
18350 does apply to fallback host lists.
18352 If Exim is unable to deliver to any of the hosts for a particular address, and
18353 the errors are not permanent rejections, the address is put on a separate
18354 transport queue with its host list replaced by the fallback hosts, unless the
18355 address was routed via MX records and the current host was in the original MX
18356 list. In that situation, the fallback host list is not used.
18358 Once normal deliveries are complete, the fallback queue is delivered by
18359 re-running the same transports with the new host lists. If several failing
18360 addresses have the same fallback hosts (and \max@_rcpt\ permits it), a single
18361 copy of the message is sent.
18363 The resolution of the host names on the fallback list is controlled by the
18364 \gethostbyname\ option, as for the \hosts\ option. Fallback hosts apply
18365 both to cases when the host list comes with the address and when it is taken
18366 from \hosts\. This option provides a `use a smart host only if delivery fails'
18369 .conf final@_timeout time 10m
18370 This is the timeout that applies while waiting for the response to the final
18371 line containing just `.' that terminates a message. Its value must not be zero.
18373 .conf gethostbyname boolean false
18374 If this option is true when the \hosts\ and/or \fallback@_hosts\ options are
18375 being used, names are looked up using \*gethostbyname()*\
18376 (or \*getipnodebyname()*\ when available)
18377 instead of using the DNS. Of course, that function may in fact use the DNS, but
18378 it may also consult other sources of information such as \(/etc/hosts)\.
18380 .index \\HELO\\||argument, setting
18381 .index \\EHLO\\||argument, setting
18382 .conf helo@_data string$**$ $tt{@$primary@_hostname}
18383 The value of this option is expanded, and used as the argument for the \\EHLO\\
18384 or \\HELO\\ command that starts the outgoing SMTP session.
18386 .conf hosts "string list$**$" unset
18387 Hosts are associated with an address by a router such as \%dnslookup%\, which
18388 finds the hosts by looking up the address domain in the DNS. However, addresses
18389 can be passed to the \%smtp%\ transport by any router, and not all of them can
18390 provide an associated host list. The \hosts\ option specifies a list of hosts
18391 which are used if the address being processed does not have any hosts
18392 associated with it. The hosts specified by \hosts\ are also used, whether or
18393 not the address has its own hosts, if \hosts@_override\ is set.
18395 The string is first expanded, before being interpreted as a colon-separated
18396 list of host names or IP addresses. If the expansion fails, delivery is
18397 deferred. Unless the failure was caused by the inability to complete a lookup,
18398 the error is logged to the panic log as well as the main log. Host names are
18399 looked up either by searching directly for address records in the DNS or by
18400 calling \*gethostbyname()*\
18401 (or \*getipnodebyname()*\ when available),
18402 depending on the setting of the \gethostbyname\ option. When Exim is compiled
18403 with IPv6 support, if a host that is looked up in the DNS has both IPv4 and
18404 IPv6 addresses, both types of address are used.
18406 During delivery, the hosts are tried in order, subject to their retry status,
18407 unless \hosts@_randomize\ is set.
18409 .conf hosts@_avoid@_esmtp "host list$**$" unset
18410 .index ESMTP, avoiding use of
18411 .index \\HELO\\||forcing use of
18412 .index \\EHLO\\||avoiding use of
18413 .index \\PIPELINING\\||avoiding the use of
18414 This option is for use with broken hosts that announce ESMTP facilities (for
18415 example, \\PIPELINING\\) and then fail to implement them properly. When a host
18416 matches \hosts@_avoid@_esmtp\, Exim sends \\HELO\\ rather than \\EHLO\\ at the
18417 start of the SMTP session. This means that it cannot use any of the ESMTP
18418 facilities such as \\AUTH\\, \\PIPELINING\\, \\SIZE\\, and \\STARTTLS\\.
18420 .conf hosts@_avoid@_tls "host list$**$" unset
18421 .index TLS||avoiding for certain hosts
18422 Exim will not try to start a TLS session when delivering to any host that
18423 matches this list. See chapter ~~CHAPTLS for details of TLS.
18425 .conf hosts@_max@_try integer 5
18426 .index host||maximum number to try
18427 .index limit||number of hosts tried
18428 .index limit||number of MX tried
18429 .index MX record||maximum tried
18430 This option limits the number of IP addresses that are tried for any one
18433 in cases where there are temporary delivery errors.
18435 Section ~~SECTvalhosmax describes in detail how the value of this option is
18438 .conf hosts@_nopass@_tls "host list$**$" unset
18439 .index TLS||passing connection
18440 .index multiple SMTP deliveries
18441 .index TLS||multiple message deliveries
18442 For any host that matches this list, a connection on which a TLS session has
18443 been started will not be passed to a new delivery process for sending another
18444 message on the same connection. See section ~~SECTmulmessam for an explanation
18445 of when this might be needed.
18447 .conf hosts@_override boolean false
18448 If this option is set and the \hosts\ option is also set, any hosts that are
18449 attached to the address are ignored, and instead the hosts specified by the
18450 \hosts\ option are always used. This option does not apply to
18453 .conf hosts@_randomize boolean false
18454 .index randomized host list
18455 .index host||list of, randomized
18456 .index fallback||randomized hosts
18457 If this option is set, and either the list of hosts is taken from the
18458 \hosts\ or the \fallback@_hosts\ option, or the hosts supplied by the router
18459 were not obtained from MX records (this includes fallback hosts from the
18460 router), and were not randomizied by the router, the order of trying the hosts
18461 is randomized each time the transport runs. Randomizing the order of a host
18462 list can be used to do crude load sharing.
18464 When \hosts@_randomize\ is true, a host list may be split into groups whose
18465 order is separately randomized. This makes it possible to set up MX-like
18466 behaviour. The boundaries between groups are indicated by an item that is just
18467 \"+"\ in the host list. For example:
18469 hosts = host1:host2:host3:+:host4:host5
18471 The order of the first three hosts and the order of the last two hosts is
18472 randomized for each use, but the first three always end up before the last two.
18473 If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored.
18475 .index authentication||required by client
18476 .conf hosts@_require@_auth "host list$**$" unset
18477 This option provides a list of servers for which authentication must succeed
18478 before Exim will try to transfer a message. If authentication fails for
18479 servers which are not in this list, Exim tries to send unauthenticated. If
18480 authentication fails for one of these servers, delivery is deferred. This
18481 temporary error is detectable in the retry rules, so it can be turned into a
18482 hard failure if required. See also \hosts@_try@_auth\, and chapter
18483 ~~CHAPSMTPAUTH for details of authentication.
18485 .conf hosts@_require@_tls "host list$**$" unset
18486 .index TLS||requiring for certain servers
18487 Exim will insist on using a TLS session when delivering to any host that
18488 matches this list. See chapter ~~CHAPTLS for details of TLS.
18489 \**Note**\: This option affects outgoing mail only. To insist on TLS for
18490 incoming messages, use an appropriate ACL.
18492 .index authentication||optional in client
18493 .conf hosts@_try@_auth "host list$**$" unset
18494 This option provides a list of servers to which, provided they announce
18495 authentication support, Exim will attempt to authenticate as a client when it
18496 connects. If authentication fails, Exim will try to transfer the message
18497 unauthenticated. See also \hosts@_require@_auth\, and chapter ~~CHAPSMTPAUTH
18498 for details of authentication.
18500 .index bind IP address
18501 .index IP address||binding
18502 .conf interface "string list$**$" unset
18503 This option specifies which interface to bind to when making an outgoing SMTP
18504 call. The variables \$host$\ and \$host@_address$\ refer to the host to which a
18505 connection is about to be made during the expansion of the string. Forced
18506 expansion failure, or an empty string result causes the option to be ignored.
18507 Otherwise, after expansion,
18509 the string must be a list of IP addresses, colon-separated by default, but the
18510 separator can be changed in the usual way.
18514 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
18516 The first interface of the correct type (IPv4 or IPv6) is used for the outgoing
18517 connection. If none of them are the correct type, the option is ignored. If
18518 \interface\ is not set, or is ignored, the system's IP functions choose which
18519 interface to use if the host has more than one.
18521 .conf keepalive boolean true
18522 .index keepalive||on outgoing connection
18523 This option controls the setting of \\SO@_KEEPALIVE\\ on outgoing TCP/IP socket
18524 connections. When set, it causes the kernel to probe idle connections
18525 periodically, by sending packets with `old' sequence numbers. The other end of
18526 the connection should send a acknowledgement if the connection is still okay or
18527 a reset if the connection has been aborted. The reason for doing this is that
18528 it has the beneficial effect of freeing up certain types of connection that can
18529 get stuck when the remote host is disconnected without tidying up the TCP/IP
18530 call properly. The keepalive mechanism takes several hours to detect
18533 .conf max@_rcpt integer 100
18534 .index \\RCPT\\||maximum number of outgoing
18535 This option limits the number of \\RCPT\\ commands that are sent in a single
18536 SMTP message transaction. Each set of addresses is treated independently, and
18537 so can cause parallel connections to the same host if \remote@_max@_parallel\
18540 .conf multi@_domain boolean true
18541 When this option is set, the \%smtp%\ transport can handle a number of addresses
18542 containing a mixture of different domains provided they all resolve to the same
18543 list of hosts. Turning the option off restricts the transport to handling only
18544 one domain at a time. This is useful if you want to use \$domain$\ in an
18545 expansion for the transport, because it is set only when there is a single
18546 domain involved in a remote delivery.
18548 .conf port string$**$ "see below"
18549 .index port||sending TCP/IP
18550 .index TCP/IP||setting outgoing port
18551 This option specifies the TCP/IP port on the server to which Exim connects. If
18552 it begins with a digit it is taken as a port number; otherwise it is looked up
18553 using \*getservbyname()*\. The default value is normally `smtp', but if
18554 \protocol\ is set to `lmtp', the default is `lmtp'.
18555 If the expansion fails, or if a port number cannot be found, delivery is
18559 .conf protocol string "smtp"
18560 .index LMTP||over TCP/IP
18561 If this option is set to `lmtp' instead of `smtp', the default value for the
18562 \port\ option changes to `lmtp', and the transport operates the LMTP protocol
18563 (RFC 2033) instead of SMTP. This protocol is sometimes used for local
18564 deliveries into closed message stores. Exim also has support for running LMTP
18565 over a pipe to a local process -- see chapter ~~CHAPLMTP.
18567 .conf retry@_include@_ip@_address boolean true
18568 Exim normally includes both the host name and the IP address in the key it
18569 constructs for indexing retry data after a temporary delivery failure. This
18570 means that when one of several IP addresses for a host is failing, it gets
18571 tried periodically (controlled by the retry rules), but use of the other IP
18572 addresses is not affected.
18574 However, in some dialup environments hosts are assigned a different IP address
18575 each time they connect. In this situation the use of the IP address as part of
18576 the retry key leads to undesirable behaviour. Setting this option false causes
18577 Exim to use only the host name. This should normally be done on a separate
18578 instance of the \%smtp%\ transport, set up specially to handle the dialup hosts.
18580 .conf serialize@_hosts "host list$**$" unset
18581 .index serializing connections
18582 .index host||serializing connections
18583 Because Exim operates in a distributed manner, if several messages for the same
18584 host arrive at around the same time, more than one simultaneous connection to
18585 the remote host can occur. This is not usually a problem except when there is a
18586 slow link between the hosts. In that situation it may be helpful to restrict
18587 Exim to one connection at a time. This can be done by setting
18588 \serialize@_hosts\ to match the relevant hosts.
18590 .index hints database||serializing deliveries to a host
18591 Exim implements serialization by means of a hints database in which a record is
18592 written whenever a process connects to one of the restricted hosts. The record
18593 is deleted when the connection is completed. Obviously there is scope for
18594 records to get left lying around if there is a system or program crash. To
18595 guard against this, Exim ignores any records that are more than six hours old.
18597 If you set up this kind of serialization, you should also arrange to delete the
18598 relevant hints database whenever your system reboots. The names of the files
18599 start with \(misc)\ and they are kept in the \(spool/db)\ directory. There
18600 may be one or two files, depending on the type of DBM in use. The same files
18601 are used for ETRN serialization.
18603 .conf size@_addition integer 1024
18604 .index SMTP||\\SIZE\\
18605 .index message||size issue for transport filter
18606 .index size||of message
18607 .index transport||filter
18608 .index filter||transport filter
18609 If a remote SMTP server indicates that it supports the \\SIZE\\ option of the
18610 \\MAIL\\ command, Exim uses this to pass over the message size at the start of
18611 an SMTP transaction. It adds the value of \size@_addition\ to the value it
18612 sends, to allow for headers and other text that may be added during delivery by
18613 configuration options or in a transport filter. It may be necessary to increase
18614 this if a lot of text is added to messages.
18616 Alternatively, if the value of \size@_addition\ is set negative, it disables
18617 the use of the \\SIZE\\ option altogether.
18619 .conf tls@_certificate string$**$ unset
18620 .index TLS||client certificate, location of
18621 .index certificate||for client, location of
18622 The value of this option must be the absolute path to a file which contains the
18623 client's certificate, for use when sending a message over an encrypted
18624 connection. The values of \$host$\ and \$host@_address$\ are set to the name
18625 and address of the server during the expansion. See chapter ~~CHAPTLS for
18628 \**Note**\: This option must be set if you want Exim to use TLS when sending
18629 messages as a client. The global option of the same name specifies the
18630 certificate for Exim as a server; it is not automatically assumed that the same
18631 certificate should be used when Exim is operating as a client.
18634 .conf tls@_crl string$**$ unset
18635 .index TLS||client certificate revocation list
18636 .index certificate||revocation list for client
18637 This option specifies a certificate revocation list. The expanded value must
18638 be the name of a file that contains a CRL in PEM format.
18641 .conf tls@_privatekey string$**$ unset
18642 .index TLS||client private key, location of
18643 The value of this option must be the absolute path to a file which contains the
18644 client's private key, for use when sending a message over an encrypted
18645 connection. The values of \$host$\ and \$host@_address$\ are set to the name
18646 and address of the server during the expansion.
18647 If this option is unset, the private key is assumed to be in the same file as
18649 See chapter ~~CHAPTLS for details of TLS.
18651 .conf tls@_require@_ciphers string$**$ unset
18652 .index TLS||requiring specific ciphers
18653 .index cipher||requiring specific
18654 The value of this option must be a list of permitted cipher suites, for use
18657 outgoing encrypted connection. (There is a global option of the same name for
18658 controlling incoming connections.)
18660 The values of \$host$\ and \$host@_address$\ are set to the name and address of
18661 the server during the expansion. See chapter ~~CHAPTLS for details of TLS; note
18662 that this option is used in different ways by OpenSSL and GnuTLS (see section
18663 ~~SECTreqciphsslgnu).
18665 .conf tls@_tempfail@_tryclear boolean true
18666 When the server host is not in \hosts@_require@_tls\, and there is a problem in
18667 setting up a TLS session, this option determines whether or not Exim should try
18668 to deliver the message unencrypted. If it is set false, delivery to the
18669 current host is deferred; if there are other hosts, they are tried. If this
18670 option is set true, Exim attempts to deliver unencrypted after a 4\*xx*\
18671 response to \\STARTTLS\\. Also, if \\STARTTLS\\ is accepted, but the subsequent
18672 TLS negotiation fails, Exim closes the current connection (because it is in an
18673 unknown state), opens a new one to the same host, and then tries the delivery
18676 .conf tls@_verify@_certificates string$**$ unset
18677 .index TLS||server certificate verification
18678 .index certificate||verification of server
18679 The value of this option must be the absolute path to a file containing
18680 permitted server certificates, for use when setting up an encrypted connection.
18681 Alternatively, if you are using OpenSSL, you can set
18682 \tls@_verify@_certificates\ to the name of a directory containing certificate
18683 files. This does not work with GnuTLS; the option must be set to the name of a
18684 single file if you are using GnuTLS. The values of \$host$\ and
18685 \$host@_address$\ are set to the name and address of the server during the
18686 expansion of this option. See chapter ~~CHAPTLS for details of TLS.
18691 .section How the value of hosts@_max@_try is used
18692 .rset SECTvalhosmax "~~chapter.~~section"
18693 .index host||maximum number to try
18694 .index limit||hosts, maximum number tried
18695 The \hosts@_max@_try\ option limits the number of hosts that are tried
18696 for a single delivery. However, despite the term `host' in its name, the option
18697 actually applies to each IP address independently. In other words, a multihomed
18698 host is treated as several independent hosts, just as it is for retrying.
18700 Many of the larger ISPs have multiple MX records which often point to
18701 multihomed hosts. As a result, a list of a dozen or more IP addresses may be
18702 created as a result of routing one of these domains.
18704 Trying every single IP address on such a long list does not seem sensible; if
18705 several at the top of the list fail, it is reasonable to assume there is some
18706 problem that is likely to affect all of them. Roughly speaking, the value of
18707 \hosts@_max@_try\ is the maximum number that are tried before deferring the
18708 delivery. However, the logic cannot be quite that simple.
18710 Firstly, IP addresses that are skipped because their retry times have not
18711 arrived do not count, and in addition, addresses that are past their retry
18712 limits are also not counted, even when they are tried. This means that when
18713 some IP addresses are past their retry limits, more than the value of
18714 \hosts@_max@_retry\ may be tried. The reason for this behaviour is to ensure
18715 that all IP addresses are considered before timing out an email address.
18717 Secondly, when the \hosts@_max@_try\ limit is reached, Exim looks down the host
18718 list to see if there is a subsequent host with a different (higher valued) MX.
18719 If there is, that host is used next, and the current IP address is used but not
18720 counted. This behaviour helps in the case of a domain with a retry rule that
18721 hardly ever delays any hosts, as is now explained:
18723 Consider the case of a long list of hosts with one MX value, and a few with a
18724 higher MX value. If \hosts@_max@_try\ is small (the default is 5) only a few
18725 hosts at the top of the list are tried at first. With the default retry rule,
18726 which specifies increasing retry times, the higher MX hosts are eventually
18727 tried when those at the top of the list are skipped because they have not
18728 reached their retry times.
18730 However, it is common practice to put a fixed short retry time on domains for
18731 large ISPs, on the grounds that their servers are rarely down for very long.
18732 Unfortunately, these are exactly the domains that tend to resolve to long lists
18733 of hosts. The short retry time means that the lowest MX hosts are tried every
18734 time. The attempts may be in a different order because of random sorting, but
18735 without the special MX check mentioned about, the higher MX hosts would never
18736 be tried at all because the lower MX hosts are never all past their retry
18739 With the special check, Exim tries least one address from each MX value, even
18740 if the \hosts@_max@_try\ limit has already been reached.
18751 . ============================================================================
18752 .chapter Address rewriting
18753 .set runningfoot "address rewriting"
18754 .rset CHAPrewrite ~~chapter
18755 .index rewriting||addresses
18756 There are some circumstances in which Exim automatically rewrites domains in
18757 addresses. The two most common are when an address is given without a domain
18758 (referred to as an `unqualified address') or when an address contains an
18759 abbreviated domain that is expanded by DNS lookup.
18761 Unqualified envelope addresses are accepted only for locally submitted
18762 messages, or messages from hosts that match \sender@_unqualified@_hosts\ or
18763 \recipient@_unqualified@_hosts\, respectively. Unqualified addresses in header
18764 lines are qualified if they are in locally submitted messages, or messages from
18765 hosts that are permitted to send unqualified envelope addresses. Otherwise,
18766 unqualified addresses in header lines are neither qualified nor rewritten.
18768 One situation in which Exim does $it{not} automatically rewrite a domain is
18769 when it is the name of a CNAME record in the DNS. The older RFCs suggest that
18770 such a domain should be rewritten using the `canonical' name, and some MTAs do
18771 this. The new RFCs do not contain this suggestion.
18773 .section Explicitly configured address rewriting
18774 This chapter describes the rewriting rules that can be used in the
18775 main rewrite section of the configuration file, and also in the generic
18776 \headers@_rewrite\ option that can be set on any transport.
18778 Some people believe that configured address rewriting is a Mortal Sin.
18779 Others believe that life is not possible without it. Exim provides the
18780 facility; you do not have to use it.
18783 The main rewriting rules that appear in the `rewrite' section of the
18784 configuration file are applied to addresses in incoming messages, both envelope
18785 addresses and addresses in header lines. Each rule specifies the types of
18786 address to which it applies.
18789 Rewriting of addresses in header lines applies only to those headers that
18790 were received with the message, and, in the case of transport rewriting, those
18791 that were added by a system filter. That is, it applies only to those headers
18792 that are common to all copies of the message. Header lines that are added by
18793 individual routers or transports (and which are therefore specific to
18794 individual recipient addresses) are not rewritten.
18796 In general, rewriting addresses from your own system or domain has some
18797 legitimacy. Rewriting other addresses should be done only with great care and
18798 in special circumstances. The author of Exim believes that rewriting should be
18799 used sparingly, and mainly for `regularizing' addresses in your own domains.
18800 Although it can sometimes be used as a routing tool, this is very strongly
18803 There are two commonly encountered circumstances where rewriting is used, as
18804 illustrated by these examples:
18806 The company whose domain is \*hitch.fict.example*\ has a number of hosts that
18807 exchange mail with each other behind a firewall, but there is only a single
18808 gateway to the outer world. The gateway rewrites \*@*.hitch.fict.example*\ as
18809 \*hitch.fict.example*\ when sending mail off-site.
18811 A host rewrites the local parts of its own users so that, for example,
18812 \*fp42@@hitch.fict.example*\ becomes \*Ford.Prefect@@hitch.fict.example*\.
18816 .section When does rewriting happen?
18817 .index rewriting||timing of
18818 .index ~~ACL||rewriting addresses in
18819 Configured address rewriting can take place at several different stages of a
18820 message's processing.
18822 At the start of an ACL for \\MAIL\\, the sender address may have been rewritten
18823 by a special SMTP-time rewrite rule (see section ~~SECTrewriteS), but no
18824 ordinary rewrite rules have yet been applied. If, however, the sender address
18825 is verified in the ACL, it is rewritten before verification, and remains
18826 rewritten thereafter. The subsequent value of \$sender@_address$\ is the
18827 rewritten address. This also applies if sender verification happens in a
18828 \\RCPT\\ ACL. Otherwise, when the sender address is not verified, it is
18829 rewritten as soon as a message's header lines have been received.
18831 Similarly, at the start of an ACL for \\RCPT\\, the current recipient's address
18832 may have been rewritten by a special SMTP-time rewrite rule, but no ordinary
18833 rewrite rules have yet been applied to it. However, the behaviour is different
18834 from the sender address when a recipient is verified. The address is rewritten
18835 for the verification, but the rewriting is not remembered at this stage. The
18836 value of \$local@_part$\ and \$domain$\ after verification are always the same
18837 as they were before (that is, they contain the unrewritten -- except for
18838 SMTP-time rewriting -- address).
18840 Once a message's header lines have been received, all the envelope recipient
18841 addresses are permanently rewritten, and rewriting is also applied to the
18842 addresses in the header lines (if configured).
18843 .index \*local@_scan()*\ function||address rewriting, timing of
18844 Thus, all the rewriting is completed before the \\DATA\\ ACL and
18845 \*local@_scan()*\ functions are run.
18847 When an address is being routed, either for delivery or for verification,
18848 rewriting is applied immediately to child addresses that are generated by
18849 redirection, unless \no@_rewrite\ is set on the router.
18852 .index envelope sender, rewriting
18853 .index rewriting||at transport time
18854 At transport time, additional rewriting of addresses in header lines can be
18855 specified by setting the generic \headers@_rewrite\ option on a transport. This
18856 option contains rules that are identical in form to those in the rewrite
18857 section of the configuration file. In addition, the outgoing envelope sender
18858 can be rewritten by means of the \return@_path\ transport option. However, it
18859 is not possible to rewrite envelope recipients at transport time.
18863 .section Testing the rewriting rules that apply on input
18864 .index rewriting||testing
18865 .index testing||rewriting
18866 Exim's input rewriting configuration appears in a part of the run time
18867 configuration file headed by `begin rewrite'. It can be tested by the \-brw-\
18868 command line option. This takes an address (which can be a full RFC 2822
18869 address) as its argument. The output is a list of how the address would be
18870 transformed by the rewriting rules for each of the different places it might
18871 appear in an incoming message, that is, for each different header and for the
18872 envelope sender and recipient fields. For example,
18874 exim -brw ph10@exim.workshop.example
18876 might produce the output
18878 sender: Philip.Hazel@exim.workshop.example
18879 from: Philip.Hazel@exim.workshop.example
18880 to: ph10@exim.workshop.example
18881 cc: ph10@exim.workshop.example
18882 bcc: ph10@exim.workshop.example
18883 reply-to: Philip.Hazel@exim.workshop.example
18884 env-from: Philip.Hazel@exim.workshop.example
18885 env-to: ph10@exim.workshop.example
18887 which shows that rewriting has been set up for that address when used in any of
18888 the source fields, but not when it appears as a recipient address. At the
18889 present time, there is no equivalent way of testing rewriting rules that are
18890 set for a particular transport.
18892 .section Rewriting rules
18893 .index rewriting||rules
18894 The rewrite section of the configuration file consists of lines of rewriting
18897 <<source pattern>> <<replacement>> <<flags>>
18899 Rewriting rules that are specified for the \headers@_rewrite\ generic transport
18900 option are given as a colon-separated list. Each item in the list takes the
18901 same form as a line in the main rewriting configuration
18902 (except that any colons must be doubled, of course).
18904 The formats of source patterns and replacement strings are described below.
18905 Each is terminated by white space, unless enclosed in double quotes, in which
18906 case normal quoting conventions apply inside the quotes. The flags are single
18907 characters which may appear in any order. Spaces and tabs between them are
18910 For each address that could potentially be rewritten, the rules are scanned in
18911 order, and replacements for the address from earlier rules can themselves be
18912 replaced by later rules (but see the `q' and `R' flags).
18914 The order in which addresses are rewritten is undefined, may change between
18915 releases, and must not be relied on, with one exception: when a message is
18916 received, the envelope sender is always rewritten first, before any header
18917 lines are rewritten. For example, the replacement string for a rewrite of an
18918 address in ::To:: must not assume that the message's address in ::From:: has (or
18919 has not) already been rewritten. However, a rewrite of ::From:: may assume that
18920 the envelope sender has already been rewritten.
18922 The variables \$local@_part$\ and \$domain$\ can be used in the replacement
18923 string to refer to the address that is being rewritten. Note that lookup-driven
18924 rewriting can be done by a rule of the form
18928 where the lookup key uses \$1$\ and \$2$\ or \$local@_part$\ and \$domain$\ to
18929 refer to the address that is being rewritten.
18931 .section Rewriting patterns
18932 .index rewriting||patterns
18933 .index address list||in a rewriting pattern
18934 The source pattern in a rewriting rule is any item which may appear in an
18935 address list (see section ~~SECTaddresslist). It is in fact processed as a
18936 single-item address list, which means that it is expanded before being tested
18937 against the address.
18939 Domains in patterns should be given in lower case. Local parts in patterns are
18940 case-sensitive. If you want to do case-insensitive matching of local parts, you
18941 can use a regular expression that starts with \"^(?i)"\.
18943 .index numerical variables (\$1$\, \$2$\, etc)||in rewriting rules
18944 After matching, the numerical variables \$1$\, \$2$\, etc. may be set,
18945 depending on the type of match which occurred. These can be used in the
18946 replacement string to insert portions of the incoming address. \$0$\ always
18947 refers to the complete incoming address. When a regular expression is used, the
18948 numerical variables are set from its capturing subexpressions. For other types
18949 of pattern they are set as follows:
18952 If a local part or domain starts with an asterisk, the numerical variables
18953 refer to the character strings matched by asterisks, with \$1$\ associated with
18954 the first asterisk, and \$2$\ with the second, if present. For example, if the
18957 *queen@@*.fict.example
18959 is matched against the address \*hearts-queen@@wonderland.fict.example*\ then
18961 $0 = hearts-queen@wonderland.fict.example
18965 Note that if the local part does not start with an asterisk, but the domain
18966 does, it is \$1$\ that contains the wild part of the domain.
18968 If the domain part of the pattern is a partial lookup, the wild and fixed parts
18969 of the domain are placed in the next available numerical variables. Suppose,
18970 for example, that the address \*foo@@bar.baz.example*\ is processed by a
18971 rewriting rule of the form
18973 *@@partial-dbm;/some/dbm/file <<replacement string>>
18975 and the key in the file that matches the domain is \"*.baz.example"\. Then
18981 If the address \*foo@@baz.example*\ is looked up, this matches the same
18982 wildcard file entry, and in this case \$2$\ is set to the empty string, but
18983 \$3$\ is still set to \*baz.example*\. If a non-wild key is matched in a
18984 partial lookup, \$2$\ is again set to the empty string and \$3$\ is set to the
18985 whole domain. For non-partial domain lookups, no numerical variables are set.
18988 .section Rewriting replacements
18989 .index rewriting||replacements
18990 If the replacement string for a rule is a single asterisk, addresses that
18991 match the pattern and the flags are $it{not} rewritten, and no subsequent
18992 rewriting rules are scanned. For example,
18994 hatta@lookingglass.fict.example * f
18996 specifies that \*hatta@@lookingglass.fict.example*\ is never to be rewritten in
18999 If the replacement string is not a single asterisk, it is expanded, and must
19000 yield a fully qualified address. Within the expansion, the variables
19001 \$local@_part$\ and \$domain$\ refer to the address that is being rewritten.
19002 Any letters they contain retain their original case -- they are not lower
19003 cased. The numerical variables are set up according to the type of pattern that
19004 matched the address, as described above. If the expansion is forced to fail by
19005 the presence of `fail' in a conditional or lookup item, rewriting by the
19006 current rule is abandoned, but subsequent rules may take effect. Any other
19007 expansion failure causes the entire rewriting operation to be abandoned, and an
19008 entry written to the panic log.
19011 .section Rewriting flags
19012 There are three different kinds of flag that may appear on rewriting rules:
19014 Flags that specify which headers and envelope addresses to rewrite: E, F, T, b,
19017 A flag that specifies rewriting at SMTP time: S.
19019 Flags that control the rewriting process: Q, q, R, w.
19021 For rules that are part of the \headers@_rewrite\ generic transport option,
19022 E, F, T, and S are not permitted.
19025 .section Flags specifying which headers and envelope addresses to rewrite
19026 .index rewriting||flags
19027 If none of the following flag letters, nor the `S' flag (see section
19028 ~~SECTrewriteS) are present, a main rewriting rule applies to all headers and
19029 to both the sender and recipient fields of the envelope, whereas a
19030 transport-time rewriting rule just applies to all headers. Otherwise, the
19031 rewriting rule is skipped unless the relevant addresses are being processed.
19033 E $rm{rewrite all envelope fields}
19034 F $rm{rewrite the envelope From field}
19035 T $rm{rewrite the envelope To field}
19036 b $rm{rewrite the ::Bcc:: header}
19037 c $rm{rewrite the ::Cc:: header}
19038 f $rm{rewrite the ::From:: header}
19039 h $rm{rewrite all headers}
19040 r $rm{rewrite the ::Reply-To:: header}
19041 s $rm{rewrite the ::Sender:: header}
19042 t $rm{rewrite the ::To:: header}
19044 You should be particularly careful about rewriting ::Sender:: headers, and
19045 restrict this to special known cases in your own domains.
19047 .section The SMTP-time rewriting flag
19048 .rset SECTrewriteS "~~chapter.~~section"
19049 .index SMTP||rewriting malformed addresses
19050 .index \\RCPT\\||rewriting argument of
19051 .index \\MAIL\\||rewriting argument of
19052 The rewrite flag `S' specifies a rewrite of incoming envelope addresses at SMTP
19053 time, as soon as an address is received in a \\MAIL\\ or \\RCPT\\ command, and
19054 before any other processing; even before syntax checking. The pattern is
19055 required to be a regular expression, and it is matched against the whole of the
19056 data for the command, including any surrounding angle brackets.
19058 This form of rewrite rule allows for the handling of addresses that are not
19059 compliant with RFCs 2821 and 2822 (for example, `bang paths' in batched SMTP
19060 input). Because the input is not required to be a syntactically valid address,
19061 the variables \$local@_part$\ and \$domain$\ are not available during the
19062 expansion of the replacement string. The result of rewriting replaces the
19063 original address in the \\MAIL\\ or \\RCPT\\ command.
19065 .section Flags controlling the rewriting process
19066 There are four flags which control the way the rewriting process works. These
19067 take effect only when a rule is invoked, that is, when the address is of the
19068 correct type (matches the flags) and matches the pattern:
19070 If the `Q' flag is set on a rule, the rewritten address is permitted to be an
19071 unqualified local part. It is qualified with \qualify@_recipient\. In the
19072 absence of `Q' the rewritten address must always include a domain.
19074 If the `q' flag is set on a rule, no further rewriting rules are considered,
19075 even if no rewriting actually takes place because of a `fail' in the expansion.
19076 The `q' flag is not effective if the address is of the wrong type (does not
19077 match the flags) or does not match the pattern.
19079 The `R' flag causes a successful rewriting rule to be re-applied to the new
19080 address, up to ten times. It can be combined with the `q' flag, to stop
19081 rewriting once it fails to match (after at least one successful rewrite).
19083 .index rewriting||whole addresses
19084 When an address in a header is rewritten, the rewriting normally applies only
19085 to the working part of the address, with any comments and RFC 2822 `phrase'
19086 left unchanged. For example, rewriting might change
19088 From: Ford Prefect <fp42@restaurant.hitch.fict.example>
19092 From: Ford Prefect <prefectf@hitch.fict.example>
19094 Sometimes there is a need to replace the whole address item, and this can be
19095 done by adding the flag letter `w' to a rule. If this is set on a rule that
19096 causes an address in a header line to be rewritten, the entire address is
19097 replaced, not just the working part. The replacement must be a complete RFC
19098 2822 address, including the angle brackets if necessary. If text outside angle
19099 brackets contains a character whose value is greater than 126 or less than 32
19100 (except for tab), the text is encoded according to RFC 2047.
19101 The character set is taken from \headers@_charset\, which defaults to
19104 When the `w' flag is set on a rule that causes an envelope address to be
19105 rewritten, all but the working part of the replacement address is discarded.
19108 .section Rewriting examples
19109 Here is an example of the two common rewriting paradigms:
19111 *@*.hitch.fict.example $1@hitch.fict.example
19112 *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\
19113 {$value}fail}@hitch.fict.example bctfrF
19115 Note the use of `fail' in the lookup expansion in the second rule, forcing
19116 the string expansion to fail if the lookup does not succeed. In this context it
19117 has the effect of leaving the original address unchanged, but Exim goes on to
19118 consider subsequent rewriting rules, if any, because the `q' flag is not
19119 present in that rule. An alternative to `fail' would be to supply \$1$\
19120 explicitly, which would cause the rewritten address to be the same as before,
19121 at the cost of a small bit of processing. Not supplying either of these is an
19122 error, since the rewritten address would then contain no local part.
19124 The first example above replaces the domain with a superior, more general
19125 domain. This may not be desirable for certain local parts. If the rule
19127 root@*.hitch.fict.example *
19129 were inserted before the first rule, rewriting would be suppressed for the
19130 local part \*root*\ at any domain ending in \*hitch.fict.example*\.
19132 Rewriting can be made conditional on a number of tests, by making use of
19133 \${if$\ in the expansion item. For example, to apply a rewriting rule only to
19134 messages that originate outside the local host:
19136 *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\
19137 {$1@hitch.fict.example}fail}"
19139 The replacement string is quoted in this example because it contains white
19142 .index rewriting||bang paths
19143 .index bang paths||rewriting
19144 Exim does not handle addresses in the form of `bang paths'. If it sees such an
19145 address it treats it as an unqualified local part which it qualifies with the
19146 local qualification domain (if the source of the message is local or if the
19147 remote host is permitted to send unqualified addresses). Rewriting can
19148 sometimes be used to handle simple bang paths with a fixed number of
19149 components. For example, the rule
19151 \N^([^!]+)!(.*)@your.domain.example$\N $2@$1
19153 rewrites a two-component bang path \*host.name!user*\ as the domain address
19154 \*user@@host.name*\. However, there is a security implication in using this as
19155 a global rewriting rule for envelope addresses. It can provide a backdoor
19156 method for using your system as a relay, because the incoming addresses appear
19157 to be local. If the bang path addresses are received via SMTP, it is safer to
19158 use the `S' flag to rewrite them as they are received, so that relay checking
19159 can be done on the rewritten addresses.
19169 . ============================================================================
19170 .chapter Retry configuration
19171 .set runningfoot "retry configuration"
19172 .rset CHAPretry ~~chapter
19173 .index retry||configuration, description of
19174 .index configuration file||retry section
19175 The `retry' section of the run time configuration file contains a list of retry
19176 rules which control how often Exim tries to deliver messages that cannot be
19177 delivered at the first attempt. If there are no retry rules, temporary errors
19178 are treated as permanent. The \-brt-\ command line option can be used to test
19179 which retry rule will be used for a given address or domain.
19181 The most common cause of retries is temporary failure to deliver to a remote
19182 host because the host is down, or inaccessible because of a network problem.
19183 Exim's retry processing in this case is applied on a per-host (strictly, per IP
19184 address) basis, not on a per-message basis. Thus, if one message has recently
19185 been delayed, delivery of a new message to the same host is not immediately
19186 tried, but waits for the host's retry time to arrive. If the \retry@_defer\ log
19187 selector is set, the message
19188 .index retry||time not reached
19189 `retry time not reached' is written to the main log whenever a delivery is
19190 skipped for this reason. Section ~~SECToutSMTPerr contains more details of the
19191 handling of errors during remote deliveries.
19193 Retry processing applies to routing as well as to delivering, except as covered
19194 in the next paragraph. The retry rules do not distinguish between these
19195 actions. It is not possible, for example, to specify different behaviour for
19196 failures to route the domain \*snark.fict.example*\ and failures to deliver to
19197 the host \*snark.fict.example*\. I didn't think anyone would ever need this
19198 added complication, so did not implement it. However, although they share the
19199 same retry rule, the actual retry times for routing and transporting a given
19200 domain are maintained independently.
19202 When a delivery is not part of a queue run (typically an immediate delivery on
19203 receipt of a message), the routers are always run, and local deliveries are
19204 always attempted, even if retry times are set for them. This makes for better
19205 behaviour if one particular message is causing problems (for example, causing
19206 quota overflow, or provoking an error in a filter file). If such a delivery
19207 suffers a temporary failure, the retry data is updated as normal, and
19208 subsequent delivery attempts from queue runs occur only when the retry time for
19209 the local address is reached.
19212 .section Retry rules
19213 .index retry||rules
19214 Each retry rule occupies one line and consists of three parts, separated by
19215 white space: a pattern, an error name, and a list of retry parameters. The
19216 pattern must be enclosed in double quotes if it contains white space. The rules
19217 are searched in order until one is found whose pattern matches the failing host
19220 The pattern is any single item that may appear in an address list (see section
19221 ~~SECTaddresslist). It is in fact processed as a one-item address list, which
19222 means that it is expanded before being tested against the address that has
19223 been delayed. Address list processing treats a plain domain name as if it were
19224 preceded by `*@@', which makes it possible for many retry rules to start with
19225 just a domain. For example,
19227 lookingglass.fict.example * F,24h,30m;
19229 provides a rule for any address in the \*lookingglass.fict.example*\ domain,
19232 alice@lookingglass.fict.example * F,24h,30m;
19234 applies only to temporary failures involving the local part \alice\.
19235 In practice, almost all rules start with a domain name pattern without a local
19238 .index regular expressions||in retry rules
19239 \**Warning**\: If you use a regular expression in a routing rule, it must match
19240 a complete address, not just a domain, because that is how regular expressions
19241 work in address lists.
19243 ^@\Nxyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Wrong\
19244 ^@\N[^@@]+@@xyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Right\
19248 .section Choosing which retry rule to use
19249 When Exim is looking for a retry rule after a routing attempt has failed (for
19250 example, after a DNS timeout), each line in the retry configuration is tested
19251 against the complete address only if \retry__use@_local@_part\ is set for the
19252 router. Otherwise, only the domain is used, except when matching against a
19253 regular expression, when the local part of the address is replaced with `*'. A
19254 domain on its own can match a domain pattern, or a pattern that starts with
19255 `*@@'. By default, \retry@_use@_local@_part\ is true for routers where
19256 \check@_local@_user\ is true, and false for other routers.
19258 Similarly, when Exim is looking for a retry rule after a local delivery has
19259 failed (for example, after a mailbox full error), each line in the retry
19260 configuration is tested against the complete address only if
19261 \retry@_use@_local@_part\ is set for the transport (it defaults true for all
19265 When Exim is looking for a retry rule after a remote delivery attempt has
19266 failed, what happens depends on the type of failure. After a 4\*xx*\ SMTP
19267 response for a recipient address, the whole address is used when searching the
19268 retry rules. The rule that is found is used to create a retry time for the
19271 For a temporary error that is not related to an individual address,
19273 (for example, a connection timeout), each line in the retry configuration is
19274 checked twice. First, the name of the remote host is used as a domain name
19275 (preceded by `*@@' when matching a regular expression). If this does not match
19276 the line, the domain from the email address is tried in a similar fashion. For
19277 example, suppose the MX records for \*a.b.c.example*\ are
19279 a.b.c.example MX 5 x.y.z.example
19283 and the retry rules are
19285 p.q.r.example * F,24h,30m;
19286 a.b.c.example * F,4d,45m;
19288 and a delivery to the host \*x.y.z.example*\ fails. The first rule matches
19289 neither the host nor the domain, so Exim looks at the second rule. This does
19290 not match the host, but it does match the domain, so it is used to calculate
19291 the retry time for the host \*x.y.z.example*\. Meanwhile, Exim tries to deliver
19292 to \*p.q.r.example*\. If this fails, the first retry rule is used, because it
19295 In other words, failures to deliver to host \*p.q.r.example*\ use the first
19296 rule to determine retry times, but for all the other hosts for the domain
19297 \*a.b.c.example*\, the second rule is used. The second rule is also used if
19298 routing to \*a.b.c.example*\ suffers a temporary failure.
19300 .section Retry rules for specific errors
19301 .index retry||specific errors, specifying
19302 The second field in a retry rule is the name of a particular error, or an
19303 asterisk, which matches any error. The errors that can be tested for are:
19305 \*auth@_failed*\: authentication failed when trying to send to a host in the
19306 \hosts@_require@_auth\ list in an \%smtp%\ transport
19308 \*refused@_MX*\: connection refused from a host obtained from an MX record
19310 \*refused@_A*\: connection refused from a host not obtained from an MX record
19312 \*refused*\: any connection refusal
19314 \*timeout@_connect@_MX*\: connection timeout from a host obtained from an MX
19317 \*timeout@_connect@_A*\: connection timeout from a host not obtained from an MX
19320 \*timeout@_connect*\: any connection timeout
19322 \*timeout@_MX*\: any timeout from a host obtained from an MX
19325 \*timeout@_A*\: any timeout from a host not obtained from an MX
19328 \*timeout*\: any timeout
19330 \*quota*\: quota exceeded in local delivery by \%appendfile%\
19332 .index quota||error testing in retry rule
19333 .index retry||quota error testing
19334 \*quota@_*\<<time>>: quota exceeded in local delivery, and the mailbox has not
19335 been read for <<time>>. For example, \*quota@_4d*\ applies to a quota error
19336 when the mailbox has not been read for four days.
19339 .index mailbox||time of last read
19340 \**Warning**\: It is not always possible to determine a `time of last read' for
19343 If the mailbox is a single file, the time of last access is used.
19345 .index maildir format||time of last read
19346 For a maildir delivery, the time of last modification of the \(new)\
19347 subdirectory is used. As the mailbox is over quota, no new files will be
19348 created in the \(new)\ subdirectory, so any change is assumed to be the result
19349 of an MUA moving a new message to the \(cur)\ directory when it is first read.
19351 For other kinds of multi-file delivery, the time of last read cannot be
19352 obtained, and so a retry rule that uses this type of error field is never
19357 The quota errors apply both to system-enforced quotas and to Exim's own quota
19358 mechanism in the \%appendfile%\ transport. The \*quota*\ error also applies
19359 when a local delivery is deferred because a partition is full (the \\ENOSPC\\
19363 .section Retry rule parameters
19364 .index retry||parameters in rules
19365 The third field in a retry rule is a sequence of retry parameter sets,
19366 separated by semicolons. Each set consists of
19368 <<letter>>,<<cutoff time>>,<<arguments>>
19370 The letter identifies the algorithm for computing a new retry time; the cutoff
19371 time is the time beyond which this algorithm no longer applies, and the
19372 arguments vary the algorithm's action. The cutoff time is measured from the
19373 time that the first failure for the domain (combined with the local part if
19374 relevant) was detected, not from the time the message was received.
19375 .index retry||algorithms
19376 The available algorithms are:
19378 \*F*\: retry at fixed intervals. There is a single time parameter specifying the
19381 \*G*\: retry at geometrically increasing intervals. The first argument specifies
19382 a starting value for the interval, and the second a multiplier, which is used
19383 to increase the size of the interval at each retry.
19385 When computing the next retry time, the algorithm definitions are scanned in
19386 order until one whose cutoff time has not yet passed is reached. This is then
19387 used to compute a new retry time that is later than the current time. In the
19388 case of fixed interval retries, this simply means adding the interval to the
19389 current time. For geometrically increasing intervals, retry intervals are
19390 computed from the rule's parameters until one that is greater than the previous
19391 interval is found. The main configuration variable
19392 .index limit||retry interval
19393 .index retry||interval, maximum
19394 .index \retry@_interval@_max\
19395 \retry@_interval@_max\ limits the maximum interval between retries.
19397 A single remote domain may have a number of hosts associated with it, and each
19398 host may have more than one IP address. Retry algorithms are selected on the
19399 basis of the domain name, but are applied to each IP address independently. If,
19400 for example, a host has two IP addresses and one is unusable, Exim will
19401 generate retry times for it and will not try to use it until its next retry
19402 time comes. Thus the good IP address is likely to be tried first most of the
19405 .index hints database||use for retrying
19406 Retry times are hints rather than promises. Exim does not make any attempt to
19407 run deliveries exactly at the computed times. Instead, a queue runner process
19408 starts delivery processes for delayed messages periodically, and these attempt
19409 new deliveries only for those addresses that have passed their next retry time.
19410 If a new message arrives for a deferred address, an immediate delivery attempt
19411 occurs only if the address has passed its retry time. In the absence of new
19412 messages, the minimum time between retries is the interval between queue runner
19413 processes. There is not much point in setting retry times of five minutes if
19414 your queue runners happen only once an hour, unless there are a significant
19415 number of incoming messages (which might be the case on a system that is
19416 sending everything to a smart host, for example).
19418 The data in the retry hints database can be inspected by using the
19419 \*exim@_dumpdb*\ or \*exim@_fixdb*\ utility programs (see chapter ~~CHAPutils). The
19420 latter utility can also be used to change the data. The \*exinext*\ utility
19421 script can be used to find out what the next retry times are for the hosts
19422 associated with a particular mail domain, and also for local deliveries that
19423 have been deferred.
19425 .section Retry rule examples
19426 Here are some example retry rules:
19428 alice@wonderland.fict.example quota_5d F,7d,3h
19429 wonderland.fict.example quota_5d
19430 wonderland.fict.example * F,1h,15m; G,2d,1h,2;
19431 lookingglass.fict.example * F,24h,30m;
19432 * refused_A F,2h,20m;
19433 * * F,2h,15m; G,16h,1h,1.5; F,5d,8h
19435 The first rule sets up special handling for mail to
19436 \*alice@@wonderland.fict.example*\ when there is an over-quota error and the
19437 mailbox has not been read for at least 5 days. Retries continue every three
19438 hours for 7 days. The second rule handles over-quota errors for all other local
19439 parts at \*wonderland.fict.example*\; the absence of a local part has the same
19440 effect as supplying `$*$@@'. As no retry algorithms are supplied, messages that
19441 fail are bounced immediately if the mailbox has not been read for at least 5
19444 The third rule handles all other errors at \*wonderland.fict.example*\; retries
19445 happen every 15 minutes for an hour, then with geometrically increasing
19446 intervals until two days have passed since a delivery first failed. After the
19447 first hour there is a delay of one hour, then two hours, then four hours, and
19448 so on (this is a rather extreme example).
19450 The fourth rule controls retries for the domain \*lookingglass.fict.example*\.
19451 They happen every 30 minutes for 24 hours only. The remaining two rules handle
19452 all other domains, with special action for connection refusal from hosts that
19453 were not obtained from an MX record.
19455 The final rule in a retry configuration should always have asterisks in the
19456 first two fields so as to provide a general catch-all for any addresses that do
19457 not have their own special handling. This example tries every 15 minutes for 2
19458 hours, then with intervals starting at one hour and increasing by a factor of
19459 1.5 up to 16 hours, then every 8 hours up to 5 days.
19462 .section Timeout of retry data
19463 .index timeout||of retry data
19464 .index \retry@_data@_expire\
19465 .index hints database||data expiry
19466 .index retry||timeout of data
19467 Exim timestamps the data that it writes to its retry hints database. When it
19468 consults the data during a delivery it ignores any that is older than the value
19469 set in \retry@_data@_expire\ (default 7 days). If, for example, a host hasn't
19470 been tried for 7 days, Exim will try to deliver to it immediately a message
19471 arrives, and if that fails, it will calculate a retry time as if it were
19472 failing for the first time.
19474 This improves the behaviour for messages routed to rarely-used hosts such as MX
19475 backups. If such a host was down at one time, and happens to be down again when
19476 Exim tries a month later, using the old retry data would imply that it had been
19477 down all the time, which is not a justified assumption.
19479 If a host really is permanently dead, this behaviour causes a burst of retries
19480 every now and again, but only if messages routed to it are rare. It there is a
19481 message at least once every 7 days the retry data never expires.
19485 .section Long-term failures
19486 .index delivery||failure, long-term
19487 .index retry||after long-term failure
19488 Special processing happens when an email address has been failing for so long
19489 that the cutoff time for the last algorithm is reached. For example, using the
19490 default retry rule:
19492 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
19494 the cutoff time is four days. Reaching the retry cutoff is independent of how
19495 long any specific message has been failing; it is the length of continuous
19496 failure for the recipient address that counts.
19498 When the cutoff time is reached for a local delivery, or for all the IP
19499 addresses associated with a remote delivery, a subsequent delivery failure
19500 causes Exim to give up on the address, and a bounce message is generated.
19501 In order to cater for new messages that use the failing address, a next retry
19502 time is still computed from the final algorithm, and is used as follows:
19504 For local deliveries, one delivery attempt is always made for any subsequent
19505 messages. If this delivery fails, the address fails immediately. The
19506 post-cutoff retry time is not used.
19508 If the delivery is remote, there are two possibilities, controlled by the
19509 .index \delay@_after@_cutoff\
19510 \delay@_after@_cutoff\ option of the \%smtp%\ transport. The option is true by
19511 default and in that case:
19513 Until the post-cutoff retry time for one of the IP addresses is reached,
19514 the failing email address is bounced immediately, without a delivery attempt
19515 taking place. After that time, one new delivery attempt is made to those IP
19516 addresses that are past their retry times, and if that still fails, the address
19517 is bounced and new retry times are computed.
19520 In other words, when all the hosts for a given email address have been failing
19521 for a long time, Exim bounces rather then defers until one of the hosts' retry
19522 times is reached. Then it tries once, and bounces if that attempt fails. This
19523 behaviour ensures that few resources are wasted in repeatedly trying to deliver
19524 to a broken destination, but if the host does recover, Exim will eventually
19527 If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP
19528 addresses are past their final cutoff time, Exim tries to deliver to those IP
19529 addresses that have not been tried since the message arrived. If there are
19530 no suitable IP addresses, or if they all fail, the address is bounced. In other
19531 words, it does not delay when a new message arrives, but tries the expired
19532 addresses immediately, unless they have been tried since the message arrived.
19533 If there is a continuous stream of messages for the failing domains, setting
19534 \delay@_after@_cutoff\ false means that there will be many more attempts to
19535 deliver to permanently failing IP addresses than when \delay@_after@_cutoff\ is
19538 .section Ultimate address timeout
19539 .index retry||ultimate address timeout
19540 An additional rule is needed to cope with cases where a host is intermittently
19541 available, or when a message has some attribute that prevents its delivery when
19542 others to the same address get through. In this situation, because some
19543 messages are successfully delivered, the `retry clock' for the address keeps
19544 getting restarted, and so a message could remain on the queue for ever. To
19545 prevent this, if a message has been on the queue for longer than the cutoff
19546 time of any applicable retry rule for a given address, a delivery is attempted
19547 for that address, even if it is not yet time, and if this delivery fails, the
19548 address is timed out. A new retry time is not computed in this case, so that
19549 other messages for the same address are considered immediately.
19559 . ============================================================================
19560 .chapter SMTP authentication
19561 .set runningfoot "SMTP authentication"
19562 .rset CHAPSMTPAUTH "~~chapter"
19563 .index SMTP||authentication configuration
19564 .index authentication
19565 The `authenticators' section of Exim's run time configuration is concerned with
19566 SMTP authentication. This facility is an extension to the SMTP protocol,
19567 described in RFC 2554, which allows a client SMTP host to authenticate itself
19568 to a server. This is a common way for a server to recognize clients that
19569 are permitted to use it as a relay. SMTP authentication is not of relevance to
19570 the transfer of mail between servers that have no managerial connection with
19573 .index \\AUTH\\||description of
19574 Very briefly, the way SMTP authentication works is as follows:
19576 The server advertises a number of authentication \*mechanisms*\ in response to
19577 the client's \\EHLO\\ command.
19579 The client issues an \\AUTH\\ command, naming a specific mechanism. The command
19580 may, optionally, contain some authentication data.
19582 The server may issue one or more \*challenges*\, to which the client must send
19583 appropriate responses. In simple authentication mechanisms, the challenges are
19584 just prompts for user names and passwords. The server does not have to issue
19585 any challenges -- in some mechanisms the relevant data may all be transmitted
19586 with the \\AUTH\\ command.
19588 The server either accepts or denies authentication.
19590 If authentication succeeds, the client may optionally make use of the \\AUTH\\
19591 option on the \\MAIL\\ command to pass an authenticated sender in subsequent
19592 mail transactions. Authentication lasts for the remainder of the SMTP
19595 If authentication fails, the client may give up, or it may try a different
19596 authentication mechanism, or it may try transferring mail over the
19597 unauthenticated connection.
19599 If you are setting up a client, and want to know which authentication
19600 mechanisms the server supports, you can use Telnet to connect to port 25 (the
19601 SMTP port) on the server, and issue an \\EHLO\\ command. The response to this
19602 includes the list of supported mechanisms. For example:
19604 @$ $cb{telnet server.example 25}
19605 Trying 192.168.34.25...
19606 Connected to server.example.
19607 Escape character is '@^]'.
19608 220 server.example ESMTP Exim 4.20 ...
19609 $cb{ehlo client.example}
19610 250-server.example Hello client.example [10.8.4.5]
19616 The second-last line of this example output shows that the server supports
19617 authentication using the PLAIN mechanism. In Exim, the different authentication
19618 mechanisms are configured by specifying \*authenticator*\ drivers. Like the
19619 routers and transports, which authenticators are included in the binary is
19620 controlled by build-time definitions. The following are currently available,
19621 included by setting
19627 in \(Local/Makefile)\, respectively. The first of these supports the CRAM-MD5
19628 authentication mechanism (RFC 2195), and the second can be configured to
19629 support the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism,
19630 which is not formally documented, but used by several MUAs. The third
19631 authenticator supports Microsoft's \*Secure Password Authentication*\
19634 The authenticators are configured using the same syntax as other drivers (see
19635 section ~~SECTfordricon). If no authenticators are required, no authentication
19636 section need be present in the configuration file. Each authenticator can in
19637 principle have both server and client functions. When Exim is receiving SMTP
19638 mail, it is acting as a server; when it is sending out messages over SMTP, it
19639 is acting as a client. Authenticator configuration options are provided for use
19640 in both these circumstances.
19642 To make it clear which options apply to which situation, the prefixes
19643 \server@_\ and \client@_\ are used on option names that are specific to either
19644 the server or the client function, respectively. Server and client functions
19645 are disabled if none of their options are set. If an authenticator is to be
19646 used for both server and client functions, a single definition, using both sets
19647 of options, is required. For example:
19651 public_name = CRAM-MD5
19652 server_secret = ${if eq{$1}{ph10}{secret1}fail}
19654 client_secret = secret2
19656 The \server@_\ option is used when Exim is acting as a server, and the
19657 \client@_\ options when it is acting as a client.
19659 Descriptions of the individual authenticators are given in subsequent chapters.
19660 The remainder of this chapter covers the generic options for the
19661 authenticators, followed by general discussion of the way authentication works
19665 .section Generic options for authenticators
19666 .index authentication||generic options
19669 .index options||generic, for authenticators
19671 .conf driver string unset
19672 This option must always be set. It specifies which of the available
19673 authenticators is to be used.
19675 .conf public@_name string unset
19676 This option specifies the name of the authentication mechanism that the driver
19677 implements, and by which it is known to the outside world. These names should
19678 contain only upper case letters, digits, underscores, and hyphens (RFC 2222),
19679 but Exim in fact matches them caselessly. If \public@_name\ is not set, it
19680 defaults to the driver's instance name.
19682 .conf server@_advertise@_condition string$**$ unset
19683 When a server is about to advertise an authentication mechanism, the condition
19684 is expanded. If it yields the empty string, `0', `no', or `false', the
19685 mechanism is not advertised.
19686 If the expansion fails, the mechanism is not advertised. If the failure was not
19687 forced, and was not caused by a lookup defer, the incident is logged.
19688 See section ~~SECTauthexiser below for further discussion.
19690 .conf server@_debug@_print string$**$ unset
19691 If this option is set and authentication debugging is enabled (see the \-d-\
19692 command line option), the string is expanded and included in the debugging
19693 output when the authenticator is run as a server. This can help with checking
19694 out the values of variables.
19695 If expansion of the string fails, the error message is written to the debugging
19696 output, and Exim carries on processing.
19698 .conf server@_set@_id string$**$ unset
19699 When an Exim server successfully authenticates a client, this string is
19700 expanded using data from the authentication, and preserved for any incoming
19701 messages in the variable \$authenticated@_id$\. It is also included in the log
19702 lines for incoming messages. For example, a user/password authenticator
19703 configuration might preserve the user name that was used to authenticate, and
19704 refer to it subsequently during delivery of the message.
19705 If expansion fails, the option is ignored.
19707 .conf server@_mail@_auth@_condition string$**$ unset
19708 This option allows a server to discard authenticated sender addresses supplied
19709 as part of \\MAIL\\ commands in SMTP connections that are authenticated by the
19710 driver on which \server__mail__auth@_condition\ is set. The option is not used
19711 as part of the authentication process; instead its (unexpanded) value is
19712 remembered for later use.
19713 How it is used is described in the following section.
19718 .section The AUTH parameter on MAIL commands
19719 .rset SECTauthparamail "~~chapter.~~section"
19720 .index authentication||sender, authenticated
19721 .index \\AUTH\\||on \\MAIL\\ command
19722 When a client supplied an \\AUTH=\\ item on a \\MAIL\\ command, Exim applies
19723 the following checks before accepting it as the authenticated sender of the
19726 If the connection is not using extended SMTP (that is, \\HELO\\ was used rather
19727 than \\EHLO\\), the use of \\AUTH=\\ is a syntax error.
19729 If the value of the \\AUTH=\\ parameter is `@<@>', it is ignored.
19731 If \acl@_smtp@_mailauth\ is defined, the ACL it specifies is run. While it is
19732 running, the value of \$authenticated@_sender$\ is set to the value obtained
19733 from the \\AUTH=\\ parameter. If the ACL does not yield `accept', the value of
19734 \$authenticated@_sender$\ is deleted. The \acl@_smtp@_mailauth\ ACL may not
19735 return `drop' or `discard'. If it defers, a temporary error code (451) is given
19736 for the \\MAIL\\ command.
19738 If \acl@_smtp@_mailauth\ is not defined, the value of the \\AUTH=\\ parameter
19739 is accepted and placed in \$authenticated@_sender$\ only if the client has
19742 If the \\AUTH=\\ value was accepted by either of the two previous rules, and
19743 the client has authenticated, and the authenticator has a setting for the
19744 \server@_mail@_auth@_condition\, the condition is checked at this point. The
19745 valued that was saved from the authenticator is expanded. If the expansion
19746 fails, or yields an empty string, `0', `no', or `false', the value of
19747 \$authenticated__sender$\ is deleted. If the expansion yields any other value,
19748 the value of \$authenticated@_sender$\ is retained and passed on with the
19752 When \$authenticated@_sender$\ is set for a message, it is passed on to other
19753 hosts to which Exim authenticates as a client. Do not confuse this value with
19754 \$authenticated@_id$\, which is a string obtained from the authentication
19755 process, and which is not usually a complete email address.
19757 Whenever an \\AUTH=\\ value is ignored, the incident is logged. The ACL for
19758 \\MAIL\\, if defined, is run after \\AUTH=\\ is accepted or ignored. It can
19759 therefore make use of \$authenticated@_sender$\. The converse is not true: the
19760 value of \$sender@_address$\ is not yet set up when the \acl@_smtp@_mailauth\
19764 .section Authentication on an Exim server
19765 .rset SECTauthexiser "~~chapter.~~section"
19766 .index authentication||on an Exim server
19767 When Exim receives an \\EHLO\\ command, it advertises the public names of those
19768 authenticators that are configured as servers, subject to the following
19771 The client host must match \auth@_advertise@_hosts\ (default $*$).
19773 It the \server@_advertise@_condition\ option is set, its expansion must not
19774 yield the empty string, `0', `no', or `false'.
19776 The order in which the authenticators are defined controls the order in which
19777 the mechanisms are advertised.
19779 Some mail clients (for example, some versions of Netscape) require the user to
19780 provide a name and password for authentication whenever \\AUTH\\ is advertised,
19781 even though authentication may not in fact be needed (for example, Exim may be
19782 set up to allow unconditional relaying from the client by an IP address check).
19783 You can make such clients more friendly by not advertising \\AUTH\\ to them.
19784 For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL
19785 that runs for \\RCPT\\) to relay without authentication, you should set
19787 auth_advertise_hosts = ! 10.9.8.0/24
19789 so that no authentication mechanisms are advertised to them.
19791 The \server@_advertise@_condition\ controls the advertisement of individual
19792 authentication mechanisms. For example, it can be used to restrict the
19793 advertisement of a patricular mechanism to encrypted connections, by a setting
19796 server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}}
19798 If the session is encrypted, \$tls@_cipher$\ is not empty, and so the expansion
19799 yields `yes', which allows the advertisement to happen.
19801 When an Exim server receives an \\AUTH\\ command from a client, it rejects it
19802 immediately if \\AUTH\\ was not advertised in response to an earlier \\EHLO\\
19803 command. This is the case if
19805 The client host does not match \auth@_advertise@_hosts\; or
19807 No authenticators are configured with server options; or
19809 Expansion of \server@_advertise@_condition\ blocked the advertising of all the
19810 server authenticators.
19813 Otherwise, Exim runs the ACL specified by \acl@_smtp@_auth\ in order
19814 to decide whether to accept the command. If \acl@_smtp@_auth\ is not set,
19815 \\AUTH\\ is accepted from any client host.
19817 If \\AUTH\\ is not rejected by the ACL, Exim searches its configuration for a
19818 server authentication mechanism that was advertised in response to \\EHLO\\ and
19819 that matches the one named in the \\AUTH\\ command. If it finds one, it runs
19820 the appropriate authentication protocol, and authentication either succeeds or
19821 fails. If there is no matching advertised mechanism, the \\AUTH\\ command is
19822 rejected with a 504 error.
19824 When a message is received from an authenticated host, the value of
19825 \$received@_protocol$\ is set to `asmtp' instead of `esmtp', and
19826 \$sender@_host@_authenticated$\ contains the name (not the public name) of the
19827 authenticator driver that successfully authenticated the client from which the
19828 message was received. This variable is empty if there was no successful
19833 .section Testing server authentication
19834 .index authentication||testing a server
19835 .index \\AUTH\\||testing a server
19836 .index base64 encoding||creating authentication test data
19837 Exim's \-bh-\ option can be useful for testing server authentication
19838 configurations. The data for the \\AUTH\\ command has to be sent using base64
19839 encoding. A quick way to produce such data for testing is the following Perl
19843 printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
19845 .index binary zero||in authentication data
19846 This interprets its argument as a Perl string, and then encodes it. The
19847 interpretation as a Perl string allows binary zeros, which are required for
19848 some kinds of authentication, to be included in the data. For example, a
19849 command line to run this script on such data might be
19851 encode '\0user\0password'
19853 Note the use of single quotes to prevent the shell interpreting the
19854 backslashes, so that they can be interpreted by Perl to specify characters
19855 whose code value is zero.
19857 \**Warning 1**\: If either of the user or password strings starts with an octal
19858 digit, you must use three zeros instead of one after the leading backslash. If
19859 you do not, the octal digit that starts your string will be incorrectly
19860 interpreted as part of the code for the first character.
19862 \**Warning 2**\: If there are characters in the strings that Perl interprets
19863 specially, you must use a Perl escape to prevent them being misinterpreted. For
19864 example, a command such as
19866 encode '\0user@domain.com\0pas$$word'
19868 gives an incorrect answer because of the unescaped `@@' and `@$' characters.
19870 If you have the \mimencode\ command installed, another way to do produce
19871 base64-encoded strings is to run the command
19873 echo -e -n `\0user\0password' | mimencode
19875 The \-e-\ option of \echo\ enables the interpretation of backslash escapes in
19876 the argument, and the \-n-\ option specifies no newline at the end of its
19877 output. However, not all versions of \echo\ recognize these options, so you
19878 should check your version before relying on this suggestion.
19881 .section Authentication by an Exim client
19882 .index authentication||on an Exim client
19883 The \%smtp%\ transport has two options called \hosts@_require@_auth\ and
19884 \hosts@_try@_auth\. When the \%smtp%\ transport connects to a server that
19885 announces support for authentication, and the host matches an entry in either
19886 of these options, Exim (as a client) tries to authenticate as follows:
19888 For each authenticator that is configured as a client, it searches the
19889 authentication mechanisms announced by the server for one whose name
19890 matches the public name of the authenticator.
19892 When it finds one that matches, it runs the authenticator's client code.
19893 The variables \$host$\ and \$host@_address$\ are available for any string
19894 expansions that the client might do. They are set to the server's name and
19895 IP address. If any expansion is forced to fail, the authentication attempt
19897 and Exim moves on to the next authenticator.
19898 Otherwise an expansion failure causes delivery to be
19901 If the result of the authentication attempt is a temporary error or a timeout,
19902 Exim abandons trying to send the message to the host for the moment. It will
19903 try again later. If there are any backup hosts available, they are tried in the
19906 If the response to authentication is a permanent error (5xx code), Exim carries
19907 on searching the list of authenticators and tries another one if possible. If
19908 all authentication attempts give permanent errors, or if there are no attempts
19909 because no mechanisms match
19910 (or option expansions force failure),
19911 what happens depends on whether the host matches \hosts@_require@_auth\ or
19912 \hosts@_try@_auth\. In the first case, a temporary error is generated, and
19913 delivery is deferred. The error can be detected in the retry rules, and thereby
19914 turned into a permanent error if you wish. In the second case, Exim tries to
19915 deliver the message unauthenticated.
19917 .index \\AUTH\\||on \\MAIL\\ command
19918 When Exim has authenticated itself to a remote server, it adds the \\AUTH\\
19919 parameter to the \\MAIL\\ commands it sends, if it has an authenticated sender
19921 If the message came from a remote host, the authenticated sender is the one
19922 that was receiving on an incoming \\MAIL\\ command, provided that the incoming
19923 connection was authenticated and the \server@_mail@_auth\ condition allowed the
19924 authenticated sender to be retained. If a local process calls Exim to send a
19925 message, the sender address that is built from the login name and
19926 \qualify@_domain\ is treated as authenticated. However, if the
19927 \authenticated@_sender\ option is set on the \%smtp%\ transport, it overrides
19928 the authenticated sender that was received with the message.
19939 . ============================================================================
19940 .chapter The plaintext authenticator
19941 .rset CHAPplaintext "~~chapter"
19942 .set runningfoot "plaintext authenticator"
19943 .index \%plaintext%\ authenticator
19944 .index authenticators||\%plaintext%\
19945 The \%plaintext%\ authenticator can be configured to support the PLAIN and
19946 LOGIN authentication mechanisms, both of which transfer authentication data as
19947 plain (unencrypted) text (though base64 encoded). The use of plain text is a
19948 security risk. If you use one of these mechanisms without also making use of
19949 SMTP encryption (see chapter ~~CHAPTLS) you should not use the same passwords
19950 for SMTP connections as you do for login accounts.
19952 .section Using plaintext in a server
19953 When running as a server, \%plaintext%\ performs the authentication test by
19954 expanding a string. It has the following options:
19957 .index options||\%plaintext%\ authenticator (server)
19959 .conf server@_prompts string$**$ unset
19960 The contents of this option, after expansion, must be a colon-separated list of
19961 prompt strings. If expansion fails, a temporary authentication rejection is
19964 .conf server@_condition string$**$ unset
19965 This option must be set in order to configure the driver as a server. Its use
19966 is described below.
19970 .index \\AUTH\\||in \%plaintext%\ authenticator
19971 .index binary zero||in \%plaintext%\ authenticator
19972 .index numerical variables (\$1$\, \$2$\, etc)||in \%plaintext%\ authenticator
19973 .index base64 encoding||in \%plaintext%\ authenticator
19974 The data sent by the client with the \\AUTH\\ command, or in response to
19975 subsequent prompts, is base64 encoded, and so may contain any byte values
19976 when decoded. If any data is supplied with the command, it is treated as a
19977 list of strings, separated by NULs (binary zeros), which are placed in the
19978 expansion variables \$1$\, \$2$\, etc. If there are more strings in
19979 \server@_prompts\ than the number of strings supplied with the \\AUTH\\
19980 command, the remaining prompts are used to obtain more data. Each response from
19981 the client may be a list of NUL-separated strings.
19983 Once a sufficient number of data strings have been received,
19984 \server@_condition\ is expanded.
19985 If the expansion is forced to fail, authentication fails. Any other expansion
19986 failure causes a temporary error code to be returned.
19987 If the result of a successful expansion is an empty string, `0', `no', or
19988 `false', authentication fails. If the result of the expansion is `1', `yes', or
19989 `true', authentication succeeds and the generic \server@_set@_id\ option is
19990 expanded and saved in \$authenticated@_id$\. For any other result, a temporary
19991 error code is returned, with the expanded string as the error text.
19993 \**Warning**\: If you use a lookup in the expansion to find the user's
19994 password, be sure to make the authentication fail if the user is unknown.
19995 There are good and bad examples at the end of the next section.
19998 .section The PLAIN authentication mechanism
19999 .index PLAIN authentication mechanism
20000 .index authentication||PLAIN mechanism
20001 .index binary zero||in \%plaintext%\ authenticator
20002 The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
20003 sent as one item of data (that is, one combined string containing two NUL
20004 separators). The data is sent either as part of the \\AUTH\\ command, or
20005 subsequently in response to an empty prompt from the server.
20007 The second and third strings are a user name and a corresponding password.
20008 Using a single fixed user name and password as an example, this could be
20009 configured as follows:
20013 public_name = PLAIN
20015 server_condition = \
20016 ${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}}
20019 The \server@_prompts\ setting specifies a single, empty prompt (empty items at
20020 the end of a string list are ignored). If all the data comes as part of the
20021 \\AUTH\\ command, as is commonly the case, the prompt is not used. This
20022 authenticator is advertised in the response to \\EHLO\\ as
20026 and a client host can authenticate itself by sending the command
20028 AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0
20030 As this contains three strings (more than the number of prompts), no further
20031 data is required from the client. Alternatively, the client may just send
20035 to initiate authentication, in which case the server replies with an empty
20036 prompt. The client must respond with the combined data string.
20039 The data string is base64 encoded, as required by the RFC. This example,
20040 when decoded, is \"<<NUL>>username<<NUL>>mysecret"\, where <<NUL>> represents a
20041 zero byte. This is split up into three strings, the first of which is empty.
20042 The \server@_condition\ option in the authenticator checks that the second two
20043 are \"username"\ and \"mysecret"\ respectively.
20045 Having just one fixed user name and password, as in this example, is not very
20046 realistic, though for a small organization with only a handful of
20047 authenticating clients it could make sense.
20050 A more sophisticated instance of this authenticator could use the user name in
20051 \$2$\ to look up a password in a file or database, and maybe do an encrypted
20052 comparison (see \crypteq\ in chapter ~~CHAPexpand). Here is a example of this
20053 approach, where the passwords are looked up in a DBM file. \**Warning**\: This
20054 is an incorrect example:
20056 server_condition = \
20057 ${if eq{$3}{${lookup{$2}dbm{/etc/authpwd}}}{yes}{no}}
20059 The expansion uses the user name (\$2$\) as the key to look up a password,
20060 which it then compares to the supplied password (\$3$\). Why is this example
20061 incorrect? It works fine for existing users, but consider what happens if a
20062 non-existent user name is given. The lookup fails, but as no success/failure
20063 strings are given for the lookup, it yields an empty string. Thus, to defeat
20064 the authentication, all a client has to do is to supply a non-existent user
20065 name and an empty password. The correct way of writing this test is:
20067 server_condition = ${lookup{$2}dbm{/etc/authpwd}\
20068 {${if eq{$value}{$3}{yes}{no}}}{no}}
20070 In this case, if the lookup succeeds, the result is checked; if the lookup
20071 fails, authentication fails. If \crypteq\ is being used instead of \eq\, the
20072 first example is in fact safe, because \crypteq\ always fails if its second
20073 argument is empty. However, the second way of writing the test makes the logic
20077 .section The LOGIN authentication mechanism
20078 .index LOGIN authentication mechanism
20079 .index authentication||LOGIN mechanism
20080 The LOGIN authentication mechanism is not documented in any RFC, but is in use
20081 in a number of programs. No data is sent with the \\AUTH\\ command. Instead, a
20082 user name and password are supplied separately, in response to prompts. The
20083 plaintext authenticator can be configured to support this as in this example:
20087 public_name = LOGIN
20088 server_prompts = User Name : Password
20089 server_condition = \
20090 ${if and {{eq{$1}{username}}{eq{$2}{mysecret}}}{yes}{no}}
20093 Because of the way plaintext operates, this authenticator accepts data supplied
20094 with the \\AUTH\\ command (in contravention of the specification of LOGIN), but
20095 if the client does not supply it (as is the case for LOGIN clients), the prompt
20096 strings are used to obtain two data items.
20098 Some clients are very particular about the precise text of the prompts. For
20099 example, Outlook Express is reported to recognize only `Username:' and
20100 `Password:'. Here is an example of a LOGIN authenticator which uses those
20101 strings, and which uses the \ldapauth\ expansion condition to check the user
20102 name and password by binding to an LDAP server:
20106 public_name = LOGIN
20107 server_prompts = Username:: : Password::
20108 server_condition = ${if ldapauth \
20110 {user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \
20113 ldap://ldap.example.org/}{yes}{no}}
20114 server_set_id = uid=$1,ou=people,o=example.org
20116 Note the use of the \quote@_ldap@_dn\ operator to correctly quote the DN for
20117 authentication. However, the basic \quote\ operator, rather than any of the
20118 LDAP quoting operators, is the correct one to use for the password, because
20119 quoting is needed only to make the password conform to the Exim syntax. At the
20120 LDAP level, the password is an uninterpreted string.
20123 .section Support for different kinds of authentication
20124 A number of string expansion features are provided for the purpose of
20125 interfacing to different ways of user authentication. These include checking
20126 traditionally encrypted passwords from \(/etc/passwd)\ (or equivalent), PAM,
20127 Radius, \ldapauth\, and \*pwcheck*\. For details see section ~~SECTexpcond.
20131 .section Using plaintext in a client
20132 The \%plaintext%\ authenticator has just one client option:
20135 .index options||\%plaintext%\ authenticator (client)
20137 .conf client@_send string$**$ unset
20138 The string is a colon-separated list of authentication data strings. Each
20139 string is independently expanded before being sent to the server. The first
20140 string is sent with the \\AUTH\\ command; any more strings are sent in response
20141 to prompts from the server.
20143 \**Note**\: you cannot use expansion to create multiple strings, because
20144 splitting takes priority and happens first.
20146 Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in
20147 the data, further processing is applied to each string before it is sent. If
20148 there are any single circumflex characters in the string, they are converted to
20149 NULs. Should an actual circumflex be required as data, it must be doubled in
20154 This is an example of a client configuration that implements the PLAIN
20155 authentication mechanism with a fixed user name and password:
20159 public_name = PLAIN
20160 client_send = ^username^mysecret
20162 The lack of colons means that the entire text is sent with the \\AUTH\\
20163 command, with the circumflex characters converted to NULs. A similar example
20164 that uses the LOGIN mechanism is:
20168 public_name = LOGIN
20169 client_send = : username : mysecret
20171 The initial colon means that the first string is empty, so no data is sent with
20172 the \\AUTH\\ command itself. The remaining strings are sent in response to
20182 . ============================================================================
20183 .chapter The cram@_md5 authenticator
20184 .set runningfoot "cram@_md5 authenticator"
20185 .index \%cram@_md5%\ authenticator
20186 .index authenticators||\%cram@_md5%\
20187 .index CRAM-MD5 authentication mechanism
20188 .index authentication||CRAM-MD5 mechanism
20189 The CRAM-MD5 authentication mechanism is described in RFC 2195. The server
20190 sends a challenge string to the client, and the response consists of a user
20191 name and the CRAM-MD5 digest of the challenge string combined with a secret
20192 string (password) which is known to both server and client. Thus, the secret
20193 is not sent over the network as plain text, which makes this authenticator more
20194 secure than \%plaintext%\. However, the downside is that the secret has to be
20195 available in plain text at either end.
20197 .section Using cram@_md5 as a server
20198 This authenticator has one server option, which must be set to configure the
20199 authenticator as a server:
20202 .index options||\%cram@_md5%\ authenticator (server)
20204 .conf server@_secret string$**$ unset
20205 .index numerical variables (\$1$\, \$2$\, etc)||in \%cram@_md5%\ authenticator
20206 When the server receives the client's response, the user name is placed in
20207 the expansion variable \$1$\, and \server@_secret\ is expanded to obtain the
20208 password for that user. The server then computes the CRAM-MD5 digest that the
20209 client should have sent, and checks that it received the correct string. If the
20210 expansion of \server@_secret\ is forced to fail, authentication fails. If the
20211 expansion fails for some other reason, a temporary error code is returned to
20216 For example, the following authenticator checks that the user name given by the
20217 client is `ph10', and if so, uses `secret' as the password. For any other user
20218 name, authentication fails.
20222 public_name = CRAM-MD5
20223 server_secret = ${if eq{$1}{ph10}{secret}fail}
20226 If authentication succeeds, the setting of \server@_set@_id\ preserves the user
20227 name in \$authenticated@_id$\.
20228 A more tyical configuration might look up the secret string in a file, using
20229 the user name as the key. For example:
20233 public_name = CRAM-MD5
20234 server_secret = ${lookup{$1}lsearch{/etc/authpwd}{$value}fail}
20237 Note that this expansion explicitly forces failure if the lookup fails
20238 because \$1$\ contains an unknown user name.
20240 .section Using cram@_md5 as a client
20241 When used as a client, the \%cram@_md5%\ authenticator has two options:
20244 .index options||\%cram@_md5%\ authenticator (client)
20246 .conf client@_name string$**$ "the primary host name"
20247 This string is expanded, and the result used as the user name data when
20248 computing the response to the server's challenge.
20250 .conf client@_secret string$**$ unset
20251 This option must be set for the authenticator to work as a client. Its value is
20252 expanded and the result used as the secret string when computing the response.
20256 Different user names and secrets can be used for different servers by referring
20257 to \$host$\ or \$host@_address$\ in the options.
20259 Forced failure of either expansion string is treated as an indication that this
20260 authenticator is not prepared to handle this case. Exim moves on to the next
20261 configured client authenticator. Any other expansion failure causes Exim to
20262 give up trying to send the message to the current server.
20264 A simple example configuration of a \%cram@_md5%\ authenticator, using fixed
20269 public_name = CRAM-MD5
20271 client_secret = secret
20282 . ============================================================================
20283 .chapter The spa authenticator
20284 .set runningfoot "spa authenticator"
20285 .index \%spa%\ authenticator
20286 .index authenticators||\%spa%\
20287 .index authentication||Microsoft Secure Password
20288 .index authentication||NTLM
20289 .index Microsoft Secure Password Authentication
20290 .index NTLM authentication
20291 The \%spa%\ authenticator provides client support for Microsoft's \*Secure
20292 Password Authentication*\ mechanism,
20293 which is also sometimes known as NTLM (NT LanMan). The code for client side of
20294 this authenticator was contributed by Marc Prud'hommeaux, and much of it is
20295 taken from the Samba project (\?http://www.samba.org?\). The code for the
20296 server side was subsequently contributed by Tom Kistner.
20298 The mechanism works as follows:
20300 After the \\AUTH\\ command has been accepted, the client sends an SPA
20301 authentication request based on the user name and optional domain.
20303 The server sends back a challenge.
20305 The client builds a challenge response which makes use of the user's password
20306 and sends it to the server, which then accepts or rejects it.
20308 Encryption is used to protect the password in transit.
20311 .section Using spa as a server
20312 The \%spa%\ authenticator has just one server option:
20315 .index options||\%spa%\ authenticator (server)
20317 .conf server@_password string$**$ unset
20318 .index numerical variables (\$1$\, \$2$\, etc)||in \%spa%\ authenticator
20319 This option is expanded, and the result must be the cleartext password for the
20320 authenticating user, whose name is at this point in \$1$\. For example:
20325 server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}}
20327 If the expansion is forced to fail, authentication fails. Any other expansion
20328 failure causes a temporary error code to be returned.
20334 .section Using spa as a client
20335 The \%spa%\ authenticator has the following client options:
20338 .index options||\%spa%\ authenticator (client)
20340 .conf client@_domain string$**$ unset
20341 This option specifies an optional domain for the authentication.
20343 .conf client@_password string$**$ unset
20344 This option specifies the user's password, and must be set.
20346 .conf client@_username string$**$ unset
20347 This option specifies the user name, and must be set.
20351 Here is an example of a configuration of this authenticator for use with the
20352 mail servers at \*msn.com*\:
20357 client_username = msn/msn_username
20358 client_password = msn_plaintext_password
20359 client_domain = DOMAIN_OR_UNSET
20371 . ============================================================================
20372 .chapter Encrypted SMTP connections using TLS/SSL
20373 .set runningfoot "TLS encryption"
20374 .rset CHAPTLS "~~chapter"
20375 .index encryption||on SMTP connection
20376 .index SMTP||encryption
20377 .index TLS||on SMTP connection
20381 Support for TLS (Transport Layer Security), formerly known as SSL (Secure
20382 Sockets Layer), is implemented by making use of the OpenSSL library or the
20383 GnuTLS library (Exim requires GnuTLS release 1.0 or later).
20385 There is no cryptographic code in the Exim distribution itself for implementing
20386 TLS. In order to use this feature you must install OpenSSL or GnuTLS, and then
20387 build a version of Exim that includes TLS support (see section
20388 ~~SECTinctlsssl). You also need to understand the basic concepts of encryption
20389 at a managerial level, and in particular, the way that public keys, private
20390 keys, and certificates are used.
20392 RFC 2487 defines how SMTP connections can make use of encryption. Once a
20393 connection is established, the client issues a \\STARTTLS\\ command. If the
20394 server accepts this, the client and the server negotiate an encryption
20395 mechanism. If the negotiation succeeds, the data that subsequently passes
20396 between them is encrypted.
20398 Exim also has support for legacy clients that do not use the \\STARTTLS\\
20399 mechanism. Instead, they connect to a different port on the server (usually
20400 called the `ssmtp' port), and expect to negotiate a TLS session as soon as the
20401 connection to the server is established. The \-tls-on-connect-\ command line
20402 option can be used to run an Exim server in this way from \*inetd*\, and it can
20403 also be used to run a special daemon that operates in this manner (use \-oX-\
20404 to specify the port).
20406 Exim's ACLs can detect whether the current SMTP session is encrypted or not,
20407 and if so, what cipher suite is in use, whether the client supplied a
20408 certificate, and whether or not that certificate was verified. This makes it
20409 possible for an Exim server to deny or accept certain commands based on the
20412 \**Warning**\: certain types of firewall and certain anti-virus products can
20413 disrupt TLS connections. You need to turn off SMTP scanning for these products
20414 in order to get TLS to work.
20417 .section OpenSSL vs GnuTLS
20418 .index TLS||OpenSSL \*vs*\ GnuTLS
20419 .rset SECTopenvsgnu "~~chapter.~~section"
20420 The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS
20421 followed later, when the first versions of GnuTLS were released. To build Exim
20422 to use GnuTLS, you need to set
20426 in Local/Makefile, in addition to
20430 You must also set \\TLS@_LIBS\\ and \\TLS@_INCLUDE\\ appropriately, so that the
20431 include files and libraries for GnuTLS can be found.
20433 There are some differences in usage when using GnuTLS instead of OpenSSL:
20436 The \tls@_verify@_certificates\ option must contain the name of a file, not the
20437 name of a directory (for OpenSSL it can be either).
20440 The \tls@_dhparam\ option is ignored, because early versions of GnuTLS had no
20441 facility for varying its Diffie-Hellman parameters. I understand that this has
20442 changed, but Exim has not been updated to provide this facility.
20444 GnuTLS uses RSA and D-H parameters that take a substantial amount of
20445 time to compute. It is unreasonable to re-compute them for every TLS
20446 session. Therefore, Exim keeps this data in a file in its spool
20447 directory, called \(gnutls-params)\. The file is owned by the Exim user and is
20448 readable only by its owner. Every Exim process that start up GnuTLS reads the
20449 RSA and D-H parameters from this file. If the file does not exist, the first
20450 Exim process that needs it computes the data and writes it to a temporary file
20451 which is renamed once it is complete. It does not matter if several Exim
20452 processes do this simultaneously (apart from wasting a few resources). Once a
20453 file is in place, new Exim processes immediately start using it.
20455 For maximum security, the parameters that are stored in this file should be
20456 recalculated periodically, the frequency depending on your paranoia level.
20457 Arranging this is easy; just delete the file when you want new values to be
20461 Distinguished Name (DN) strings reported by the OpenSSL library use a slash for
20462 separating fields; GnuTLS uses commas, in accordance with RFC 2253. This
20463 affects the value of the \$tls@_peerdn$\ variable.
20466 OpenSSL identifies cipher suites using hyphens as separators, for example:
20467 DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA@_ARCFOUR@_SHA. What is
20468 more, OpenSSL complains if underscores are present in a cipher list. To make
20469 life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to
20470 underscores for GnuTLS when processing lists of cipher suites in the
20472 \tls@_require@_ciphers\ options (the global option and the \%smtp%\ transport
20477 The \tls@_require@_ciphers\ options operate differently, as described in the
20483 .section Requiring specific ciphers in OpenSSL and GnuTLS
20484 .rset SECTreqciphsslgnu "~~chapter.~~section"
20485 .index TLS||requiring specific ciphers
20486 .index \tls@_require@_ciphers\||OpenSSL \*vs*\ GnuTLS
20487 This section documents the different ways the \tls@_require@_ciphers\ options
20488 (the global option and the \%smtp%\ transport option) operate in OpenSSL and
20491 There is a function in the OpenSSL library that can be passed a list of
20492 cipher suites before the cipher negotiation takes place. This specifies which
20493 ciphers are acceptable. The list is colon separated and may contain names like
20494 DES-CBC3-SHA. Exim passes the expanded value of \tls@_require@_ciphers\
20495 directly to this function call. The following quotation from
20496 the OpenSSL documentation specifies what forms of item are allowed in the
20499 It can consist of a single cipher suite such as RC4-SHA.
20501 It can represent a list of cipher suites containing a certain algorithm,
20502 or cipher suites of a certain type. For example SHA1 represents all
20503 ciphers suites using the digest algorithm SHA1 and SSLv3 represents all
20506 Lists of cipher suites can be combined in a single cipher string using
20507 the + character. This is used as a logical and operation. For example
20508 SHA1+DES represents all cipher suites containing the SHA1 and the DES
20511 Each cipher string can be optionally preceded by the characters \"!"\, \"-"\ or
20514 If \"!"\ is used then the ciphers are permanently deleted from the list. The
20515 ciphers deleted can never reappear in the list even if they are explicitly
20518 If \"-"\ is used then the ciphers are deleted from the list, but some or all
20519 of the ciphers can be added again by later options.
20521 If \"+"\ is used then the ciphers are moved to the end of the list. This
20522 option doesn't add any new ciphers it just moves matching existing ones.
20524 If none of these characters is present then the string is just interpreted as a
20525 list of ciphers to be appended to the current preference list. If the list
20526 includes any ciphers already present they will be ignored: that is, they will
20527 not moved to the end of the list.
20531 The GnuTLS library does not have a combined function like OpenSSL. Instead,
20532 it allows the caller to specify separate lists of key-exchange methods,
20533 main cipher algorithms, and MAC algorithms. Unfortunately, these lists are
20534 numerical, and the library does not have a function for turning names into
20535 numbers. Consequently, the list of recognized names has to be built into
20538 At present, Exim permits only the list of main cipher algorithms to be
20539 changed. The \tls@_require@_ciphers\ option is in the same format as for
20540 OpenSSL. Exim searches each item for the name of available algorithm. For
20541 example, if the list contains RSA@_ARCFOUR@_SHA then ARCFOUR is recognized.
20543 The cipher algorithms list starts out with a default set of algorithms. If
20544 the first item in \tls@_require@_ciphers\ does \*not*\ start with an
20545 exclamation mark, all the default items are deleted. Thus, only those specified
20546 can be used. If the first item in \tls@_require@_ciphers\ \*does*\ start with
20547 an exclamation mark, the defaults are left on the list.
20549 Then, any item that starts with an exclamation mark causes the relevent
20550 algorithms to be removed from the list, and any item that does not start
20551 with an exclamation mark causes the relevant algorithms to be added to the
20554 tls_require_ciphers = !RSA_ARCFOUR_SHA
20556 allows all the defaults except those that use ARCFOUR, whereas
20558 tls_require_ciphers = AES : 3DES
20560 allows only cipher suites that use AES and 3DES. The currently recognized
20561 algorithms are: ARCFOUR@_128, ARCFOUR@_40, ARCFOUR (both of the preceding),
20562 AES@_256, AES@_128, AES (both of the preceding), and 3DES.
20564 Unrecognized algorithms are ignored. In a client, the order of the list
20565 specifies a preference order for the algorithms.
20569 .section Configuring an Exim server to use TLS
20570 .index TLS||configuring an Exim server
20571 When Exim has been built with TLS support, it advertises the availability of
20572 the \\STARTTLS\\ command to client hosts that match \tls@_advertise@_hosts\,
20573 but not to any others. The default value of this option is unset, which means
20574 that \\STARTTLS\\ is not advertised at all. This default is chosen because you
20575 need to set some other options in order to make TLS avaliable, and also it is
20576 sensible for systems that want to use TLS only as a client.
20578 If a client issues a \\STARTTLS\\ command and there is some configuration
20579 problem in the server, the command is rejected with a 454 error. If the client
20580 persists in trying to issue SMTP commands, all except \\QUIT\\ are rejected
20583 554 Security failure
20585 If a \\STARTTLS\\ command is issued within an existing TLS session, it is
20586 rejected with a 554 error code.
20588 To enable TLS operations on a server, you must set \tls@_advertise@_hosts\ to
20589 match some hosts. You can, of course, set it to $*$ to match all hosts.
20590 However, this is not all you need to do. TLS sessions to a server won't work
20591 without some further configuration at the server end.
20593 It is rumoured that all existing clients that support TLS/SSL use RSA
20594 encryption. To make this work you need to set, in the server,
20596 tls_certificate = /some/file/name
20597 tls_privatekey = /some/file/name
20599 The first file contains the server's X509 certificate, and the second contains
20600 the private key that goes with it. These files need to be readable by the Exim
20601 user, and must always be given as full path names. They can be the same file if
20602 both the certificate and the key are contained within it. If \tls@_privatekey\
20603 is not set, this is assumed to be the case. The certificate file may also
20604 contain intermediate certificates that need to be sent to the client to enable
20605 it to authenticate the server's certificate.
20607 If you do not understand about certificates and keys, please try to find a
20608 source of this background information, which is not Exim-specific. (There are a
20609 few comments below in section ~~SECTcerandall.)
20611 \**Note**\: These options do not apply when Exim is operating as a client --
20612 they apply only in the case of a server. For a client, you must set the options
20613 of the same name in an \%smtp%\ transport.
20615 With just these options, Exim will work as a server with clients such as
20616 Netscape. It does not require the client to have a certificate (but see below
20617 for how to insist on this). There is one other option that may be needed in
20618 other situations. If
20620 tls_dhparam = /some/file/name
20622 is set, the SSL library is initialized for the use of Diffie-Hellman ciphers
20623 with the parameters contained in the file. This increases the set of cipher
20624 suites that the server supports. See the command
20628 for a way of generating this data.
20629 At present, \tls@_dhparam\ is used only when Exim is linked with OpenSSL. It is
20630 ignored if GnuTLS is being used.
20632 The strings supplied for these three options are expanded every time a client
20633 host connects. It is therefore possible to use different certificates and keys
20634 for different hosts, if you so wish, by making use of the client's IP address
20635 in \$sender@_host@_address$\ to control the expansion. If a string expansion is
20636 forced to fail, Exim behaves as if the option is not set.
20638 .index cipher||logging
20639 .index log||TLS cipher
20640 The variable \$tls@_cipher$\ is set to the cipher suite that was negotiated for
20641 an incoming TLS connection. It is included in the ::Received:: header of an
20642 incoming message (by default -- you can, of course, change this), and it is
20643 also included in the log line that records a message's arrival, keyed by `X=',
20644 unless the \tls@_cipher\ log selector is turned off.
20645 The \encrypted\ condition can be used to test for specific cipher suites in
20648 The ACLs that run for subsequent SMTP commands can check the name of the cipher
20649 suite and vary their actions accordingly. The cipher suite names are those used
20650 by OpenSSL. These may differ from the names used elsewhere. For example,
20651 OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts
20652 is known as TLS@_RSA@_WITH@_3DES@_EDE@_CBC@_SHA. Check the OpenSSL
20653 documentation for more details.
20656 .section Requesting and verifying client certificates
20657 .index certificate||verification of client
20658 .index TLS||client certificate verification
20659 If you want an Exim server to request a certificate when negotiating a TLS
20660 session with a client, you must set either \tls@_verify@_hosts\ or
20661 \tls@_try@_verify@_hosts\. You can, of course, set either of them to $*$ to
20662 apply to all TLS connections. For any host that matches one of these options,
20663 Exim requests a certificate as part of the setup of the TLS session. The
20664 contents of the certificate are verified by comparing it with a list of
20665 expected certificates. These must be available in a file or,
20667 for OpenSSL only (not GnuTLS), a directory, identified by
20668 \tls@_verify@_certificates\.
20671 A file can contain multiple certificates, concatenated end to end. If a
20676 each certificate must be in a separate file, with a name (or a symbolic link)
20677 of the form <<hash>>.0, where <<hash>> is a hash value constructed from the
20678 certificate. You can compute the relevant hash by running the command
20680 openssl x509 -hash -noout -in /cert/file
20682 where \(/cert/file)\ contains a single certificate.
20684 The difference between \tls@_verify@_hosts\ and \tls@_try@_verify@_hosts\ is
20685 what happens if the client does not supply a certificate, or if the certificate
20686 does not match any of the certificates in the collection named by
20687 \tls@_verify@_certificates\. If the client matches \tls@_verify@_hosts\, the
20688 attempt to set up a TLS session is aborted, and the incoming connection is
20689 dropped. If the client matches \tls@_try@_verify@_hosts\, the (encrypted) SMTP
20690 session continues. ACLs that run for subsequent SMTP commands can detect the
20691 fact that no certificate was verified, and vary their actions accordingly. For
20692 example, you can insist on a certificate before accepting a message for
20693 relaying, but not when the message is destined for local delivery.
20695 When a client supplies a certificate (whether it verifies or not), the value of
20696 the Distinguished Name of the certificate is made available in the variable
20697 \$tls@_peerdn$\ during subsequent processing of the message.
20698 .index log||distinguished name
20699 Because it is often a long text string, it is not included in the log line or
20700 ::Received:: header by default. You can arrange for it to be logged, keyed by
20701 `DN=', by setting the \tls@_peerdn\ log selector, and you can use
20702 \received@_header@_text\ to change the ::Received:: header. When no certificate
20703 is supplied, \$tls@_peerdn$\ is empty.
20706 .section Revoked certificates
20707 .index TLS||revoked certificates
20708 .index revocation list
20709 .index certificate||revocation list
20710 Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
20711 certificates are revoked. If you have such a list, you can pass it to an Exim
20712 server using the global option called \tls@_crl\ and to an Exim client using an
20713 identically named option for the \%smtp%\ transport. In each case, the value of
20714 the option is expanded and must then be the name of a file that contains a CRL
20718 .section Configuring an Exim client to use TLS
20719 .index cipher||logging
20720 .index log||TLS cipher
20721 .index log||distinguished name
20722 .index TLS||configuring an Exim client
20723 The \tls@_cipher\ and \tls@_peerdn\ log selectors apply to outgoing SMTP
20724 deliveries as well as to incoming, the latter one causing logging of the
20725 server certificate's DN. The remaining client configuration for TLS is all
20726 within the \%smtp%\ transport.
20728 It is not necessary to set any options to have TLS work in the \%smtp%\
20729 transport. If Exim is built with TLS support, and TLS is advertised by a
20730 server, the \%smtp%\ transport always tries to start a TLS session. However,
20731 this can be prevented by setting \hosts@_avoid@_tls\ (an option of the
20732 transport) to a list of server hosts for which TLS should not be used.
20734 If you do not want Exim to attempt to send messages unencrypted when an attempt
20735 to set up an encrypted connection fails in any way, you can set
20736 \hosts@_require@_tls\ to a list of hosts for which encryption is mandatory. For
20737 those hosts, delivery is always deferred if an encrypted connection cannot be
20738 set up. If there are any other hosts for the address, they are tried in the
20741 When the server host is not in \hosts@_require@_tls\, Exim may try to deliver
20742 the message unencrypted. It always does this if the response to \\STARTTLS\\ is
20743 a 5\*xx*\ code. For a temporary error code, or for a failure to negotiate a TLS
20744 session after a success response code, what happens is controlled by the
20745 \tls@_tempfail@_tryclear\ option of the \%smtp%\ transport. If it is false,
20746 delivery to this host is deferred, and other hosts (if available) are tried. If
20747 it is true, Exim attempts to deliver unencrypted after a 4\*xx*\ response to
20748 \\STARTTLS\\, and if \\STARTTLS\\ is accepted, but the subsequent TLS
20749 negotiation fails, Exim closes the current connection (because it is in an
20750 unknown state), opens a new one to the same host, and then tries the delivery
20754 The \tls@_certificate\ and \tls@_privatekey\ options of the \%smtp%\ transport
20755 provide the client with a certificate, which is passed to the server if it
20756 requests it. If the server is Exim, it will request a certificate only if
20757 \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\ matches the client.
20758 \**Note**\: these options must be set in the \%smtp%\ transport for Exim to use
20759 TLS when it is operating as a client. Exim does not assume that a server
20760 certificate (set by the global options of the same name) should also be used
20761 when operating as a client.
20763 If \tls@_verify@_certificates\ is set, it must name a file or,
20765 for OpenSSL only (not GnuTLS), a directory, that contains a collection of
20766 expected server certificates. The client verifies the server's certificate
20767 against this collection, taking into account any revoked certificates that are
20768 in the list defined by \tls@_crl\.
20772 \tls@_require@_ciphers\ is set on the \%smtp%\ transport, it must contain a
20773 list of permitted cipher suites. If either of these checks fails, delivery to
20774 the current host is abandoned, and the \%smtp%\ transport tries to deliver to
20775 alternative hosts, if any.
20777 All the TLS options in the \%smtp%\ transport are expanded before use, with
20778 \$host$\ and \$host@_address$\ containing the name and address of the server to
20779 which the client is connected. Forced failure of an expansion causes Exim to
20780 behave as if the relevant option were unset.
20783 .section Multiple messages on the same encrypted TCP/IP connection
20784 .rset SECTmulmessam "~~chapter.~~section"
20785 .index multiple SMTP deliveries with TLS
20786 .index TLS||multiple message deliveries
20787 Exim sends multiple messages down the same TCP/IP connection by starting up
20788 an entirely new delivery process for each message, passing the socket from
20789 one process to the next. This implementation does not fit well with the use
20790 of TLS, because there is quite a lot of state information associated with a TLS
20791 connection, not just a socket identification. Passing all the state information
20792 to a new process is not feasible. Consequently, Exim shuts down an existing TLS
20793 session before passing the socket to a new process. The new process may then
20794 try to start a new TLS session, and if successful, may try to re-authenticate
20795 if \\AUTH\\ is in use, before sending the next message.
20797 The RFC is not clear as to whether or not an SMTP session continues in clear
20798 after TLS has been shut down, or whether TLS may be restarted again later, as
20799 just described. However, if the server is Exim, this shutdown and
20800 reinitialization works. It is not known which (if any) other servers operate
20801 successfully if the client closes a TLS session and continues with unencrypted
20802 SMTP, but there are certainly some that do not work. For such servers, Exim
20803 should not pass the socket to another process, because the failure of the
20804 subsequent attempt to use it would cause Exim to record a temporary host error,
20805 and delay other deliveries to that host.
20807 To test for this case, Exim sends an \\EHLO\\ command to the server after
20808 closing down the TLS session. If this fails in any way, the connection is
20809 closed instead of being passed to a new delivery process, but no retry
20810 information is recorded.
20812 There is also a manual override; you can set \hosts@_nopass@_tls\ on the
20813 \%smtp%\ transport to match those hosts for which Exim should not pass
20814 connections to new processes if TLS has been used.
20818 .section Certificates and all that
20819 .rset SECTcerandall "~~chapter.~~section"
20820 .index certificate||references to discussion
20821 In order to understand fully how TLS works, you need to know about
20822 certificates, certificate signing, and certificate authorities. This is not the
20823 place to give a tutorial, especially as I do not know very much about it
20824 myself. Some helpful introduction can be found in the FAQ for the SSL addition
20825 to Apache, currently at
20827 \?http://www.modssl.org/docs/2.7/ssl@_faq.html@#ToC24?\
20829 Other parts of the \*modssl*\ documentation are also helpful, and have
20830 links to further files.
20831 Eric Rescorla's book, \*SSL and TLS*\, published by Addison-Wesley (ISBN
20832 0-201-61598-3), contains both introductory and more in-depth descriptions.
20833 Some sample programs taken from the book are available from
20835 \?http://www.rtfm.com/openssl-examples/?\
20838 .section Certificate chains
20839 The file named by \tls@_certificate\ may contain more than one
20840 certificate. This is useful in the case where the certificate that is being
20841 sent is validated by an intermediate certificate which the other end does
20842 not have. Multiple certificates must be in the correct order in the file.
20843 First the host's certificate itself, then the first intermediate
20844 certificate to validate the issuer of the host certificate, then the next
20845 intermediate certificate to validate the issuer of the first intermediate
20846 certificate, and so on, until finally (optionally) the root certificate.
20847 The root certificate must already be trusted by the recipient for
20848 validation to succeed, of course, but if it's not preinstalled, sending the
20849 root certificate along with the rest makes it available for the user to
20850 install if the receiving end is a client MUA that can interact with a user.
20852 .section Self-signed certificates
20853 .index certificate||self-signed
20854 You can create a self-signed certificate using the \*req*\ command provided
20855 with OpenSSL, like this:
20857 openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \
20860 \(file1)\ and \(file2)\ can be the same file; the key and the certificate are
20861 delimited and so can be identified independently. The \-days-\ option
20862 specifies a period for which the certificate is valid. The \-nodes-\ option is
20863 important: if you do not set it, the key is encrypted with a passphrase
20864 that you are prompted for, and any use that is made of the key causes more
20865 prompting for the passphrase. This is not helpful if you are going to use
20866 this certificate and key in an MTA, where prompting is not possible.
20868 A self-signed certificate made in this way is sufficient for testing, and
20869 may be adequate for all your requirements if you are mainly interested in
20870 encrypting transfers, and not in secure identification.
20872 However, many clients require that the certificate presented by the server be a
20873 user (also called `leaf' or `site') certificate, and not a self-signed
20874 certificate. In this situation, the self-signed certificate described above
20875 must be installed on the client host as a trusted root \*certification
20876 authority*\ (CA), and the certificate used by Exim must be a user certificate
20877 signed with that self-signed certificate.
20879 For information on creating self-signed CA certificates and using them to sign
20880 user certificates, see the \*General implementation overview*\ chapter of the
20881 Open-source PKI book, available online at \?http://ospkibook.sourceforge.net/?\.
20889 . ============================================================================
20890 .chapter Access control lists
20891 .set runningfoot "ACL"
20892 .rset CHAPACL "~~chapter"
20893 .index ~~ACL||description
20894 .index control of incoming mail
20895 .index message||controlling incoming
20896 .index policy control||access control lists
20897 Access Control Lists (ACLs) are defined in a separate section of the run time
20898 configuration file, headed by `begin acl'. Each ACL definition starts with a
20899 name, terminated by a colon. Here is a complete ACL section which contains just
20900 one very small ACL:
20905 accept hosts = one.host.only
20907 You can have as many lists as you like in the ACL section, and the order in
20908 which they appear does not matter. The lists are self-terminating.
20910 The majority of ACLs are used to control Exim's behaviour when it receives
20911 certain SMTP commands. This applies both to incoming TCP/IP connections, and
20912 when a local process submits a message over a pipe (using the \-bs-\ option).
20913 The most common use is for controlling which recipients are accepted in
20914 incoming messages. In addition, you can also define an ACL that is used to
20915 check local non-SMTP messages. The default configuration file contains an
20916 example of a realistic ACL for checking \\RCPT\\ commands. This is discussed in
20917 chapter ~~CHAPdefconfil.
20919 .section Testing ACLs
20920 The \-bh-\ command line option provides a way of testing your ACL configuration
20921 locally by running a fake SMTP session with which you interact. The host
20922 \*relay-test.mail-abuse.org*\ provides a service for checking your relaying
20923 configuration (see section ~~SECTcheralcon for more details).
20926 .section Specifying when ACLs are used
20927 .index ~~ACL||options for specifying
20928 In order to cause an ACL to be used, you have to name it in one of the relevant
20929 options in the main part of the configuration. These options are:
20930 .index \\AUTH\\||ACL for
20931 .index \\DATA\\, ACL for
20932 .index \\ETRN\\||ACL for
20933 .index \\EXPN\\||ACL for
20934 .index \\HELO\\||ACL for
20935 .index \\EHLO\\||ACL for
20936 .index \\MAIL\\||ACL for
20937 .index \\RCPT\\||ACL for
20938 .index \\STARTTLS\\, ACL for
20939 .index \\VRFY\\||ACL for
20945 \acl@_not@_smtp\ $t $rm{ACL for non-SMTP messages}
20946 \acl@_smtp@_auth\ $t $rm{ACL for \\AUTH\\}
20947 \acl@_smtp@_connect\ $t $rm{ACL for start of SMTP connection}
20948 \acl@_smtp@_data\ $t $rm{ACL after \\DATA\\}
20949 \acl@_smtp@_etrn\ $t $rm{ACL for \\ETRN\\}
20950 \acl@_smtp@_expn\ $t $rm{ACL for \\EXPN\\}
20951 \acl@_smtp@_helo\ $t $rm{ACL for \\HELO\\ or \\EHLO\\}
20952 \acl@_smtp@_mail\ $t $rm{ACL for \\MAIL\\}
20954 \acl@_smtp@_mailauth\ $t $rm{ACL for the \\AUTH\\ parameter of \\MAIL\\}
20956 \acl@_smtp@_rcpt\ $t $rm{ACL for \\RCPT\\}
20957 \acl@_smtp@_starttls\ $t $rm{ACL for \\STARTTLS\\}
20958 \acl@_smtp@_vrfy\ $t $rm{ACL for \\VRFY\\}
20960 For example, if you set
20962 acl_smtp_rcpt = small_acl
20964 the little ACL defined above is used whenever Exim receives a \\RCPT\\ command
20965 in an SMTP dialogue. The majority of policy tests on incoming messages can be
20966 done when \\RCPT\\ commands arrive. A rejection of \\RCPT\\ should cause the
20967 sending MTA to give up on the recipient address contained in the \\RCPT\\
20968 command, whereas rejection at other times may cause the client MTA to keep on
20969 trying to deliver the message. It is therefore recommended that you do as much
20970 testing as possible at \\RCPT\\ time.
20972 However, you cannot test the contents of the message, for example, to verify
20973 addresses in the headers, at \\RCPT\\ time. Such tests have to appear in the
20974 ACL that is run after the message has been received, before the final response
20975 to the \\DATA\\ command is sent. This is the ACL specified by
20976 \acl@_smtp@_data\. At this time, it is no longer possible to reject individual
20977 recipients. An error response should reject the entire message. Unfortunately,
20978 it is known that some MTAs do not treat hard (5$it{xx}) errors correctly at
20979 this point -- they keep the message on their queues and try again later, but
20980 that is their problem, though it does waste some of your resources.
20982 The ACL test specified by \acl@_smtp@_connect\ happens after the test specified
20983 by \host__reject__connection\ (which is now an anomaly) and any TCP Wrappers
20984 testing (if configured).
20986 The non-SMTP ACL applies to all non-interactive incoming messages, that is, it
20987 applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not
20988 really SMTP.) This ACL is run just before the \*local@_scan()*\ function. Any
20989 kind of rejection is treated as permanent, because there is no way of sending a
20990 temporary error for these kinds of message. Many of the ACL conditions (for
20991 example, host tests, and tests on the state of the SMTP connection such as
20992 encryption and authentication) are not relevant and are forbidden in this ACL.
20995 .section ACL return codes
20996 .index ~~ACL||return codes
20997 The result of running an ACL is either `accept' or `deny', or, if some test
20998 cannot be completed (for example, if a database is down), `defer'. These
20999 results cause 2$it{xx}, 5$it{xx}, and 4$it{xx} return codes, respectively, to
21000 be used in the SMTP dialogue. A fourth return, `error', occurs when there is an
21001 error such as invalid syntax in the ACL. This also causes a 4$it{xx} return
21004 The ACLs that are relevant to message reception may also return `discard'. This
21005 has the effect of `accept', but causes either the entire message or an
21006 individual recipient address to be discarded. In other words, it is a
21007 blackholing facility. Use it with great care.
21009 If the ACL for \\MAIL\\ returns `discard', all recipients are discarded, and no
21010 ACL is run for subsequent \\RCPT\\ commands. The effect of `discard' in a
21011 \\RCPT\\ ACL is to discard just the one address. If there are no recipients
21012 left when the message's data is received, the \\DATA\\ ACL is not run. A
21013 `discard' return from the \\DATA\\ or the non-SMTP ACL discards all the
21014 remaining recipients.
21016 The \*local@_scan()*\ function is always run, even if there are no remaining
21017 recipients; it may create new recipients.
21020 .section Unset ACL options
21021 .index ~~ACL||unset options
21023 The default actions when any of the \acl@_$it{xxx}\ options are unset are not
21024 all the same. \**Note**\: These defaults apply only when the relevant ACL is
21025 not defined at all. For any defined ACL, the default action if control reaches
21026 the end of the ACL statements is `deny'.
21029 For \acl@_not@_smtp\, \acl@_smtp@_auth\, \acl@_smtp@_connect\,
21030 \acl@_smtp@_data\, \acl@_smtp@_helo\, \acl__smtp__mail\, \acl@_smtp@_mailauth\,
21031 and \acl@_smtp@_starttls\, the
21033 action when the ACL is not defined is `accept'.
21035 For the others (\acl@_smtp@_etrn\, \acl@_smtp@_expn\, \acl@_smtp@_rcpt\, and
21036 \acl@_smtp@_vrfy\), the action when the ACL is not defined is `deny'.
21038 This means that \acl@_smtp@_rcpt\ must be defined in order to receive any
21039 messages over an SMTP connection. For an example, see the ACL in the default
21040 configuration file.
21044 .section Data for message ACLs
21045 .index ~~ACL||data for message ACL
21046 When an ACL for \\MAIL\\, \\RCPT\\, or \\DATA\\ is being run, the variables
21047 that contain information about the host and the message's sender (for example,
21048 \$sender@_host@_address$\ and \$sender@_address$\) are set, and can be used in
21049 ACL statements. In the case of \\RCPT\\ (but not \\MAIL\\ or \\DATA\\),
21050 \$domain$\ and \$local@_part$\ are set from the argument address.
21052 When an ACL for the \\AUTH\\ parameter of \\MAIL\\ is being run, the variables
21053 that contain information about the host are set, but \$sender@_address$\ is not
21056 The \$message@_size$\ variable is set to the value of the \\SIZE\\ parameter on
21057 the \\MAIL\\ command at \\MAIL\\ and \\RCPT\\ time, or -1 if that parameter was
21059 Its value is updated to the true message size by the time the ACL after
21062 The \$rcpt@_count$\ variable increases by one for each \\RCPT\\ command
21063 received. The \$recipients@_count$\ variable increases by one each time a
21064 \\RCPT\\ command is accepted, so while an ACL for \\RCPT\\ is being processed,
21065 it contains the number of previously accepted recipients. At \\DATA\\ time,
21066 \$rcpt@_count$\ contains the total number of \\RCPT\\ commands, and
21067 \$recipients@_count$\ contains the total number of accepted recipients.
21071 .section Data for non-message ACLs
21072 .rset SECTdatfornon "~~chapter.~~section"
21073 .index ~~ACL||data for non-message ACL
21074 When an ACL for \\AUTH\\, \\ETRN\\, \\EXPN\\,
21076 or \\VRFY\\ is being run, the remainder of the SMTP command line is placed in
21077 \$smtp@_command@_argument$\. This can be tested using a \condition\ condition.
21078 For example, here is an ACL for use with \\AUTH\\, which insists that either
21079 the session is encrypted, or the CRAM-MD5 authentication method is used. In
21080 other words, it does not permit authentication methods that use cleartext
21081 passwords on unencrypted connections.
21084 accept encrypted = *
21085 accept condition = ${if eq{${uc:$smtp_command_argument}}\
21086 {CRAM-MD5}{yes}{no}}
21087 deny message = TLS encryption or CRAM-MD5 required
21089 (Another way of applying this restriction is to arrange for the authenticators
21090 that use cleartext passwords not to be advertised when the connection is not
21091 encrypted. You can use the generic \server@_advertise@_condition\ authenticator
21092 option to do this.)
21095 .section Use of the ACL selection options
21096 .index ~~ACL||specifying which to use
21097 The value of an \acl@_smtp@_$it{xxx}\ option is expanded before use, so you can
21098 use different ACLs in different circumstances, and in fact the resulting string
21099 does not have to be the name of a configured list. Having expanded the string,
21100 Exim searches for an ACL as follows:
21102 If the string begins with a slash, Exim attempts to open the file and read
21103 its contents as an ACL.
21104 The lines are processed in the same way as lines in the Exim configuration
21105 file. In particular, continuation lines are supported, blank lines are ignored,
21106 as are lines whose first non-whitespace character is `@#'.
21107 If the file does not exist or cannot be read, an error occurs (typically
21108 causing a temporary failure of whatever caused the ACL to be run). For example:
21110 acl_smtp_data = /etc/acls/\
21111 ${lookup{$sender_host_address}lsearch\
21112 {/etc/acllist}{$value}{default}}
21114 This looks up an ACL file to use on the basis of the host's IP address, falling
21115 back to a default if the lookup fails. If an ACL is successfully read from a
21116 file, it is retained in memory for the duration of the Exim process, so that it
21117 can be re-used without having to re-read the file.
21119 If the string does not start with a slash, and does not contain any spaces,
21120 Exim searches the ACL section of the configuration for a list whose name
21121 matches the string.
21123 If no named ACL is found, or if the string contains spaces, Exim parses
21124 the string as an inline ACL. This can save typing in cases where you just
21125 want to have something like
21127 acl_smtp_vrfy = accept
21129 in order to allow free use of the \\VRFY\\ command.
21130 Such a string may contain newlines; it is processed in the same way as an ACL
21131 that is read from a file.
21135 .section Format of an ACL
21136 .index ~~ACL||format of
21137 .index ~~ACL||verbs, definition of
21138 An individual ACL consists of a number of statements. Each statement starts
21139 with a verb, optionally followed by a number of conditions and other modifiers.
21140 If all the conditions are met, the verb is obeyed.
21141 The same condition may be used (with different arguments) more than once in the
21142 same statement. This provides a means of specifying an `and' conjunction
21143 between conditions. For example:
21145 deny dnslists = list1.example
21146 dnslists = list2.example
21149 If there are no conditions, the verb is always obeyed. What happens if any of
21150 the conditions are not met depends on the verb (and in one case, on a special
21151 modifier). Not all the conditions make sense at every testing point. For
21152 example, you cannot test a sender address in the ACL that is run for a \\VRFY\\
21155 The verbs are as follows:
21157 \accept\: If all the conditions are met, the ACL returns `accept'. If any of
21158 the conditions are not met, what happens depends on whether \endpass\ appears
21159 among the conditions (for syntax see below). If the failing condition precedes
21160 \endpass\, control is passed to the next ACL statement; if it follows
21161 \endpass\, the ACL returns `deny'. Consider this statement, used to check a
21164 accept domains = +local_domains
21168 If the recipient domain does not match the \domains\ condition, control passes
21169 to the next statement. If it does match, the recipient is verified, and the
21170 command is accepted if verification succeeds. However, if verification fails,
21171 the ACL yields `deny', because the failing condition is after \endpass\.
21173 \defer\: If all the conditions are met, the ACL returns `defer' which, in an
21174 SMTP session, causes a 4\*xx*\ response to be given. For a non-SMTP ACL,
21175 \defer\ is the same as \deny\, because there is no way of sending a temporary
21176 error. For a \\RCPT\\ command, \defer\ is much the same as using a
21177 \%redirect%\ router and \":defer:"\ while verifying, but the \defer\ verb can
21178 be used in any ACL, and even for a recipient it might be a simpler approach.
21180 \deny\: If all the conditions are met, the ACL returns `deny'. If any of the
21181 conditions are not met, control is passed to the next ACL statement. For
21184 deny dnslists = blackholes.mail-abuse.org
21186 rejects commands from hosts that are on a DNS black list.
21188 \discard\: This verb behaves like \accept\, except that it returns `discard'
21189 from the ACL instead of `accept'. It is permitted only on ACLs that are
21190 concerned with receiving messages, and it causes recipients to be discarded.
21191 If the \log@_message\ modifier is set when \discard\ operates, its contents are
21192 added to the line that is automatically written to the log.
21194 If \discard\ is used in an ACL for \\RCPT\\, just the one recipient is
21195 discarded; if used for \\MAIL\\, \\DATA\\ or in the non-SMTP ACL, all the
21196 message's recipients are discarded. Recipients that are discarded before
21197 \\DATA\\ do not appear in the log line when the \log@_recipients\ log selector
21200 \drop\: This verb behaves like \deny\, except that an SMTP connection is
21201 forcibly closed after the 5\*xx*\ error message has been sent. For example:
21203 drop message = I don't take more than 20 RCPTs
21204 condition = ${if > {$rcpt_count}{20}{yes}{no}}
21206 There is no difference between \deny\ and \drop\ for the connect-time ACL. The
21207 connection is always dropped after sending a 550 response.
21209 \require\: If all the conditions are met, control is passed to the next ACL
21210 statement. If any of the conditions are not met, the ACL returns `deny'. For
21211 example, when checking a \\RCPT\\ command,
21213 require verify = sender
21215 passes control to subsequent statements only if the message's sender can be
21216 verified. Otherwise, it rejects the command.
21219 \warn\: If all the conditions are met, a header line is added to an incoming
21220 message and/or a line is written to Exim's main log. In all cases, control
21221 passes to the next ACL statement. The text of the added header line and the log
21222 line are specified by modifiers; if they are not present, a \warn\ verb just
21223 checks its conditions and obeys any `immediate' modifiers such as \set\ and
21226 If any condition on a \warn\ statement cannot be completed (that is, there is
21227 some sort of defer), no header is added and the configured log line is not
21228 written. No further conditions or modifiers in the \warn\ statement are
21229 processed. The incident is logged, but the ACL continues to be processed, from
21230 the next statement onwards.
21232 When testing an incoming message, the \message\ modifier can be used on a
21233 \warn\ statement to add an extra header line,
21235 as in this example:
21237 warn message = X-blacklisted-at: $dnslist_domain
21238 dnslists = blackholes.mail-abuse.org : \
21239 dialup.mail-abuse.org
21241 If an identical header line is requested several times (provoked, for example,
21242 by multiple \\RCPT\\ commands), only one copy is actually added to the message.
21244 If the text of the \message\ modifier is not a valid header line,
21245 \"X-ACL-Warn:"\ is added to the front of it.
21248 Header lines that are added by an ACL at \\MAIL\\ or \\RCPT\\ time are not
21249 visible in string expansions in the ACL for subsequent \\RCPT\\ commands.
21250 However they are visible in string expansions in the ACL that is run after
21251 \\DATA\\. If you want to preserve data between \\MAIL\\ and \\RCPT\\ ACLs, you
21252 can use ACL variables, as described in the next section. If a message is
21253 rejected after \\DATA\\, all added header lines are included in the entry that
21254 is written to the reject log.
21256 If a \message\ modifier is present on a \warn\ verb in an ACL that is not
21257 testing an incoming message, it is ignored, and the incident is logged.
21259 A \warn\ statement may use the \log@_message\ modifier to cause a line to be
21260 written to the main log when the statement's conditions are true.
21262 Just as for \message\, if an identical log line is requested several times in
21263 the same message, only one copy is actually written to the log. If you want to
21264 force duplicates to be written, use the \logwrite\ modifier instead.
21267 When one of the \warn\ conditions is an address verification that fails, the
21268 text of the verification failure message is in \$acl@_verify@_message$\. If you
21269 want this logged, you must set it up explicitly. For example:
21271 warn !verify = sender
21272 log_message = sender verify failed: $acl_verify_message
21276 At the end of each ACL there is an implicit unconditional \deny\.
21278 As you can see from the examples above, the conditions and modifiers are
21279 written one to a line, with the first one on the same line as the verb, and
21280 subsequent ones on following lines. If you have a very long condition, you can
21281 continue it onto several physical lines by the usual @\ continuation mechanism.
21282 It is conventional to align the conditions vertically.
21285 .section ACL variables
21286 .rset SECTaclvariables "~~chapter.~~section"
21287 .index ~~ACL||variables
21288 There are some special variables that can be set during ACL processing. They
21289 can be used to pass information between different ACLs, different
21290 invocations of the same ACL in the same SMTP connection, and between ACLs and
21291 the routers, transports, and filters that are used to deliver a message.
21292 There are two sets of these variables:
21294 The values of \$acl@_c0$\ to \$acl@_c9$\ persist throughout an SMTP connection.
21295 They are never reset. Thus, a value that is set while receiving one message is
21296 still available when receiving the next message on the same SMTP connection.
21298 The values of \$acl@_m0$\ to \$acl@_m9$\ persist only while a message is being
21299 received. They are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\,
21300 \\EHLO\\, \\HELO\\, and after starting up a TLS session.
21302 When a message is accepted, the current values of all the ACL variables are
21303 preserved with the message and are subsequently made available at delivery
21306 The ACL variables are set by modifier called \set\. For example:
21308 accept hosts = whatever
21309 set acl_m4 = some value
21311 Note that the leading dollar sign is not used when naming a variable that is to
21312 be set. If you want to set a variable without taking any action, you can use a
21313 \warn\ verb without any other modifiers.
21316 .section Condition and modifier processing
21317 .index ~~ACL||conditions, processing
21318 .index ~~ACL||modifiers, processing
21319 An exclamation mark preceding a condition negates its result. For example,
21321 deny domains = *.dom.example
21322 !verify = recipient
21324 causes the ACL to return `deny' if the recipient domain ends in
21325 \*dom.example*\, but the recipient address cannot be verified.
21327 The arguments of conditions and modifiers are expanded. A forced failure
21328 of an expansion causes a condition to be ignored, that is, it behaves as if the
21329 condition is true. Consider these two statements:
21331 accept senders = ${lookup{$host_name}lsearch\
21332 {/some/file}{$value}fail}
21333 accept senders = ${lookup{$host_name}lsearch\
21334 {/some/file}{$value}{}}
21336 Each attempts to look up a list of acceptable senders. If the lookup succeeds,
21337 the returned list is searched, but if the lookup fails the behaviour is
21338 different in the two cases. The \fail\ in the first statement causes the
21339 condition to be ignored, leaving no further conditions. The \accept\ verb
21340 therefore succeeds. The second statement, however, generates an empty list when
21341 the lookup fails. No sender can match an empty list, so the condition fails,
21342 and therefore the \accept\ also fails.
21344 ACL modifiers appear mixed in with conditions in ACL statements. Some of them
21345 specify actions that are taken as the conditions for a statement are checked;
21346 others specify text for messages that are used when access is denied or a
21347 warning is generated.
21349 The positioning of the modifiers in an ACL statement important, because the
21350 processing of a verb ceases as soon as its outcome is known. Only those
21351 modifiers that have already been encountered will take effect. For the \accept\
21352 and \require\ statements, this means that processing stops as soon as a false
21353 condition is met. For example, consider this use of the \message\ modifier:
21355 require message = Can't verify sender
21357 message = Can't verify recipient
21359 message = This message cannot be used
21361 If sender verification fails, Exim knows that the result of the statement is
21362 `deny', so it goes no further. The first \message\ modifier has been seen, so
21363 its text is used as the error message. If sender verification succeeds, but
21364 recipient verification fails, the second message is used. If recipient
21365 verification succeeds, the third message becomes `current', but is never used
21366 because there are no more conditions to cause failure.
21368 For the \deny\ verb, on the other hand, it is always the last \message\
21369 modifier that is used, because all the conditions must be true for rejection to
21370 happen. Specifying more than one \message\ modifier does not make sense, and
21371 the message can even be specified after all the conditions. For example:
21374 !senders = *@my.domain.example
21375 message = Invalid sender from client host
21377 The `deny' result does not happen until the end of the statement is reached, by
21378 which time Exim has set up the message.
21381 .section ACL modifiers
21382 .rset SECTACLmodi "~~chapter.~~section"
21383 .index ~~ACL||modifiers, list of
21384 The ACL modifiers are as follows:
21388 .item "control = <<text>>"
21389 .index message||submission
21390 This modifier may appear only in ACLs for commands relating to incoming
21391 messages. It affects the subsequent processing of the message, provided that
21392 the message is eventually accepted.
21394 The text must be one of the words `freeze', `queue@_only', or `submission' (in
21395 the latter case, optionally followed by slash-delimited options). The first two
21396 cause the message to be frozen or just queued (without immediate delivery),
21397 respectively. The third tells Exim that this message is a submission from a
21398 local MUA. In this case, Exim applies certain fixups to the message if
21399 necessary. For example, it add a ::Date:: header line if one is not present.
21400 Details are given in chapter ~~CHAPmsgproc.
21403 Once one of these controls is set, it remains set for the message. For example,
21404 if \control\ is used in a \\RCPT\\ ACL, it applies to the whole message, not
21405 just the individual recipient. The \control\ modifier can be used in several
21406 different ways. For example:
21408 It can be at the end of an \accept\ statement:
21410 accept ...some conditions...
21411 control = queue_only
21413 In this case, the control is applied when this statement yields `accept'.
21415 It can be in the middle of an \accept\ statement:
21417 accept ...some conditions...
21418 control = queue_only
21419 ...some more conditions...
21421 If the first set of conditions are true, the control is applied, even if the
21422 statement does not accept because one of the second set of conditions is false.
21423 In this case, some subsequent statement must yield `accept' for the control to
21426 It can be used with \warn\ to apply the control, leaving the
21427 decision about accepting or denying to a subsequent verb. For
21430 warn ...some conditions...
21435 This example of \warn\ does not contain \message\, \log@_message\, or
21436 \logwrite\, so it does not add anything to the message and does not write a log
21441 .item "delay = <<time>>"
21442 .index \-bh-\ option
21443 This modifier causes Exim to wait for the time interval before proceeding. The
21444 time is given in the usual Exim notation. This modifier may appear in any ACL.
21445 The delay happens as soon as the modifier is processed.
21447 However, when testing Exim using the \-bh-\ option, the delay is not actually
21448 imposed (an appropriate message is output).
21451 Like \control\, \delay\ can be used with \accept\ or
21452 \deny\, for example:
21454 deny ...some conditions...
21457 The delay happens if all the conditions are true, before the statement returns
21458 `deny'. Compare this with:
21461 ...some conditions...
21463 which waits for 30s before processing the conditions. The \delay\ modifier can
21464 also be used with \warn\ and together with \control\:
21466 warn ...some conditions...
21473 This modifier, which has no argument, is recognized only in \accept\
21474 statements. It marks the boundary between the conditions whose failure causes
21475 control to pass to the next statement, and the conditions whose failure causes
21476 the ACL to return `deny'. See the description of \accept\ above.
21478 .item "log@_message = <<text>>"
21479 This modifier sets up a message that is used as part of the log message if the
21482 or a \warn\ statement's conditions are true.
21486 require log_message = wrong cipher suite $tls_cipher
21487 encrypted = DES-CBC3-SHA
21489 \log@_message\ adds to any underlying error message that may exist because of
21490 the condition failure. For example, while verifying a recipient address, a
21491 :::fail:: redirection might have already set up a message. Although the message
21492 is usually defined before the conditions to which it applies, the expansion
21493 does not happen until Exim decides that access is to be denied. This means that
21494 any variables that are set by the condition are available for inclusion in the
21495 message. For example, the \$dnslist@_<<xxx>>$\ variables are set after a DNS
21496 black list lookup succeeds. If the expansion of \log@_message\ fails, or if the
21497 result is an empty string, the modifier is ignored.
21499 If you want to use a \warn\ statement to log the result of an address
21500 verification, you can use \$acl__verify__message$\ to include the verification
21504 If \log@_message\ is used with a \warn\ statement, `Warning:' is added to the
21505 start of the logged message. If the same warning log message is requested more
21506 than once while receiving a single email message, only one copy is actually
21507 logged. If you want to log multiple copies, use \logwrite\ instead of
21508 \log@_message\. In the absence of \log@_message\ and \logwrite\, nothing is
21509 logged for a succesful \warn\ statement.
21512 If \log@_message\ is not present and there is no underlying error message (for
21513 example, from the failure of address verification), but \message\ is present,
21514 the \message\ text is used for logging rejections. However, if any text for
21515 logging contains newlines, only the first line is logged. In the absence of
21516 both \log@_message\ and \message\, a default built-in message is used for
21517 logging rejections.
21519 .item "logwrite = <<text>>"
21520 .index log||in ACL, immediate
21521 This modifier writes a message to a log file as soon as it is encountered when
21522 processing an ACL. (Compare \log@_message\, which,
21524 except in the case of \warn\,
21526 is used only if the ACL statement denies access.) The \logwrite\ modifier can
21527 be used to log special incidents in ACLs. For example:
21529 accept <<some special conditions>>
21531 logwrite = froze message because ...
21533 By default, the message is written to the main log. However, it may begin
21534 with a colon, followed by a comma-separated list of log names, and then
21535 another colon, to specify exactly which logs are to be written. For
21538 logwrite = :main,reject: text for main and reject logs
21539 logwrite = :panic: text for panic log only
21542 .item "message = <<text>>"
21543 This modifier sets up a text string that is expanded and used as an error
21544 message if the current statement causes the ACL to deny access. The expansion
21545 happens at the time Exim decides that access is to be denied, not at the time
21546 it processes \message\. If the expansion fails, or generates an empty string,
21547 the modifier is ignored. For ACLs that are triggered by SMTP commands, the
21548 message is returned as part of the SMTP error response.
21550 The \message\ modifier is also used with the \warn\ verb to specify one or more
21551 header lines to be added to an incoming message when all the conditions are
21553 If \message\ is used with \warn\ in an ACL that is not concerned with receiving
21554 a message, it has no effect.
21556 The text is literal; any quotes are taken as literals, but because the string
21557 is expanded, backslash escapes are processed anyway. If the message contains
21558 newlines, this gives rise to a multi-line SMTP response. Like \log@_message\,
21559 the contents of \message\ are not expanded until after a condition has failed.
21561 If \message\ is used on a statement that verifies an address, the message
21562 specified overrides any message that is generated by the verification process.
21563 However, the original message is available in the variable
21564 \$acl@_verify@_message$\, so you can incorporate it into your message if you
21565 wish. In particular, if you want the text from \:fail:\ items in \%redirect%\
21566 routers to be passed back as part of the SMTP response, you should either not
21567 use a \message\ modifier, or make use of \$acl@_verify@_message$\.
21569 .item "set <<acl@_name>> = <<value>>"
21570 This modifier puts a value into one of the ACL variables (see section
21571 ~~SECTaclvariables).
21578 .section ACL conditions
21579 .rset SECTaclconditions "~~chapter.~~section"
21580 .index ~~ACL||conditions, list of
21581 Not all conditions are relevant in all circumstances. For example, testing
21582 senders and recipients does not make sense in an ACL that is being run as the
21583 result of the arrival of an \\ETRN\\ command, and checks on message headers can
21584 be done only in the ACLs specified by \acl@_smtp@_data\
21585 and \acl__not__smtp\.
21586 You can use the same condition (obviously with different parameters) more than
21587 once in the same ACL statement. This provides a way of specifying an `and'
21589 The conditions are as follows:
21593 .item "acl = <<name of acl or ACL string or file name >>"
21594 .index ~~ACL||nested
21595 .index ~~ACL||indirect
21596 The possible values of the argument are the same as for the
21597 \acl@_smtp@_$it{xxx}\ options. The named or inline ACL is run. If it returns
21598 `accept' the condition is true; if it returns `deny' the condition is false; if
21599 it returns `defer', the current ACL returns `defer'.
21600 If it returns `drop' and the outer condition denies access, the connection is
21601 dropped. If it returns `discard', the verb must be \accept\ or \discard\, and
21602 the action is taken immediately -- no further conditions are tested.
21604 ACLs may be nested up to 20 deep; the limit exists purely to catch runaway
21605 loops. This condition allows you to use different ACLs in different
21606 circumstances. For example, different ACLs can be used to handle \\RCPT\\
21607 commands for different local users or different local domains.
21609 .item "authenticated = <<string list>>"
21610 .index authentication||ACL checking
21611 .index ~~ACL||testing for authentication
21612 If the SMTP connection is not authenticated, the condition is false. Otherwise,
21613 the name of the authenticator is tested against the list. To test for
21614 authentication by any authenticator, you can set
21619 .item "condition = <<string>>"
21620 .index customizing||ACL condition
21621 .index ~~ACL||customized test
21622 This feature allows you to make up custom conditions. If the result of
21623 expanding the string is an empty string, the number zero, or one of the strings
21624 `no' or `false', the condition is false. If the result is any non-zero number,
21625 or one of the strings `yes' or `true', the condition is true. For any other
21626 values, some error is assumed to have occured, and the ACL returns `defer'.
21628 .item "dnslists = <<list of domain names and other data>>"
21629 .index DNS list||in ACL
21630 .index black list (DNS)
21631 .index ~~ACL||testing a DNS list
21632 This condition checks for entries in DNS black lists. These are also known as
21633 `RBL lists', after the original Realtime Blackhole List, but note that the use
21634 of the lists at \*mail-abuse.org*\ now carries a charge.
21635 There are too many different variants of this condition to describe briefly
21636 here. See sections ~~SECTmorednslists--~~SECTmorednslistslast for details.
21638 .item "domains = <<domain list>>"
21639 .index domain||ACL checking
21640 .index ~~ACL||testing a recipient domain
21641 This condition is relevant only after a \\RCPT\\ command. It checks that the
21642 domain of the recipient address is in the domain list. If percent-hack
21643 processing is enabled, it is done before this test is done. If the check
21644 succeeds with a lookup, the result of the lookup is placed in \$domain@_data$\
21645 until the next \domains\ test.
21647 .item "encrypted = <<string list>>"
21648 .index encryption||checking in an ACL
21649 .index ~~ACL||testing for encryption
21650 If the SMTP connection is not encrypted, the condition is false. Otherwise, the
21651 name of the cipher suite in use is tested against the list. To test for
21652 encryption without testing for any specific cipher suite(s), set
21657 .item "hosts = << host list>>"
21658 .index host||ACL checking
21659 .index ~~ACL||testing the client host
21660 This condition tests that the calling host matches the host list. If you have
21661 name lookups or wildcarded host names and IP addresses in the same host list,
21662 you should normally put the IP addresses first. For example, you could have:
21664 accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
21666 The reason for this lies in the left-to-right way that Exim processes lists.
21667 It can test IP addresses without doing any DNS lookups, but when it reaches an
21668 item that requires a host name, it fails if it cannot find a host name to
21669 compare with the pattern. If the above list is given in the opposite order, the
21670 \accept\ statement fails for a host whose name cannot be found, even if its
21671 IP address is 10.9.8.7.
21673 If you really do want to do the name check first, and still recognize the IP
21674 address even if the name lookup fails, you can rewrite the ACL like this:
21676 accept hosts = dbm;/etc/friendly/hosts
21677 accept hosts = 10.9.8.7
21679 The default action on failing to find the host name is to assume that the host
21680 is not in the list, so the first \accept\ statement fails. The second statement
21681 can then check the IP address.
21683 If a \hosts\ condition is satisfied by means of a lookup, the result
21684 of the lookup is made available in the \$host@_data$\ variable. This
21685 allows you, for example, to set up a statement like this:
21687 deny hosts = net-lsearch;/some/file
21688 message = $host_data
21690 which gives a custom error message for each denied host.
21692 .item "local@_parts = <<local part list>>"
21693 .index local part||ACL checking
21694 .index ~~ACL||testing a local part
21695 This condition is relevant only after a \\RCPT\\ command. It checks that the
21696 local part of the recipient address is in the list. If percent-hack processing
21697 is enabled, it is done before this test. If the check succeeds with a lookup,
21698 the result of the lookup is placed in \$local@_part@_data$\ until the next
21699 \local@_parts\ test.
21701 .item "recipients = <<address list>>"
21702 .index recipient||ACL checking
21703 .index ~~ACL||testing a recipient
21704 This condition is relevant only after a \\RCPT\\ command. It checks the entire
21705 recipient address against a list of recipients.
21707 .item "sender@_domains = <<domain list>>"
21708 .index sender||ACL checking
21709 .index ~~ACL||testing a sender domain
21710 This condition tests the domain of the sender of the message against the given
21712 \**Note**\: the domain of the sender address is in
21713 \$sender@_address@_domain$\. It is \*not*\ put in \$domain$\ during the testing
21714 of this condition. This is an exception to the general rule for testing
21715 domain lists. It is done this way so that, if this condition is used in an
21716 ACL for a \\RCPT\\ command, the recipient's domain (which is in \$domain$\) can
21717 be used to influence the sender checking.
21719 .item "senders = <<address list>>"
21720 .index sender||ACL checking
21721 .index ~~ACL||testing a sender
21722 This condition tests the sender of the message against the given list. To test
21723 for a bounce message, which has an empty sender, set
21728 .item "verify = certificate"
21729 .index TLS||client certificate verification
21730 .index certificate||verification of client
21731 .index ~~ACL||certificate verification
21732 This condition is true in an SMTP session if the session is encrypted, and a
21733 certificate was received from the client, and the certificate was verified. The
21734 server requests a certificate only if the client matches \tls@_verify@_hosts\
21735 or \tls@_try@_verify@_hosts\ (see chapter ~~CHAPTLS).
21737 .item "verify = header@_sender/<<options>>"
21738 .index ~~ACL||verifying sender in the header
21739 .index header lines||verifying the sender in
21740 .index sender||verifying in header
21741 .index verifying||sender in header
21742 This condition is relevant only in an ACL that is run after a message has been
21743 received, that is, in an ACL specified by \acl@_smtp@_data\. It checks that
21744 there is a verifiable sender address in at least one of the ::Sender::,
21745 ::Reply-To::, or ::From:: header lines. Details of address verification and the
21746 options are given later, starting at section ~~SECTaddressverification. You can
21747 combine this condition with the \senders\ condition to restrict it to bounce
21751 message = A valid sender header is required for bounces
21752 !verify = header_sender
21755 .item "verify = header@_syntax"
21756 .index ~~ACL||verifying header syntax
21757 .index header lines||verifying syntax
21758 .index verifying||header syntax
21759 This condition is relevant only in an ACL that is run after a message has been
21760 received, that is, in an ACL specified by \acl@_smtp@_data\
21761 or \acl@_not@_smtp\.
21762 It checks the syntax of all header lines that can contain lists of addresses
21763 (::Sender::, ::From::, ::Reply-To::, ::To::, ::Cc::, and ::Bcc::).
21764 Unqualified addresses (local parts without domains) are permitted only in
21765 locally generated messages and from hosts that match
21766 \sender@_unqualified@_hosts\ or \recipient@_unqualified@_hosts\, as
21769 Note that this condition is a syntax check only. However, a common spamming
21770 ploy is to send syntactically invalid headers such as
21774 and this condition can be used to reject such messages.
21776 .item "verify = helo"
21777 .index ~~ACL||verifying HELO/EHLO
21778 .index \\HELO\\||verifying
21779 .index \\EHLO\\||verifying
21780 .index verifying||\\EHLO\\
21781 .index verifying||\\HELO\\
21782 This condition is true if a \\HELO\\ or \\EHLO\\ command has been received from
21783 the client host, and its contents have been verified. Verification of these
21784 commands does not happen by default. See the description of the
21785 \helo@_verify@_hosts\ and \helo@_try@_verify@_hosts\ options for details of how
21788 .item "verify = recipient/<<options>>"
21789 .index ~~ACL||verifying recipient
21790 .index recipient||verifying
21791 .index verifying||recipient
21792 This condition is relevant only after a \\RCPT\\ command. It verifies the
21793 current recipient. Details of address verification are given later, starting at
21794 section ~~SECTaddressverification. After a recipient has been verified, the
21795 value of \$address@_data$\ is the last value that was set while routing the
21796 address. This applies even if the verification fails. When an address that is
21797 being verified is redirected to a single address, verification continues with
21798 the new address, and in that case, the subsequent value of \$address@_data$\ is
21799 the value for the child address.
21802 .item "verify = reverse@_host@_lookup"
21803 .index ~~ACL||verifying host reverse lookup
21804 .index host||verifying reverse lookup
21805 This condition ensures that a verified host name has been looked up from the IP
21806 address of the client host. (This may have happened already if the host name
21807 was needed for checking a host list, or if the host matched \host@_lookup\.)
21808 Verification ensures that the host name obtained from a reverse DNS lookup, or
21809 one of its aliases, does, when it is itself looked up in the DNS, yield the
21810 original IP address.
21812 If this condition is used for a locally generated message (that is, when there
21813 is no client host involved), it always succeeds.
21816 .item "verify = sender/<<options>>"
21817 .index ~~ACL||verifying sender
21818 .index sender||verifying
21819 .index verifying||sender
21820 This condition is relevant only after a
21821 \\MAIL\\ or \\RCPT\\ command, or after a message has been received (the
21822 \acl@_smtp@_data\ or \acl@_not@_smtp\ ACLs).
21823 If the message's sender is empty (that is, this is a bounce message), the
21824 condition is true. Otherwise, the sender address is verified. Details of
21825 verification are given later, starting at section ~~SECTaddressverification.
21826 Exim caches the result of sender verification, to avoid doing it more than once
21829 .item "verify = sender=address/<<options>>"
21830 This is a variation of the previous option, in which a modified address is
21831 verified as a sender.
21837 .section Using DNS lists
21838 .rset SECTmorednslists "~~chapter.~~section"
21839 .index DNS list||in ACL
21840 .index black list (DNS)
21841 .index ~~ACL||testing a DNS list
21842 In its simplest form, the \dnslists\ condition tests whether the calling host
21843 is on a DNS list by looking up the inverted IP address in one or more DNS
21844 domains. For example, if the calling host's IP address is 192.168.62.43, and
21845 the ACL statement is
21847 deny dnslists = blackholes.mail-abuse.org : \
21848 dialups.mail-abuse.org
21850 the following domains are looked up:
21852 43.62.168.192.blackholes.mail-abuse.org
21853 43.62.168.192.dialups.mail-abuse.org
21855 If a DNS lookup times out or otherwise fails to give a decisive answer, Exim
21856 behaves as if the host is not on the relevant list. This is usually the
21857 required action when \dnslists\ is used with \deny\ (which is the most common
21858 usage), because it prevents a DNS failure from blocking mail. However, you can
21859 change this behaviour by putting one of the following special items in the
21861 .index \"+include@_unknown"\
21862 .index \"+exclude@_unknown"\
21863 .index \"+defer@_unknown"\
21865 +include@_unknown $rm{behave as if the item is on the list}
21866 +exclude@_unknown $rm{behave as if the item is not on the list (default)}
21867 +defer@_unknown $rm{give a temporary error}
21869 Each of these applies to any subsequent items on the list. For example:
21871 deny dnslists = +defer_unknown : foo.bar.example
21874 Testing the list of domains stops as soon as a match is found. If you want to
21875 warn for one list and block for another, you can use two different statements:
21877 deny dnslists = blackholes.mail-abuse.org
21878 warn message = X-Warn: sending host is on dialups list
21879 dnslists = dialups.mail-abuse.org
21882 DNS list lookups are cached by Exim for the duration of the SMTP session,
21883 so a lookup based on the IP address is done at most once for any incoming
21884 connection. Exim does not share information between multiple incoming
21885 connections (but your local name server cache should be active).
21888 .section DNS lists keyed on domain names
21889 There are some lists that are keyed on domain names rather than inverted IP
21890 addresses (see for example the \*domain based zones*\ link at
21891 \?http://www.rfc-ignorant.org/?\).
21893 No reversing of components is used with these lists.
21895 You can change the name that is looked up in a DNS list by adding additional
21896 data to a \dnslists\ item, introduced by a slash. For example,
21898 deny message = Sender's domain is listed at $dnslist_domain
21899 dnslists = dsn.rfc-ignorant.org/$sender_address_domain
21901 This particular example is useful only in ACLs that are obeyed after the
21902 \\RCPT\\ or \\DATA\\ commands, when a sender address is available. If (for
21903 example) the message's sender is \*user@@tld.example*\ the name that is looked
21904 up by this example is
21906 tld.example.dsn.rfc-ignorant.org
21908 You can mix entries with and without additional data in the same \dnslists\
21911 .section Data returned by DNS lists
21912 DNS lists are constructed using address records in the DNS. The original RBL
21913 just used the address 127.0.0.1 on the right hand side of each record, but the
21914 RBL+ list and some other lists use a number of values with different meanings.
21915 The values used on the RBL+ list are:
21920 127.1.0.3 $t DUL and RBL
21922 127.1.0.5 $t RSS and RBL
21923 127.1.0.6 $t RSS and DUL
21924 127.1.0.7 $t RSS and DUL and RBL
21926 Some DNS lists may return more than one address record.
21928 .section Variables set from DNS lists
21929 When an entry is found in a DNS list, the variable \$dnslist@_domain$\
21930 contains the name of the domain that matched, \$dnslist@_value$\ contains the
21931 data from the entry, and \$dnslist@_text$\ contains the contents of any
21932 associated TXT record. If more than one address record is returned by the DNS
21933 lookup, all the IP addresses are included in \$dnslist@_value$\, separated by
21936 You can use these variables in \message\ or \log@_message\ modifiers --
21937 although these appear before the condition in the ACL, they are not expanded
21938 until after it has failed. For example:
21940 deny hosts = !+local_networks
21941 message = $sender_host_address is listed \
21943 dnslists = rbl-plus.mail-abuse.example
21947 .section Additional matching conditions for DNS lists
21948 If you add an equals sign and an IP address after a \dnslists\ domain name, you
21949 can restrict its action to DNS records with a matching right hand side. For
21952 deny dnslists = rblplus.mail-abuse.org=127.0.0.2
21954 rejects only those hosts that yield 127.0.0.2. Without this additional data,
21955 any address record is considered to be a match. If more than one address record
21956 is found on the list, they are all checked for a matching right-hand side.
21958 If you want to specify a constraining address and also change the name that is
21959 looked up, the address list must be specified first. For example:
21961 deny dnslists = dsn.rfc-ignorant.org\
21962 =127.0.0.2/$sender_address_domain
21965 More than one IP address may be given for checking, using a comma as a
21966 separator. These are alternatives -- if any one of them matches, the \dnslists\
21967 condition is true. For example:
21969 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
21972 If the character `&' is used instead of `=', the comparison for each listed
21973 IP address is done by a bitwise `and' instead of by an equality test. In
21974 other words, the listed addresses are used as bit masks. The comparison is
21975 true if all the bits in the mask are present in the address that is being
21976 tested. For example:
21978 dnslists = a.b.c&0.0.0.3
21980 matches if the address is \*x.x.x.*\3, \*x.x.x.*\7, \*x.x.x.*\11, etc. If you
21981 want to test whether one bit or another bit is present (as opposed to both
21982 being present), you must use multiple values. For example:
21984 dnslists = a.b.c&0.0.0.1,0.0.0.2
21986 matches if the final component of the address is an odd number or two times
21990 .section Negated DNS matching conditions
21991 You can supply a negative list of IP addresses as part of a \dnslists\
21994 deny dnslists = a.b.c=127.0.0.2,127.0.0.3
21996 means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP
21997 address yielded by the list is either 127.0.0.2 or 127.0.0.3',
21999 deny dnslists = a.b.c!=127.0.0.2,127.0.0.3
22001 means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP
22002 address yielded by the list is not 127.0.0.2 and not 127.0.0.3'. In other
22003 words, the result of the test is inverted if an exclamation mark appears before
22004 the `=' (or the `&') sign.
22006 \**Note**\: this kind of negation is not the same as negation in a domain,
22007 host, or address list (which is why the syntax is different).
22009 If you are using just one list, the negation syntax does not gain you much. The
22010 previous example is precisely equivalent to
22012 deny dnslists = a.b.c
22013 !dnslists = a.b.c=127.0.0.2,127.0.0.3
22015 However, if you are using multiple lists, the negation syntax is clearer.
22016 Consider this example:
22018 deny dnslists = sbl.spamhaus.org : \
22020 dnsbl.njabl.org!=127.0.0.3 : \
22023 Using only positive lists, this would have to be:
22025 deny dnslists = sbl.spamhaus.org : \
22027 deny dnslists = dnsbl.njabl.org
22028 !dnslists = dnsbl.njabl.org=127.0.0.3
22029 deny dnslists = relays.ordb.org
22031 which is less clear, and harder to maintain.
22035 .section DNS lists and IPv6
22036 .rset SECTmorednslistslast "~~chapter.~~section"
22037 If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
22038 nibble by nibble. For example, if the calling host's IP address is
22039 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up
22041 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8.
22042 f.f.f.f.e.f.f.3.blackholes.mail-abuse.org
22044 (split over two lines here to fit on the page). Unfortunately, some of the DNS
22045 lists contain wildcard records, intended for IPv4, that interact badly with
22046 IPv6. For example, the DNS entry
22048 *.3.some.list.example. A 127.0.0.1
22050 is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list.
22051 Unfortunately, it also matches the entire 3@:@:/124 IPv6 network.
22053 You can exclude IPv6 addresses from DNS lookups by making use of a suitable
22054 \condition\ condition, as in this example:
22056 deny condition = ${if isip4{$sender_host_address}{yes}{no}}
22057 dnslists = some.list.example
22061 .section Address verification
22062 .rset SECTaddressverification "~~chapter.~~section"
22063 .index verifying||address, options for
22064 .index policy control||address verification
22065 Several of the \verify\ conditions described in section ~~SECTaclconditions
22066 cause addresses to be verified. These conditions can be followed by options
22067 that modify the verification process. The options are separated from the
22068 keyword and from each other by slashes, and some of them contain parameters.
22071 verify = sender/callout
22072 verify = recipient/defer_ok/callout=10s,defer_ok
22074 The first stage of verification is to run the address through the routers, in
22075 `verify mode'. Routers can detect the difference between verification and
22076 routing for delivery, and their actions can be varied by a number of generic
22077 options such as \verify\ and \verify@_only\ (see chapter ~~CHAProutergeneric).
22079 If there is a defer error while doing this verification routing, the ACL
22080 normally returns `defer'. However, if you include \defer@_ok\ in the options,
22081 the condition is forced to be true instead.
22083 .section Callout verification
22084 .rset SECTcallver "~~chapter.~~section"
22085 .index verifying||address, by callout
22086 .index callout||verification
22087 .index SMTP||callout verification
22088 For non-local addresses, routing verifies the domain, but is unable to do any
22089 checking of the local part. There are situations where some means of verifying
22090 the local part is desirable. One way this can be done is to make an SMTP
22091 \*callback*\ to the sending host (for a sender address) or a \*callforward*\ to
22092 a subsequent host (for a recipient address), to see if the host accepts the
22093 address. We use the term \*callout*\ to cover both cases. This facility should
22094 be used with care, because it can add a lot of resource usage to the cost of
22095 verifying an address. However, Exim does cache the results of callouts, which
22096 helps to reduce the cost. Details of caching are in the next section.
22099 Recipient callouts are usually used only between hosts that are controlled by
22100 the same administration. For example, a corporate gateway host could use
22101 callouts to check for valid recipients on an internal mailserver.
22103 A successful callout does not guarantee that a real delivery to the address
22104 would succeed; on the other hand, a failing callout does guarantee that
22105 a delivery would fail.
22107 If the \callout\ option is present on a condition that verifies an address, a
22108 second stage of verification occurs if the address is successfully routed to
22109 one or more remote hosts. The usual case is routing by a \%dnslookup%\ or a
22110 \%manualroute%\ router, where the router specifies the hosts. However, if a
22111 router that does not set up hosts routes to an \%smtp%\ transport with a
22112 \hosts\ setting, the transport's hosts are used. If an \%smtp%\ transport has
22113 \hosts@_override\ set, its hosts are always used, whether or not the router
22114 supplies a host list.
22116 The port that is used is taken from the transport, if it is specified and is a
22117 remote transport. (For routers that do verification only, no transport need be
22118 specified.) Otherwise, the default SMTP port is used. If a remote transport
22119 specifies an outgoing interface, this is used; otherwise the interface is not
22122 For a sender callout check, Exim makes SMTP connections to the remote hosts, to
22123 test whether a bounce message could be delivered to the sender address. The
22124 following SMTP commands are sent:
22126 HELO <<primary host name>>
22128 RCPT TO:<<the address to be tested>>
22131 \\LHLO\\ is used instead of \\HELO\\ if the transport's \protocol\ option is
22135 A recipient callout check is similar. By default, it also uses an empty address
22136 for the sender. This default is chosen because most hosts do not make use of
22137 the sender address when verifying a recipient. Using the same address means
22138 that a single cache entry can be used for each recipient. Some sites, however,
22139 do make use of the sender address when verifying. These are catered for by the
22140 \use@_sender\ and \use@_postmaster\ options, described in the next section.
22143 If the response to the \\RCPT\\ command is a 2$it{xx} code, the verification
22144 succeeds. If it is 5$it{xx}, the verification fails. For any other condition,
22145 Exim tries the next host, if any. If there is a problem with all the remote
22146 hosts, the ACL yields `defer', unless the \defer@_ok\ parameter of the
22147 \callout\ option is given, in which case the condition is forced to succeed.
22150 .section Additional parameters for callouts
22151 .rset CALLaddparcall "~~chapter.~~section"
22152 .index callout||timeout, specifying
22153 The \callout\ option can be followed by an equals sign and a number of optional
22154 parameters, separated by commas. For example:
22156 verify = recipient/callout=10s,defer_ok
22158 The old syntax, which had \callout@_defer@_ok\ and \check@_postmaster\ as
22159 separate verify options, is retained for backwards compatibility, but is now
22160 deprecated. The additional parameters for \callout\ are as follows:
22163 <<a time>>: This specifies the timeout that applies for the callout attempt to
22164 each host. For example:
22166 verify = sender/callout=5s
22168 The default is 30 seconds. The timeout is used for each response from the
22171 .index callout||defer, action on
22172 \defer@_ok\: Failure to contact any host, or any other kind of temporary error
22173 is treated as success by the ACL. However, the cache is not updated in this
22176 .index callout||cache, suppressing
22177 .index caching||callout, suppressing
22178 \no@_cache\: The callout cache is neither read nor updated.
22180 .index callout||postmaster, checking
22181 \postmaster\: A successful callout check is followed by a similar check for the
22182 local part \*postmaster*\ at the same domain. If this address is rejected, the
22183 callout fails. The result of the postmaster check is recorded in a cache
22184 record; if it is a failure, this is used to fail subsequent callouts for the
22185 domain without a connection being made, until the cache record expires.
22187 .index callout||`random' check
22188 \random\: Before doing the normal callout check, Exim does a
22189 check for a `random' local part at the same domain. The local part is not
22190 really random -- it is defined by the expansion of the option
22191 \callout@_random@_local@_part\, which defaults to
22193 $primary_host_name-$tod_epoch-testing
22195 The idea here is to try to determine whether the remote host accepts all local
22196 parts without checking. If it does, there is no point in doing callouts for
22197 specific local parts. If the `random' check succeeds, the result is saved in
22198 a cache record, and used to force the current and subsequent callout checks to
22199 succeed without a connection being made, until the cache record expires.
22201 .index callout||sender for recipient check
22203 \use@_postmaster\: This option applies to recipient callouts only. For example:
22205 deny !verify = recipient/callout=use_postmaster
22207 It causes a non-empty postmaster address to be used in the \\MAIL\\ command
22208 when performing the callout. The local part of the address is \"postmaster"\
22209 and the domain is the contents of \$qualify@_domain$\.
22211 \use@_sender\: This option applies to recipient callouts only. For example:
22213 require verify = recipient/callout=use_sender
22215 It causes the message's actual sender address to be used in the \\MAIL\\
22216 command when performing the callout, instead of an empty address. The cache for
22217 such callouts is keyed by the sender/recipient combination; thus, for any given
22218 recipient, many more actual callouts are performed than when an empty sender or
22219 postmaster is used. This option should be set only when you know that the
22220 called hosts make use of the sender when checking recipients.
22225 .section Callout caching
22226 .rset SECTcallvercache "~~chapter.~~section"
22227 .index hints database||callout cache
22228 .index callout||caching
22229 .index caching||callout
22230 Exim caches the results of callouts in order to reduce the amount of resources
22231 used, unless you specify the \no@_cache\ parameter with the \callout\ option.
22232 A hints database called `callout' is used for the cache. Two different record
22233 types are used: one records the result of a callout check for a specific
22234 address, and the other records information that applies to the entire domain
22235 (for example, that it accepts the local part \*postmaster*\).
22237 When an original callout fails, a detailed SMTP error message is given about
22238 the failure. However, for subsequent failures use the cache data, this message
22241 The expiry times for negative and positive address cache records are
22242 independent, and can be set by the global options \callout@_negative@_expire\
22243 (default 2h) and \callout@_positive@_expire\ (default 24h), respectively.
22245 If a host gives a negative response to an SMTP connection, or rejects any
22246 commands up to and including
22251 (but not including the \\MAIL\\ command with a non-empty address),
22253 any callout attempt is bound to fail. Exim remembers such failures in a
22254 domain cache record, which it uses to fail callouts for the domain without
22255 making new connections, until the domain record times out. There are two
22256 separate expiry times for domain cache records:
22257 \callout@_domain@_negative@_expire\ (default 3h) and
22258 \callout__domain__positive@_expire\ (default 7d).
22260 Domain records expire when the negative expiry time is reached if callouts
22261 cannot be made for the domain, or if the postmaster check failed.
22262 Otherwise, they expire when the positive expiry time is reached. This
22263 ensures that, for example, a host that stops accepting `random' local parts
22264 will eventually be noticed.
22266 The callout caching mechanism is based entirely on the domain of the
22267 address that is being tested. If the domain routes to several hosts, it is
22268 assumed that their behaviour will be the same.
22271 .section Sender address verification reporting
22272 .index verifying||suppressing error details
22273 When sender verification fails in an ACL, the details of the failure are
22274 given as additional output lines before the 550 response to the relevant
22275 SMTP command (\\RCPT\\ or \\DATA\\). For example, if sender callout is in use,
22278 MAIL FROM:<xyz@abc.example>
22280 RCPT TO:<pqr@def.example>
22281 550-Verification failed for <xyz@abc.example>
22282 550-Called: 192.168.34.43
22283 550-Sent: RCPT TO:<xyz@abc.example>
22284 550-Response: 550 Unknown local part xyz in <xyz@abc.example>
22285 550 Sender verification failed
22287 If more than one \\RCPT\\ command fails in the same way, the details are given
22288 only for the first of them. However, some administrators do not want to send
22289 out this much information. You can suppress the details by adding
22290 `/no@_details' to the ACL statement that requests sender verification. For
22293 verify = sender/no_details
22297 .section Redirection while verifying
22298 .index verifying||redirection while
22299 .index address redirection||while verifying
22300 A dilemma arises when a local address is redirected by aliasing or forwarding
22301 during verification: should the generated addresses themselves be verified,
22302 or should the successful expansion of the original address be enough to verify
22303 it? Exim takes the following pragmatic approach:
22305 When an incoming address is redirected to just one child address, verification
22306 continues with the child address, and if that fails to verify, the original
22307 verification also fails.
22309 When an incoming address is redirected to more than one child address,
22310 verification does not continue. A success result is returned.
22312 This seems the most reasonable behaviour for the common use of aliasing as a
22313 way of redirecting different local parts to the same mailbox. It means, for
22314 example, that a pair of alias entries of the form
22317 aw123: :fail: Gone away, no forwarding address
22319 work as expected, with both local parts causing verification failure. When a
22320 redirection generates more than one address, the behaviour is more like a
22321 mailing list, where the existence of the alias itself is sufficient for
22322 verification to succeed.
22325 .section Using an ACL to control relaying
22326 .rset SECTrelaycontrol "~~chapter.~~section"
22327 .index ~~ACL||relay control
22328 .index relaying||control by ACL
22329 .index policy control||relay control
22330 An MTA is said to \*relay*\ a message if it receives it from some host and
22331 delivers it directly to another host as a result of a remote address contained
22332 within it. Redirecting a local address via an alias or forward file and then
22333 passing the message on to another host is not relaying,
22334 .index `percent hack'
22335 but a redirection as a result of the `percent hack' is.
22337 Two kinds of relaying exist, which are termed `incoming' and `outgoing'. A host
22338 which is acting as a gateway or an MX backup is concerned with incoming
22339 relaying from arbitrary hosts to a specific set of domains. On the other hand,
22340 a host which is acting as a smart host for a number of clients is concerned
22341 with outgoing relaying from those clients to the Internet at large. Often the
22342 same host is fulfilling both functions, as illustrated in the diagram below,
22343 but in principle these two kinds of relaying are entirely independent. What is
22344 not wanted is the transmission of mail from arbitrary remote hosts through your
22345 system to arbitrary domains.
22347 .figure "Controlled relaying" rm
22350 centre ~~sys.linelength;
22356 A: box "Arbitrary" "remote hosts";
22358 D: box "Arbitrary" "domains";
22359 iline down 50 from bottom of C;
22360 H: box width 180 "Local host";
22363 SH: box "Specific" "hosts";
22364 SD: box join right to E "Specific" "domains";
22365 arcarrow clockwise from top of SH to bottom of D plus (-10,-4)
22366 via right of H plus (-20,0);
22367 arcarrow clockwise from bottom of A to top of SD plus (10,4)
22368 via left of H plus (20,0);
22370 ibox join left to right of H "$it{Outgoing}";
22372 ibox join right to left of H "$it{Incoming}";
22374 L: line dashed from right of A to top of H plus (-15,0);
22375 arc dashed to top of H plus (15,0);
22376 arrow dashed to left of D plus (-2,0);
22378 arrow dashed back up 72 right 32 from middle of L plus (8,0);
22379 text at end plus (0, 4) "$it{Not wanted}";
22384 -------------- -----------
22385 | Arbitrary | |Arbitrary|
22386 |remote hosts| | domains |
22387 -------------- -----------
22390 c ---v----------------^--- t
22393 i ---v----------------^--- i
22400 [(IMG SRC="relaying.gif" alt="Controlled relaying")][(br)]
22403 You can implement relay control by means of suitable statements in the ACL that
22404 runs for each \\RCPT\\ command. For convenience, it is often easiest to use
22405 Exim's named list facility to define the domains and hosts involved. For
22406 example, suppose you want to do the following:
22408 Deliver a number of domains to mailboxes on the local host (or process them
22409 locally in some other way). Let's say these are \*my.dom1.example*\ and
22410 \*my.dom2.example*\.
22412 Relay mail for a number of other domains for which you are the secondary MX.
22413 These might be \*friend1.example*\ and \*friend2.example*\.
22415 Relay mail from the hosts on your local LAN, to whatever domains are involved.
22416 Suppose your LAN is 192.168.45.0/24.
22418 In the main part of the configuration, you put the following definitions:
22420 domainlist local_domains = my.dom1.example : my.dom2.example
22421 domainlist relay_domains = friend1.example : friend2.example
22422 hostlist relay_hosts = 192.168.45.0/24
22424 Now you can use these definitions in the ACL that is run for every \\RCPT\\
22428 accept domains = +local_domains : +relay_domains
22429 accept hosts = +relay_hosts
22431 The first statement accepts any \\RCPT\\ command that contains an address in
22432 the local or relay domains. For any other domain, control passes to the second
22433 statement, which accepts the command only if it comes from one of the relay
22434 hosts. In practice, you will probably want to make your ACL more sophisticated
22435 than this, for example, by including sender and recipient verification. The
22436 default configuration includes a more comprehensive example, which is described
22437 in chapter ~~CHAPdefconfil.
22440 .section Checking a relay configuration
22441 .rset SECTcheralcon "~~chapter.~~section"
22442 .index relaying||checking control of
22443 You can check the relay characteristics of your configuration in the same way
22444 that you can test any ACL behaviour for an incoming SMTP connection, by using
22445 the \-bh-\ option to run a fake SMTP session with which you interact.
22447 For specifically testing for unwanted relaying, the host
22448 \*relay-test.mail-abuse.org*\ provides a useful service. If you telnet to this
22449 host from the host on which Exim is running, using the normal telnet port, you
22450 will see a normal telnet connection message and then quite a long delay. Be
22451 patient. The remote host is making an SMTP connection back to your host, and
22452 trying a number of common probes to test for open relay vulnerability. The
22453 results of the tests will eventually appear on your terminal.
22462 . ============================================================================
22463 .chapter Adding a local scan function to Exim
22464 .set runningfoot "local scan function"
22465 .rset CHAPlocalscan "~~chapter"
22466 .index \*local@_scan()*\ function||description of
22467 .index customizing||input scan using C function
22468 .index policy control||by local scan function
22470 In these days of email worms, viruses, and ever-increasing spam, some sites
22471 want to apply a lot of checking to messages before accepting them. You can do a
22472 certain amount through string expansions and the \condition\ condition in the
22473 ACL that runs after the SMTP \\DATA\\ command or the ACL for non-SMTP messages
22474 (see chapter ~~CHAPACL), but this has its limitations.
22477 An increasingly popular way of doing additional checking is to make use of the
22478 Exiscan patch for Exim, which adds ACL conditions that perform body scans of
22479 various kinds. This is available from
22481 [(A HREF="http://duncanthrax.net/exiscan-acl/")]
22482 /?http://duncanthrax.net/exiscan-acl/?\.
22485 \?http:@/@/duncanthrax.net/exiscan-acl/?\.
22488 To allow for even more general checking that can be customized to a site's own
22489 requirements, there is the possibility of linking Exim with a private message
22490 scanning function, written in C. If you want to run code that is written in
22491 something other than C, you can of course use a little C stub to call it.
22493 The local scan function is run once for every incoming message, at the point
22494 when Exim is just about to accept the message.
22495 It can therefore be used to control non-SMTP messages from local processes as
22496 well as messages arriving via SMTP.
22498 Exim applies a timeout to calls of the local scan function, and there is an
22499 option called \local@_scan@_timeout\ for setting it. The default is 5 minutes.
22500 Zero means `no timeout'.
22501 Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS
22502 before calling the local scan function, so that the most common types of crash
22503 are caught. If the timeout is exceeded or one of those signals is caught, the
22504 incoming message is rejected with a temporary error if it is an SMTP message.
22505 For a non-SMTP message, the message is dropped and Exim ends with a non-zero
22506 code. The incident is logged on the main and reject logs.
22509 .section Building Exim to use a local scan function
22510 .index \*local@_scan()*\ function||building Exim to use
22511 To make use of the local scan function feature, you must tell Exim where your
22512 function is before building Exim, by setting \\LOCAL@_SCAN@_SOURCE\\ in your
22513 \(Local/Makefile)\. A recommended place to put it is in the \(Local)\
22514 directory, so you might set
22516 LOCAL_SCAN_SOURCE=Local/local_scan.c
22518 for example. The function must be called \*local@_scan()*\. It is called by
22519 Exim after it has received a message, when the success return code is about to
22520 be sent. This is after all the ACLs have been run. The return code from your
22521 function controls whether the message is actually accepted or not. There is a
22522 commented template function (that just accepts the message) in the file
22523 \(src/local@_scan.c)\.
22525 If you want to make use of Exim's run time configuration file to set options
22526 for your \*local@_scan()*\ function, you must also set
22528 LOCAL_SCAN_HAS_OPTIONS=yes
22530 in \(Local/Makefile)\ (see section ~~SECTconoptloc below).
22534 .section API for local@_scan()
22535 .rset SECTapiforloc "~~chapter.~~section"
22536 .index \*local@_scan()*\ function||API description
22537 You must include this line near the start of your code:
22539 #include "local_scan.h"
22541 This header file defines a number of variables and other values, and the
22542 prototype for the function itself. Exim is coded to use unsigned char values
22543 almost exclusively, and one of the things this header defines is a shorthand
22544 for \"unsigned char"\ called \"uschar"\.
22545 It also contains the following macro definitions, to simplify casting character
22546 strings and pointers to character strings:
22548 #define CS (char *)
22549 #define CCS (const char *)
22550 #define CSS (char **)
22551 #define US (unsigned char *)
22552 #define CUS (const unsigned char *)
22553 #define USS (unsigned char **)
22556 The function prototype for \*local@_scan()*\ is:
22558 extern int local_scan(int fd, uschar **return_text);
22560 The arguments are as follows:
22562 \fd\ is a file descriptor for the file that contains the body of the message
22564 The file is open for reading and writing, but updating it is not recommended.
22565 \**Warning**\: You must \*not*\ close this file descriptor.
22567 The descriptor is positioned at character 19 of the file, which is the first
22568 character of the body itself, because the first 19 characters are the message
22569 id followed by \"-D"\ and a newline. If you rewind the file, you should use the
22570 macro \\SPOOL@_DATA@_START@_OFFSET\\ to reset to the start of the data, just in
22571 case this changes in some future version.
22574 \return@_text\ is an address which you can use to return a pointer to a text
22575 string at the end of the function. The value it points to on entry is NULL.
22577 The function must return an \int\ value which is one of the following macros:
22579 \"LOCAL@_SCAN@_ACCEPT"\
22581 The message is accepted. If you pass back a string of text, it is saved with
22582 the message, and made available in the variable \$local@_scan@_data$\. No
22583 newlines are permitted (if there are any, they are turned into spaces) and the
22584 maximum length of text is 1000 characters.
22586 \"LOCAL@_SCAN@_ACCEPT@_FREEZE"\
22588 This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is
22589 queued without immediate delivery, and is frozen.
22591 \"LOCAL@_SCAN@_ACCEPT@_QUEUE"\
22593 This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is
22594 queued without immediate delivery.
22596 \"LOCAL@_SCAN@_REJECT"\
22598 The message is rejected; the returned text is used as an error message which is
22599 passed back to the sender and which is also logged. Newlines are permitted --
22600 they cause a multiline response for SMTP rejections, but are converted to
22601 \"@\n"\ in log lines.
22602 If no message is given, `Administrative prohibition' is used.
22604 \"LOCAL@_SCAN@_TEMPREJECT"\
22606 The message is temporarily rejected; the returned text is used as an error
22607 message as for \\LOCAL@_SCAN@_REJECT\\. If no message is given, `Temporary
22608 local problem' is used.
22610 \"LOCAL@_SCAN@_REJECT@_NOLOGHDR"\
22612 This behaves as \\LOCAL@_SCAN@_REJECT\\, except that the header of the rejected
22613 message is not written to the reject log. It has the effect of unsetting the
22614 \rejected@_header\ log selector for just this rejection. If \rejected@_header\
22615 is already unset (see the discussion of the \log@_selection\ option in section
22616 ~~SECTlogselector), this code is the same as \\LOCAL@_SCAN@_REJECT\\.
22619 \"LOCAL@_SCAN@_TEMPREJECT@_NOLOGHDR"\
22621 This code is a variation of \\LOCAL@_SCAN@_TEMPREJECT\\ in the same way that
22622 \\LOCAL__SCAN__REJECT__NOLOGHDR\\ is a variation of \\LOCAL@_SCAN@_REJECT\\.
22625 If the message is not being received by interactive SMTP, rejections are
22626 reported by writing to \stderr\ or by sending an email, as configured by the
22627 \-oe-\ command line options.
22630 .section Configuration options for local@_scan()
22631 .rset SECTconoptloc "~~chapter.~~section"
22632 .index \*local@_scan()*\ function||configuration options
22633 It is possible to have option settings in the main configuration file
22634 that set values in static variables in the \*local@_scan()*\ module. If you
22635 want to do this, you must have the line
22637 LOCAL_SCAN_HAS_OPTIONS=yes
22639 in your \(Local/Makefile)\ when you build Exim. (This line is in
22640 \(OS/Makefile-Default)\, commented out). Then, in the \*local@_scan()*\ source
22641 file, you must define static variables to hold the option values, and a table to
22644 The table must be a vector called \local@_scan@_options\, of type
22645 \"optionlist"\. Each entry is a triplet, consisting of a name, an option type,
22646 and a pointer to the variable that holds the value. The entries must appear in
22647 alphabetical order. Following \local@_scan@_options\ you must also define a
22648 variable called \local@_scan@_options@_count\ that contains the number of
22649 entries in the table. Here is a short example, showing two kinds of option:
22651 static int my_integer_option = 42;
22652 static uschar *my_string_option = US"a default string";
22654 optionlist local_scan_options[] = {
22655 { "my_integer", opt_int, &my_integer_option },
22656 { "my_string", opt_stringptr, &my_string_option }
22658 int local_scan_options_count =
22659 sizeof(local_scan_options)/sizeof(optionlist);
22661 The values of the variables can now be changed from Exim's runtime
22662 configuration file by including a local scan section as in this example:
22666 my_string = some string of text...
22668 The available types of option data are as follows:
22673 This specifies a boolean (true/false) option. The address should point to
22674 a variable of type \"BOOL"\, which will be set to \\TRUE\\ or \\FALSE\\, which
22675 are macros that are defined as `1' and `0', respectively. If you want to detect
22676 whether such a variable has been set at all, you can initialize it to
22677 \\TRUE@_UNSET\\. (BOOL variables are integers underneath, so can hold more than
22681 This specifies a fixed point number, such as is used for load averages.
22682 The address should point to a variable of type \"int"\. The value is stored
22683 multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414.
22686 This specifies an integer; the address should point to a variable of type
22687 \"int"\. The value may be specified in any of the integer formats accepted by
22691 This is the same as \opt@_int\, except that when such a value is output in a
22692 \-bP-\ listing, if it is an exact number of kilobytes or megabytes, it is
22693 printed with the suffix K or M.
22695 .item "opt@_octint"
22696 This also specifies an integer, but the value is always interpeted as an
22697 octal integer, whether or not it starts with the digit zero, and it is
22698 always output in octal.
22700 .item "opt@_stringptr"
22701 This specifies a string value; the address must be a pointer to a
22702 variable that points to a string (for example, of type \"uschar $*$"\).
22705 This specifies a time interval value. The address must point to a variable of
22706 type \"int"\. The value that is placed there is a number of seconds.
22710 If the \-bP-\ command line option is followed by \"local@_scan"\, Exim prints
22711 out the values of all the \*local@_scan()*\ options.
22714 .section Available Exim variables
22715 .index \*local@_scan()*\ function||available Exim variables
22716 The header \(local@_scan.h)\ gives you access to a number of C variables.
22717 These are the only ones that are guaranteed to be maintained from release to
22718 release. Note, however, that you can obtain the value of any Exim variable by
22719 calling \*expand@_string()*\. The exported variables are as follows:
22723 .item "unsigned int debug@_selector"
22724 This variable is set to zero when no debugging is taking place. Otherwise, it
22725 is a bitmap of debugging selectors. Two bits are identified for use in
22726 \*local@_scan()*\; they are defined as macros:
22728 The \"D@_v"\ bit is set when \-v-\ was present on the command line. This is a
22729 testing option that is not privileged -- any caller may set it. All the
22730 other selector bits can be set only by admin users.
22732 The \"D@_local@_scan"\ bit is provided for use by \*local@_scan()*\; it is set
22733 by the \"+local@_scan"\ debug selector. It is not included in the default set
22736 Thus, to write to the debugging output only when \"+local@_scan"\ has been
22737 selected, you should use code like this:
22739 if ((debug_selector & D_local_scan) != 0)
22740 debug_printf("xxx", ...);
22743 .item "uschar *expand@_string@_message"
22744 After a failing call to \*expand@_string()*\ (returned value NULL), the
22745 variable \expand__string__message\ contains the error message, zero-terminated.
22747 .item "header@_line *header@_list"
22748 A pointer to a chain of header lines. The \header@_line\ structure is discussed
22751 .item "header@_line *header@_last"
22752 A pointer to the last of the header lines.
22754 .item "uschar *headers@_charset"
22755 The value of the \headers@_charset\ configuration option.
22757 .item "BOOL host@_checking"
22758 This variable is TRUE during a host checking session that is initiated by the
22759 \-bh-\ command line option.
22761 .item "uschar *interface@_address"
22762 The IP address of the interface that received the message, as a string. This
22763 is NULL for locally submitted messages.
22765 .item "int interface@_port"
22766 The port on which this message was received.
22768 .item "uschar *message@_id"
22769 This variable contains the message id for the incoming message as a
22770 zero-terminated string.
22773 .item "uschar *received@_protocol"
22774 The name of the protocol by which the message was received.
22776 .item "int recipients@_count"
22777 The number of accepted recipients.
22779 .item "recipient@_item *recipients@_list"
22780 .index recipient||adding in local scan
22781 .index recipient||removing in local scan
22782 The list of accepted recipients, held in a vector of length
22783 \recipients@_count\. The \recipient@_item\ structure is discussed below. You
22784 can add additional recipients by calling \*receive@_add@_recipient()*\ (see
22785 below). You can delete recipients by removing them from the vector and adusting
22786 the value in \recipients@_count\. In particular, by setting \recipients@_count\
22787 to zero you remove all recipients. If you then return the value
22788 \"LOCAL@_SCAN@_ACCEPT"\, the message is accepted, but immediately blackholed.
22789 To replace the recipients, set \recipients@_count\ to zero and then call
22790 \*receive@_add@_recipient()*\ as often as needed.
22792 .item "uschar *sender@_address"
22793 The envelope sender address. For bounce messages this is the empty string.
22795 .item "uschar *sender@_host@_address"
22796 The IP address of the sending host, as a string. This is NULL for
22797 locally-submitted messages.
22799 .item "uschar *sender@_host@_authenticated"
22800 The name of the authentication mechanism that was used, or NULL if the message
22801 was not received over an authenticated SMTP connection.
22803 .item "uschar *sender@_host@_name"
22804 The name of the sending host, if known.
22806 .item "int sender@_host@_port"
22807 The port on the sending host.
22809 .item "BOOL smtp@_input"
22810 This variable is TRUE for all SMTP input, including BSMTP.
22812 .item "BOOL smtp@_batched@_input"
22813 This variable is TRUE for BSMTP input.
22815 .item "int store@_pool"
22816 The contents of this variable control which pool of memory is used for new
22817 requests. See section ~~SECTmemhanloc for details.
22822 .section Structure of header lines
22823 The \header@_line\ structure contains the members listed below.
22824 You can add additional header lines by calling the \*header@_add()*\ function
22825 (see below). You can cause header lines to be ignored (deleted) by setting
22830 .item "struct header@_line *next"
22831 A pointer to the next header line, or NULL for the last line.
22834 A code identifying certain headers that Exim recognizes. The codes are printing
22835 characters, and are documented in chapter ~~CHAPspool of this manual. Notice in
22836 particular that any header line whose type is $*$ is not transmitted with the
22837 message. This flagging is used for header lines that have been rewritten, or
22838 are to be removed (for example, ::Envelope-sender:: header lines.) Effectively,
22839 $*$ means `deleted'.
22842 The number of characters in the header line, including the terminating and any
22845 .item "uschar *text"
22846 A pointer to the text of the header. It always ends with a newline, followed by
22847 a zero byte. Internal newlines are preserved.
22853 .section Structure of recipient items
22854 The \recipient@_item\ structure contains these members:
22858 .item "uschar *address"
22859 This is a pointer to the recipient address as it was received.
22862 This is used in later Exim processing when top level addresses are created
22863 by the \one@_time\ option. It is not relevant at the time \*local@_scan()*\ is
22865 must always contain -1 at this stage.
22867 .item "uschar *errors@_to"
22868 If this value is not NULL, bounce messages caused by failing to deliver to the
22869 recipient are sent to the address it contains. In other words, it overrides the
22870 envelope sender for this one recipient. (Compare the \errors@_to\ generic
22872 If a \*local@_scan()*\ function sets an \errors@_to\ field to an unqualified
22873 address, Exim qualifies it using the domain from \qualify@_recipient\.
22874 When \*local@_scan()*\ is called, the \errors@_to\ field is NULL for all
22879 .section Available Exim functions
22880 .index \*local@_scan()*\ function||available Exim functions
22881 The header \(local@_scan.h)\ gives you access to a number of Exim functions.
22882 These are the only ones that are guaranteed to be maintained from release to
22887 .item "pid@_t child@_open(uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, BOOL make@_leader)"
22888 This function creates a child process that runs the command specified by
22889 \argv\. The environment for the process is specified by \envp\, which can be
22890 NULL if no environment variables are to be passed. A new umask is supplied for
22891 the process in \newumask\.
22893 Pipes to the standard input and output of the new process are set up
22894 and returned to the caller via the \infdptr\ and \outfdptr\ arguments. The
22895 standard error is cloned to the standard output. If there are any file
22896 descriptors `in the way' in the new process, they are closed. If the final
22897 argument is TRUE, the new process is made into a process group leader.
22899 The function returns the pid of the new process, or -1 if things go wrong.
22902 .item "int child@_close(pid@_t pid, int timeout)"
22903 This function waits for a child process to terminate, or for a timeout (in
22904 seconds) to expire. A timeout value of zero means wait as long as it takes. The
22905 return value is as follows:
22909 The process terminated by a normal exit and the value is the process ending
22914 The process was terminated by a signal and the value is the negation of the
22919 The process timed out.
22923 The was some other error in wait(); \errno\ is still set.
22927 .item "pid@_t child@_open@_exim(int *fd)"
22928 This function provide you with a means of submitting a new message to
22929 Exim. (Of course, you can also call \(/usr/sbin/sendmail)\ yourself if you
22930 want, but this packages it all up for you.) The function creates a pipe,
22931 forks a subprocess that is running
22933 exim -t -oem -oi -f <>
22935 and returns to you (via the \"int *"\ argument) a file descriptor for the pipe
22936 that is connected to the standard input. The yield of the function is the PID
22937 of the subprocess. You can then write a message to the file descriptor, with
22938 recipients in ::To::, ::Cc::, and/or ::Bcc:: header lines.
22940 When you have finished, call \*child@_close()*\ to wait for the process to
22941 finish and to collect its ending status. A timeout value of zero is usually
22942 fine in this circumstance. Unless you have made a mistake with the recipient
22943 addresses, you should get a return code of zero.
22945 .item "void debug@_printf(char *, ...)"
22946 This is Exim's debugging function, with arguments as for \*(printf()*\. The
22947 output is written to the standard error stream. If no debugging is selected,
22948 calls to \*debug@_printf()*\ have no effect. Normally, you should make calls
22949 conditional on the \"local@_scan"\ debug selector by coding like this:
22951 if ((debug_selector & D_local_scan) != 0)
22952 debug_printf("xxx", ...);
22955 .item "uschar *expand@_string(uschar *string)"
22956 This is an interface to Exim's string expansion code. The return value is the
22957 expanded string, or NULL if there was an expansion failure.
22958 The C variable \expand@_string@_message\ contains an error message after an
22959 expansion failure. If expansion does not change the string, the return value is
22960 the pointer to the input string. Otherwise, the return value points to a new
22961 block of memory that was obtained by a call to \*store@_get()*\. See section
22962 ~~SECTmemhanloc below for a discussion of memory handling.
22964 .item "void header@_add(int type, char *format, ...)"
22965 This function allows you to add additional header lines. The first argument is
22966 the type, and should normally be a space character. The second argument is a
22967 format string and any number of substitution arguments as for \*sprintf()*\.
22968 You may include internal newlines if you want, and you must ensure that the
22969 string ends with a newline.
22971 .item "uschar *lss@_b64encode(uschar *cleartext, int length)"
22972 .index base64 encoding||functions for \*local@_scan()*\ use
22973 This function base64-encodes a string, which is passed by address and length.
22974 The text may contain bytes of any value, including zero. The result is passed
22975 back in dynamic memory that is obtained by calling \*store@_get()*\. It is
22978 .item "int lss@_b64decode(uschar *codetext, uschar **cleartext)"
22979 This function decodes a base64-encoded string. Its arguments are a
22980 zero-terminated base64-encoded string and the address of a variable that is set
22981 to point to the result, which is in dynamic memory. The length of the
22982 decoded string is the yield of the function. If the input is invalid base64
22983 data, the yield is -1. A zero byte is added to the end of the output string to
22984 make it easy to interpret as a C string (assuming it contains no zeros of its
22985 own). The added zero byte is not included in the returned count.
22987 .item "int lss@_match@_domain(uschar *domain, uschar *list)"
22988 This function checks for a match in a domain list. Domains are always
22989 matched caselessly. The return value is one of the following:
22991 OK $rm{match succeeded}
22992 FAIL $rm{match failed}
22993 DEFER $rm{match deferred}
22995 DEFER is usually caused by some kind of lookup defer, such as the
22996 inability to contact a database.
22998 .item "int lss@_match@_local@_part(uschar *localpart, uschar *list, BOOL caseless)"
22999 This function checks for a match in a local part list. The third argument
23000 controls case-sensitivity. The return values are as for
23001 \*lss@_match@_domain()*\.
23003 .item "int lss@_match@_address(uschar *address, uschar *list, BOOL caseless)"
23004 This function checks for a match in an address list. The third argument
23005 controls the case-sensitivity of the local part match. The domain is always
23006 matched caselessly. The return values are as for \*lss@_match@_domain()*\.
23008 .item "int lss@_match@_host(uschar *host@_name, uschar *host@_address, uschar *list)"
23009 This function checks for a match in a host list. The most common usage is
23012 lss_match_host(sender_host_name, sender_host_address, ...)
23014 An empty address field matches an empty item in the host list. If the
23015 host name is NULL, the name corresponding to \$sender@_host@_address$\ is
23016 automatically looked up if a host name is required to match an item in the
23017 list. The return values are as for \*lss@_match@_domain()*\, but in addition,
23018 \*lss@_match@_host()*\ returns ERROR in the case when it had to look up a host
23019 name, but the lookup failed.
23021 .item "void log@_write(unsigned int selector, int which, char *format, ...)"
23022 This function writes to Exim's log files. The first argument should be zero (it
23023 is concerned with \log@_selector\). The second argument can be \"LOG@_MAIN"\ or
23025 \"LOG@_PANIC"\ or the inclusive `or' of any combination of them. It specifies
23026 to which log or logs the message is written.
23027 The remaining arguments are a format and relevant insertion arguments. The
23028 string should not contain any newlines, not even at the end.
23031 .item "void receive@_add@_recipient(uschar *address, int pno)"
23032 This function adds an additional recipient to the message. The first argument
23033 is the recipient address. If it is unqualified (has no domain), it is qualified
23034 with the \qualify@_recipient\ domain. The second argument must always be -1.
23036 This function does not allow you to specify a private \errors@_to\ address (as
23037 described with the structure of \recipient@_item\ above), because it pre-dates
23038 the addition of that field to the structure. However, it is easy to add such a
23039 value afterwards. For example:
23041 receive_add_recipient(US"monitor@mydom.example", -1);
23042 recipients_list[recipients_count-1].errors_to =
23043 US"postmaster@mydom.example";
23046 .item "uschar *rfc2047@_decode(uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr, uschar **error)"
23047 This function decodes strings that are encoded according to RFC 2047. Typically
23048 these are the contents of header lines. First, each encoded `word' is decoded
23049 from the Q or B encoding into a byte-string. Then, if provided with the name of
23050 a charset encoding, and if the \*iconv()*\ function is available, an attempt is
23051 made to translate the result to the named character set. If this fails, the
23052 binary string is returned with an error message.
23054 The first argument is the string to be decoded. If \lencheck\ is TRUE, the
23055 maximum MIME word length is enforced. The third argument is the target
23056 encoding, or NULL if no translation is wanted.
23058 .index binary zero||in RFC 2047 decoding
23059 If a binary zero is encountered in the decoded string, it is replaced by the
23060 contents of the \zeroval\ argument. For use with Exim headers, the value must
23061 not be 0 because header lines are handled as zero-terminated strings.
23063 The function returns the result of processing the string, zero-terminated; if
23064 \lenptr\ is not NULL, the length of the result is set in the variable to which
23065 it points. When \zeroval\ is 0, \lenptr\ should not be NULL.
23067 If an error is encountered, the function returns NULL and uses the \error\
23068 argument to return an error message. The variable pointed to by \error\ is set
23069 to NULL if there is no error; it may be set non-NULL even when the function
23070 returns a non-NULL value if decoding was successful, but there was a problem
23074 .item "int smtp@_fflush(void)"
23075 This function is used in conjunction with \*smtp@_printf()*\, as described
23078 .item "void smtp@_printf(char *, ...)"
23079 The arguments of this function are like \*printf()*\; it writes to the SMTP
23080 output stream. You should use this function only when there is an SMTP output
23081 stream, that is, when the incoming message is being received via interactive
23082 SMTP. This is the case when \smtp@_input\ is TRUE and \smtp@_batched@_input\ is
23083 FALSE. If you want to test for an incoming message from another host (as
23084 opposed to a local process that used the \-bs-\ command line option), you can
23085 test the value of \sender@_host@_address\, which is non-NULL when a remote host
23088 If an SMTP TLS connection is established, \*smtp@_printf()*\ uses the TLS
23089 output function, so it can be used for all forms of SMTP connection.
23091 Strings that are written by \*smtp@_printf()*\ from within \*local@_scan()*\
23092 must start with an appropriate response code: 550 if you are going to return
23093 \\LOCAL@_SCAN@_REJECT\\, 451 if you are going to return
23094 \\LOCAL@_SCAN@_TEMPREJECT\\, and 250 otherwise. Because you are writing the
23095 initial lines of a multi-line response, the code must be followed by a hyphen
23096 to indicate that the line is not the final response line. You must also ensure
23097 that the lines you write terminate with CRLF. For example:
23099 smtp_printf("550-this is some extra info\r\n");
23100 return LOCAL_SCAN_REJECT;
23102 Note that you can also create multi-line responses by including newlines in
23103 the data returned via the \return@_text\ argument. The added value of using
23104 \*smtp@_printf()*\ is that, for instance, you could introduce delays between
23105 multiple output lines.
23107 The \*smtp@_printf()*\ function does not return any error indication, because it
23108 does not automatically flush pending output, and therefore does not test
23109 the state of the stream. (In the main code of Exim, flushing and error
23110 detection is done when Exim is ready for the next SMTP input command.) If
23111 you want to flush the output and check for an error (for example, the
23112 dropping of a TCP/IP connection), you can call \*smtp@_fflush()*\, which has no
23113 arguments. It flushes the output stream, and returns a non-zero value if there
23116 .item "void *store@_get(int)"
23117 This function accesses Exim's internal store (memory) manager. It gets a new
23118 chunk of memory whose size is given by the argument. Exim bombs out if it ever
23119 runs out of memory. See the next section for a discussion of memory handling.
23121 .item "void *store@_get@_perm(int)"
23122 This function is like \*store@_get()*\, but it always gets memory from the
23123 permanent pool. See the next section for a discussion of memory handling.
23125 .item "uschar *string@_copy(uschar *string)"
23126 .item "uschar *string@_copyn(uschar *string, int length)" 0
23127 .item "uschar *string@_sprintf(char *format, ...)" 0
23128 These three functions create strings using Exim's dynamic memory facilities.
23129 The first makes a copy of an entire string. The second copies up to a maximum
23130 number of characters, indicated by the second argument. The third uses a format
23131 and insertion arguments to create a new string. In each case, the result is a
23132 pointer to a new string
23133 in the current memory pool. See the next section for more discussion.
23139 .section More about Exim's memory handling
23140 .rset SECTmemhanloc "~~chapter.~~section"
23141 .index \*local@_scan()*\ function||memory handling
23142 No function is provided for freeing memory, because that is never needed.
23143 The dynamic memory that Exim uses when receiving a message is automatically
23144 recycled if another message is received by the same process (this applies only
23145 to incoming SMTP connections -- other input methods can supply only one message
23146 at a time). After receiving the last message, a reception process terminates.
23148 Because it is recycled, the normal dynamic memory cannot be used for holding
23149 data that must be preserved over a number of incoming messages on the same SMTP
23150 connection. However, Exim in fact uses two pools of dynamic memory; the second
23151 one is not recycled, and can be used for this purpose.
23153 If you want to allocate memory that remains available for subsequent messages
23154 in the same SMTP connection, you should set
23156 store_pool = POOL_PERM
23158 before calling the function that does the allocation. There is no need to
23159 restore the value if you do not need to; however, if you do want to revert to
23160 the normal pool, you can either restore the previous value of \store@_pool\ or
23161 set it explicitly to \\POOL@_MAIN\\.
23163 The pool setting applies to all functions that get dynamic memory, including
23164 \*expand@_string()*\, \*store@_get()*\, and the \*string@_xxx()*\ functions.
23165 There is also a convenience function called \*store@_get@_perm()*\ that gets a
23166 block of memory from the permanent pool while preserving the value of
23177 . ============================================================================
23178 .chapter System-wide message filtering
23179 .set runningfoot "system filtering"
23180 .rset CHAPsystemfilter "~~chapter"
23181 .index filter||system filter
23182 .index filtering all mail
23183 .index system filter
23184 The previous chapters (on ACLs and the local scan function) describe checks
23185 that can be applied to messages before they are accepted by a host. There is
23186 also a mechanism for checking messages once they have been received, but before
23187 they are delivered. This is called the $it{system filter}.
23189 The system filter operates in a similar manner to users' filter files, but it
23190 is run just once per message (however many recipients the message has).
23191 It should not normally be used as a substitute for routing, because \deliver\
23192 commands in a system router provide new envelope recipient addresses.
23193 The system filter must be an Exim filter. It cannot be a Sieve filter.
23195 The system filter is run at the start of a delivery attempt, before any routing
23196 is done. If a message fails to be completely delivered at the first attempt,
23197 the system filter is run again at the start of every retry.
23198 If you want your filter to do something only once per message, you can make use
23199 of the \first@_delivery\ condition in an \if\ command in the filter to prevent
23200 it happening on retries.
23202 \**Warning**\: Because the system filter runs just once, variables that are
23203 specific to individual recipient addresses, such as \$local@_part$\ and
23204 \$domain$\, are not set, and the `personal' condition is not meaningful. If you
23205 want to run a centrally-specified filter for each recipient address
23206 independently, you can do so by setting up a suitable \%redirect%\ router, as
23207 described in section ~~SECTperaddfil below.
23209 .section Specifying a system filter
23210 .index uid (user id)||system filter
23211 .index gid (group id)||system filter
23212 The name of the file that contains the system filter must be specified by
23213 setting \system@_filter\. If you want the filter to run under a uid and gid
23214 other than root, you must also set \system@_filter@_user\ and
23215 \system@_filter@_group\ as appropriate. For example:
23217 system_filter = /etc/mail/exim.filter
23218 system_filter_user = exim
23220 If a system filter generates any deliveries directly to files or pipes (via the
23221 \save\ or \pipe\ commands), transports to handle these deliveries must be
23222 specified by setting \system@_filter@_file@_transport\ and
23223 \system@_filter@_pipe@_transport\, respectively. Similarly,
23224 \system@_filter@_reply@_transport\ must be set to handle any messages generated
23225 by the \reply\ command.
23227 .section Testing a system filter
23228 You can run simple tests of a system filter in the same way as for a user
23229 filter, but you should use \-bF-\ rather than \-bf-\, so that features that
23230 are permitted only in system filters are recognized.
23232 .section Contents of a system filter
23233 The language used to specify system filters is the same as for users' filter
23234 files. It is described in the separate end-user document \*Exim's interface to
23235 mail filtering*\. However, there are some additional features that are
23236 available only in system filters; these are described in subsequent sections.
23237 If they are encountered in a user's filter file or when testing with \-bf-\,
23240 .index frozen messages||manual thaw, testing in filter
23241 There are two special conditions which, though available in users' filter
23242 files, are designed for use in system filters. The condition \first@_delivery\
23243 is true only for the first attempt at delivering a message, and
23244 \manually@_thawed\ is true only if the message has been frozen, and
23245 subsequently thawed by an admin user. An explicit forced delivery counts as a
23246 manual thaw, but thawing as a result of the \auto__thaw\ setting does not.
23248 \**Warning**\: If a system filter uses the \first@_delivery\ condition to
23249 specify an `unseen' (non-significant) delivery, and that delivery does not
23250 succeed, it will not be tried again.
23251 If you want Exim to retry an unseen delivery until it succeeds, you should
23252 arrange to set it up every time the filter runs.
23254 When a system filter finishes running, the values of the variables \$n0$\ --
23255 \$n9$\ are copied into \$sn0$\ -- \$sn9$\ and are thereby made available to
23256 users' filter files. Thus a system filter can, for example, set up `scores' to
23257 which users' filter files can refer.
23260 .section Additional variable for system filters
23261 The expansion variable \$recipients$\, containing a list of all the recipients
23262 of the message (separated by commas and white space), is available in system
23263 filters. It is not available in users' filters for privacy reasons.
23266 .section Defer, freeze, and fail commands for system filters
23267 .index freezing messages
23268 .index message||freezing
23269 .index message||forced failure
23270 .index \fail\||in system filter
23271 .index \freeze\ in system filter
23272 .index \defer\ in system filter
23273 There are three extra commands (\defer\, \freeze\ and \fail\) which are always
23274 available in system filters, but are not normally enabled in users' filters.
23275 (See the \allow@_defer\,
23276 \allow@_freeze\ and \allow@_fail\ options for the \%redirect%\ router.) These
23277 commands can optionally be followed by the word \text\ and a string containing
23278 an error message, for example:
23280 fail text "this message looks like spam to me"
23282 The keyword \text\ is optional if the next character is a double quote.
23284 The \defer\ command defers delivery of the original recipients of the message.
23285 The \fail\ command causes all the original recipients to be failed, and a
23286 bounce message to be created. The \freeze\ command suspends all delivery
23287 attempts for the original recipients. In all cases, any new deliveries that are
23288 specified by the filter are attempted as normal after the filter has run.
23290 The \freeze\ command is ignored if the message has been manually unfrozen and
23291 not manually frozen since. This means that automatic freezing by a system
23292 filter can be used as a way of checking out suspicious messages. If a message
23293 is found to be all right, manually unfreezing it allows it to be delivered.
23295 .index log||\fail\ command log line
23296 .index \fail\||log line, reducing
23297 The text given with a fail command is used as part of the bounce message as
23298 well as being written to the log. If the message is quite long, this can fill
23299 up a lot of log space when such failures are common. To reduce the size of the
23300 log message, Exim interprets the text in a special way if it starts with the
23301 two characters \"@<@<"\ and contains \"@>@>"\ later. The text between these two
23302 strings is written to the log, and the rest of the text is used in the bounce
23303 message. For example:
23305 fail "<<filter test 1>>Your message is rejected \
23306 because it contains attachments that we are \
23307 not prepared to receive."
23310 .index loop||caused by \fail\
23311 Take great care with the \fail\ command when basing the decision to fail on the
23312 contents of the message, because the bounce message will of course include the
23313 contents of the original message and will therefore trigger the \fail\ command
23314 again (causing a mail loop) unless steps are taken to prevent this. Testing the
23315 \error@_message\ condition is one way to prevent this. You could use, for
23318 if $message_body contains "this is spam" and not error_message
23319 then fail text "spam is not wanted here" endif
23321 though of course that might let through unwanted bounce messages. The
23322 alternative is clever checking of the body and/or headers to detect bounces
23323 generated by the filter.
23325 The interpretation of a system filter file ceases after a
23327 \freeze\, or \fail\ command is obeyed. However, any deliveries that were set up
23328 earlier in the filter file are honoured, so you can use a sequence such as
23333 to send a specified message when the system filter is freezing (or deferring or
23334 failing) a message. The normal deliveries for the message do not, of course,
23338 .section Adding and removing headers in a system filter
23339 .index header lines||adding in system filter
23340 .index header lines||removing in system filter
23341 .index filter||header lines, adding/removing
23342 Two filter commands that are available only in system filters are:
23344 headers add <<string>>
23345 headers remove <<string>>
23347 The argument for the \headers add\ is a string which is expanded and then added
23348 to the end of the message's headers. It is the responsibility of the filter
23349 maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is
23350 ignored, and if the string is otherwise empty, or if the expansion is forced to
23351 fail, the command has no effect.
23353 If the message is not delivered at the first attempt, header lines that were
23354 added by the system filter are stored with the message, and so are still
23355 present at the next delivery attempt. For that reason, it is usual to make the
23356 \headers add\ command conditional on \first@_delivery\.
23359 You can use `@\n' within the string, followed by white space, to specify
23360 continued header lines. More than one header may be added in one command by
23361 including `@\n' within the string without any following white space. For
23364 headers add "X-header-1: ....\n \
23365 continuation of X-header-1 ...\n\
23368 Note that the header line continuation white space after the first newline must
23369 be placed before the backslash that continues the input string, because white
23370 space after input continuations is ignored.
23372 Header lines that are added by a system filter are visible to users' filter
23373 files and to all routers and transports.
23376 The argument for \headers remove\ is a colon-separated list of header names.
23377 This command applies only to those headers that are stored with the message;
23378 those that are added at delivery time (such as ::Envelope-To:: and
23379 ::Return-Path::) cannot be removed by this means.
23380 If there is more than one header with the same name, they are all removed.
23383 .section Setting an errors address in a system filter
23384 .index envelope sender
23385 In a system filter, if a \deliver\ command is followed by
23387 errors@_to <<some address>>
23389 in order to change the envelope sender (and hence the error reporting) for that
23390 delivery, any address may be specified. (In a user filter, only the current
23391 user's address can be set.) For example, if some mail is being monitored, you
23394 unseen deliver monitor@spying.example errors_to root@local.example
23396 to take a copy which would not be sent back to the normal error reporting
23397 address if its delivery failed.
23400 .section Per-address filtering
23401 .rset SECTperaddfil "~~chapter.~~section"
23402 In contrast to the system filter, which is run just once per message for each
23403 delivery attempt, it is also possible to set up a system-wide filtering
23404 operation that runs once for each recipient address. In this case, variables
23405 such as \$local@_part$\ and \$domain$\ can be used, and indeed, the choice of
23406 filter file could be made dependent on them. This is an example of a router
23407 which implements such a filter:
23416 domains = +local_domains
23417 file = /central/filters/$local_part
23423 The filter is run in a separate process under its own uid. Therefore, either
23424 \check@_local@_user\ must be set (as above), in which case the filter is run as
23425 the local user, or the \user\ option must be used to specify which user to use.
23426 If both are set, \user\ overrides.
23429 Care should be taken to ensure that none of the commands in the filter file
23430 specify a significant delivery if the message is to go on to be delivered to
23431 its intended recipient. The router will not then claim to have dealt with the
23432 address, so it will be passed on to subsequent routers to be delivered in the
23443 . ============================================================================
23444 .chapter Customizing bounce and warning messages
23445 .set runningfoot "customizing messages"
23446 .rset CHAPemsgcust "~~chapter"
23447 When a message fails to be delivered, or remains on the queue for more than a
23448 configured amount of time, Exim sends a message to the original sender, or
23449 to an alternative configured address. The text of these messages is built into
23450 the code of Exim, but it is possible to change it, either by adding a single
23451 string, or by replacing each of the paragraphs by text supplied in a file.
23453 The ::From:: and ::To:: header lines are automatically generated; you can cause
23454 a ::Reply-To:: line to be added by setting the \errors@_reply@_to\ option. Exim
23457 Auto-Submitted: auto-generated
23459 to all warning and bounce messages,
23461 .section Customizing bounce messages
23462 .index customizing||bounce message
23463 .index bounce message||customizing
23464 If \bounce@_message@_text\ is set, its contents are included in the default
23465 message immediately after `This message was created automatically by mail
23466 delivery software.' The string is not expanded. It is not used if
23467 \bounce@_message@_file\ is set.
23469 When \bounce@_message@_file\ is set, it must point to a template file for
23470 constructing error messages. The file consists of a series of text items,
23471 separated by lines consisting of exactly four asterisks. If the file cannot be
23472 opened, default text is used and a message is written to the main and panic
23473 logs. If any text item in the file is empty, default text is used for that
23476 Each item of text that is read from the file is expanded, and there are two
23477 expansion variables which can be of use here: \$bounce@_recipient$\ is set to
23478 the recipient of an error message while it is being created, and
23479 \$return@_size@_limit$\ contains the value of the \return@_size@_limit\ option,
23480 rounded to a whole number.
23482 The items must appear in the file in the following order:
23484 The first item is included in the headers, and should include at least a
23485 ::Subject:: header. Exim does not check the syntax of these headers.
23487 The second item forms the start of the error message. After it, Exim lists the
23488 failing addresses with their error messages.
23490 The third item is used to introduce any text from pipe transports that is to be
23491 returned to the sender. It is omitted if there is no such text.
23493 The fourth item is used to introduce the copy of the message that is returned
23494 as part of the error report.
23496 The fifth item is added after the fourth one if the returned message is
23497 truncated because it is bigger than \return@_size@_limit\.
23499 The sixth item is added after the copy of the original message.
23501 The default state (\bounce@_message@_file\ unset) is equivalent to the
23502 following file, in which the sixth item is empty. The ::Subject:: line has been
23503 split into two here in order to fit it on the page:
23514 Subject: Mail delivery failed
23515 ${if eq{$sender_address}{$bounce_recipient}{: returning message to sender}}
23517 This message was created automatically by mail delivery software.
23519 A message ${if eq{$sender_address}{$bounce_recipient}{that you sent }{sent by
23523 }}could not be delivered to all of its recipients.
23524 The following address(es) failed:
23526 The following text was generated during the delivery attempt(s):
23528 ------ This is a copy of the message, including all the headers. ------
23530 ------ The body of the message is $message_size characters long; only the first
23531 ------ $return_size_limit or so are included here.
23538 .section Customizing warning messages
23539 .rset SECTcustwarn "~~chapter.~~section"
23540 .index customizing||warning message
23541 .index warning of delay||customizing the message
23543 \warn@_message@_file\
23544 can be pointed at a template file for use when
23545 warnings about message delays are created. In this case there are only three
23548 The first item is included in the headers, and should include at least a
23549 ::Subject:: header. Exim does not check the syntax of these headers.
23551 The second item forms the start of the warning message. After it, Exim lists
23552 the delayed addresses.
23554 The third item then ends the message.
23556 The default state is equivalent to the following file, except that the line
23557 starting `A message' has been split here, in order to fit it on the page:
23569 Subject: Warning: message $message_id delayed $warn_message_delay
23571 This message was created automatically by mail delivery software.
23573 A message ${if eq{$sender_address}{$warn_message_recipients}
23574 {that you sent }{sent by
23578 }}has not been delivered to all of its recipients after
23579 more than $warn_message_delay on the queue on $primary_hostname.
23582 The message identifier is: $message_id
23583 The subject of the message is: $h_subject
23584 The date of the message is: $h_date
23586 The following address(es) have not yet been delivered:
23588 No action is required on your part. Delivery attempts will continue for
23589 some time, and this warning may be repeated at intervals if the message
23590 remains undelivered. Eventually the mail delivery software will give up,
23591 and when that happens, the message will be returned to you.
23596 except that in the default state the subject and date lines are omitted if no
23597 appropriate headers exist. During the expansion of this file,
23598 \$warn@_message@_delay$\
23599 is set to the delay time in one of the forms `<<n>> minutes'
23600 or `<<n>> hours', and
23601 \$warn@_message@_recipients$\
23602 contains a list of recipients for the warning message. There may be more than
23603 one if there are multiple addresses with different \errors@_to\ settings on the
23604 routers that handled them.
23612 . ============================================================================
23613 .chapter Some common configuration requirements
23614 .set runningfoot "common configuration requirements"
23615 .rset CHAPcomconreq "~~chapter"
23616 This chapter discusses some configuration requirements that seem to be fairly
23617 common. More examples and discussion can be found in the Exim book.
23620 .section Sending mail to a smart host
23621 .index smart host||example router
23622 If you want to send all mail for non-local domains to a `smart host', you
23623 should replace the default \%dnslookup%\ router with a router which does the
23624 routing explicitly:
23626 send_to_smart_host:
23627 driver = manualroute
23628 route_list = !+local_domains smart.host.name
23629 transport = remote_smtp
23631 You can use the smart host's IP address instead of the name if you wish.
23634 .section Using Exim to handle mailing lists
23635 .rset SECTmailinglists "~~chapter.~~section"
23636 .index mailing lists
23637 Exim can be used to run simple mailing lists, but for large and/or complicated
23638 requirements, the use of additional specialized mailing list software such as
23639 Majordomo or Mailman is recommended.
23641 The \%redirect%\ router can be used to handle mailing lists where each list
23642 is maintained in a separate file, which can therefore be managed by an
23643 independent manager. The \domains\ router option can be used to run these
23644 lists in a separate domain from normal mail. For example:
23648 domains = lists.example
23649 file = /usr/lists/$local_part
23652 errors_to = $local_part-request@lists.example
23655 This router is skipped for domains other than \*lists.example*\. For addresses
23656 in that domain, it looks for a file that matches the local part. If there is no
23657 such file, the router declines, but because \no@_more\ is set, no subsequent
23658 routers are tried, and so the whole delivery fails.
23660 The \forbid@_pipe\ and \forbid@_file\ options prevent a local part from being
23661 expanded into a file name or a pipe delivery, which is usually inappropriate in
23664 .index \errors@_to\
23665 The \errors@_to\ option specifies that any delivery errors caused by addresses
23666 taken from a mailing list are to be sent to the given address rather than the
23667 original sender of the message. However, before acting on this, Exim verifies
23668 the error address, and ignores it if verification fails.
23670 For example, using the configuration above, mail sent to
23671 \*dicts@@lists.example*\ is passed on to those addresses contained in
23672 \(/usr/lists/dicts)\, with error reports directed to
23673 \*dicts-request@@lists.example*\, provided that this address can be verified.
23674 There could be a file called \(/usr/lists/dicts-request)\ containing
23675 the address(es) of this particular list's manager(s), but other approaches,
23676 such as setting up an earlier router (possibly using the \local@_part@_prefix\
23677 or \local@_part@_suffix\ options) to handle addresses of the form \owner-xxx\
23678 or \xxx-request\, are also possible.
23681 .section Syntax errors in mailing lists
23682 .index mailing lists||syntax errors in
23683 If an entry in redirection data contains a syntax error, Exim normally defers
23684 delivery of the original address. That means that a syntax error in a mailing
23685 list holds up all deliveries to the list. This may not be appropriate when a
23686 list is being maintained automatically from data supplied by users, and the
23687 addresses are not rigorously checked.
23689 If the \skip@_syntax@_errors\ option is set, the \%redirect%\ router just skips
23690 entries that fail to parse, noting the incident in the log. If in addition
23691 \syntax@_errors@_to\ is set to a verifiable address, a message is sent to it
23692 whenever a broken address is skipped. It is usually appropriate to set
23693 \syntax@_errors@_to\ to the same address as \errors@_to\.
23696 .section Re-expansion of mailing lists
23697 .index mailing lists||re-expansion of
23698 Exim remembers every individual address to which a message has been delivered,
23699 in order to avoid duplication, but it normally stores only the original
23700 recipient addresses with a message. If all the deliveries to a mailing list
23701 cannot be done at the first attempt, the mailing list is re-expanded when the
23702 delivery is next tried. This means that alterations to the list are taken into
23703 account at each delivery attempt, so addresses that have been added to
23704 the list since the message arrived will therefore receive a copy of the
23705 message, even though it pre-dates their subscription.
23707 If this behaviour is felt to be undesirable, the \one@_time\ option can be set
23708 on the \%redirect%\ router. If this is done, any addresses generated by the
23709 router that fail to deliver at the first attempt are added to the message as
23710 `top level' addresses, and the parent address that generated them is marked
23711 `delivered'. Thus, expansion of the mailing list does not happen again at the
23712 subsequent delivery attempts. The disadvantage of this is that if any of the
23713 failing addresses are incorrect, correcting them in the file has no effect on
23714 pre-existing messages.
23716 The original top-level address is remembered with each of the generated
23717 addresses, and is output in any log messages. However, any intermediate parent
23718 addresses are not recorded. This makes a difference to the log only if the
23719 \all@_parents\ selector is set, but for mailing lists there is normally only
23720 one level of expansion anyway.
23723 .section Closed mailing lists
23724 .index mailing lists||closed
23725 The examples so far have assumed open mailing lists, to which anybody may
23726 send mail. It is also possible to set up closed lists, where mail is accepted
23727 from specified senders only. This is done by making use of the generic
23728 \senders\ option to restrict the router that handles the list.
23730 The following example uses the same file as a list of recipients and as a list
23731 of permitted senders. It requires three routers:
23735 domains = lists.example
23736 local_part_suffix = -request
23737 file = /usr/lists/$local_part$local_part_suffix
23742 domains = lists.example
23743 senders = ${if exists {/usr/lists/$local_part}\
23744 {lsearch;/usr/lists/$local_part}{*}}
23745 file = /usr/lists/$local_part
23748 errors_to = $local_part-request@lists.example
23753 domains = lists.example
23755 data = :fail: $local_part@lists.example is a closed mailing list
23757 All three routers have the same \domains\ setting, so for any other domains,
23758 they are all skipped. The first router runs only if the local part ends in
23759 \@-request\. It handles messages to the list manager(s) by means of an open
23762 The second router runs only if the \senders\ precondition is satisfied. It
23763 checks for the existence of a list that corresponds to the local part, and then
23764 checks that the sender is on the list by means of a linear search. It is
23765 necessary to check for the existence of the file before trying to search it,
23766 because otherwise Exim thinks there is a configuration error. If the file does
23767 not exist, the expansion of \senders\ is $*$, which matches all senders. This
23768 means that the router runs, but because there is no list, declines, and
23769 \no@_more\ ensures that no further routers are run. The address fails with an
23770 `unrouteable address' error.
23772 The third router runs only if the second router is skipped, which happens when
23773 a mailing list exists, but the sender is not on it. This router forcibly fails
23774 the address, giving a suitable error message.
23778 .section Virtual domains
23779 .rset SECTvirtualdomains "~~chapter.~~section"
23780 .index virtual domains
23781 .index domain||virtual
23782 The phrase \*virtual domain*\ is unfortunately used with two rather different
23785 A domain for which there are no real mailboxes; all valid local parts are
23786 aliases for other email addresses. Common examples are organizational
23787 top-level domains and `vanity' domains.
23789 One of a number of independent domains that are all handled by the same host,
23790 with mailboxes on that host, but where the mailbox owners do not necessarily
23791 have login accounts on that host.
23793 The first usage is probably more common, and does seem more `virtual' than the
23794 second. This kind of domain can be handled in Exim with a straightforward
23795 aliasing router. One approach is to create a separate alias file for each
23796 virtual domain. Exim can test for the existence of the alias file to determine
23797 whether the domain exists. The \%dsearch%\ lookup type is useful here, leading
23798 to a router of this form:
23802 domains = dsearch;/etc/mail/virtual
23803 data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}}
23806 The \domains\ option specifies that the router is to be skipped, unless there
23807 is a file in the \(/etc/mail/virtual)\ directory whose name is the same as the
23808 domain that is being processed. When the router runs, it looks up the local
23809 part in the file to find a new address (or list of addresses). The \no@_more\
23810 setting ensures that if the lookup fails (leading to \data\ being an empty
23811 string), Exim gives up on the address without trying any subsequent routers.
23813 This one router can handle all the virtual domains because the alias file names
23814 follow a fixed pattern. Permissions can be arranged so that appropriate people
23815 can edit the different alias files. A successful aliasing operation results in
23816 a new envelope recipient address, which is then routed from scratch.
23818 The other kind of `virtual' domain can also be handled in a straightforward
23819 way. One approach is to create a file for each domain containing a list of
23820 valid local parts, and use it in a router like this:
23824 domains = dsearch;/etc/mail/domains
23825 local_parts = lsearch;/etc/mail/domains/$domain
23826 transport = my_mailboxes
23828 The address is accepted if there is a file for the domain, and the local part
23829 can be found in the file. The \domains\ option is used to check for the file's
23830 existence because \domains\ is tested before the \local@_parts\ option (see
23831 section ~~SECTrouprecon). You can't use \require@_files\, because that option
23832 is tested after \local@_parts\. The transport is as follows:
23835 driver = appendfile
23836 file = /var/mail/$domain/$local_part
23839 This uses a directory of mailboxes for each domain. The \user\ setting is
23840 required, to specify which uid is to be used for writing to the mailboxes.
23842 The configuration shown here is just one example of how you might support this
23843 requirement. There are many other ways this kind of configuration can be set
23844 up, for example, by using a database instead of separate files to hold all the
23845 information about the domains.
23848 .section Multiple user mailboxes
23849 .rset SECTmulbox "~~chapter.~~section"
23850 .index multiple mailboxes
23851 .index mailbox||multiple
23852 .index local part||prefix
23853 .index local part||suffix
23854 Heavy email users often want to operate with multiple mailboxes, into which
23855 incoming mail is automatically sorted. A popular way of handling this is to
23856 allow users to use multiple sender addresses, so that replies can easily be
23857 identified. Users are permitted to add prefixes or suffixes to their local
23858 parts for this purpose. The wildcard facility of the generic router options
23859 \local@_part@_prefix\ and \local@_part@_suffix\ can be used for this. For
23860 example, consider this router:
23865 file = $home/.forward
23866 local_part_suffix = -*
23867 local_part_suffix_optional
23870 It runs a user's \(.forward)\ file for all local parts of the form
23871 \*username-$*$*\. Within the filter file the user can distinguish different
23872 cases by testing the variable \$local@_part@_suffix$\. For example:
23874 if $local_part_suffix contains -special then
23875 save /home/$local_part/Mail/special
23878 If the filter file does not exist, or does not deal with such addresses, they
23879 fall through to subsequent routers, and, assuming no subsequent use of the
23880 \local@_part@_suffix\ option is made, they presumably fail. Thus, users have
23881 control over which suffixes are valid.
23883 Alternatively, a suffix can be used to trigger the use of a different
23884 \(.forward)\ file -- which is the way a similar facility is implemented in
23890 file = $home/.forward$local_part_suffix
23891 local_part_suffix = -*
23892 local_part_suffix_optional
23895 If there is no suffix, \(.forward)\ is used; if the suffix is \*-special*\, for
23896 example, \(.forward-special)\ is used. Once again, if the appropriate file
23897 does not exist, or does not deal with the address, it is passed on to
23898 subsequent routers, which could, if required, look for an unqualified
23899 \(.forward)\ file to use as a default.
23902 .section Simplified vacation processing
23903 .index vacation processing
23904 The traditional way of running the \*vacation*\ program is for a user to set up
23905 a pipe command in a \(.forward)\ file
23906 (see section ~~SECTspecitredli for syntax details).
23907 This is prone to error by inexperienced users. There are two features of Exim
23908 that can be used to make this process simpler for users:
23910 A local part prefix such as `vacation-' can be specified on a router which
23911 can cause the message to be delivered directly to the \*vacation*\ program, or
23912 alternatively can use Exim's \%autoreply%\ transport. The contents of a user's
23913 \(.forward)\ file are then much simpler. For example:
23915 spqr, vacation-spqr
23918 The \require@_files\ generic router option can be used to trigger a
23919 vacation delivery by checking for the existence of a certain file in the
23920 user's home directory. The \unseen\ generic option should also be used, to
23921 ensure that the original delivery also proceeds. In this case, all the user has
23922 to do is to create a file called, say, \(.vacation)\, containing a vacation
23925 Another advantage of both these methods is that they both work even when the
23926 use of arbitrary pipes by users is locked out.
23929 .section Taking copies of mail
23930 .index message||copying every
23931 Some installations have policies that require archive copies of all messages to
23932 be made. A single copy of each message can easily be taken by an appropriate
23933 command in a system filter, which could, for example, use a different file for
23934 each day's messages.
23936 There is also a shadow transport mechanism that can be used to take copies of
23937 messages that are successfully delivered by local transports, one copy per
23938 delivery. This could be used, $it{inter alia}, to implement automatic
23939 notification of delivery by sites that insist on doing such things.
23942 .section Intermittently connected hosts
23943 .index intermittently connected hosts
23944 It has become quite common (because it is cheaper) for hosts to connect to the
23945 Internet periodically rather than remain connected all the time. The normal
23946 arrangement is that mail for such hosts accumulates on a system that is
23947 permanently connected.
23949 Exim was designed for use on permanently connected hosts, and so it is not
23950 particularly well-suited to use in an intermittently connected environment.
23951 Nevertheless there are some features that can be used.
23953 .section Exim on the upstream server host
23954 It is tempting to arrange for incoming mail for the intermittently connected
23955 host to remain on Exim's queue until the client connects. However, this
23956 approach does not scale very well. Two different kinds of waiting message are
23957 being mixed up in the same queue -- those that cannot be delivered because of
23958 some temporary problem, and those that are waiting for their destination host
23959 to connect. This makes it hard to manage the queue, as well as wasting
23960 resources, because each queue runner scans the entire queue.
23962 A better approach is to separate off those messages that are waiting for an
23963 intermittently connected host. This can be done by delivering these messages
23964 into local files in batch SMTP, `mailstore', or other envelope-preserving
23965 format, from where they are transmitted by other software when their
23966 destination connects. This makes it easy to collect all the mail for one host
23967 in a single directory, and to apply local timeout rules on a per-message basis
23970 On a very small scale, leaving the mail on Exim's queue can be made to work. If
23971 you are doing this, you should configure Exim with a long retry period for the
23972 intermittent host. For example:
23974 cheshire.wonderland.fict.example * F,5d,24h
23976 This stops a lot of failed delivery attempts from occurring, but Exim remembers
23977 which messages it has queued up for that host. Once the intermittent host comes
23978 online, forcing delivery of one message (either by using the \-M-\ or \-R-\
23979 options, or by using the \\ETRN\\ SMTP command (see section ~~SECTETRN)
23980 causes all the queued up messages to be delivered, often down a single SMTP
23981 connection. While the host remains connected, any new messages get delivered
23984 If the connecting hosts do not have fixed IP addresses, that is, if a host is
23985 issued with a different IP address each time it connects, Exim's retry
23986 mechanisms on the holding host get confused, because the IP address is normally
23987 used as part of the key string for holding retry information. This can be
23988 avoided by unsetting \retry__include__ip__address\ on the \%smtp%\ transport.
23989 Since this has disadvantages for permanently connected hosts, it is best to
23990 arrange a separate transport for the intermittently connected ones.
23993 .section Exim on the intermittently connected client host
23994 The value of \smtp@_accept@_queue@_per@_connection\ should probably be
23995 increased, or even set to zero (that is, disabled) on the intermittently
23996 connected host, so that all incoming messages down a single connection get
23997 delivered immediately.
23999 .index SMTP||passed connection
24000 .index SMTP||multiple deliveries
24001 .index multiple SMTP deliveries
24002 Mail waiting to be sent from an intermittently connected host will probably
24003 not have been routed, because without a connection DNS lookups are not
24004 possible. This means that if a normal queue run is done at connection time,
24005 each message is likely to be sent in a separate SMTP session. This can be
24006 avoided by starting the queue run with a command line option beginning with
24007 \-qq-\ instead of \-q-\. In this case, the queue is scanned twice. In the first
24008 pass, routing is done but no deliveries take place. The second pass is a normal
24009 queue run; since all the messages have been previously routed, those destined
24010 for the same host are likely to get sent as multiple deliveries in a single
24021 . ============================================================================
24022 .chapter SMTP processing
24023 .set runningfoot "smtp processing"
24024 .rset CHAPSMTP ~~chapter
24025 .index SMTP||processing details
24026 .index LMTP||processing details
24027 Exim supports a number of different ways of using the SMTP protocol, and its
24028 LMTP variant, which is an interactive protocol for transferring messages into a
24029 closed mail store application. This chapter contains details of how SMTP is
24030 processed. For incoming mail, the following are available:
24032 SMTP over TCP/IP (Exim daemon or \*inetd*\);
24034 SMTP over the standard input and output (the \-bs-\ option);
24036 Batched SMTP on the standard input (the \-bS-\ option).
24038 For mail delivery, the following are available:
24040 SMTP over TCP/IP (the \%smtp%\ transport);
24042 LMTP over TCP/IP (the \%smtp%\ transport with the \protocol\ option set to
24045 LMTP over a pipe to a process running in the local host (the \%lmtp%\
24048 Batched SMTP to a file or pipe (the \%appendfile%\ and \%pipe%\ transports with
24049 the \use@_bsmtp\ option set).
24051 \*Batched SMTP*\ is the name for a process in which batches of messages are
24052 stored in or read from files (or pipes), in a format in which SMTP commands are
24053 used to contain the envelope information.
24056 .section Outgoing SMTP and LMTP over TCP/IP
24057 .rset SECToutSMTPTCP "~~chapter.~~section"
24058 .index SMTP||outgoing over TCP/IP
24059 .index outgoing SMTP over TCP/IP
24060 .index LMTP||over TCP/IP
24061 .index outgoing LMTP over TCP/IP
24064 .index \\SIZE\\ option on \\MAIL\\ command
24065 Outgoing SMTP and LMTP over TCP/IP is implemented by the \%smtp%\ transport.
24066 The \protocol\ option selects which protocol is to be used, but the actual
24067 processing is the same in both cases.
24069 If, in response to its \\EHLO\\ command, Exim is told that the \\SIZE\\
24070 parameter is supported, it adds \\SIZE\\=<<n>> to each subsequent \\MAIL\\
24071 command. The value of <<n>> is the message size plus the value of the
24072 \size@_addition\ option (default 1024) to allow for additions to the message
24073 such as per-transport header lines, or changes made in a
24074 .index transport||filter
24075 .index filter||transport filter
24076 transport filter. If \size@_addition\ is set negative, the use of \\SIZE\\ is
24079 If the remote server advertises support for \\PIPELINING\\, Exim uses the
24080 pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets
24081 required for the transaction.
24083 If the remote server advertises support for the \\STARTTLS\\ command, and Exim
24084 was built to support TLS encryption, it tries to start a TLS session unless the
24085 server matches \hosts@_avoid@_tls\. See chapter ~~CHAPTLS for more details.
24087 If the remote server advertises support for the \\AUTH\\ command, Exim scans
24088 the authenticators configuration for any suitable client settings, as described
24089 in chapter ~~CHAPSMTPAUTH.
24091 .index carriage return
24093 Responses from the remote host are supposed to be terminated by CR followed by
24094 LF. However, there are known to be hosts that do not send CR characters, so in
24095 order to be able to interwork with such hosts, Exim treats LF on its own as a
24098 If a message contains a number of different addresses, all those with the same
24099 characteristics (for example, the same envelope sender) that resolve to the
24100 same set of hosts, in the same order, are sent in a single SMTP transaction,
24101 even if they are for different domains, unless there are more than the setting
24102 of the \max@_rcpts\ option in the \%smtp%\ transport allows, in which case they
24103 are split into groups containing no more than \max@_rcpts\ addresses each. If
24104 \remote@_max@_parallel\ is greater than one, such groups may be sent in
24105 parallel sessions. The order of hosts with identical MX values is not
24106 significant when checking whether addresses can be batched in this way.
24108 When the \%smtp%\ transport suffers a temporary failure that is not
24109 message-related, Exim updates its transport-specific database, which contains
24110 records indexed by host name that remember which messages are waiting for each
24111 particular host. It also updates the retry database with new retry times.
24112 .index hints database||retry keys
24113 Exim's retry hints are based on host name plus IP address, so if one address of
24114 a multi-homed host is broken, it will soon be skipped most of the time.
24115 See the next section for more detail about error handling.
24117 .index SMTP||passed connection
24118 .index SMTP||batching over TCP/IP
24119 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
24120 looks in the hints database for the transport to see if there are any queued
24121 messages waiting for the host to which it is connected. If it finds one, it
24122 creates a new Exim process using the \-MC-\ option (which can only be used by a
24123 process running as root or the Exim user) and passes the TCP/IP socket to it so
24124 that it can deliver another message using the same socket. The new process does
24125 only those deliveries that are routed to the connected host, and may in turn
24126 pass the socket on to a third process, and so on.
24128 The \connection@_max@_messages\ option of the \%smtp%\ transport can be used to
24129 limit the number of messages sent down a single TCP/IP connection.
24130 .index asterisk||after IP address
24131 The second and subsequent messages delivered down an existing connection are
24132 identified in the main log by the addition of an asterisk after the closing
24133 square bracket of the IP address.
24137 .section Errors in outgoing SMTP
24138 .rset SECToutSMTPerr "~~chapter.~~section"
24139 .index error||in outgoing SMTP
24140 .index SMTP||errors in outgoing
24142 Three different kinds of error are recognized for outgoing SMTP: host errors,
24143 message errors, and recipient errors.
24145 A host error is not associated with a particular message or with a
24146 particular recipient of a message. The host errors are:
24148 Connection refused or timed out,
24150 Any error response code on connection,
24152 Any error response code to \\EHLO\\ or \\HELO\\,
24154 Loss of connection at any time, except after `.',
24156 I/O errors at any time,
24158 Timeouts during the session, other than in response to \\MAIL\\, \\RCPT\\ or
24159 the `.' at the end of the data.
24161 For a host error, a permanent error response on connection, or in response to
24162 \\EHLO\\, causes all addresses routed to the host to be failed. Any other host
24163 error causes all addresses to be deferred, and retry data to be created for the
24164 host. It is not tried again, for any message, until its retry time arrives. If
24165 the current set of addresses are not all delivered in this run (to some
24166 alternative host), the message is added to the list of those waiting for this
24167 host, so if it is still undelivered when a subsequent successful delivery is
24168 made to the host, it will be sent down the same SMTP connection.
24170 .index message||error
24171 A message error is associated with a particular message when sent to a
24172 particular host, but not with a particular recipient of the message. The
24173 message errors are:
24175 Any error response code to \\MAIL\\, \\DATA\\, or the `.' that terminates
24178 Timeout after \\MAIL\\,
24181 or loss of connection after the `.' that terminates the data. A timeout after
24182 the \\DATA\\ command itself is treated as a host error, as is loss of
24183 connection at any other time.
24185 For a message error, a permanent error response (5$it{xx}) causes all addresses
24186 to be failed, and a delivery error report to be returned to the sender. A
24187 temporary error response (4$it{xx}), or one of the timeouts, causes all
24188 addresses to be deferred. Retry data is not created for the host, but instead,
24189 a retry record for the combination of host plus message id is created. The
24190 message is not added to the list of those waiting for this host. This ensures
24191 that the failing message will not be sent to this host again until the retry
24192 time arrives. However, other messages that are routed to the host are not
24193 affected, so if it is some property of the message that is causing the error,
24194 it will not stop the delivery of other mail.
24196 If the remote host specified support for the \\SIZE\\ parameter in its response
24197 to \\EHLO\\, Exim adds SIZE=$it{nnn} to the \\MAIL\\ command, so an
24198 over-large message will cause a message error because the error arrives as a
24199 response to \\MAIL\\.
24201 .index recipient||error
24202 A recipient error is associated with a particular recipient of a message. The
24203 recipient errors are:
24205 Any error response to \\RCPT\\,
24207 Timeout after \\RCPT\\.
24209 For a recipient error, a permanent error response (5$it{xx}) causes the
24210 recipient address to be failed, and a bounce message to be returned to the
24211 sender. A temporary error response (4$it{xx}) or a timeout causes the failing
24212 address to be deferred, and routing retry data to be created for it. This is
24213 used to delay processing of the address in subsequent queue runs, until its
24214 routing retry time arrives. This applies to all messages, but because it
24215 operates only in queue runs, one attempt will be made to deliver a new message
24216 to the failing address before the delay starts to operate. This ensures that,
24217 if the failure is really related to the message rather than the recipient
24218 (`message too big for this recipient' is a possible example), other messages
24219 have a chance of getting delivered. If a delivery to the address does succeed,
24220 the retry information gets cleared, so all stuck messages get tried again, and
24221 the retry clock is reset.
24223 The message is not added to the list of those waiting for this host. Use of the
24224 host for other messages is unaffected, and except in the case of a timeout,
24225 other recipients are processed independently, and may be successfully delivered
24226 in the current SMTP session. After a timeout it is of course impossible to
24227 proceed with the session, so all addresses get deferred. However, those other
24228 than the one that failed do not suffer any subsequent retry delays. Therefore,
24229 if one recipient is causing trouble, the others have a chance of getting
24230 through when a subsequent delivery attempt occurs before the failing
24231 recipient's retry time.
24234 In all cases, if there are other hosts (or IP addresses) available for the
24235 current set of addresses (for example, from multiple MX records), they are
24236 tried in this run for any undelivered addresses, subject of course to their
24237 own retry data. In other words, recipient error retry data does not take effect
24238 until the next delivery attempt.
24240 Some hosts have been observed to give temporary error responses to every
24241 \\MAIL\\ command at certain times (`insufficient space' has been seen). It
24242 would be nice if such circumstances could be recognized, and defer data for the
24243 host itself created, but this is not possible within the current Exim design.
24244 What actually happens is that retry data for every (host, message) combination
24247 The reason that timeouts after \\MAIL\\ and \\RCPT\\ are treated specially is
24248 that these can sometimes arise as a result of the remote host's verification
24249 procedures. Exim makes this assumption, and treats them as if a temporary error
24250 response had been received. A timeout after `.' is treated specially because it
24251 is known that some broken implementations fail to recognize the end of the
24252 message if the last character of the last line is a binary zero. Thus, it is
24253 helpful to treat this case as a message error.
24255 Timeouts at other times are treated as host errors, assuming a problem with the
24256 host, or the connection to it. If a timeout after \\MAIL\\, \\RCPT\\,
24257 or `.' is really a connection problem, the assumption is that at the next try
24258 the timeout is likely to occur at some other point in the dialogue, causing it
24259 then to be treated as a host error.
24261 There is experimental evidence that some MTAs drop the connection after the
24262 terminating `.' if they do not like the contents of the message for some
24263 reason, in contravention of the RFC, which indicates that a 5$it{xx} response
24264 should be given. That is why Exim treats this case as a message rather than a
24265 host error, in order not to delay other messages to the same host.
24270 .section Variable Envelope Return Paths (VERP)
24272 .index Variable Envelope Return Paths
24273 .index envelope sender
24274 Variable Envelope Return Paths -- see
24275 \?ftp://koobera.math.uic.edu/www/proto/verp.txt?\ -- can be supported in Exim
24276 by using the \return@_path\ generic transport option to rewrite the return path
24277 at transport time. For example, the following could be used on an \%smtp%\
24281 ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
24282 {$1-request=$local_part%$domain@your.dom.example}fail}
24284 This has the effect of rewriting the return path (envelope sender) on all
24285 outgoing SMTP messages, if the local part of the original return path ends in
24286 `-request', and the domain is \*your.dom.example*\. The rewriting inserts the
24287 local part and domain of the recipient into the return path. Suppose, for
24288 example, that a message whose return path has been set to
24289 \*somelist-request@@your.dom.example*\ is sent to
24290 \*subscriber@@other.dom.example*\. In the transport, the return path is
24293 somelist-request=subscriber%other.dom.example@your.dom.example
24295 For this to work, you must arrange for outgoing messages that have `-request'
24296 in their return paths to have just a single recipient. This can be done by
24301 in the \%smtp%\ transport. Otherwise a single copy of a message might be
24302 addressed to several different recipients in the same domain, in which case
24303 \$local@_part$\ is not available (because it is not unique). Of course, if you
24304 do start sending out messages with this kind of return path, you must also
24305 configure Exim to accept the bounce messages that come back to those paths.
24306 Typically this would be done by setting an \local@_part@_suffix\ option for a
24309 The overhead incurred in using VERP depends very much on the size of the
24310 message, the number of recipient addresses that resolve to the same remote
24311 host, and the speed of the connection over which the message is being sent. If
24312 a lot of addresses resolve to the same host and the connection is slow, sending
24313 a separate copy of the message for each address may take substantially longer
24314 than sending a single copy with many recipients (for which VERP cannot be
24318 .section Incoming SMTP messages over TCP/IP
24319 .index SMTP||incoming over TCP/IP
24320 .index incoming SMTP over TCP/IP
24323 Incoming SMTP messages can be accepted in one of two ways: by running a
24324 listening daemon, or by using \*inetd*\. In the latter case, the entry in
24325 \(/etc/inetd.conf)\ should be like this:
24327 smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs
24329 Exim distinguishes between this case and the case of a locally running user
24330 agent using the \-bs-\ option by checking whether or not the standard input is
24331 a socket. When it is, either the port must be privileged (less than 1024), or
24332 the caller must be root or the Exim user. If any other user passes a socket
24333 with an unprivileged port number, Exim prints a message on the standard error
24334 stream and exits with an error code.
24336 By default, Exim does not make a log entry when a remote host connects or
24337 disconnects (either via the daemon or \*inetd*\), unless the disconnection is
24338 unexpected. It can be made to write such log entries by setting the
24339 \smtp@_connection\ log selector.
24341 .index carriage return
24343 Commands from the remote host are supposed to be terminated by CR followed by
24344 LF. However, there are known to be hosts that do not send CR characters. In
24345 order to be able to interwork with such hosts, Exim treats LF on its own as a
24347 Furthermore, because common code is used for receiving messages from all
24348 sources, a CR on its own is also interpreted as a line terminator. However, the
24349 sequence `CR, dot, CR' does not terminate incoming SMTP data.
24351 .index \\EHLO\\||invalid data
24352 .index \\HELO\\||invalid data
24353 One area that sometimes gives rise to problems concerns the \\EHLO\\ or
24354 \\HELO\\ commands. Some clients send syntactically invalid versions of these
24355 commands, which Exim rejects by default. (This is nothing to do with verifying
24356 the data that is sent, so \helo@_verify@_hosts\ is not relevant.) You can tell
24357 Exim not to apply a syntax check by setting \helo@_accept@_junk@_hosts\ to
24358 match the broken hosts that send invalid commands.
24360 .index \\SIZE\\ option on \\MAIL\\ command
24361 .index \\MAIL\\||\\SIZE\\ option
24362 The amount of disk space available is checked whenever \\SIZE\\ is received on
24363 a \\MAIL\\ command, independently of whether \message@_size@_limit\ or
24364 \check@_spool@_space\ is configured, unless \smtp__check__spool__space\ is set
24365 false. A temporary error is given if there is not enough space. If
24366 \check@_spool@_space\ is set, the check is for that amount of space plus the
24367 value given with \\SIZE\\, that is, it checks that the addition of the incoming
24368 message will not reduce the space below the threshold.
24370 When a message is successfully received, Exim includes the local message id in
24371 its response to the final `.' that terminates the data. If the remote host logs
24372 this text it can help with tracing what has happened to a message.
24374 The Exim daemon can limit the number of simultaneous incoming connections it is
24375 prepared to handle (see the \smtp@_accept@_max\ option). It can also limit the
24376 number of simultaneous incoming connections from a single remote host (see the
24377 \smtp@_accept@_max@_per@_host\ option). Additional connection attempts are
24378 rejected using the SMTP temporary error code 421.
24380 The Exim daemon does not rely on the \\SIGCHLD\\ signal to detect when a
24381 subprocess has finished, as this can get lost at busy times. Instead, it looks
24382 for completed subprocesses every time it wakes up. Provided there are other
24383 things happening (new incoming calls, starts of queue runs), completed
24384 processes will be noticed and tidied away. On very quiet systems you may
24385 sometimes see a `defunct' Exim process hanging about. This is not a problem; it
24386 will be noticed when the daemon next wakes up.
24388 When running as a daemon, Exim can reserve some SMTP slots for specific hosts,
24389 and can also be set up to reject SMTP calls from non-reserved hosts at times of
24390 high system load -- for details see the \smtp@_accept@_reserve\,
24391 \smtp@_load@_reserve\, and \smtp@_reserve@_hosts\ options. The load check
24392 applies in both the daemon and \*inetd*\ cases.
24394 Exim normally starts a delivery process for each message received, though this
24395 can be varied by means of the \-odq-\ command line option and the
24396 \queue@_only\, \queue@_only@_file\, and \queue@_only@_load\ options. The number
24397 of simultaneously running delivery processes started in this way from SMTP
24398 input can be limited by the \smtp__accept__queue\ and
24399 \smtp__accept__queue__per__connection\ options. When either limit is reached,
24400 subsequently received messages are just put on the input queue without starting
24401 a delivery process.
24403 The controls that involve counts of incoming SMTP calls (\smtp@_accept@_max\,
24404 \smtp@_accept@_queue\, \smtp__accept__reserve\) are not available when Exim is
24405 started up from the \*inetd*\ daemon, because in that case each connection is
24406 handled by an entirely independent Exim process. Control by load average is,
24407 however, available with \*inetd*\.
24409 Exim can be configured to verify addresses in incoming SMTP commands as they
24410 are received. See chapter ~~CHAPACL for details. It can also be configured to
24411 rewrite addresses at this time -- before any syntax checking is done. See
24412 section ~~SECTrewriteS.
24414 Exim can also be configured to limit the rate at which a client host submits
24415 \\MAIL\\ and \\RCPT\\ commands in a single SMTP session. See the
24416 \smtp@_ratelimit@_hosts\ option.
24419 .section Unrecognized SMTP commands
24420 .index SMTP||unrecognized commands
24421 If Exim receives more than \smtp@_max@_unknown@_commands\ unrecognized SMTP
24422 commands during a single SMTP connection, it drops the connection after sending
24423 the error response to the last command. The default value for
24424 \smtp@_max@_unknown@_commands\ is 3. This is a defence against some kinds of
24425 abuse that subvert web servers into making connections to SMTP ports; in these
24426 circumstances, a number of non-SMTP lines are sent first.
24428 .section Syntax and protocol errors in SMTP commands
24429 .index SMTP||syntax errors
24430 .index SMTP||protocol errors
24431 A syntax error is detected if an SMTP command is recognized, but there is
24432 something syntactically wrong with its data, for example, a malformed email
24433 address in a \\RCPT\\ command. Protocol errors include invalid command
24434 sequencing such as \\RCPT\\ before \\MAIL\\. If Exim receives more than
24435 \smtp@_max@_synprot@_errors\ such commands during a single SMTP connection, it
24436 drops the connection after sending the error response to the last command. The
24437 default value for \smtp__max__synprot__errors\ is 3. This is a defence against
24438 broken clients that loop sending bad commands (yes, it has been seen).
24441 .section Use of non-mail SMTP commands
24442 .index SMTP||non-mail commands
24443 The `non-mail' SMTP commands are those other than \\MAIL\\, \\RCPT\\, and
24444 \\DATA\\. Exim counts such commands, and drops the connection if there are too
24445 many of them in a single SMTP session. This action catches some
24446 denial-of-service attempts and things like repeated failing \\AUTH\\s, or a mad
24447 client looping sending \\EHLO\\. The global option \smtp@_accept@_max@_nonmail\
24448 defines what `too many' means. Its default value is 10.
24450 When a new message is expected, one occurrence of \\RSET\\ is not counted. This
24451 allows a client to send one \\RSET\\ between messages (this is not necessary,
24452 but some clients do it). Exim also allows one uncounted occurence of \\HELO\\
24453 or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After
24454 starting up a TLS session, another \\EHLO\\ is expected, and so it too is not
24457 The first occurrence of \\AUTH\\ in a connection, or immediately following
24458 \\STARTTLS\\ is also not counted. Otherwise, all commands other than \\MAIL\\,
24459 \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted.
24461 You can control which hosts are subject to the limit set by
24462 \smtp@_accept@_max@_nonmail\ by setting
24463 \smtp@_accept@_max@_nonmail@_hosts\. The default value is \"$*$"\, which makes
24464 the limit apply to all hosts. This option means that you can exclude any
24465 specific badly-behaved hosts that you have to live with.
24469 .section The \\VRFY\\ and \\EXPN\\ commands
24470 When Exim receives a \\VRFY\\ or \\EXPN\\ command on a TCP/IP connection, it
24471 runs the ACL specified by \acl@_smtp@_vrfy\ or \acl@_smtp@_expn\ (as
24472 appropriate) in order to decide whether the command should be accepted or not.
24473 If no ACL is defined, the command is rejected.
24475 .index \\VRFY\\||processing
24476 When \\VRFY\\ is accepted, it runs exactly the same code as when Exim is
24477 called with the \-bv-\ option.
24478 .index \\EXPN\\||processing
24479 When \\EXPN\\ is accepted, a single-level expansion of the address is done.
24480 \\EXPN\\ is treated as an `address test' (similar to the \-bt-\ option) rather
24481 than a verification (the \-bv-\ option). If an unqualified local part is given
24482 as the argument to \\EXPN\\, it is qualified with \qualify@_domain\. Rejections
24483 of \\VRFY\\ and \\EXPN\\ commands are logged on the main and reject logs, and
24484 \\VRFY\\ verification failures are logged on the main log for consistency with
24488 .section The \\ETRN\\ command
24489 .rset SECTETRN "~~chapter.~~section"
24490 .index \\ETRN\\||processing
24491 RFC 1985 describes an SMTP command called \\ETRN\\ that is designed to
24492 overcome the security problems of the \\TURN\\ command (which has fallen into
24493 disuse). When Exim receives an \\ETRN\\ command on a TCP/IP connection, it runs
24494 the ACL specified by \acl@_smtp@_etrn\ in order to decide whether the command
24495 should be accepted or not. If no ACL is defined, the command is rejected.
24497 The \\ETRN\\ command is concerned with `releasing' messages that are awaiting
24498 delivery to certain hosts. As Exim does not organize its message queue by host,
24499 the only form of \\ETRN\\ that is supported by default is the one where the
24500 text starts with the `@#' prefix, in which case the remainder of the text is
24501 specific to the SMTP server. A valid \\ETRN\\ command causes a run of Exim with
24502 the \-R-\ option to happen, with the remainder of the \\ETRN\\ text as its
24503 argument. For example,
24511 which causes a delivery attempt on all messages with undelivered addresses
24512 containing the text `brigadoon'. When \smtp@_etrn@_serialize\ is set (the
24513 default), Exim prevents the simultaneous execution of more than one queue run
24514 for the same argument string as a result of an \\ETRN\\ command. This stops
24515 a misbehaving client from starting more than one queue runner at once.
24517 .index hints database||\\ETRN\\ serialization
24518 Exim implements the serialization by means of a hints database in which a
24519 record is written whenever a process is started by \\ETRN\\, and deleted when
24520 the process completes. However, Exim does not keep the SMTP session waiting for
24521 the \\ETRN\\ process to complete. Once \\ETRN\\ is accepted, the client is sent
24522 a `success' return code. Obviously there is scope for hints records to get left
24523 lying around if there is a system or program crash. To guard against this, Exim
24524 ignores any records that are more than six hours old.
24526 .index \smtp@_etrn@_command\
24527 For more control over what \\ETRN\\ does, the \smtp@_etrn@_command\ option can
24528 used. This specifies a command that is run whenever \\ETRN\\ is received,
24529 whatever the form of its argument. For
24532 smtp_etrn_command = /etc/etrn_command $domain $sender_host_address
24534 The string is split up into arguments which are independently expanded. The
24535 expansion variable \$domain$\ is set to the argument of the \\ETRN\\ command,
24536 and no syntax checking is done on the contents of this argument. Exim does not
24537 wait for the command to complete, so its status code is not checked. Exim runs
24538 under its own uid and gid when receiving incoming SMTP, so it is not possible
24539 for it to change them before running the command.
24542 .section Incoming local SMTP
24543 .index SMTP||local incoming
24544 Some user agents use SMTP to pass messages to their local MTA using the
24545 standard input and output, as opposed to passing the envelope on the command
24546 line and writing the message to the standard input. This is supported by the
24547 \-bs-\ option. This form of SMTP is handled in the same way as incoming
24548 messages over TCP/IP (including the use of ACLs), except that the envelope
24549 sender given in a \\MAIL\\ command is ignored unless the caller is trusted. In
24550 an ACL you can detect this form of SMTP input by testing for an empty host
24551 identification. It is common to have this as the first line in the ACL that
24552 runs for \\RCPT\\ commands:
24556 This accepts SMTP messages from local processes without doing any other tests.
24559 .section Outgoing batched SMTP
24560 .rset SECTbatchSMTP "~~chapter.~~section"
24561 .index SMTP||batched outgoing
24562 .index batched SMTP output
24563 Both the \%appendfile%\ and \%pipe%\ transports can be used for handling batched
24564 SMTP. Each has an option called \use@_bsmtp\ which causes messages to be output
24565 in BSMTP format. No SMTP responses are possible for this form of delivery. All
24566 it is doing is using SMTP commands as a way of transmitting the envelope along
24569 The message is written to the file or pipe preceded by the SMTP commands
24570 \\MAIL\\ and \\RCPT\\, and followed by a line containing a single dot. Lines in
24571 the message that start with a dot have an extra dot added. The SMTP command
24572 \\HELO\\ is not normally used. If it is required, the \message@_prefix\ option
24573 can be used to specify it.
24575 Because \%appendfile%\ and \%pipe%\ are both local transports, they accept only
24576 one recipient address at a time by default. However, you can arrange for them
24577 to handle several addresses at once by setting the \batch@_max\ option. When
24578 this is done for BSMTP, messages may contain multiple \\RCPT\\ commands. See
24579 chapter ~~CHAPbatching for more details.
24581 When one or more addresses are routed to a BSMTP transport by a router that
24582 sets up a host list, the name of the first host on the list is available to the
24583 transport in the variable \$host$\. Here is an example of such a transport and
24588 driver = manualroute
24589 transport = smtp_appendfile
24590 route_list = domain.example batch.host.example
24594 driver = appendfile
24595 directory = /var/bsmtp/$host
24600 This causes messages addressed to \*domain.example*\ to be written in BSMTP
24601 format to \(/var/bsmtp/batch.host.example)\, with only a single copy of each
24602 message (unless there are more than 1000 recipients).
24605 .section Incoming batched SMTP
24606 .rset SECTincomingbatchedSMTP "~~chapter.~~section"
24607 .index SMTP||batched incoming
24608 .index batched SMTP input
24609 The \-bS-\ command line option causes Exim to accept one or more messages by
24610 reading SMTP on the standard input, but to generate no responses. If the caller
24611 is trusted, the senders in the \\MAIL\\ commands are believed; otherwise the
24612 sender is always the caller of Exim. Unqualified senders and receivers are not
24613 rejected (there seems little point) but instead just get qualified. \\HELO\\
24614 and \\EHLO\\ act as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\ and \\HELP\\, act
24615 as \\NOOP\\; \\QUIT\\ quits.
24617 No policy checking is done for BSMTP input. That is, no ACL is run at anytime.
24618 In this respect it is like non-SMTP local input.
24620 If an error is detected while reading a message, including a missing `.' at
24621 the end, Exim gives up immediately. It writes details of the error to the
24622 standard output in a stylized way that the calling program should be able to
24623 make some use of automatically, for example:
24625 554 Unexpected end of file
24626 Transaction started in line 10
24627 Error detected in line 14
24629 It writes a more verbose version, for human consumption, to the standard error
24632 An error was detected while processing a file of BSMTP input.
24633 The error message was:
24635 501 '>' missing at end of address
24637 The SMTP transaction started in line 10.
24638 The error was detected in line 12.
24639 The SMTP command at fault was:
24641 rcpt to:<malformed@in.com.plete
24643 1 previous message was successfully processed.
24644 The rest of the batch was abandoned.
24646 The return code from Exim is zero only if there were no errors. It is 1 if some
24647 messages were accepted before an error was detected, and 2 if no messages were
24657 . ============================================================================
24658 .chapter Message processing
24659 .set runningfoot "message processing"
24660 .rset CHAPmsgproc "~~chapter"
24661 .index message||general processing
24662 Exim performs various transformations on the sender and recipient addresses of
24663 all messages that it handles, and also on the messages' header lines. Some of
24664 these are optional and configurable, while others always take place. All of
24665 this processing, except rewriting as a result of routing, and the addition or
24666 removal of header lines while delivering, happens when a message is received,
24667 before it is placed on Exim's queue.
24669 Some of the automatic processing takes place
24673 only for `locally-originated' messages. This adjective is used to describe
24674 messages that are not received over TCP/IP, but instead are passed to an Exim
24675 process on its standard input. This includes the interactive `local SMTP' case
24676 that is set up by the \-bs-\ command line option. \**Note**\: messages received
24677 over TCP/IP on the loopback interface (127.0.0.1 or @:@:1) are not considered
24678 to be locally-originated. Exim does not treat the loopback interface specially
24682 .index message||submission
24683 Processing that happens automatically for locally-originated messages can also
24684 be requested for other messages. This is done by obeying the modifier
24686 control = submission
24688 in one of the ACLs that are run for an incoming message (see section
24689 ~~SECTACLmodi). This makes Exim treat the message as a local submission, and is
24690 normally used when the source of the message is known to be an MUA running on a
24691 client host (as opposed to an MTA). In the descriptions below, the term
24692 `submission mode' is used to describe this state.
24694 When a ::From:: or ::Sender:: header is generated in submission mode, the value
24695 of \qualify@_domain\ is used by default. However, it is possible to specify
24696 another domain by a setting such as
24698 control = submission/domain=some.other.domain
24704 .section Line endings
24705 .rset SECTlineendings "~~chapter.~~section"
24706 .index line endings
24707 .index carriage return
24709 RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
24710 linefeed) is the line ending for messages transmitted over the Internet using
24711 SMTP over TCP/IP. However, within individual operating systems, different
24712 conventions are used. For example, Unix-like systems use just LF, but others
24713 use CRLF or just CR.
24715 Exim was designed for Unix-like systems, and internally, it stores messages
24716 using the system's convention of a single LF as a line terminator. When
24717 receiving a message, all line endings are translated to this standard format.
24718 Originally, it was thought that programs that passed messages directly to an
24719 MTA within an operating system would use that system's convention. Experience
24720 has shown that this is not the case; for example, there are Unix applications
24721 that use CRLF in this circumstance. For this reason, and for compatibility with
24722 other MTAs, the way Exim handles line endings for all messages is now as
24725 LF not preceded by CR is treated as a line ending.
24727 CR is treated as a line ending; if it is immediately followed by LF, the LF
24730 The sequence `CR, dot, CR' does not terminate an incoming SMTP message,
24731 nor a local message in the state where a line containing only a dot is a
24734 If a bare CR is encountered within a header line, an extra space is added after
24735 the line terminator so as not to end the header line. The reasoning behind this
24736 is that bare CRs in header lines are most likely either to be mistakes, or
24737 people trying to play silly games.
24740 If the first header line received in a message ends with CRLF, a subsequent
24741 bare LF in a header line is treated in the same way as a bare CR in a header
24748 .section Unqualified addresses
24749 .index unqualified addresses
24750 .index address||qualification
24751 By default, Exim expects every address it receives from an external host to be
24752 fully qualified. Unqualified addresses cause negative responses to SMTP
24753 commands. However, because SMTP is used as a means of transporting messages
24754 from MUAs running on personal workstations, there is sometimes a requirement to
24755 accept unqualified addresses from specific hosts or IP networks.
24757 Exim has two options that separately control which hosts may send unqualified
24758 sender or receipient addresses in SMTP commands, namely
24759 \sender__unqualified__hosts\ and \recipient__unqualified__hosts\. In both
24760 cases, if an unqualified address is accepted, it is qualified by adding the
24761 value of \qualify__domain\ or \qualify__recipient\, as appropriate.
24762 .index \qualify@_domain\
24763 .index \qualify@_recipient\
24766 .section The UUCP From line
24768 .index UUCP||`From' line
24769 .index sender||address
24770 .index \uucp@_from@_pattern\
24771 .index \uucp@_from@_sender\
24772 .index envelope sender
24773 .index Sendmail compatibility||`From' line
24774 Messages that have come from UUCP (and some other applications) often begin
24775 with a line containing the envelope sender and a timestamp, following the word
24776 `From'. Examples of two common formats are:
24778 From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996
24779 From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT
24781 This line precedes the RFC 2822 header lines. For compatibility with Sendmail,
24782 Exim recognizes such lines at the start of messages that are submitted to it
24783 via the command line (that is, on the standard input). It does not recognize
24784 such lines in incoming SMTP messages, unless the sending host matches
24785 \ignore@_fromline@_hosts\ or the \-bs-\ option was used for a local message and
24786 \ignore@_fromline@_local\ is set. The recognition is controlled by a regular
24787 expression that is defined by the \uucp@_from@_pattern\ option, whose default
24788 value matches the two common cases shown above and puts the address that
24789 follows `From' into \$1$\.
24791 .index numerical variables (\$1$\, \$2$\, etc)||in `From ' line handling
24792 When the caller of Exim for a non-SMTP message that contains a `From' line is a
24793 trusted user, the message's sender address is constructed by expanding the
24794 contents of \uucp@_sender@_address\, whose default value is `@$1'. This is then
24795 parsed as an RFC 2822 address. If there is no domain, the local part is
24796 qualified with \qualify@_domain\ unless it is the empty string. However, if the
24797 command line \-f-\ option is used, it overrides the `From' line.
24799 If the caller of Exim is not trusted, the `From' line is recognized, but the
24800 sender address is not changed. This is also the case for incoming SMTP messages
24801 that are permitted to contain `From' lines.
24803 Only one `From' line is recognized. If there is more than one, the second is
24804 treated as a data line that starts the body of the message, as it is not valid
24805 as a header line. This also happens if a `From' line is present in an incoming
24806 SMTP message from a source that is not permitted to send them.
24809 .section Resent- header lines
24810 .index \Resent@-\ header lines
24811 RFC 2822 makes provision for sets of header lines starting with the string
24812 \"Resent-"\ to be added to a message when it is resent by the original
24813 recipient to somebody else. These headers are ::Resent-Date::, ::Resent-From::,
24814 ::Resent-Sender::, ::Resent-To::, ::Resent-Cc::, ::Resent-Bcc:: and
24815 ::Resent-Message-ID::. The RFC says:
24817 \*Resent fields are strictly informational. They MUST NOT be used in the normal
24818 processing of replies or other such automatic actions on messages.*\
24820 This leaves things a bit vague as far as other processing actions such as
24821 address rewriting are concerned. Exim treats \Resent@-\ header lines as
24824 A ::Resent-From:: line that just contains the login id of the submitting user
24825 is automatically rewritten in the same way as ::From:: (see below).
24827 If there's a rewriting rule for a particular header line, it is also applied to
24828 \Resent@-\ header lines of the same type. For example, a rule that rewrites
24829 ::From:: also rewrites ::Resent-From::.
24831 For local messages, if ::Sender:: is removed on input, ::Resent-Sender:: is also
24834 For a locally-submitted message,
24835 if there are any \Resent@-\ header lines but no ::Resent-Date::,
24836 ::Resent-From::, or ::Resent-Message-Id::, they are added as necessary. It is
24837 the contents of ::Resent-Message-Id:: (rather than ::Message-Id::) which are
24838 included in log lines in this case.
24840 The logic for adding ::Sender:: is duplicated for ::Resent-Sender:: when any
24841 \Resent@-\ header lines are present.
24845 .section The Auto-Submitted: header line
24846 Whenever Exim generates a bounce or a delay warning message, it includes the
24849 Auto-Submitted: auto-generated
24853 .section The Bcc: header line
24854 .index ::Bcc:: header line
24855 If Exim is called with the \-t-\ option, to take recipient addresses from a
24856 message's header, it removes any ::Bcc:: header line that may exist (after
24857 extracting its addresses). If \-t-\ is not present on the command line, any
24858 existing ::Bcc:: is not removed.
24860 .section The Date: header line
24861 .index ::Date:: header line
24862 If a locally-generated
24866 message has no ::Date:: header line, Exim adds one, using the current date and
24869 .section The Delivery-date: header line
24870 .index ::Delivery-date:: header line
24871 .index \delivery@_date@_remove\
24872 ::Delivery-date:: header lines are not part of the standard RFC 2822 header
24873 set. Exim can be configured to add them to the final delivery of messages. (See
24874 the generic \delivery@_date@_add\ transport option.) They should not be present
24875 in messages in transit. If the \delivery@_date@_remove\ configuration option is
24876 set (the default), Exim removes ::Delivery-date:: header lines from incoming
24879 .section The Envelope-to: header line
24880 .index ::Envelope-to:: header line
24881 .index \envelope@_to@_remove\
24882 ::Envelope-to:: header lines are not part of the standard RFC 2822 header set.
24883 Exim can be configured to add them to the final delivery of messages. (See the
24884 generic \envelope@_to@_add\ transport option.) They should not be present in
24885 messages in transit. If the \envelope@_to@_remove\ configuration option is set
24886 (the default), Exim removes ::Envelope-to:: header lines from incoming
24889 .section The From: header line
24890 .index ::From:: header line
24891 .index Sendmail compatibility||`From' line
24893 If a submission-mode message does not contain a ::From:: header line, Exim adds
24894 one if either of the following conditions is true:
24896 The envelope sender address is not empty (that is, this is not a bounce
24897 message); the added header line copies the envelope sender address.
24899 The SMTP session is authenticated and \$authenticated@_id$\ is not empty; the
24900 added header's local part is \$authenticated@_id$\ and the domain is
24901 the domain specified on the submission control, or \$qualify@_domain$\ if that
24904 A non-empty envelope sender takes precedence.
24907 If a locally-generated incoming message does not contain a ::From:: header
24908 line, Exim adds one containing the sender's address. The calling user's login
24909 name and full name are used to construct the address, as described in section
24910 ~~SECTconstr. They are obtained from the password data by calling
24911 \*getpwuid()*\ (but see the \unknown@_login\ configuration option). The address
24912 is qualified with \qualify@_domain\.
24914 For compatibility with Sendmail, if an incoming, non-SMTP message has a
24915 ::From:: header line containing just the unqualified login name of the calling
24916 user, this is replaced by an address containing the user's login name and full
24917 name as described in section ~~SECTconstr.
24919 .section The Message-ID: header line
24920 .index ::Message-ID:: header line
24921 If a locally-generated
24925 incoming message does not contain a ::Message-ID:: or ::Resent-Message-ID::
24926 header line, Exim adds one to the message. If there are any ::Resent-:: headers
24927 in the message, it creates ::Resent-Message-ID::. The id is constructed from
24928 Exim's internal message id, preceded by the letter E to ensure it starts with a
24929 letter, and followed by @@ and the primary host name. Additional information
24930 can be included in this header line by setting the
24931 .index \message@_id@_header@_text\
24932 \message@_id@_header@_text\ and/or \message__id__header__domain\ options.
24935 .section The Received: header line
24936 .index ::Received:: header line
24937 A ::Received:: header line is added at the start of every message. The contents
24938 are defined by the \received@_header@_text\ configuration option, and Exim
24939 automatically adds a semicolon and a timestamp to the configured string.
24942 The ::Received:: header is generated as soon as the message's header lines have
24943 been received. At this stage, the timestamp in the ::Received:: header line is
24944 the time that the message started to be received. This is the value that is
24945 seen by the \\DATA\\ ACL and by the \*local@_scan()*\ function.
24947 Once a message is accepted, the timestamp in the ::Received:: header line is
24948 changed to the time of acceptance, which is (apart from a small delay while the
24949 -H spool file is written) the earliest time at which delivery could start.
24953 .section The Return-path: header line
24954 .index ::Return-path:: header line
24955 .index \return@_path@_remove\
24956 ::Return-path:: header lines are defined as something an MTA may insert when
24957 it does the final delivery of messages. (See the generic \return@_path@_add\
24958 transport option.) Therefore, they should not be present in messages in
24959 transit. If the \return@_path@_remove\ configuration option is set (the
24960 default), Exim removes ::Return-path:: header lines from incoming messages.
24963 .section The Sender: header line
24964 .rset SECTthesenhea "~~chapter.~~section"
24965 .index ::Sender:: header line
24966 For a locally-originated message from an untrusted user, Exim may remove an
24967 existing ::Sender:: header line, and it may add a new one. You can modify these
24968 actions by setting \local@_sender@_retain\ true or \local@_from@_check\ false.
24970 When a local message is received from an untrusted user and
24971 \local@_from@_check\ is true (the default), a check is made to see if the
24972 address given in the ::From:: header line is the correct (local) sender of the
24973 message. The address that is expected has the login name as the local part and
24974 the value of \qualify@_domain\ as the domain. Prefixes and suffixes for the
24975 local part can be permitted by setting \local@_from@_prefix\ and
24976 \local@_from@_suffix\ appropriately. If ::From:: does not contain the correct
24977 sender, a ::Sender:: line is added to the message.
24979 If you set \local@_from@_check\ false, this checking does not occur. However,
24980 the removal of an existing ::Sender:: line still happens, unless you also set
24981 \local@_sender@_retain\ to be true. It is not possible to set both of these
24982 options true at the same time.
24985 By default, no processing of ::Sender:: header lines is done for messages
24986 received by TCP/IP or for messages submitted by trusted users. However, when a
24987 message is received over TCP/IP in submission mode, ::Sender:: header lines are
24988 always removed. If the SMTP session is authenticated, and \$authenticated@_id$\
24989 is not empty, a sender address is created with \$authenticated@_id$\ as the
24990 local part and either the domain specified in the submission control or, if
24991 that is not specified, \$qualify@_domain$\ as the domain. This is compared with
24992 the address in the ::From:: header line. If they are different, a ::Sender::
24993 header line is added. Prefixes and suffixes for the local part in ::From:: can
24994 be permitted by setting \local@_from@_prefix\ and \local@_from@_suffix\
24999 .section Adding and removing header lines
25000 .index header lines||adding
25001 .index header lines||removing
25002 .rset SECTheadersaddrem "~~chapter.~~section"
25003 When a message is delivered, the addition and removal of header lines can be
25004 specified on any of the routers and transports, and also in the system filter.
25005 Changes specified in the system filter affect all deliveries of a message.
25007 Header changes specified on a router affect all addresses handled by that
25008 router, and also any new addresses it generates. If an address passes through
25009 several routers, the changes are cumulative. When a message is processed by a
25010 transport, the message's original set of header lines is output, except for
25011 those named in any \headers@_remove\ options that the address has encountered
25012 as it was processed, and any in the transport's own \headers@_remove\ option.
25013 Then the new header lines from \headers@_add\ options are output.
25016 .section Constructed addresses
25017 .rset SECTconstr "~~chapter.~~section"
25018 .index address||constructed
25019 .index constructed address
25020 When Exim constructs a sender address for a locally-generated message, it uses
25023 <<user name>> <$$<<login>>@@<<qualify@_domain>>$$>
25027 Zaphod Beeblebrox <zaphod@end.univ.example>
25029 The user name is obtained from the \-F-\ command line option if set, or
25030 otherwise by looking up the calling user by \*getpwuid()*\ and extracting the
25031 `gecos' field from the password entry. If the `gecos' field contains an
25032 ampersand character, this is replaced by the login name with the first letter
25033 upper cased, as is conventional in a number of operating systems. See the
25034 \gecos@_name\ option for a way to tailor the handling of the `gecos' field. The
25035 \unknown@_username\ option can be used to specify user names in cases when
25036 there is no password file entry.
25038 In all cases, the user name is made to conform to RFC 2822 by quoting all or
25039 parts of it if necessary. In addition, if it contains any non-printing
25040 characters, it is encoded as described in RFC 2047, which defines a way of
25041 including non-ASCII characters in header lines.
25042 The value of the \headers@_charset\ option specifies the name of the encoding
25043 that is used (the characters are assumed to be in this encoding).
25044 The setting of \print@_topbitchars\ controls whether characters with the top
25045 bit set (that is, with codes greater than 127) count as printing characters or
25049 .section Case of local parts
25050 .index case of local parts
25051 .index local part||case of
25052 RFC 2822 states that the case of letters in the local parts of addresses cannot
25053 be assumed to be non-significant. Exim preserves the case of local parts of
25054 addresses, but by default it uses a lower-cased form when it is routing,
25055 because on most Unix systems, usernames are in lower case and case-insensitive
25056 routing is required. However, any particular router can be made to use the
25057 original case for local parts by setting the \caseful@_local@_part\ generic
25060 .index mixed-case login names
25061 If you must have mixed-case user names on your system, the best way to proceed,
25062 assuming you want case-independent handling of incoming email, is to set up
25063 your first router to convert incoming local parts in your domains to the
25064 correct case by means of a file lookup. For example:
25068 domains = +local_domains
25069 data = ${lookup{$local_part}cdb\
25070 {/etc/usercased.cdb}{$value}fail}\
25073 For this router, the local part is forced to lower case by the default action
25074 (\caseful@_local@_part\ is not set). The lower-cased local part is used to look
25075 up a new local part in the correct case. If you then set \caseful@_local@_part\
25076 on any subsequent routers which process your domains, they will operate on
25077 local parts with the correct case in a case-sensitive manner.
25080 .section Dots in local parts
25081 .index dot||in local part
25082 .index local part||dots in
25083 RFC 2822 forbids empty components in local parts. That is, an unquoted local
25084 part may not begin or end with a dot, nor have two consecutive dots in the
25085 middle. However, it seems that many MTAs do not enforce this, so Exim permits
25086 empty components for compatibility.
25089 .section Rewriting addresses
25090 .index rewriting||addresses
25091 Rewriting of sender and recipient addresses, and addresses in headers, can
25092 happen automatically, or as the result of configuration options, as described
25093 in chapter ~~CHAPrewrite. The headers that may be affected by this are ::Bcc::,
25094 ::Cc::, ::From::, ::Reply-To::, ::Sender::, and ::To::.
25096 Automatic rewriting includes qualification, as mentioned above. The other case
25097 in which it can happen is when an incomplete non-local domain is given. The
25098 routing process may cause this to be expanded into the full domain name. For
25099 example, a header such as
25103 might get rewritten as
25105 To: hare@teaparty.wonderland.fict.example
25107 Rewriting as a result of routing is the one kind of message processing that
25108 does not happen at input time, as it cannot be done until the address has
25111 Strictly, one should not do $it{any} deliveries of a message until all its
25112 addresses have been routed, in case any of the headers get changed as a
25113 result of routing. However, doing this in practice would hold up many
25114 deliveries for unreasonable amounts of time, just because one address could not
25115 immediately be routed. Exim therefore does not delay other deliveries when
25116 routing of one or more addresses is deferred.
25126 . ============================================================================
25128 .set runningfoot "log files"
25129 .rset CHAPlog "~~chapter"
25130 .index log||types of
25131 .index log||general description
25132 Exim writes three different logs, referred to as the main log, the reject log,
25136 The main log records the arrival of each message and each delivery in a single
25137 line in each case. The format is as compact as possible, in an attempt to keep
25138 down the size of log files. Two-character flag sequences make it easy to pick
25139 out these lines. A number of other events are recorded in the main log. Some of
25140 them are optional, in which case the \log@_selector\ option controls whether
25141 they are included or not. A Perl script called \*eximstats*\, which does simple
25142 analysis of main log files, is provided in the Exim distribution (see section
25146 The reject log records information from messages that are rejected as a result
25147 of a configuration option (that is, for policy reasons).
25149 The first line of each rejection is a copy of the line that is also written to
25150 the main log. Then, if the message's header has been read at the time the log
25151 is written, its contents are written to this log. Only the original header
25152 lines are available; header lines added by ACLs are not logged. You can use the
25153 reject log to check that your policy controls are working correctly; on a busy
25154 host this may be easier than scanning the main log for rejection messages. You
25155 can suppress the writing of the reject log by setting \write@_rejectlog\ false.
25160 When certain serious errors occur, Exim writes entries to its panic log. If the
25161 error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries
25162 are usually written to the main log as well, but can get lost amid the mass of
25163 other entries. The panic log should be empty under normal circumstances. It is
25164 therefore a good idea to check it (or to have a \*cron*\ script check it)
25165 regularly, in order to become aware of any problems. When Exim cannot open its
25166 panic log, it tries as a last resort to write to the system log (syslog). This
25167 is opened with LOG@_PID+LOG@_CONS and the facility code of LOG@_MAIL. The
25168 message itself is written at priority LOG@_CRIT.
25170 Every log line starts with a timestamp, in the format shown in this example:
25172 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed by QUIT
25174 By default, the timestamps are in the local timezone. There are two
25175 ways of changing this:
25177 You can set the \timezone\ option to a different time zone; in particular, if
25182 the timestamps will be in UTC (aka GMT).
25184 If you set \log@_timezone\ true, the time zone is added to the timestamp, for
25187 2003-04-25 11:17:07 +0100 Start queue run: pid=12762
25193 .section Where the logs are written
25194 .rset SECTwhelogwri "~~chapter.~~section"
25195 .index log||destination
25196 .index log||to file
25197 .index log||to syslog
25199 The logs may be written to local files, or to syslog, or both. However, it
25200 should be noted that many syslog implementations use UDP as a transport, and
25201 are therefore unreliable in the sense that messages are not guaranteed to
25202 arrive at the loghost, nor is the ordering of messages necessarily maintained.
25203 It has also been reported that on large log files (tens of megabytes) you may
25204 need to tweak syslog to prevent it syncing the file with each write -- on Linux
25205 this has been seen to make syslog take 90% plus of CPU time.
25207 The destination for Exim's logs is configured by setting \\LOG@_FILE@_PATH\\ in
25208 \(Local/Makefile)\ or by setting \log@_file@_path\ in the run time
25209 configuration. This latter string is expanded, so it can contain, for example,
25210 references to the host name:
25212 log_file_path = /var/log/$primary_hostname/exim_%slog
25214 It is generally advisable, however, to set the string in \(Local/Makefile)\
25215 rather than at run time, because then the setting is available right from the
25216 start of Exim's execution. Otherwise, if there's something it wants to log
25217 before it has read the configuration file (for example, an error in the
25218 configuration file) it will not use the path you want, and may not be able to
25221 The value of \\LOG@_FILE@_PATH\\ or \log@_file@_path\ is a colon-separated
25222 list, currently limited to at most two items. This is one option where the
25223 facility for changing a list separator may not be used. The list must always be
25224 colon-separated. If an item in the list is `syslog' then syslog is used;
25225 otherwise the item must either be an absolute path, containing \"%s"\ at the
25226 point where `main', `reject', or `panic' is to be inserted, or be empty,
25227 implying the use of a default path.
25229 When Exim encounters an empty item in the list, it searches the list defined by
25230 \\LOG@_FILE@_PATH\\, and uses the first item it finds that is neither empty nor
25231 `syslog'. This means that an empty item in \log@_file@_path\ can be used to
25232 mean `use the path specified at build time'. It no such item exists, log files
25233 are written in the \(log)\ subdirectory of the spool directory. This is
25234 equivalent to the setting:
25236 log_file_path = $spool_directory/log/%slog
25238 If you do not specify anything at build time or run time, that is where the
25241 A log file path may also contain \"%D"\ if datestamped log file names are in
25242 use -- see section ~~SECTdatlogfil below.
25244 Here are some examples of possible settings:
25247 LOG@_FILE@_PATH=syslog $t $rm{syslog only}
25248 LOG@_FILE@_PATH=:syslog $t $rm{syslog and default path}
25249 LOG@_FILE@_PATH=syslog : /usr/log/exim@_%s $t $rm{syslog and specified path}
25250 LOG@_FILE@_PATH=/usr/log/exim@_%s $t $rm{specified path only}
25252 If there are more than two paths in the list, the first is used and a panic
25256 .section Logging to local files that are periodically `cycled'
25257 .index log||cycling local files
25258 .index cycling logs
25259 .index \*exicyclog*\
25260 .index log||local files, writing to
25261 Some operating systems provide centralized and standardised methods for cycling
25262 log files. For those that do not, a utility script called \*exicyclog*\ is
25263 provided (see section ~~SECTcyclogfil). This renames and compresses the main
25264 and reject logs each time it is called. The maximum number of old logs to keep
25265 can be set. It is suggested this script is run as a daily \*cron*\ job.
25267 An Exim delivery process opens the main log when it first needs to write to it,
25268 and it keeps the file open in case subsequent entries are required -- for
25269 example, if a number of different deliveries are being done for the same
25270 message. However, remote SMTP deliveries can take a long time, and this means
25271 that the file may be kept open long after it is renamed if \*exicyclog*\ or
25272 something similar is being used to rename log files on a regular basis. To
25273 ensure that a switch of log files is noticed as soon as possible, Exim calls
25274 \*stat()*\ on the main log's name before reusing an open file, and if the file
25275 does not exist, or its inode has changed, the old file is closed and Exim
25276 tries to open the main log from scratch. Thus, an old log file may remain open
25277 for quite some time, but no Exim processes should write to it once it has been
25281 .section Datestamped log files
25282 .rset SECTdatlogfil "~~chapter.~~section"
25283 .index log||datestamped files
25284 Instead of cycling the main and reject log files by renaming them
25285 periodically, some sites like to use files whose names contain a datestamp,
25286 for example, \(mainlog-20031225)\. The datestamp is in the form \(yyyymmdd)\.
25287 Exim has support for this way of working. It is enabled by setting the
25288 \log@_file@_path\ option to a path that includes \"%D"\ at the point where the
25289 datestamp is required. For example:
25291 log_file_path = /var/spool/exim/log/%slog-%D
25292 log_file_path = /var/log/exim-%s-%D.log
25293 log_file_path = /var/spool/exim/log/%D-%slog
25295 As before, \"%s"\ is replaced by `main' or `reject'; the following are examples
25296 of names generated by the above examples:
25298 /var/spool/exim/log/mainlog-20021225
25299 /var/log/exim-reject-20021225.log
25300 /var/spool/exim/log/20021225-mainlog
25302 When this form of log file is specified, Exim automatically switches to new
25303 files at midnight. It does not make any attempt to compress old logs; you
25304 will need to write your own script if you require this. You should not
25305 run \*exicyclog*\ with this form of logging.
25307 The location of the panic log is also determined by \log@_file@_path\, but it
25308 is not datestamped, because rotation of the panic log does not make sense.
25309 When generating the name of the panic log, \"%D"\ is removed from the string.
25310 In addition, if it immediately follows a slash, a following non-alphanumeric
25311 character is removed; otherwise a preceding non-alphanumeric character is
25312 removed. Thus, the three examples above would give these panic log names:
25314 /var/spool/exim/log/paniclog
25315 /var/log/exim-panic.log
25316 /var/spool/exim/log/paniclog
25320 .section Logging to syslog
25321 .index log||syslog, writing to
25322 The use of syslog does not change what Exim logs or the format of its messages,
25323 except in one respect. If \syslog@_timestamp\ is set false, the timestamps on
25324 Exim's log lines are omitted when these lines are sent to syslog. Apart from
25325 that, the same strings are written to syslog as to log files. The syslog
25326 `facility' is set to \\LOG@_MAIL\\, and the program name to `exim'
25327 by default, but you can change these by setting the \syslog@_facility\ and
25328 \syslog@_processname\ options, respectively. If Exim was compiled with
25329 \\SYSLOG@_LOG@_PID\\ set in \(Local/Makefile)\ (this is the default in
25330 \(src/EDITME)\), then, on systems that permit it (all except ULTRIX), the
25331 \\LOG@_PID\\ flag is set so that the \*syslog()*\ call adds the pid as well as
25332 the time and host name to each line.
25333 The three log streams are mapped onto syslog priorities as follows:
25335 \*mainlog*\ is mapped to \\LOG@_INFO\\
25337 \*rejectlog*\ is mapped to \\LOG@_NOTICE\\
25339 \*paniclog*\ is mapped to \\LOG@_ALERT\\
25341 Many log lines are written to both \*mainlog*\ and \*rejectlog*\, and some are
25342 written to both \*mainlog*\ and \*paniclog*\, so there will be duplicates if
25343 these are routed by syslog to the same place. You can suppress this duplication
25344 by setting \syslog@_duplication\ false.
25346 Exim's log lines can sometimes be very long, and some of its \*rejectlog*\
25347 entries contain multiple lines when headers are included. To cope with both
25348 these cases, entries written to syslog are split into separate \*syslog()*\
25349 calls at each internal newline, and also after a maximum of
25350 870 data characters. (This allows for a total syslog line length of 1024, when
25351 additions such as timestamps are added.) If you are running a syslog
25352 replacement that can handle lines longer than the 1024 characters allowed by
25353 RFC 3164, you should set
25355 SYSLOG_LONG_LINES=yes
25357 in \(Local/Makefile)\ before building Exim. That stops Exim from splitting long
25358 lines, but it still splits at internal newlines in \*reject*\ log entries.
25360 To make it easy to re-assemble split lines later, each component of a split
25361 entry starts with a string of the form `[<<n>>/<<m>>]' or `[<<n>>@\<<m>>]'
25362 where <<n>> is the component number and <<m>> is the total number of components
25363 in the entry. The / delimiter is used when the line was split because it was
25364 too long; if it was split because of an internal newline, the @\ delimiter is
25365 used. For example, supposing the length limit to be 70 instead of 1000, the
25366 following would be the result of a typical rejection message to \*mainlog*\
25367 (LOG@_INFO), each line in addition being preceded by the time, host name, and
25368 pid as added by syslog:
25371 $smc{[1/3] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10):
25372 [2/3] syntax error in 'From' header when scanning for sender: missing or ma
25373 [3/3] lformed local part in "<>" (envelope sender is <ph10@@cam.example>)}
25375 The same error might cause the following lines to be written to `rejectlog'
25379 $smc{[1/14] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10):
25380 [2/14] syntax error in 'From' header when scanning for sender: missing or ma
25381 [3@\14] lformed local part in "@<@>" (envelope sender is <ph10@@cam.example>)
25382 [4@\14] Recipients: ph10@@some.domain.cam.example
25383 [5@\14] P Received: from [127.0.0.1] (ident=ph10)
25384 [6@\14] by xxxxx.cam.example with smtp (Exim 4.00)
25385 [7@\14] id 16RdAL-0006pc-00
25386 [8@\14] for ph10@@cam.example; Mon, 16 Sep 2002 16:09:43 +0100
25387 [9@\14] F From: @<@>
25388 [10@\14] Subject: this is a test header
25389 [11@\14] X-something: this is another header
25390 [12@\14] I Message-Id: <E16RdAL-0006pc-00@@xxxxx.cam.example>
25392 [14/14] Date: Mon, 16 Sep 2002 16:09:43 +0100}
25394 Log lines that are neither too long nor contain newlines are written to syslog
25395 without modification.
25397 If only syslog is being used, the Exim monitor is unable to provide a log tail
25398 display, unless syslog is routing \*mainlog*\ to a file on the local host and
25399 the environment variable \\EXIMON@_LOG@_FILE@_PATH\\ is set to tell the monitor
25403 .section Log line flags
25404 One line is written to the main log for each message received, and for each
25405 successful, unsuccessful, and delayed delivery. These lines can readily be
25406 picked out by the distinctive two-character flags that immediately follow the
25407 timestamp. The flags are:
25410 <= $t $rm{message arrival}
25411 => $t $rm{normal message delivery}
25412 -> $t $rm{additional address in same delivery}
25413 *> $t $rm{delivery suppressed by \-N-\}
25414 ** $t $rm{delivery failed; address bounced}
25415 == $t $rm{delivery deferred; temporary problem}
25419 .section Logging message reception
25420 .index log||reception line
25421 The format of the single-line entry in the main log that is written for every
25422 message received is shown in the basic example below, which is split over
25423 several lines in order to fit it on the page:
25426 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@@dwarf.fict.example
25427 H=mailer.fict.example [192.168.123.123] U=exim
25428 P=smtp S=5678 id=<<incoming message id>>
25430 The address immediately following `<=' is the envelope sender address. A bounce
25431 message is shown with the sender address `<>', and if it is locally generated,
25432 this is followed by an item of the form
25436 which is a reference to the message that caused the bounce to be sent.
25440 For messages from other hosts, the H and U fields identify the remote host and
25441 record the RFC 1413 identity of the user that sent the message, if one was
25442 received. The number given in square brackets is the IP address of the sending
25443 host. If there is a single, unparenthesized host name in the H field, as
25444 above, it has been verified to correspond to the IP address (see the
25445 \host@_lookup\ option). If the name is in parentheses, it was the name quoted
25446 by the remote host in the SMTP \\HELO\\ or \\EHLO\\ command, and has not been
25447 verified. If verification yields a different name to that given for \\HELO\\ or
25448 \\EHLO\\, the verified name appears first, followed by the \\HELO\\ or \\EHLO\\
25449 name in parentheses.
25451 Misconfigured hosts (and mail forgers) sometimes put an IP address, with or
25452 without brackets, in the \\HELO\\ or \\EHLO\\ command, leading to entries in
25453 the log containing text like these examples:
25455 H=(10.21.32.43) [192.168.8.34]
25456 H=([10.21.32.43]) [192.168.8.34]
25458 This can be confusing. Only the final address in square brackets can be relied
25461 For locally generated messages (that is, messages not received over TCP/IP),
25462 the H field is omitted, and the U field contains the login name of the caller
25465 .index authentication||logging
25466 .index \\AUTH\\||logging
25467 For all messages, the P field specifies the protocol used to receive the
25468 message. This is set to `asmtp' for messages received from hosts which have
25469 authenticated themselves using the SMTP \\AUTH\\ command. In this case there is
25470 an additional item A= followed by the name of the authenticator that was used.
25471 If an authenticated identification was set up by the authenticator's
25472 \server@_set@_id\ option, this is logged too, separated by a colon from the
25473 authenticator name.
25475 The id field records the existing message id, if present.
25476 .index size||of message
25477 The size of the received message is given by the S field. When the message is
25478 delivered, headers may get removed or added, so that the size of delivered
25479 copies of the message may not correspond with this value (and indeed may be
25480 different to each other).
25482 The \log@_selector\ option can be used to request the logging of additional
25483 data when a message is received. See section ~~SECTlogselector below.
25486 .section Logging deliveries
25487 .index log||delivery line
25488 The format of the single-line entry in the main log that is written for every
25489 delivery is shown in one of the examples below, for local and remote deliveries,
25490 respectively. Each example has been split into two lines in order to fit
25494 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv <marv@@hitch.fict.example>
25495 R=localuser T=local@_delivery
25496 2002-10-31 09:00:10 16ZCW1-0005MB-00 => monk@@holistic.fict.example
25497 R=dnslookup T=remote@_smtp H=holistic.fict.example [192.168.234.234]
25499 For ordinary local deliveries, the original address is given in angle brackets
25500 after the final delivery address, which might be a pipe or a file. If
25501 intermediate address(es) exist between the original and the final address, the
25502 last of these is given in parentheses after the final address. The R and T
25503 fields record the router and transport that were used to process the address.
25505 If a shadow transport was run after a successful local delivery, the log line
25506 for the successful delivery has an item added on the end, of the form
25508 ST=<<shadow transport name>>
25510 If the shadow transport did not succeed, the error message is put in
25511 parentheses afterwards.
25513 When more than one address is included in a single delivery (for example, two
25514 SMTP \\RCPT\\ commands in one transaction) the second and subsequent
25515 addresses are flagged with `$tt{@-@>}' instead of `$tt{@=@>}'. When two or more
25516 messages are delivered down a single SMTP connection, an asterisk follows the
25517 IP address in the log lines for the second and subsequent messages.
25519 The generation of a reply message by a filter file gets logged as a `delivery'
25520 to the addressee, preceded by `>'.
25522 The \log@_selector\ option can be used to request the logging of additional
25523 data when a message is delivered. See section ~~SECTlogselector below.
25526 .section Discarded deliveries
25527 .index discarded messages
25528 .index message||discarded
25529 .index delivery||discarded, logging
25530 When a message is discarded as a result of the command `seen finish' being
25531 obeyed in a filter file which generates no deliveries, a log entry of the form
25533 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded
25534 <low.club@@bridge.example> R=userforward
25536 is written, to record why no deliveries are logged. When a message is discarded
25537 because it is aliased to `:blackhole:' the log line is like this:
25539 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole:
25540 <hole@nowhere.example> R=blackhole_router
25544 .section Deferred deliveries
25545 When a delivery is deferred, a line of the following form is logged:
25548 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@@endrest.example
25549 R=dnslookup T=smtp defer (146): Connection refused
25551 In the case of remote deliveries, the error is the one that was given for the
25552 last IP address that was tried. Details of individual SMTP failures are also
25553 written to the log, so the above line would be preceded by something like
25556 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to
25557 mail1.endrest.example [192.168.239.239]: Connection refused
25559 When a deferred address is skipped because its retry time has not been reached,
25560 a message is written to the log, but this can be suppressed by setting an
25561 appropriate value in \log@_selector\.
25564 .section Delivery failures
25565 .index delivery||failure, logging
25566 If a delivery fails because an address cannot be routed, a line of the
25567 following form is logged:
25570 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example
25571 <jim@trek99.example>: unknown mail domain
25573 If a delivery fails at transport time, the router and transport are shown, and
25574 the response from the remote host is included, as in this example:
25577 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example R=dnslookup
25580 T=remote_smtp: SMTP error from remote mailer after pipelined
25583 RCPT TO:<ace400@pb.example>: host pbmail3.py.example
25584 [192.168.63.111]: 553 5.3.0 <ace400@pb.example>...
25588 The word `pipelined' indicates that the SMTP \\PIPELINING\\ extension was being
25589 used. See \hosts@_avoid@_esmtp\ in the \%smtp%\ transport for a way of
25590 disabling \\PIPELINING\\.
25593 The log lines for all forms of delivery failure are flagged with \"**"\.
25596 .section Fake deliveries
25597 .index delivery||fake, logging
25598 If a delivery does not actually take place because the \-N-\ option has been
25599 used to suppress it, a normal delivery line is written to the log, except that
25600 `=>' is replaced by `$*$>'.
25603 .section Completion
25606 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed
25608 is written to the main log when a message is about to be removed from the spool
25609 at the end of its processing.
25613 .section Summary of Fields in Log Lines
25614 .index log||summary of fields
25615 A summary of the field identifiers that are used in log lines is shown in
25616 the following table:
25619 A $t $rm{authenticator name (and optional id)}
25620 C $t $rm{SMTP confirmation on delivery}
25623 CV $t $rm{certificate verification status}
25624 DN $t $rm{distinguished name from peer certificate}
25625 DT $t $rm{time taken for a delivery}
25628 F $t $rm{sender address (on delivery lines)}
25629 H $t $rm{host name and IP address}
25632 I $t $rm{local interface used}
25635 id $t $rm{message id for incoming message}
25636 P $t $rm{on \"<="\ lines: protocol used}
25639 $t $rm{on \"=>"\ lines: return path}
25640 QT $t $rm{time spent on queue}
25643 R $t $rm{on \"<="\ lines: reference for local bounce}
25644 $t $rm{on \"=>"\ lines: router name}
25645 S $t $rm{size of message}
25646 ST $t $rm{shadow transport name}
25647 T $t $rm{on \"<="\ lines: message subject (topic)}
25648 $t $rm{on \"=>"\ lines: transport name}
25649 U $t $rm{local user or RFC 1413 identity}
25650 X $t $rm{TLS cipher suite}
25654 .section Other log entries
25655 Various other types of log entry are written from time to time. Most should be
25656 self-explanatory. Among the more common are:
25658 .index retry||time not reached
25659 \*retry time not reached*\##An address previously suffered a temporary error
25660 during routing or local delivery, and the time to retry has not yet arrived.
25661 This message is not written to an individual message log file unless it happens
25662 during the first delivery attempt.
25664 \*retry time not reached for any host*\##An address previously suffered
25665 temporary errors during remote delivery, and the retry time has not yet arrived
25666 for any of the hosts to which it is routed.
25668 .index spool directory||file locked
25669 \*spool file locked*\##An attempt to deliver a message cannot proceed because
25670 some other Exim process is already working on the message. This can be quite
25671 common if queue running processes are started at frequent intervals. The
25672 \*exiwhat*\ utility script can be used to find out what Exim processes are
25676 .index error||ignored
25677 \*error ignored*\##There are several circumstances that give rise to this
25680 Exim failed to deliver a bounce message whose age was greater than
25681 \ignore__bounce__errors__after\. The bounce was discarded.
25683 A filter file set up a delivery using the `noerror' option, and the delivery
25684 failed. The delivery was discarded.
25686 A delivery set up by a router configured with
25690 failed. The delivery was discarded.
25697 .section Reducing or increasing what is logged
25698 .rset SECTlogselector "~~chapter.~~section"
25699 .index log||selectors
25700 By setting the \log@_selector\ global option, you can disable some of Exim's
25701 default logging, or you can request additional logging. The value of
25702 \log@_selector\ is made up of names preceded by plus or minus characters. For
25705 log_selector = +arguments -retry_defer
25707 The list of optional log items is in the following table, with the default
25708 selection marked by asterisks:
25711 address@_rewrite $t $rm{address rewriting}
25712 all@_parents $t $rm{all parents in => lines}
25713 arguments $t $rm{command line arguments}
25714 *connection@_reject $t $rm{connection rejections}
25715 *delay@_delivery $t $rm{immediate delivery delayed (message queued)}
25718 deliver@_time $t $rm{time taken to perform delivery}
25721 delivery@_size $t $rm{add S=nnn to => lines}
25722 *dnslist@_defer $t $rm{defers of DNS list (aka RBL) lookups}
25723 *etrn $t $rm{ETRN commands}
25724 *host@_lookup@_failed $t $rm{as it says}
25727 ident@_timeout $t $rm{timeout for ident connection}
25730 incoming@_interface $t $rm{incoming interface on <= lines}
25731 incoming@_port $t $rm{incoming port on <= lines}
25732 *lost@_incoming@_connection $t $rm{as it says (includes timeouts)}
25735 outgoing@_port $t $rm{add remote port to => lines}
25738 *queue@_run $t $rm{start and end queue runs}
25741 queue@_time $t $rm{time on queue}
25744 received@_recipients $t $rm{recipients on <= lines}
25745 received@_sender $t $rm{sender on <= lines}
25746 *rejected@_header $t $rm{header contents on reject log}
25747 *retry@_defer $t $rm{`retry time not reached'}
25750 return@_path@_on@_delivery $t $rm{put return path on => and ** lines}
25753 sender@_on@_delivery $t $rm{add sender to => lines}
25754 *size@_reject $t $rm{rejection because too big}
25755 *skip@_delivery $t $rm{`message is frozen', `spool file is locked'}
25758 smtp@_confirmation $t $rm{SMTP confirmation on => lines}
25761 smtp@_connection $t $rm{SMTP connections}
25762 smtp@_incomplete@_transaction $t $rm{incomplete SMTP transactions}
25763 smtp@_protocol@_error $t $rm{SMTP protocol errors}
25764 smtp@_syntax@_error $t $rm{SMTP syntax errors}
25765 subject $t $rm{contents of ::Subject:: on <= lines}
25768 tls@_certificate@_verified $t $rm{certificate verification status}
25771 *tls@_cipher $t $rm{TLS cipher suite on <= and => lines}
25772 tls@_peerdn $t $rm{TLS peer DN on <= and => lines}
25774 all $t $rm{all of the above}
25776 More details on each of these items follows:
25778 .index log||rewriting
25779 .index rewriting||logging
25780 \address@_rewrite\: This applies both to global rewrites and per-transport
25783 but not to rewrites in filters run as an unprivileged user (because such users
25784 cannot access the log).
25787 .index log||full parentage
25788 \all@_parents\: Normally only the original and final addresses are logged on
25789 delivery lines; with this selector, intermediate parents are given in
25790 parentheses between them.
25792 .index log||Exim arguments
25793 .index Exim arguments, logging
25794 \arguments\: This causes Exim to write the arguments with which it was called
25796 preceded by the current working directory.
25797 This is a debugging feature, added to make it easier to find out how certain
25798 MUAs call \(/usr/sbin/sendmail)\. The logging does not happen if Exim has given
25799 up root privilege because it was called with the \-C-\ or \-D-\ options.
25800 Arguments that are empty or that contain whitespace are quoted. Non-printing
25801 characters are shown as escape sequences.
25802 This facility cannot log unrecognized arguments, because the arguments are
25803 checked before the configuration file is read. The only way to log such cases
25804 is to interpose a script such as \(util/logargs.sh)\ between the caller and
25807 .index log||connection rejections
25808 \connection@_reject\: A log entry is written whenever an incoming SMTP
25809 connection is rejected, for whatever reason.
25811 .index log||delayed delivery
25812 .index delayed delivery, logging
25813 \delay@_delivery\: A log entry is written whenever a delivery process is not
25814 started for an incoming message because the load is too high or too many
25815 messages were received on one connection. Logging does not occur if no delivery
25816 process is started because \queue@_only\ is set or \-odq-\ was used.
25819 .index log||delivery duration
25820 \deliver@_time\: For each delivery, the amount of real time it has taken to
25821 perform the actual delivery is logged as DT=<<time>>, for example, \"DT=1s"\.
25824 .index log||message size on delivery
25825 .index size||of message
25826 \delivery@_size\: For each delivery, the size of message delivered is added to
25827 the `=>' line, tagged with S=.
25829 .index log||dnslist defer
25830 .index DNS list||logging defer
25831 .index black list (DNS)
25832 \dnslist@_defer\: A log entry is written if an attempt to look up a host in a
25833 DNS black list suffers a temporary error.
25835 .index log||ETRN commands
25836 .index \\ETRN\\||logging
25837 \etrn\: Every legal ETRN command that is received is logged, before the ACL is
25838 run to determine whether or not it is actually accepted. An invalid ETRN
25839 command, or one received within a message transaction is not logged by this
25840 selector (see \smtp@_syntax@_error\ and \smtp@_protocol@_error\).
25842 .index log||host lookup failure
25843 \host@_lookup@_failed\: When a lookup of a host's IP addresses fails to find
25844 any addresses, or when a lookup of an IP address fails to find a host name, a
25845 log line is written. This logging does not apply to direct DNS lookups when
25846 routing email addresses, but it does apply to `byname' lookups.
25849 .index log||ident timeout
25850 .index RFC 1413||logging timeout
25851 \ident@_timeout\: A log line is written whenever an attempt to connect to a
25852 client's ident port times out.
25855 .index log||incoming interface
25856 .index interface||logging
25857 \incoming@_interface\: The interface on which a message was received is added
25858 to the `<=' line as an IP address in square brackets, tagged by I= and followed
25859 by a colon and the port number.
25861 The local interface and port are also added to other SMTP log
25862 lines, for example `SMTP connection from', and to rejection lines.
25865 .index log||incoming remote port
25866 .index port||logging remote
25867 .index TCP/IP||logging incoming remote port
25868 \incoming@_port\: The remote port number from which a message was received is
25869 added to log entries and ::Received:: header lines, following the IP address in
25870 square brackets, and separated from it by a colon. This is implemented by
25871 changing the value that is put in the \$sender@_fullhost$\ and
25872 \$sender@_rcvhost$\ variables. Recording the remote port number has become more
25873 important with the widening use of NAT (see RFC 2505).
25875 .index log||dropped connection
25876 \lost@_incoming@_connection\: A log line is written when an incoming SMTP
25877 connection is unexpectedly dropped.
25880 .index log||outgoing remote port
25881 .index port||logging outgoint remote
25882 .index TCP/IP||logging ougtoing remote port
25883 \outgoing@_port\: The remote port number is added to delivery log lines (those
25884 containing => tags) following the IP address. This option is not included in
25885 the default setting, because for most ordinary configurations, the remote port
25886 number is always 25 (the SMTP port).
25889 .index log||queue run
25890 .index queue runner||logging
25891 \queue@_run\: The start and end of every queue run are logged.
25894 .index log||queue time
25895 \queue@_time\: The amount of time the message has been in the queue on the
25896 local host is logged as QT=<<time>>, for example, \"QT=3m45s"\. The clock
25897 starts when Exim starts to receive the message, so it includes reception time
25898 as well as the delivery time of the current address.
25901 .index log||recipients
25902 \received@_recipients\: The recipients of a message are listed in the main log
25903 as soon as the message is received. The list appears at the end of the log line
25904 that is written when a message is received, preceded by the word `for'. The
25905 addresses are listed after they have been qualified, but before any rewriting
25907 Recipients that were discarded by an ACL for \\MAIL\\ or \\RCPT\\ do not appear
25910 .index log||sender reception
25911 \received@_sender\: The unrewritten original sender of a message is added to
25912 the end of the log line that records the message's arrival, after the word
25913 `from' (before the recipients if \received@_recipients\ is also set).
25915 .index log||header lines for rejection
25916 \rejected@_header\: If a message's header has been received at the time a
25917 rejection is written to the reject log, the complete header is added to the
25918 log. Header logging can be turned off individually for messages that are
25919 rejected by the \*local@_scan()*\ function (see section ~~SECTapiforloc).
25921 .index log||retry defer
25922 \retry@_defer\: A log line is written if a delivery is deferred because a retry
25923 time has not yet been reached. However, this `retry time not reached' message
25924 is always omitted from individual message logs after the first delivery
25927 .index log||return path
25929 \return@_path@_on@_delivery\: The return path that is being transmitted with
25930 the message is included in delivery and bounce lines, using the tag P=.
25933 .index log||sender on delivery
25934 \sender@_on@_delivery\: The message's sender address is added to every delivery
25935 and bounce line, tagged by F= (for `from').
25937 This is the original sender that was received with the message; it is not
25938 necessarily the same as the outgoing return path.
25941 .index log||size rejection
25942 \size@_reject\: A log line is written whenever a message is rejected because it
25945 .index log||frozen messages, skipped
25946 .index frozen messages||logging skipping
25947 \skip@_delivery\: A log line is written whenever a message is skipped during a
25948 queue run because it is frozen or because another process is already delivering
25951 .index log||smtp confirmation
25952 .index SMTP||logging confirmation
25953 \smtp@_confirmation\: The response to the final `.' in the SMTP dialogue for
25954 outgoing messages is added to delivery log lines in the form `C="<<text>>"'. A
25955 number of MTAs (including Exim) return an identifying string in this response.
25957 .index log||SMTP connections
25958 .index SMTP||logging connections
25959 \smtp@_connection\: A log line is written whenever an SMTP connection is
25960 established or closed. (By contrast, \lost@_incoming@_connection\ applies only
25961 when the closure is unexpected.) This applies to connections from local
25962 processes that use \-bs-\ as well as to TCP/IP connections. If a connection is
25963 dropped in the middle of a message, a log line is always written, whether this
25964 selector is set or not, but otherwise nothing is written at the start and end
25965 of connections unless this selector is enabled.
25967 For TCP/IP connections to an Exim daemon, the current number of connections is
25968 included in the log message for each new connection, but note that the count is
25969 reset if the daemon is restarted.
25970 Also, because connections are closed (and the closure is logged) in
25971 subprocesses, the count may not include connections that have been closed but
25972 whose termination the daemon has not yet noticed. Thus, while it is possible to
25973 match up the opening and closing of connections in the log, the value of the
25974 logged counts may not be entirely accurate.
25976 .index log||SMTP transaction, incomplete
25977 .index SMTP||logging incomplete transactions
25978 \smtp@_incomplete@_transaction\: When a mail transaction is aborted by
25979 \\RSET\\, \\QUIT\\, loss of connection, or otherwise, the incident is logged,
25980 and the message sender plus any accepted recipients are included in the log
25981 line. This can provide evidence of dictionary attacks.
25983 .index log||SMTP protocol error
25984 .index SMTP||logging protocol error
25985 \smtp@_protocol@_error\: A log line is written for every SMTP protocol error
25988 Exim does not have perfect detection of all protocol errors because of
25989 transmission delays and the use of pipelining. If \\PIPELINING\\ has been
25990 advertised to a client, an Exim server assumes that the client will use it, and
25991 therefore it does not count `expected' errors (for example, \\RCPT\\ received
25992 after rejecting \\MAIL\\) as protocol errors.
25995 .index SMTP||logging syntax errors
25996 .index SMTP||syntax errors, logging
25997 .index SMTP||unknown command, logging
25998 .index log||unknown SMTP command
25999 .index log||SMTP syntax error
26000 \smtp@_syntax@_error\: A log line is written for every SMTP syntax error
26001 encountered. An unrecognized command is treated as a syntax error. For an
26002 external connection, the host identity is given; for an internal connection
26003 using \-bs-\ the sender identification (normally the calling user) is given.
26005 .index log||subject
26006 .index subject, logging
26007 \subject\: The subject of the message is added to the arrival log line,
26008 preceded by `T=' (T for `topic', since S is already used for `size').
26009 Any MIME `words' in the subject are decoded. The \print@_topbitchars\ option
26010 specifies whether characters with values greater than 127 should be logged
26011 unchanged, or whether they should be rendered as escape sequences.
26013 .index log||certificate verification
26015 \tls@_certificate@_verified\: An extra item is added to <= and => log lines
26016 when TLS is in use. The item is \"CV=yes"\ if the peer's certificate was
26017 verified, and \"CV=no"\ if not.
26020 .index log||TLS cipher
26021 .index TLS||logging cipher
26022 \tls@_cipher\: When a message is sent or received over an encrypted connection,
26023 the cipher suite used is added to the log line, preceded by X=.
26025 .index log||TLS peer DN
26026 .index TLS||logging peer DN
26027 \tls@_peerdn\: When a message is sent or received over an encrypted connection,
26028 and a certificate is supplied by the remote host, the peer DN is added to the
26029 log line, preceded by DN=.
26032 .section Message log
26033 .index message||log file for
26034 .index log||message log, description of
26035 In addition to the general log files, Exim writes a log file for each message
26036 that it handles. The names of these per-message logs are the message ids, and
26037 .index \(msglog)\ directory
26038 they are kept in the \(msglog)\ sub-directory of the spool directory. Each
26039 message log contains copies of the log lines that apply to the message. This
26040 makes it easier to inspect the status of an individual message without having
26041 to search the main log. A message log is deleted when processing of the message
26043 .index \preserve@_message@_logs\
26044 unless \preserve__message__logs\ is set, but this should be used only with
26045 great care because they can fill up your disk very quickly.
26047 On a heavily loaded system, it may be desirable to disable the use of
26048 per-message logs, in order to reduce disk I/O. This can be done by setting the
26049 \message@_logs\ option false.
26056 . ============================================================================
26057 .chapter Exim utilities
26058 .set runningfoot "utilities"
26059 .rset CHAPutils ~~chapter
26061 A number of utility scripts and programs are supplied with Exim and are
26062 described in this chapter. There is also the Exim Monitor, which is covered in
26063 the next chapter. The utilities described here are:
26065 . This duplication seems to be the only way to arrange that the cross-
26066 . references are omitted in the Texinfo version. They look horribly ugly.
26071 \*exiwhat*\ $t $rm{list what Exim processes are doing}
26073 \*exiqgrep*\ $t $rm{grep the queue}
26075 \*exiqsumm*\ $t $rm{summarize the queue}
26076 \*exigrep*\ $t $rm{search the main log}
26077 \*exipick*\ $t $rm{select messages on various criteria}
26078 \*exicyclog*\ $t $rm{cycle (rotate) log files}
26079 \*eximstats*\ $t $rm{extract statistics from the log}
26080 \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP}
26081 \*exim@_dbmbuild*\ $t $rm{build a DBM file}
26082 \*exinext*\ $t $rm{extract retry information}
26083 \*exim@_dumpdb*\ $t $rm{dump a hints database}
26084 \*exim@_tidydb*\ $t $rm{clean up a hints database}
26085 \*exim@_fixdb*\ $t $rm{patch a hints database}
26086 \*exim@_lock*\ $t $rm{lock a mailbox file}
26093 ~~SECTfinoutwha \*exiwhat*\ $t $rm{list what Exim processes are doing}
26095 ~~SECTgreptheque \*exiqgrep*\ $t $rm{grep the queue}
26097 ~~SECTsumtheque \*exiqsumm*\ $t $rm{summarize the queue}
26098 ~~SECTextspeinf \*exigrep*\ $t $rm{search the main log}
26101 ~~SECTexipick \*exipick*\ $t $rm{select messages on various criteria}
26104 ~~SECTcyclogfil \*exicyclog*\ $t $rm{cycle (rotate) log files}
26105 ~~SECTmailstat \*eximstats*\ $t $rm{extract statistics from the log}
26106 ~~SECTcheckaccess \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP}
26107 ~~SECTdbmbuild \*exim@_dbmbuild*\ $t $rm{build a DBM file}
26108 ~~SECTfinindret \*exinext*\ $t $rm{extract retry information}
26109 ~~SECThindatmai \*exim@_dumpdb*\ $t $rm{dump a hints database}
26110 ~~SECThindatmai \*exim@_tidydb*\ $t $rm{clean up a hints database}
26111 ~~SECThindatmai \*exim@_fixdb*\ $t $rm{patch a hints database}
26112 ~~SECTmailboxmaint \*exim@_lock*\ $t $rm{lock a mailbox file}
26116 .section Finding out what Exim processes are doing (exiwhat)
26117 .rset SECTfinoutwha "~~chapter.~~section"
26119 .index process, querying
26121 On operating systems that can restart a system call after receiving a signal
26122 (most modern OS), an Exim process responds to the \\SIGUSR1\\ signal by writing
26123 a line describing what it is doing to the file \(exim-process.info)\ in the
26124 Exim spool directory. The \*exiwhat*\ script sends the signal to all Exim
26125 processes it can find, having first emptied the file. It then waits for one
26126 second to allow the Exim processes to react before displaying the results.
26127 In order to run \*exiwhat*\ successfully you have to have sufficient privilege to
26128 send the signal to the Exim processes, so it is normally run as root.
26130 Unfortunately, the \*ps*\ command which \*exiwhat*\ uses to find Exim processes
26131 varies in different operating systems. Not only are different options used,
26132 but the format of the output is different. For this reason, there are some
26133 system configuration options that configure exactly how \*exiwhat*\ works. If it
26134 doesn't seem to be working for you, check the following compile-time options:
26136 EXIWHAT@_PS@_CMD $rm{the command for running \*ps*\}
26137 EXIWHAT@_PS@_ARG $rm{the argument for \*ps*\}
26138 EXIWHAT@_EGREP@_ARG $rm{the argument for \*egrep*\ to select from \*ps*\ output}
26139 EXIWHAT@_KILL@_ARG $rm{the argument for the \*kill*\ command}
26141 An example of typical output from \*exiwhat*\ is
26144 164 daemon: -q1h, listening on port 25
26145 10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
26146 10492 delivering 0tAycK-0002ij-00 to mail.ref.example [10.19.42.42]
26147 (editor@@ref.example)
26148 10592 handling incoming call from [192.168.243.242]
26149 10628 accepting a local non-SMTP message
26151 The first number in the output line is the process number. The third line has
26152 been split here, in order to fit it on the page.
26155 .section Selective queue listing (exiqgrep)
26156 .rset SECTgreptheque "~~chapter.~~section"
26157 .index \*exiqgrep*\
26158 .index queue||grepping
26159 This utility is a Perl script contributed by Matt Hubbard. It runs
26163 to obtain a queue listing with undelivered recipients only, and then greps the
26164 output to select messages that match given criteria. The following selection
26165 options are available:
26169 .option f <<regex>>
26170 Match the sender address. The field that is tested is enclosed in angle
26171 brackets, so you can test for bounce messages with
26176 .option r <<regex>>
26177 Match a recipient address. The field that is tested is not enclosed in angle
26180 .option s <<regex>>
26181 Match against the size field.
26183 .option y <<seconds>>
26184 Match messages that are younger than the given time.
26186 .option o <<seconds>>
26187 Match messages that are older than the given time.
26190 Match only frozen messages.
26193 Match only non-frozen messages.
26197 The following options control the format of the output:
26202 Display only the count of matching messages.
26205 Long format -- display the full message information as output by Exim. This is
26209 Display message ids only.
26212 Brief format -- one line per message.
26215 Display messages in reverse order.
26219 There is one more option, \-h-\, which outputs a list of options.
26222 .section Summarising the queue (exiqsumm)
26223 .rset SECTsumtheque "~~chapter.~~section"
26224 .index \*exiqsumm*\
26225 .index queue||summary
26226 The \*exiqsumm*\ utility is a Perl script which reads the output of \*exim
26227 -bp*\ and produces a summary of the messages on the queue. Thus, you use it by
26228 running a command such as
26230 exim -bp | exiqsumm
26232 The output consists of one line for each domain that has messages waiting for
26233 it, as in the following example:
26235 3 2322 74m 66m msn.com.example
26237 Each line lists the number of
26238 pending deliveries for a domain, their total volume, and the length of time
26239 that the oldest and the newest messages have been waiting. Note that the number
26240 of pending deliveries is greater than the number of messages when messages
26241 have more than one recipient.
26243 A summary line is output at the end. By default the output is sorted on the
26244 domain name, but \*exiqsumm*\ has the options \-a-\ and \-c-\, which cause the
26245 output to be sorted by oldest message and by count of messages, respectively.
26247 The output of \*exim -bp*\ contains the original addresses in the message, so
26248 this also applies to the output from \*exiqsumm*\. No domains from addresses
26249 generated by aliasing or forwarding are included (unless the \one@_time\ option
26250 of the \%redirect%\ router has been used to convert them into `top level'
26255 .section Extracting specific information from the log (exigrep)
26256 .rset SECTextspeinf "~~chapter.~~section"
26258 .index log||extracts, grepping for
26259 The \*exigrep*\ utility is a Perl script that searches one or more main log
26260 files for entries that match a given pattern. When it finds a match, it
26261 extracts all the log entries for the relevant message, not just those that
26262 match the pattern. Thus, \*exigrep*\ can extract complete log entries for a
26263 given message, or all mail for a given user, or for a given host, for example.
26266 If a matching log line is not associated with a specific message, it is always
26267 included in \*exigrep*\'s output.
26271 exigrep [-l] [-t<n>] <pattern> [<log file>] ...
26273 The \-t-\ argument specifies a number of seconds. It adds an additional
26274 condition for message selection. Messages that are complete are shown only if
26275 they spent more than <<n>> seconds on the queue.
26277 The \-l-\ flag means `literal', that is, treat all characters in the
26278 pattern as standing for themselves. Otherwise the pattern must be a Perl
26279 regular expression. The pattern match is case-insensitive. If no file names are
26280 given on the command line, the standard input is read.
26282 If the location of a \*zcat*\ command is known from the definition of
26283 \\ZCAT@_COMMAND\\ in \(Local/Makefile)\, \*exigrep*\ automatically passes any
26284 file whose name ends in \\COMPRESS@_SUFFIX\\ through \*zcat*\ as it searches
26288 .section Selecting messages by various criteria (exipick)
26289 .rset SECTexipick "~~chapter.~~section"
26291 John Jetmore's \*exipick*\ utility is included in the Exim distribution. It
26292 lists messages from the queue according to a variety of criteria. For details,
26300 .section Cycling log files (exicyclog)
26301 .rset SECTcyclogfil "~~chapter.~~section"
26302 .index log||cycling local files
26303 .index cycling logs
26304 .index \*exicyclog*\
26305 The \*exicyclog*\ script can be used to cycle (rotate) \*mainlog*\ and
26306 \*rejectlog*\ files. This is not necessary if only syslog is being used,
26307 or if you are using log files with datestamps in their names (see section
26309 Some operating systems have their own standard mechanisms for log cycling, and
26310 these can be used instead of \*exicyclog*\ if preferred.
26312 Each time \*exicyclog*\ is run the file names get `shuffled down' by one. If the
26313 main log file name is \(mainlog)\ (the default) then when \*exicyclog*\ is run
26314 \(mainlog)\ becomes \(mainlog.01)\, the previous \(mainlog.01)\ becomes
26315 \(mainlog.02)\ and so on, up to a limit which is set in the script, and which
26316 defaults to 10. Reject logs are handled similarly.
26318 If no \(mainlog)\ file exists, the script does nothing. Files that `drop off'
26319 the end are deleted. All files with numbers greater than 01 are compressed,
26320 using a compression command which is configured by the \\COMPRESS@_COMMAND\\
26321 setting in \(Local/Makefile)\. It is usual to run \*exicyclog*\ daily from a
26322 root \crontab\ entry of the form
26324 1 0 * * * su exim -c /usr/exim/bin/exicyclog
26326 assuming you have used the name `exim' for the Exim user. You can run
26327 \*exicyclog*\ as root if you wish, but there is no need.
26330 .section Mail statistics (eximstats)
26331 .rset SECTmailstat "~~chapter.~~section"
26333 .index \*eximstats*\
26334 A Perl script called \*eximstats*\ is provided for extracting statistical
26335 information from log files. The output is either plain text, or HTML.
26336 Exim log files are also suported by the \*Lire*\ system produced by the
26337 LogReport Foundation (\?http://www.logreport.org?\).
26339 The \*eximstats*\ script has been hacked about quite a bit over time. The
26340 latest version is the result of some extensive revision by Steve Campbell. A
26341 lot of information is given by default, but there are options for suppressing
26342 various parts of it. Following any options, the arguments to the script are a
26343 list of files, which should be main log files. For example:
26345 eximstats -nr /var/spool/exim/log/mainlog.01
26347 By default, \*eximstats*\ extracts information about the number and volume of
26348 messages received from or delivered to various hosts. The information is sorted
26349 both by message count and by volume, and the top fifty hosts in each category
26350 are listed on the standard output. Similar information, based on email
26351 addresses or domains instead of hosts can be requested by means of various
26352 options. For messages delivered and received locally, similar statistics are
26353 also produced per user.
26355 The output also includes total counts and statistics about delivery errors, and
26356 histograms showing the number of messages received and deliveries made in each
26357 hour of the day. A delivery with more than one address in its envelope (for
26358 example, an SMTP transaction with more than one \\RCPT\\ command) is counted
26359 as a single delivery by \*eximstats*\.
26361 Though normally more deliveries than receipts are reported (as messages may
26362 have multiple recipients), it is possible for \*eximstats*\ to report more
26363 messages received than delivered, even though the queue is empty at the start
26364 and end of the period in question. If an incoming message contains no valid
26365 recipients, no deliveries are recorded for it. A bounce message is handled as
26366 an entirely separate message.
26368 \*eximstats*\ always outputs a grand total summary giving the volume and number
26369 of messages received and deliveries made, and the number of hosts involved in
26370 each case. It also outputs the number of messages that were delayed (that is,
26371 not completely delivered at the first attempt), and the number that had at
26372 least one address that failed.
26374 The remainder of the output is in sections that can be independently disabled
26375 or modified by various options. It consists of a summary of deliveries by
26376 transport, histograms of messages received and delivered per time interval
26377 (default per hour), information about the time messages spent on the queue,
26378 a list of relayed messages, lists of the top fifty sending hosts, local
26379 senders, destination hosts, and destination local users by count and by volume,
26380 and a list of delivery errors that occurred.
26382 The relay information lists messages that were actually relayed, that is, they
26383 came from a remote host and were directly delivered to some other remote host,
26384 without being processed (for example, for aliasing or forwarding) locally.
26386 The options for \*eximstats*\ are as follows:
26389 .index \*eximstats*\||options
26391 The `league tables' are computed on the basis of the superior domains of the
26392 sending hosts instead of the sending and receiving hosts. This option may be
26393 combined with \-byhost-\ and/or \-byemail-\.
26396 This is a synonym for \-byemaildomain-\.
26399 The `league tables' are computed on the basis of complete email addresses,
26400 instead of sending and receiving hosts. This option may be combined with
26401 \-byhost-\ and/or \-bydomain-\.
26403 .option byemaildomain
26404 The `league tables' are computed on the basis of the sender's email domain
26405 instead of the sending and receiving hosts. This option may be combined with
26406 \-byhost-\, \-bydomain-\, or \-byemail-\.
26409 The `league tables' are computed on the basis of sending and receiving hosts.
26410 This is the default option. It may be combined with \-bydomain-\ and/or
26414 Cache results of \*timegm()*\ lookups. This results in a significant speedup
26415 when processing hundreds of thousands of messages, at a cost of increasing the
26416 memory utilisation.
26418 .option chartdir <<dir>>
26419 When \-charts-\ is specified, create the charts in the directory <<dir>>.
26421 .option chartrel <<dir>>
26422 When \-charts-\ is specified, this option specifies the relative directory for
26423 the \"img src="\ tags from where to include the charts.
26426 Create graphical charts to be displayed in HTML output. This requires the
26427 \"GD"\, \"GDTextUtil"\, and \"GDGraph"\ Perl modules, which can be obtained
26428 from \?http://www.cpan.org/modules/01modules.index.html?\.
26430 To install these, download and unpack them, then use the normal Perl
26431 installation procedure:
26440 This is a debug flag. It causes \*eximstats*\ to output the \*eval()*\'d parser
26441 to the standard output, which makes it easier to trap errors in the eval
26442 section. Remember to add one to the line numbers to allow for the title.
26446 Show help information about \*eximstats*\' options.
26449 This option controls the histograms of messages received and deliveries per
26450 time interval. By default the time interval is one hour. If \-h0-\ is given,
26451 the histograms are suppressed; otherwise the value of <<n>> gives the number of
26452 divisions per hour. Valid values are 0, 1, 2, 3, 5, 10, 15, 20, 30 or 60, so
26453 \-h2-\ sets an interval of 30 minutes, and the default is equivalent to \-h1-\.
26456 Output the results in HTML instead of plain text.
26459 This option causes \*eximstats*\ to merge old reports into a combined report.
26460 When this option is used, the input files must be outputs from previous calls
26461 to \*eximstats*\, not raw log files. For example, you could produce a set of
26462 daily reports and a weekly report by commands such as
26464 eximstats mainlog.sun > report.sun.txt
26465 eximstats mainlog.mon > report.mon.txt
26466 eximstats mainlog.tue > report.tue.txt
26467 eximstats mainlog.wed > report.wed.txt
26468 eximstats mainlog.thu > report.thu.txt
26469 eximstats mainlog.fri > report.fri.txt
26470 eximstats mainlog.sat > report.sat.txt
26471 eximstats -merge -html report.*.txt > weekly_report.html
26473 You can merge text or html reports and output the results as text or html. You
26474 can use all the normal \*eximstats*\ output options, but only data included in
26475 the original reports can be shown. When merging reports, some loss of accuracy
26476 may occur in the `league tables', towards the ends of the lists. The order of
26477 items in the `league tables' may vary when the data volumes round to the same
26481 Suppress the display of information about failed deliveries (errors).
26484 Suppress information about messages relayed through this host.
26486 .option nr /pattern/
26487 Suppress information about relayed messages that match the pattern, which is
26488 matched against a string of the following form (split over two lines here in
26489 order to fit it on the page):
26491 H=<host> [<ip address>] A=<sender address> =>
26492 H=<host> A=<recipient address>
26496 H=in.host [1.2.3.4] A=from@some.where.example =>
26497 H=out.host A=to@else.where.example
26499 The sending host name appears in parentheses if it has not been verified as
26500 matching the IP address. The mail addresses are taken from the envelope, not
26501 the headers. This option allows you to screen out hosts whom you are happy to
26502 have using your host as a relay.
26505 Suppress the statistics about delivery by transport.
26507 .option nt/<<pattern>>/
26508 Suppress the statistics about delivery by any transport whose name matches the
26509 pattern. If you are using one transport to send all messages to a scanning
26510 mechanism before doing the real delivery, this feature can be used to omit that
26511 transport from your normal statistics (on the grounds that it is of no
26515 .option "pattern" "#<<description>>#/<<pattern>>/"
26516 Count lines matching specified patterns and show them in
26517 the results. For example:
26519 -pattern 'Refused connections' '/refused connection/'
26521 This option can be specified multiple times.
26524 Suppress information about times messages spend on the queue.
26526 .option q <<n1>>...
26527 This option sets an alternative list of time intervals for the queueing
26528 information. The values are separated by commas and are in seconds, but can
26529 involve arithmetic multipliers, so for example you can set 3$*$60 to specify 3
26530 minutes. A setting such as
26534 causes \*eximstats*\ to give counts of messages that stayed on the queue for less
26535 than one minute, less than five minutes, less than ten minutes, and over ten
26539 Sets the `top' count to <<n>>. This controls the listings of the `top <<n>>'
26540 hosts and users by count and volume. The default is 50, and setting 0
26541 suppresses the output altogether.
26544 Omit local information from the `top' listings.
26546 .option t@_remote@_users
26547 Include remote users in the `top' listings.
26552 .section Checking access policy (exim@_checkaccess)
26553 .rset SECTcheckaccess "~~chapter.~~section"
26554 .index \*exim@_checkaccess*\
26555 .index policy control||checking access
26556 .index checking access
26557 The \-bh-\ command line argument allows you to run a fake SMTP session with
26558 debugging output, in order to check what Exim is doing when it is applying
26559 policy controls to incoming SMTP mail. However, not everybody is sufficiently
26560 familiar with the SMTP protocol to be able to make full use of \-bh-\, and
26561 sometimes you just want to answer the question \*Does this address have
26562 access?*\ without bothering with any further details.
26564 The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\. It takes
26565 two arguments, an IP address and an email address:
26567 exim_checkaccess 10.9.8.7 A.User@a.domain.example
26569 The utility runs a call to Exim with the \-bh-\ option, to test whether the
26570 given email address would be accepted in a \\RCPT\\ command in a TCP/IP
26571 connection from the host with the given IP address. The output of the utility
26572 is either the word `accepted', or the SMTP error response, for example:
26575 550 Relay not permitted
26577 When running this test, the utility uses \"<>"\ as the envelope sender address
26578 for the \\MAIL\\ command, but you can change this by providing additional
26579 options. These are passed directly to the Exim command. For example, to specify
26580 that the test is to be run with the sender address \*himself@@there.example*\
26583 exim_checkaccess 10.9.8.7 A.User@a.domain.example \
26584 -f himself@there.example
26586 Note that these additional Exim command line items must be given after the two
26587 mandatory arguments.
26589 Because the \exim@_checkaccess\ uses \-bh-\, it does not perform callouts while
26590 running its checks. You can run checks that include callouts by using \-bhc-\,
26591 but this is not yet available in a `packaged' form.
26594 .section Making DBM files (exim@_dbmbuild)
26595 .rset SECTdbmbuild "~~chapter.~~section"
26596 .index DBM||building dbm files
26597 .index building DBM files
26598 .index \*exim@_dbmbuild*\
26599 .index lower casing
26600 .index binary zero||in lookup key
26601 The \*exim@_dbmbuild*\ program reads an input file containing keys and data in
26602 the format used by the \%lsearch%\ lookup (see section ~~SECTsinglekeylookups).
26603 It writes a DBM file using the lower-cased alias names as keys and the
26604 remainder of the information as data. The lower-casing can be prevented by
26605 calling the program with the \-nolc-\ option.
26607 A terminating zero is included as part of the key string. This is expected by
26608 the \%dbm%\ lookup type. However, if the option \-nozero-\ is given,
26609 \*exim@_dbmbuild*\ creates files without terminating zeroes in either the key
26610 strings or the data strings. The \%dbmnz%\ lookup type can be used with such
26613 The program requires two arguments: the name of the input file (which can be a
26614 single hyphen to indicate the standard input), and the name of the output file.
26615 It creates the output under a temporary name, and then renames it if all went
26618 If the native DB interface is in use (\\USE@_DB\\ is set in a compile-time
26619 configuration file -- this is common in free versions of Unix) the two file
26620 names must be different, because in this mode the Berkeley DB functions create
26621 a single output file using exactly the name given. For example,
26623 exim_dbmbuild /etc/aliases /etc/aliases.db
26625 reads the system alias file and creates a DBM version of it in
26626 \(/etc/aliases.db)\.
26628 In systems that use the \*ndbm*\ routines (mostly proprietary versions of Unix),
26629 two files are used, with the suffixes \(.dir)\ and \(.pag)\. In this
26630 environment, the suffixes are added to the second argument of
26631 \*exim@_dbmbuild*\, so it can be the same as the first. This is also the case
26632 when the Berkeley functions are used in compatibility mode (though this is not
26633 recommended), because in that case it adds a \(.db)\ suffix to the file name.
26635 If a duplicate key is encountered, the program outputs a warning, and when it
26636 finishes, its return code is 1 rather than zero, unless the \-noduperr-\ option
26637 is used. By default, only the first of a set of duplicates is used -- this
26638 makes it compatible with \%lsearch%\ lookups. There is an option \-lastdup-\
26639 which causes it to use the data for the last duplicate instead. There is also
26640 an option \-nowarn-\, which stops it listing duplicate keys to \stderr\. For
26641 other errors, where it doesn't actually make a new file, the return code is 2.
26645 .section Finding individual retry times (exinext)
26646 .rset SECTfinindret "~~chapter.~~section"
26647 .index retry||times
26649 A utility called \*exinext*\ (mostly a Perl script) provides the ability to fish
26650 specific information out of the retry database. Given a mail domain (or a
26651 complete address), it looks up the hosts for that domain, and outputs any retry
26652 information for the hosts or for the domain. At present, the retry information
26653 is obtained by running \*exim@_dumpdb*\ (see below) and post-processing the
26654 output. For example:
26656 $ exinext piglet@milne.fict.example
26657 kanga.milne.fict.example:192.168.8.1 error 146: Connection refused
26658 first failed: 21-Feb-1996 14:57:34
26659 last tried: 21-Feb-1996 14:57:34
26660 next try at: 21-Feb-1996 15:02:34
26661 roo.milne.fict.example:192.168.8.3 error 146: Connection refused
26662 first failed: 20-Jan-1996 13:12:08
26663 last tried: 21-Feb-1996 11:42:03
26664 next try at: 21-Feb-1996 19:42:03
26665 past final cutoff time
26667 You can also give \*exinext*\ a local part, without a domain, and it
26668 will give any retry information for that local part in your default domain.
26669 A message id can be used to obtain retry information pertaining to a specific
26670 message. This exists only when an attempt to deliver a message to a remote host
26671 suffers a message-specific error (see section ~~SECToutSMTPerr). \*exinext*\ is
26672 not particularly efficient, but then it isn't expected to be run very often.
26675 The \*exinext*\ utility calls Exim to find out information such as the location
26676 of the spool directory. The utility has \-C-\ and \-D-\ options, which are
26677 passed on to the \*exim*\ commands. The first specifies an alternate Exim
26678 configuration file, and the second sets macros for use within the configuration
26679 file. These features are mainly to help in testing, but might also be useful in
26680 environments where more than one configuration file is in use.
26685 .section Hints database maintenance (exim@_dumpdb, exim@_fixdb, exim@_tidydb)
26686 .rset SECThindatmai "~~chapter.~~section"
26687 .index hints database||maintenance
26688 .index maintaining Exim's hints database
26689 Three utility programs are provided for maintaining the DBM files that Exim
26690 uses to contain its delivery hint information. Each program requires two
26691 arguments. The first specifies the name of Exim's spool directory, and the
26692 second is the name of the database it is to operate on. These are as
26695 \*retry*\: the database of retry information
26697 \*wait-*\<<transport name>>: databases of information about messages waiting
26701 \*callout*\: the callout cache
26704 \*misc*\: other hints data
26707 The \*misc*\ database is used for
26709 Serializing \\ETRN\\ runs (when \smtp@_etrn@_serialize\ is set)
26711 Serializing delivery to a specific host (when \serialize@_hosts\ is set in an
26712 \%smtp%\ transport)
26715 .index \*exim@_dumpdb*\
26716 The entire contents of a database are written to the standard output by the
26717 \*exim@_dumpdb*\ program, which has no options or arguments other than the
26718 spool and database names. For example, to dump the retry database:
26720 exim_dumpdb /var/spool/exim retry
26722 Two lines of output are produced for each entry:
26724 T:mail.ref.example:192.168.242.242 146 77 Connection refused
26725 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 *
26727 The first item on the first line is the key of the record. It starts with one
26728 of the letters R, or T, depending on whether it refers to a routing or
26729 transport retry. For a local delivery, the next part is the local address; for
26730 a remote delivery it is the name of the remote host, followed by its failing IP
26731 address (unless \no@_retry@_include@_ip@_address\ is set on the \%smtp%\
26734 If the remote port is not the standard one (port 25), it is added to the IP
26737 Then there follows an error code, an additional error code, and a
26738 textual description of the error.
26740 The three times on the second line are the time of first failure, the time of
26741 the last delivery attempt, and the computed time for the next attempt. The line
26742 ends with an asterisk if the cutoff time for the last retry rule has been
26745 Each output line from \*exim@_dumpdb*\ for the \*wait-*\$it{xxx} databases
26746 consists of a host name followed by a list of ids for messages that are or were
26747 waiting to be delivered to that host. If there are a very large number for any
26748 one host, continuation records, with a sequence number added to the host name,
26749 may be seen. The data in these records is often out of date, because a message
26750 may be routed to several alternative hosts, and Exim makes no effort to keep
26753 .index \*exim@_tidydb*\
26754 The \*exim@_tidydb*\ utility program is used to tidy up the contents of the
26755 hints databases. If run with no options, it removes all records from a database
26756 that are more than 30 days old. The cutoff date can be altered by means of the
26757 \-t-\ option, which must be followed by a time. For example, to remove all
26758 records older than a week from the retry database:
26760 exim_tidydb -t 7d /var/spool/exim retry
26762 Both the \*wait-*\$it{xxx} and \*retry*\ databases contain items that involve
26763 message ids. In the former these appear as data in records keyed by host --
26764 they were messages that were waiting for that host -- and in the latter they
26765 are the keys for retry information for messages that have suffered certain
26766 types of error. When \*exim@_tidydb*\ is run, a check is made to ensure that
26767 message ids in database records are those of messages that are still on the
26768 queue. Message ids for messages that no longer exist are removed from
26769 \*wait-*\$it{xxx} records, and if this leaves any records empty, they are
26770 deleted. For the \*retry*\ database, records whose keys are non-existent message
26771 ids are removed. The \*exim@_tidydb*\ utility outputs comments on the standard
26772 output whenever it removes information from the database.
26774 Removing records from a DBM file does not normally make the file smaller, but
26775 all the common DBM libraries are able to re-use the space that is released.
26776 It is therefore suggested that \*exim@_tidydb*\ be run periodically on all the
26777 hints databases, but at a quiet time of day, because it requires a database to
26778 be locked (and therefore inaccessible to Exim) while it does its work.
26780 .index \*exim@_fixdb*\
26781 The \*exim@_fixdb*\ program is a utility for interactively modifying databases.
26782 Its main use is for testing Exim, but it might also be occasionally useful for
26783 getting round problems in a live system. It has no options, and its interface
26784 is somewhat crude. On entry, it prompts for input with a right angle-bracket. A
26785 key of a database record can then be entered, and the data for that record is
26788 If `d' is typed at the next prompt, the entire record is deleted. For all
26789 except the \*retry*\ database, that is the only operation that can be carried
26790 out. For the \*retry*\ database, each field is output preceded by a number, and
26791 data for individual fields can be changed by typing the field number followed
26792 by new data, for example:
26796 resets the time of the next delivery attempt. Time values are given as a
26797 sequence of digit pairs for year, month, day, hour, and minute. Colons can be
26798 used as optional separators.
26802 .section Mailbox maintenance (exim@_lock)
26803 .rset SECTmailboxmaint "~~chapter.~~section"
26804 .index mailbox||maintenance
26805 .index \*exim@_lock*\
26806 .index locking mailboxes
26807 The \*exim@_lock*\ utility locks a mailbox file using the same algorithm as
26808 Exim. For a discussion of locking issues, see section ~~SECTopappend.
26809 \*Exim@_lock*\ can be used to prevent any modification of a mailbox by Exim or
26810 a user agent while investigating a problem. The utility requires the name of
26811 the file as its first argument. If the locking is successful, the second
26812 argument is run as a command (using C's \*system()*\ function); if there is no
26813 second argument, the value of the SHELL environment variable is used; if this
26814 is unset or empty, \(/bin/sh)\ is run. When the command finishes, the mailbox
26815 is unlocked and the utility ends. The following options are available:
26820 Use \*fcntl()*\ locking on the open mailbox.
26823 Use \*flock()*\ locking on the open mailbox, provided the operating system
26827 This must be followed by a number, which is a number of seconds; it sets the
26828 interval to sleep between retries (default 3).
26831 Create a lock file before opening the mailbox.
26834 Lock the mailbox using MBX rules.
26837 Suppress verification output.
26840 This must be followed by a number; it sets the number of times to try to get
26841 the lock (default 10).
26843 .option restore@_time
26844 This option causes \exim@_lock\ to restore the modified and read times to the
26845 locked file before exiting. This allows you to access a locked mailbox (for
26846 example, to take a backup copy) without disturbing the times that the user
26850 This must be followed by a number, which is a number of seconds; it sets a
26851 timeout to be used with a blocking \*fcntl()*\ lock. If it is not set (the
26852 default), a non-blocking call is used.
26855 Generate verbose output.
26859 If none of \-fcntl-\,
26861 \-lockfile-\ or \-mbx-\ are given, the default is to create a lock file and
26862 also to use \*fcntl()*\ locking on the mailbox, which is the same as Exim's
26863 default. The use of
26865 or \-fcntl-\ requires that the file be writeable; the use of
26866 \-lockfile-\ requires that the directory containing the file be writeable.
26867 Locking by lock file does not last for ever; Exim assumes that a lock file is
26868 expired if it is more than 30 minutes old.
26870 The \-mbx-\ option can be used with either or both of \-fcntl-\ or \-flock-\.
26871 It assumes \-fcntl-\ by default.
26872 MBX locking causes a shared lock to be taken out on the open mailbox, and an
26873 exclusive lock on the file \(/tmp/.$it{n}.$it{m})\ where $it{n} and $it{m} are
26874 the device number and inode number of the mailbox file. When the locking is
26875 released, if an exclusive lock can be obtained for the mailbox, the file in
26876 \(/tmp)\ is deleted.
26878 The default output contains verification of the locking that takes place. The
26879 \-v-\ option causes some additional information to be given. The \-q-\ option
26880 suppresses all output except error messages.
26884 exim_lock /var/spool/mail/spqr
26886 runs an interactive shell while the file is locked, whereas
26888 exim@_lock -q /var/spool/mail/spqr @<@<End
26892 runs a specific non-interactive sequence of commands while the file is locked,
26893 suppressing all verification output. A single command can be run by a command
26896 exim_lock -q /var/spool/mail/spqr \
26897 "cp /var/spool/mail/spqr /some/where"
26899 Note that if a command is supplied, it must be entirely contained within the
26900 second argument -- hence the quotes.
26908 . ============================================================================
26909 .chapter The Exim monitor
26910 .set runningfoot "monitor"
26911 .rset CHAPeximon ~~chapter
26913 .index Exim monitor
26916 .index Local/eximon.conf
26917 .index \(exim@_monitor/EDITME)\
26918 The Exim monitor is an application which displays in an X window information
26919 about the state of Exim's queue and what Exim is doing. An admin user can
26920 perform certain operations on messages from this GUI interface; however all
26921 such facilities are also available from the command line, and indeed, the
26922 monitor itself makes use of the command line to perform any actions requested.
26925 .section Running the monitor
26926 The monitor is started by running the script called \*eximon*\. This is a shell
26927 script that sets up a number of environment variables, and then runs the
26928 binary called \(eximon.bin)\. The default appearance of the monitor window can
26929 be changed by editing the \(Local/eximon.conf)\ file created by editing
26930 \(exim@_monitor/EDITME)\. Comments in that file describe what the various
26931 parameters are for.
26933 The parameters that get built into the \*eximon*\ script can be overridden for a
26934 particular invocation by setting up environment variables of the same names,
26935 preceded by `$tt{EXIMON@_}'. For example, a shell command such as
26937 EXIMON_LOG_DEPTH=400 eximon
26939 (in a Bourne-compatible shell) runs \*eximon*\ with an overriding setting of the
26940 \\LOG@_DEPTH\\ parameter. If \\EXIMON@_LOG@_FILE@_PATH\\ is set in the
26941 environment, it overrides the Exim log file configuration. This makes it
26942 possible to have \*eximon*\ tailing log data that is written to syslog, provided
26943 that MAIL.INFO syslog messages are routed to a file on the local host.
26945 X resources can be used to change the appearance of the window in the normal
26946 way. For example, a resource setting of the form
26948 Eximon*background: gray94
26950 changes the colour of the background to light grey rather than white. The
26951 stripcharts are drawn with both the data lines and the reference lines in
26952 black. This means that the reference lines are not visible when on top of the
26953 data. However, their colour can be changed by setting a resource called
26954 `highlight' (an odd name, but that's what the Athena stripchart widget uses).
26955 For example, if your X server is running Unix, you could set up lighter
26956 reference lines in the stripcharts by obeying
26959 Eximon*highlight: gray
26964 In order to see the contents of messages on the queue, and to operate on them,
26965 \*eximon*\ must either be run as root or by an admin user.
26967 The monitor's window is divided into three parts. The first contains one or
26968 more stripcharts and two action buttons, the second contains a `tail' of the
26969 main log file, and the third is a display of the queue of messages awaiting
26970 delivery, with two more action buttons. The following sections describe these
26971 different parts of the display.
26975 .section The stripcharts
26977 The first stripchart is always a count of messages on the queue. Its name can
26978 be configured by setting \\QUEUE@_STRIPCHART@_NAME\\ in the
26979 \(Local/eximon.conf)\ file. The remaining stripcharts are defined in the
26980 configuration script by regular expression matches on log file entries, making
26981 it possible to display, for example, counts of messages delivered to certain
26982 hosts or using certain transports. The supplied defaults display counts of
26983 received and delivered messages, and of local and SMTP deliveries. The default
26984 period between stripchart updates is one minute; this can be adjusted by a
26985 parameter in the \(Local/eximon.conf)\ file.
26987 The stripchart displays rescale themselves automatically as the value they are
26988 displaying changes. There are always 10 horizontal lines in each chart; the
26989 title string indicates the value of each division when it is greater than one.
26990 For example, `x2' means that each division represents a value of 2.
26992 It is also possible to have a stripchart which shows the percentage fullness of
26993 a particular disk partition, which is useful when local deliveries are confined
26994 to a single partition.
26995 .index \statvfs\ function
26996 This relies on the availability of the \*statvfs()*\ function or equivalent in
26997 the operating system. Most, but not all versions of Unix that support Exim have
26998 this. For this particular stripchart, the top of the chart always represents
26999 100%, and the scale is given as `x10%'. This chart is configured by setting
27000 \\SIZE@_STRIPCHART\\ and (optionally) \\SIZE@_STRIPCHART@_NAME\\ in the
27001 \(Local/eximon.conf)\ file.
27005 .section Main action buttons
27006 .index size||of monitor window
27007 .index monitor window size
27009 Below the stripcharts there is an action button for quitting the monitor. Next
27010 to this is another button marked `Size'. They are placed here so that shrinking
27011 the window to its default minimum size leaves just the queue count stripchart
27012 and these two buttons visible. Pressing the `Size' button causes the window to
27013 expand to its maximum size, unless it is already at the maximum, in which case
27014 it is reduced to its minimum.
27016 When expanding to the maximum, if the window cannot be fully seen where it
27017 currently is, it is moved back to where it was the last time it was at full
27018 size. When it is expanding from its minimum size, the old position is
27019 remembered, and next time it is reduced to the minimum it is moved back there.
27021 The idea is that you can keep a reduced window just showing one or two
27022 stripcharts at a convenient place on your screen, easily expand it to show
27023 the full window when required, and just as easily put it back to what it was.
27024 The idea is copied from what the \*twm*\ window manager does for its
27025 \*f.fullzoom*\ action. The minimum size of the window can be changed by setting
27026 the \\MIN@_HEIGHT\\ and \\MIN@_WIDTH\\ values in \(Local/eximon.conf)\.
27028 Normally, the monitor starts up with the window at its full size, but it can be
27029 built so that it starts up with the window at its smallest size, by setting
27030 \\START@_SMALL\\=yes in \(Local/eximon.conf)\.
27033 .section The log display
27034 .index log||tail of, in monitor
27035 The second section of the window is an area in which a display of the tail of
27036 the main log is maintained.
27037 To save space on the screen, the timestamp on each log line is shortened by
27038 removing the date and, if \log@_timezone\ is set, the timezone.
27039 The log tail is not available when the only destination for logging data is
27040 syslog, unless the syslog lines are routed to a local file whose name is passed
27041 to \*eximon*\ via the \\EXIMON@_LOG@_FILE@_PATH\\ environment variable.
27043 The log sub-window has a scroll bar at its lefthand side which can be used to
27044 move back to look at earlier text, and the up and down arrow keys also have a
27045 scrolling effect. The amount of log that is kept depends on the setting of
27046 \\LOG@_BUFFER\\ in \(Local/eximon.conf)\, which specifies the amount of memory
27047 to use. When this is full, the earlier 50% of data is discarded -- this is much
27048 more efficient than throwing it away line by line. The sub-window also has a
27049 horizontal scroll bar for accessing the ends of long log lines. This is the
27050 only means of horizontal scrolling; the right and left arrow keys are not
27051 available. Text can be cut from this part of the window using the mouse in the
27052 normal way. The size of this subwindow is controlled by parameters in the
27053 configuration file \(Local/eximon.conf)\.
27055 Searches of the text in the log window can be carried out by means of the ^R
27056 and ^S keystrokes, which default to a reverse and a forward search,
27057 respectively. The search covers only the text that is displayed in the window.
27058 It cannot go further back up the log.
27060 The point from which the search starts is indicated by a caret marker. This is
27061 normally at the end of the text in the window, but can be positioned explicitly
27062 by pointing and clicking with the left mouse button, and is moved automatically
27063 by a successful search. If new text arrives in the window when it is scrolled
27064 back, the caret remains where it is, but if the window is not scrolled back,
27065 the caret is moved to the end of the new text.
27067 Pressing ^R or ^S pops up a window into which the search text can be typed.
27068 There are buttons for selecting forward or reverse searching, for carrying out
27069 the search, and for cancelling. If the `Search' button is pressed, the search
27070 happens and the window remains so that further searches can be done. If the
27071 `Return' key is pressed, a single search is done and the window is closed. If
27072 ^C is typed the search is cancelled.
27074 The searching facility is implemented using the facilities of the Athena text
27075 widget. By default this pops up a window containing both `search' and `replace'
27076 options. In order to suppress the unwanted `replace' portion for eximon, a
27077 modified version of the \TextPop\ widget is distributed with Exim. However, the
27078 linkers in BSDI and HP-UX seem unable to handle an externally provided version
27079 of \TextPop\ when the remaining parts of the text widget come from the standard
27080 libraries. The compile-time option \\EXIMON@_TEXTPOP\\ can be unset to cut out
27081 the modified \TextPop\, making it possible to build Eximon on these systems, at
27082 the expense of having unwanted items in the search popup window.
27085 .section The queue display
27086 .index queue||display in monitor
27087 The bottom section of the monitor window contains a list of all messages that
27088 are on the queue, which includes those currently being received or delivered,
27089 as well as those awaiting delivery. The size of this subwindow is controlled by
27090 parameters in the configuration file \(Local/eximon.conf)\, and the frequency
27091 at which it is updated is controlled by another parameter in the same file --
27092 the default is 5 minutes, since queue scans can be quite expensive. However,
27093 there is an `Update' action button just above the display which can be used to
27094 force an update of the queue display at any time.
27096 When a host is down for some time, a lot of pending mail can build up for it,
27097 and this can make it hard to deal with other messages on the queue. To help
27098 with this situation there is a button next to `Update' called `Hide'. If
27099 pressed, a dialogue box called `Hide addresses ending with' is put up. If you
27100 type anything in here and press `Return', the text is added to a chain of such
27101 texts, and if every undelivered address in a message matches at least one
27102 of the texts, the message is not displayed.
27104 If there is an address that does not match any of the texts, all the addresses
27105 are displayed as normal. The matching happens on the ends of addresses so, for
27106 example, \*cam.ac.uk*\ specifies all addresses in Cambridge, while
27107 \*xxx@@foo.com.example*\ specifies just one specific address. When any hiding
27108 has been set up, a button called `Unhide' is displayed. If pressed, it cancels
27109 all hiding. Also, to ensure that hidden messages do not get forgotten, a hide
27110 request is automatically cancelled after one hour.
27112 While the dialogue box is displayed, you can't press any buttons or do anything
27113 else to the monitor window. For this reason, if you want to cut text from the
27114 queue display to use in the dialogue box, you have to do the cutting before
27115 pressing the `Hide' button.
27117 The queue display contains, for each unhidden queued message, the length of
27118 time it has been on the queue, the size of the message, the message id, the
27119 message sender, and the first undelivered recipient, all on one line. If it is
27120 a bounce message, the sender is shown as `<>'. If there is more than one
27121 recipient to which the message has not yet been delivered, subsequent ones are
27122 listed on additional lines, up to a maximum configured number, following which
27123 an ellipsis is displayed. Recipients that have already received the message are
27125 .index frozen messages||display
27126 If a message is frozen, an asterisk is displayed at the left-hand side.
27128 The queue display has a vertical scroll bar, and can also be scrolled by means
27129 of the arrow keys. Text can be cut from it using the mouse in the normal way.
27130 The text searching facilities, as described above for the log window, are also
27131 available, but the caret is always moved to the end of the text when the queue
27132 display is updated.
27135 .section The queue menu
27136 .index queue||menu in monitor
27137 If the \shift\ key is held down and the left button is clicked when the mouse
27138 pointer is over the text for any message, an action menu pops up, and the first
27139 line of the queue display for the message is highlighted. This does not affect
27142 If you want to use some other event for popping up the menu, you can set the
27143 \\MENU@_EVENT\\ parameter in \(Local/eximon.conf)\ to change the default, or
27144 set \\EXIMON@_MENU@_EVENT\\ in the environment before starting the monitor. The
27145 value set in this parameter is a standard X event description. For example, to
27146 run eximon using \ctrl\ rather than \shift\ you could use
27148 EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
27150 The title of the menu is the message id, and it contains entries which act as
27153 \*message log*\: The contents of the message log for the message are displayed in
27156 \*headers*\: Information from the spool file that contains the envelope
27157 information and headers is displayed in a new text window. See chapter
27158 ~~CHAPspool for a description of the format of spool files.
27160 \*body*\: The contents of the spool file containing the body of the message are
27161 displayed in a new text window. There is a default limit of 20,000 bytes to the
27162 amount of data displayed. This can be changed by setting the \\BODY@_MAX\\
27163 option at compile time, or the \\EXIMON@_BODY@_MAX\\ option at run time.
27165 \*deliver message*\: A call to Exim is made using the \-M-\ option to request
27166 delivery of the message. This causes an automatic thaw if the message is
27167 frozen. The \-v-\ option is also set, and the output from Exim is displayed in
27168 a new text window. The delivery is run in a separate process, to avoid holding
27169 up the monitor while the delivery proceeds.
27171 \*freeze message*\: A call to Exim is made using the \-Mf-\ option to request
27172 that the message be frozen.
27174 .index thawing messages
27175 .index unfreezing messages
27176 .index frozen messages||thawing
27177 \*thaw message*\: A call to Exim is made using the \-Mt-\ option to request that
27178 the message be thawed.
27180 .index delivery||forcing failure
27181 \*give up on msg*\: A call to Exim is made using the \-Mg-\ option to request
27182 that Exim gives up trying to deliver the message. A bounce message is generated
27183 for any remaining undelivered addresses.
27185 \*remove message*\: A call to Exim is made using the \-Mrm-\ option to request
27186 that the message be deleted from the system without generating a bounce
27189 \*add recipient*\: A dialog box is displayed into which a recipient address can
27190 be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter
27191 is set in \(Local/eximon.conf)\, the address is qualified with that domain.
27192 Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\
27193 causes a call to Exim to be made using the \-Mar-\ option to request that an
27194 additional recipient be added to the message, unless the entry box is empty, in
27195 which case no action is taken.
27197 \*mark delivered*\: A dialog box is displayed into which a recipient address can
27198 be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter
27199 is set in \(Local/eximon.conf)\, the address is qualified with that domain.
27200 Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\
27201 causes a call to Exim to be made using the \-Mmd-\ option to mark the given
27202 recipient address as already delivered, unless the entry box is empty, in which
27203 case no action is taken.
27205 \*mark all delivered*\: A call to Exim is made using the \-Mmad-\ option to mark
27206 all recipient addresses as already delivered.
27208 \*edit sender*\: A dialog box is displayed initialized with the current sender's
27209 address. Pressing \\RETURN\\ causes a call to Exim to be made using the \-Mes-\
27210 option to replace the sender address, unless the entry box is empty, in which
27211 case no action is taken. If you want to set an empty sender (as in bounce
27212 messages), you must specify it as `<>'. Otherwise, if the address is not
27213 qualified and the \\QUALIFY@_DOMAIN\\ parameter is set in
27214 \(Local/eximon.conf)\, the address is qualified with that domain.
27216 When a delivery is forced, a window showing the \-v-\ output is displayed. In
27217 other cases when a call to Exim is made, if there is any output from Exim (in
27218 particular, if the command fails) a window containing the command and the
27219 output is displayed. Otherwise, the results of the action are normally apparent
27220 from the log and queue displays. However, if you set \\ACTION@_OUTPUT\\=yes in
27221 \(Local/eximon.conf)\, a window showing the Exim command is always opened, even
27222 if no output is generated.
27224 The queue display is automatically updated for actions such as freezing and
27225 thawing, unless \\ACTION@_QUEUE@_UPDATE\\=no has been set in
27226 \(Local/eximon.conf)\. In this case the `Update' button has to be used to force
27227 an update of the display after one of these actions.
27229 In any text window that is displayed as result of a menu action, the normal
27230 cut-and-paste facility is available, and searching can be carried out using ^R
27231 and ^S, as described above for the log tail window.
27242 . ============================================================================
27243 .chapter Security considerations
27244 .set runningfoot "security"
27245 .rset CHAPsecurity ~~chapter
27247 This chapter discusses a number of issues concerned with security, some of
27248 which are also covered in other parts of this manual.
27250 For reasons that this author does not understand, some people have promoted
27251 Exim as a `particularly secure' mailer. Perhaps it is because of the existence
27252 of this chapter in the documentation. However, the intent of the chapter is
27253 simply to describe the way Exim works in relation to certain security concerns,
27254 not to make any specific claims about the effectiveness of its security as
27255 compared with other MTAs.
27257 What follows is a description of the way Exim is supposed to be. Best efforts
27258 have been made to try to ensure that the code agrees with the theory, but an
27259 absence of bugs can never be guaranteed. Any that are reported will get fixed
27260 as soon as possible.
27262 .section Building a more `hardened' Exim
27263 .index security||build-time features
27264 There are a number of build-time options that can be set in \(Local/Makefile)\
27265 to create Exim binaries that are `harder' to attack, in particular by a rogue
27266 Exim administrator who does not have the root password, or by someone who has
27267 penetrated the Exim (but not the root) account. These options are as follows:
27269 \\ALT@_CONFIG@_PREFIX\\ can be set to a string that is required to match the
27270 start of any file names used with the \-C-\ option. When it is set, these file
27271 names are also not allowed to contain the sequence `/../'. (However, if the
27272 value of the \-C-\ option is identical to the value of \\CONFIGURE@_FILE\\ in
27273 \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as usual.) There is no
27274 default setting for \ALT@_CONFIG@_PREFIX\.
27276 If the permitted configuration files are confined to a directory to
27277 which only root has access, this guards against someone who has broken
27278 into the Exim account from running a privileged Exim with an arbitrary
27279 configuration file, and using it to break into other accounts.
27281 If \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined, root privilege is retained for \-C-\
27282 and \-D-\ only if the caller of Exim is root. Without it, the Exim user may
27283 also use \-C-\ and \-D-\ and retain privilege. Setting this option locks out
27284 the possibility of testing a configuration using \-C-\ right through message
27285 reception and delivery, even if the caller is root. The reception works, but by
27286 that time, Exim is running as the Exim user, so when it re-execs to regain
27287 privilege for the delivery, the use of \-C-\ causes privilege to be lost.
27288 However, root can test reception and delivery using two separate commands.
27289 \\ALT@_CONFIG@_ROOT@_ONLY\\ is not set by default.
27291 If \\DISABLE@_D@_OPTION\\ is defined, the use of the \-D-\ command line option
27294 \\FIXED@_NEVER@_USERS\\ can be set to a colon-separated list of users that are
27295 never to be used for any deliveries. This is like the \never@_users\ runtime
27296 option, but it cannot be overridden; the runtime option adds additional users
27297 to the list. The default setting is `root'; this prevents a non-root user who
27298 is permitted to modify the runtime file from using Exim as a way to get root.
27302 .section Root privilege
27304 .index root privilege
27305 The Exim binary is normally setuid to root, which means that it gains root
27306 privilege (runs as root) when it starts execution. In some special cases (for
27307 example, when the daemon is not in use and there are no local deliveries), it
27308 may be possible to run Exim setuid to some user other than root. This is
27309 discussed in the next section. However, in most installations, root privilege
27310 is required for two things:
27312 To set up a socket connected to the standard SMTP port (25) when initialising
27313 the listening daemon. If Exim is run from \*inetd*\, this privileged action is
27316 To be able to change uid and gid in order to read users' \(.forward)\ files and
27317 perform local deliveries as the receiving user or as specified in the
27320 It is not necessary to be root to do any of the other things Exim does, such as
27321 receiving messages and delivering them externally over SMTP, and it is
27322 obviously more secure if Exim does not run as root except when necessary.
27323 For this reason, a user and group for Exim to use must be defined in
27324 \(Local/Makefile)\. These are known as `the Exim user' and `the Exim group'.
27325 Their values can be changed by the run time configuration, though this is not
27326 recommended. Often a user called \*exim*\ is used, but some sites use \*mail*\
27327 or another user name altogether.
27329 Exim uses \*setuid()*\ whenever it gives up root privilege. This is a permanent
27330 abdication; the process cannot regain root afterwards. Prior to release 4.00,
27331 \*seteuid()*\ was used in some circumstances, but this is no longer the case.
27333 After a new Exim process has interpreted its command line options, it changes
27334 uid and gid in the following cases:
27336 .index \-C-\ option
27337 .index \-D-\ option
27338 If the \-C-\ option is used to specify an alternate configuration file, or if
27339 the \-D-\ option is used to define macro values for the configuration, and the
27340 calling process is not running as root or the Exim user, the uid and gid are
27341 changed to those of the calling process.
27342 However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in \(Local/Makefile)\, only
27343 root callers may use \-C-\ and \-D-\ without losing privilege, and if
27344 \\DISABLE@_D@_OPTION\\ is set, the \-D-\ option may not be used at all.
27346 .index \-be-\ option
27347 .index \-bf-\ option
27348 .index \-bF-\ option
27349 If the expansion test option (\-be-\) or one of the filter testing options
27350 (\-bf-\ or \-bF-\) are used, the uid and gid are changed to those of the
27353 If the process is not a daemon process or a queue runner process or a delivery
27354 process or a process for testing address routing (started with \-bt-\), the uid
27355 and gid are changed to the Exim user and group. This means that Exim always
27356 runs under its own uid and gid when receiving messages. This also applies when
27357 testing address verification
27358 .index \-bv-\ option
27359 .index \-bh-\ option
27360 (the \-bv-\ option) and testing incoming message policy controls (the \-bh-\
27363 For a daemon, queue runner, delivery, or address testing process, the uid
27364 remains as root at this stage, but the gid is changed to the Exim group.
27366 The processes that initially retain root privilege behave as follows:
27368 A daemon process changes the gid to the Exim group and the uid to the Exim user
27369 after setting up one or more listening sockets. The \*initgroups()*\ function
27370 is called, so that if the Exim user is in any additional groups, they will be
27371 used during message reception.
27373 A queue runner process retains root privilege throughout its execution. Its job
27374 is to fork a controlled sequence of delivery processes.
27376 A delivery process retains root privilege throughout most of its execution,
27377 but any actual deliveries (that is, the transports themselves) are run in
27378 subprocesses which always change to a non-root uid and gid. For local
27379 deliveries this is typically the uid and gid of the owner of the mailbox; for
27380 remote deliveries, the Exim uid and gid are used. Once all the delivery
27381 subprocesses have been run, a delivery process changes to the Exim uid and gid
27382 while doing post-delivery tidying up such as updating the retry database and
27383 generating bounce and warning messages.
27385 While the recipient addresses in a message are being routed, the delivery
27386 process runs as root. However, if a user's filter file has to be processed,
27387 this is done in a subprocess that runs under the individual user's uid and
27388 gid. A system filter is run as root unless \system@_filter@_user\ is set.
27390 A process that is testing addresses (the \-bt-\ option) runs as root so that
27391 the routing is done in the same environment as a message delivery.
27395 .section Running Exim without privilege
27396 .index privilege, running without
27397 .index unprivileged running
27398 .index root privilege||running without
27399 Some installations like to run Exim in an unprivileged state for more of its
27400 operation, for added security. Support for this mode of operation is provided
27401 by the global option \deliver@_drop@_privilege\. When this is set, the uid and
27402 gid are changed to the Exim user and group at the start of a delivery process
27403 (and also queue runner and address testing processes). This means that address
27404 routing is no longer run as root, and the deliveries themselves cannot change
27407 Leaving the binary setuid to root, but setting \deliver@_drop@_privilege\ means
27408 that the daemon can still be started in the usual way, and it can respond
27409 correctly to SIGHUP because the re-invocation regains root privilege.
27411 An alternative approach is to make Exim setuid to the Exim user and also setgid
27413 If you do this, the daemon must be started from a root process. (Calling
27414 Exim from a root process makes it behave in the way it does when it is setuid
27415 root.) However, the daemon cannot restart itself after a SIGHUP signal because
27416 it cannot regain privilege.
27418 It is still useful to set \deliver@_drop@_privilege\ in this case, because it
27419 stops Exim from trying to re-invoke itself to do a delivery after a message has
27420 been received. Such a re-invocation is a waste of resources because it has no
27423 If restarting the daemon is not an issue (for example, if \*inetd*\ is being
27424 used instead of a daemon), having the binary setuid to the Exim user seems a
27425 clean approach, but there is one complication:
27427 In this style of operation, Exim is running with the real uid and gid set to
27428 those of the calling process, and the effective uid/gid set to Exim's values.
27429 Ideally, any association with the calling process' uid/gid should be dropped,
27430 that is, the real uid/gid should be reset to the effective values so as to
27431 discard any privileges that the caller may have. While some operating systems
27432 have a function that permits this action for a non-root effective uid, quite a
27433 number of them do not. Because of this lack of standardization, Exim does not
27434 address this problem at this time.
27436 For this reason, the recommended approach for `mostly unprivileged' running is
27437 to keep the Exim binary setuid to root, and to set \deliver@_drop@_privilege\.
27438 This also has the advantage of allowing a daemon to be used in the most
27439 straightforward way.
27441 If you configure Exim not to run delivery processes as root, there are a
27442 number of restrictions on what you can do:
27444 You can deliver only as the Exim user/group. You should explicitly use the
27445 \user\ and \group\ options to override routers or local transports that
27446 normally deliver as the recipient. This makes sure that configurations that
27447 work in this mode function the same way in normal mode. Any implicit or
27448 explicit specification of another user causes an error.
27450 Use of \(.forward)\ files is severely restricted, such that it is usually
27451 not worthwhile to include them in the configuration.
27453 Users who wish to use \(.forward)\ would have to make their home directory and
27454 the file itself accessible to the Exim user. Pipe and append-to-file entries,
27455 and their equivalents in Exim filters, cannot be used. While they could be
27456 enabled in the Exim user's name, that would be insecure and not very useful.
27458 Unless the local user mailboxes are all owned by the Exim user (possible in
27459 some POP3 or IMAP-only environments):
27461 They must be owned by the Exim group and be writable by that group. This
27462 implies you must set \mode\ in the appendfile configuration, as well as the
27463 mode of the mailbox files themselves.
27465 You must set \no@_check@_owner\, since most or all of the files will not be
27466 owned by the Exim user.
27468 You must set \file@_must@_exist\, because Exim cannot set the owner correctly
27469 on a newly created mailbox when unprivileged. This also implies that new
27470 mailboxes need to be created manually.
27473 These restrictions severely restrict what can be done in local deliveries.
27474 However, there are no restrictions on remote deliveries. If you are running a
27475 gateway host that does no local deliveries, setting \deliver@_drop@_privilege\
27476 gives more security at essentially no cost.
27479 .section Delivering to local files
27480 Full details of the checks applied by \%appendfile%\ before it writes to a file
27481 are given in chapter ~~CHAPappendfile.
27484 .section IPv4 source routing
27485 .index source routing||in IP packets
27486 .index IP source routing
27487 Many operating systems suppress IP source-routed packets in the kernel, but
27488 some cannot be made to do this, so Exim does its own check. It logs incoming
27489 IPv4 source-routed TCP calls, and then drops them. Things are all different in
27490 IPv6. No special checking is currently done.
27493 .section The VRFY, EXPN, and ETRN commands in SMTP
27494 Support for these SMTP commands is disabled by default. If required, they can
27495 be enabled by defining suitable ACLs.
27499 .section Privileged users
27500 .index trusted user
27502 .index privileged user
27503 .index user||trusted
27505 Exim recognises two sets of users with special privileges. Trusted users are
27506 able to submit new messages to Exim locally, but supply their own sender
27507 addresses and information about a sending host. For other users submitting
27508 local messages, Exim sets up the sender address from the uid, and doesn't
27509 permit a remote host to be specified.
27511 .index \-f-\ option
27512 However, an untrusted user is permitted to use the \-f-\ command line option in
27513 the special form \-f @<@>-\ to indicate that a delivery failure for the message
27514 should not cause an error report. This affects the message's envelope, but it
27515 does not affect the ::Sender:: header. Untrusted users may also be permitted to
27516 use specific forms of address with the \-f-\ option by setting the
27517 \untrusted@_set@_sender\ option.
27519 Trusted users are used to run processes that receive mail messages from some
27520 other mail domain and pass them on to Exim for delivery either locally, or over
27521 the Internet. Exim trusts a caller that is running as root, as the Exim user,
27522 as any user listed in the \trusted@_users\ configuration option, or under any
27523 group listed in the \trusted@_groups\ option.
27525 Admin users are permitted to do things to the messages on Exim's queue. They
27526 can freeze or thaw messages, cause them to be returned to their senders, remove
27527 them entirely, or modify them in various ways. In addition, admin users can run
27528 the Exim monitor and see all the information it is capable of providing, which
27529 includes the contents of files on the spool.
27531 .index \-M-\ option
27532 .index \-q-\ option
27533 By default, the use of the \-M-\ and \-q-\ options to cause Exim to attempt
27534 delivery of messages on its queue is restricted to admin users. This
27535 restriction can be relaxed by setting the \no@_prod@_requires@_admin\ option.
27536 Similarly, the use of \-bp-\ (and its variants) to list the contents of the
27537 queue is also restricted to admin users. This restriction can be relaxed by
27538 setting \no@_queue@_list@_requires@_admin\.
27540 Exim recognises an admin user if the calling process is running as root or as
27541 the Exim user or if any of the groups associated with the calling process is
27542 the Exim group. It is not necessary actually to be running under the Exim
27543 group. However, if admin users who are not root or the Exim user are to access
27544 the contents of files on the spool via the Exim monitor (which runs
27545 unprivileged), Exim must be built to allow group read access to its spool
27549 .section Spool files
27550 .index spool directory||files
27551 Exim's spool directory and everything it contains is owned by the Exim user and
27552 set to the Exim group. The mode for spool files is defined in the
27553 \(Local/Makefile)\ configuration file, and defaults to 0640. This means that
27554 any user who is a member of the Exim group can access these files.
27557 .section Use of argv[0]
27558 Exim examines the last component of \argv[0]\, and if it matches one of a set
27559 of specific strings, Exim assumes certain options. For example, calling Exim
27560 with the last component of \argv[0]\ set to `rsmtp' is exactly equivalent to
27561 calling it with the option \-bS-\. There are no security implications in this.
27564 .section Use of %f formatting
27565 The only use made of `%f' by Exim is in formatting load average values. These
27566 are actually stored in integer variables as 1000 times the load average.
27567 Consequently, their range is limited and so therefore is the length of the
27571 .section Embedded Exim path
27572 Exim uses its own path name, which is embedded in the code, only when it needs
27573 to re-exec in order to regain root privilege. Therefore, it is not root when it
27574 does so. If some bug allowed the path to get overwritten, it would lead to an
27575 arbitrary program's being run as exim, not as root.
27578 .section Use of sprintf()
27579 .index \*sprintf()*\
27580 A large number of occurrences of `sprintf' in the code are actually calls to
27581 \*string@_sprintf()*\, a function that returns the result in malloc'd store.
27582 The intermediate formatting is done into a large fixed buffer by a function
27583 that runs through the format string itself, and checks the length of each
27584 conversion before performing it, thus preventing buffer overruns.
27586 The remaining uses of \*sprintf()*\ happen in controlled circumstances where
27587 the output buffer is known to be sufficiently long to contain the converted
27591 .section Use of debug@_printf() and log@_write()
27592 Arbitrary strings are passed to both these functions, but they do their
27593 formatting by calling the function \*string@_vformat()*\, which runs through
27594 the format string itself, and checks the length of each conversion.
27597 .section Use of strcat() and strcpy()
27598 These are used only in cases where the output buffer is known to be large
27599 enough to hold the result.
27608 . ============================================================================
27609 .chapter Format of spool files
27610 .set runningfoot "spool file format"
27611 .rset CHAPspool ~~chapter
27612 .index format||spool files
27613 .index spool directory||format of files
27614 .index spool||files, format of
27615 .index spool||files, editing
27616 A message on Exim's queue consists of two files, whose names are the message id
27617 followed by -D and -H, respectively. The data portion of the message is kept in
27618 the -D file on its own. The message's envelope, status, and headers are all
27619 kept in the -H file, whose format is described in this chapter. Each of these
27620 two files contains the final component of its own name as its first line. This
27621 is insurance against disk crashes where the directory is lost but the files
27622 themselves are recoverable.
27625 Some people are tempted into editing -D files in order to modify messages. You
27626 need to be extremely careful if you do this; it is not recommended and you are
27627 on your own if you do it. Here are some of the pitfalls:
27629 You must use the \*exim@_lock*\ utility to ensure that Exim does not try to
27630 deliver the message while you are fiddling with it. The lock is implemented
27631 by opening the -D file and taking out a write lock on it. If you update the
27632 file in place, the lock will be retained. If you write a new file and rename
27633 it, the lock will be lost at the instant of rename.
27635 If you change the number of lines in the file, the value of
27636 \$body@_linecount$\, which is stored in the -H file, will be incorrect.
27638 If the message is in MIME format, you must take care not to break it.
27640 If the message is cryptographically signed, any change will invalidate the
27645 Files whose names end with -J may also be seen in the \(input)\ directory (or
27646 its subdirectories when \split@_spool@_directory\ is set). These are journal
27647 files, used to record addresses to which the message has been delivered during
27648 the course of a delivery run. At the end of the run, the -H file is updated,
27649 and the -J file is deleted.
27651 .section Format of the -H file
27652 .index uid (user id)||in spool file
27653 .index gid (group id)||in spool file
27654 The second line of the -H file contains the login name for the uid of the
27655 process that called Exim to read the message, followed by the numerical uid and
27656 gid. For a locally generated message, this is normally the user who sent the
27657 message. For a message received over TCP/IP, it is normally the Exim user.
27659 The third line of the file contains the address of the message's sender as
27660 transmitted in the envelope, contained in angle brackets. The sender address is
27661 empty for bounce messages. For incoming SMTP mail, the sender address is given
27662 in the \\MAIL\\ command. For locally generated mail, the sender address is
27663 created by Exim from the login name of the current user and the configured
27664 \qualify@_domain\. However, this can be overridden by the \-f-\ option or a
27665 leading `From' line if the caller is trusted, or if the supplied address is
27666 `@<@>' or an address that matches \untrusted@_set@_senders\.
27668 The fourth line contains two numbers. The first is the time that the message
27669 was received, in the conventional Unix form -- the number of seconds since the
27670 start of the epoch. The second number is a count of the number of messages
27671 warning of delayed delivery that have been sent to the sender.
27673 There follow a number of lines starting with a hyphen. These can appear in any
27674 order, and are omitted when not relevant:
27677 \-acl <<number>> <<length>>-\: A line of this form is present for every ACL
27678 variable that is not empty. The number identifies the variable; the
27679 \acl@_c\*x*\$$\ variables are numbered 0--9 and the \acl@_m\*x*\$$\ variables
27680 are numbered 10--19. The length is the length of the data string for the
27681 variable. The string itself starts at the beginning of the next line, and is
27682 followed by a newline character. It may contain internal newlines.
27684 \-allow@_unqualified@_recipient-\: This is present if unqualified recipient
27685 addresses are permitted in header lines (to stop such addresses from being
27686 qualified if rewriting occurs at transport time). Local messages that were
27687 input using \-bnq-\ and remote messages from hosts that match
27688 \recipient@_unqualified@_hosts\ set this flag.
27690 \-allow@_unqualified@_sender-\: This is present if unqualified sender
27691 addresses are permitted in header lines (to stop such addresses from being
27692 qualified if rewriting occurs at transport time). Local messages that were
27693 input using \-bnq-\ and remote messages from hosts that match
27694 \sender@_unqualified@_hosts\ set this flag.
27697 \-auth@_id <<text>>-\: The id information for a message received on an
27698 authenticated SMTP connection -- the value of the \$authenticated@_id$\
27701 \-auth@_sender <<address>>-\: The address of an authenticated sender -- the
27702 value of the \$authenticated@_sender$\ variable.
27704 \-body@_linecount <<number>>-\: This records the number of lines in the body of
27705 the message, and is always present.
27707 \-deliver@_firsttime-\: This is written when a new message is first added to
27708 the spool. When the spool file is updated after a deferral, it is omitted.
27710 .index frozen messages||spool data
27711 \-frozen <<time>>-\: The message is frozen, and the freezing happened at
27714 \-helo@_name <<text>>-\: This records the host name as specified by a remote
27715 host in a \\HELO\\ or \\EHLO\\ command.
27717 \-host@_address <<address>>.<<port>>-\: This records the IP address of the host
27718 from which the message was received and the remote port number that was used.
27719 It is omitted for locally generated messages.
27721 \-host@_auth <<text>>-\: If the message was received on an authenticated SMTP
27722 connection, this records the name of the authenticator -- the value of the
27723 \$sender@_host@_authenticated$\ variable.
27725 \-host@_lookup@_failed-\: This is present if an attempt to look up the sending
27726 host's name from its IP address failed. It corresponds to the
27727 \$host@_lookup@_failed$\ variable.
27729 .index DNS||reverse lookup
27730 .index reverse DNS lookup
27731 \-host@_name <<text>>-\: This records the name of the remote host from which
27732 the message was received, if the host name was looked up from the IP address
27733 when the message was being received. It is not present if no reverse lookup was
27736 \-ident <<text>>-\: For locally submitted messages, this records the login of
27737 the originating user, unless it was a trusted user and the \-oMt-\ option was
27738 used to specify an ident value. For messages received over TCP/IP, this records
27739 the ident string supplied by the remote host, if any.
27741 \-interface@_address <<address>>.<<port>>-\: This records the IP address of the
27742 local interface and the port number through which a message was received from a
27743 remote host. It is omitted for locally generated messages.
27745 \-local-\: The message is from a local sender.
27747 \-localerror-\: The message is a locally-generated bounce message.
27749 \-local@_scan <<string>>-\: This records the data string that was
27750 returned by the \*local@_scan()*\ function when the message was received -- the
27751 value of the \$local@_scan@_data$\ variable. It is omitted if no data was
27754 \-manual@_thaw-\: The message was frozen but has been thawed manually, that is,
27755 by an explicit Exim command rather than via the auto-thaw process.
27757 \-N-\: A testing delivery process was started using the \-N-\ option to
27758 suppress any actual deliveries, but delivery was deferred. At any further
27759 delivery attempts, \-N-\ is assumed.
27761 \-received@_protocol-\: This records the value of the \$received@_protocol$\
27762 variable, which contains the name of the protocol by which the message was
27765 \-sender@_set@_untrusted-\: The envelope sender of this message was set by an
27766 untrusted local caller (used to ensure that the caller is displayed in queue
27769 \-tls@_certificate@_verified-\: A TLS certificate was received from the client
27770 that sent this message, and the certificate was verified by the server.
27772 \-tls@_cipher <<cipher name>>-\: When the message was received over an
27773 encrypted connection, this records the name of the cipher suite that was used.
27775 \-tls@_peerdn <<peer DN>>-\: When the message was received over an encrypted
27776 connection, and a certificate was received from the client, this records the
27777 Distinguished Name from that certificate.
27780 Following the options there is a list of those addresses to which the message
27781 is not to be delivered. This set of addresses is initialized from the command
27782 line when the \-t-\ option is used and \extract__addresses__remove__arguments\
27783 is set; otherwise it starts out empty. Whenever a successful delivery is made,
27784 the address is added to this set. The addresses are kept internally as a
27785 balanced binary tree, and it is a representation of that tree which is written
27786 to the spool file. If an address is expanded via an alias or forward file, the
27787 original address is added to the tree when deliveries to all its child
27788 addresses are complete.
27790 If the tree is empty, there is a single line in the spool file containing just
27791 the text `XX'. Otherwise, each line consists of two letters, which are either Y
27792 or N, followed by an address. The address is the value for the node of the
27793 tree, and the letters indicate whether the node has a left branch and/or a
27794 right branch attached to it, respectively. If branches exist, they immediately
27795 follow. Here is an example of a three-node tree:
27797 YY darcy@austen.fict.example
27798 NN alice@wonderland.fict.example
27799 NN editor@thesaurus.ref.example
27801 After the non-recipients tree, there is a list of the message's recipients.
27802 This is a simple list, preceded by a count. It includes all the original
27803 recipients of the message, including those to whom the message has already been
27804 delivered. In the simplest case, the list contains one address per line. For
27808 editor@thesaurus.ref.example
27809 darcy@austen.fict.example
27811 alice@wonderland.fict.example
27813 However, when a child address has been added to the top-level addresses as a
27814 result of the use of the \one@_time\ option on a \%redirect%\ router, each line
27815 is of the following form:
27817 <<top-level address>> <<errors@_to address>> <<length>>,<<parent number>>@#<<flag bits>>
27819 The 01 flag bit indicates the presence of the three other fields that follow
27820 the top-level address. Other bits may be used in future to support additional
27821 fields. The <<parent number>> is the offset in the recipients list of the
27822 original parent of the `one time' address. The first two fields are the
27823 envelope sender that is associated with this address and its length. If the
27824 length is zero, there is no special envelope sender (there are then two space
27825 characters in the line). A non-empty field can arise from a \%redirect%\ router
27826 that has an \errors@_to\ setting.
27829 A blank line separates the envelope and status information from the headers
27830 which follow. A header may occupy several lines of the file, and to save effort
27831 when reading it in, each header is preceded by a number and an identifying
27832 character. The number is the number of characters in the header, including any
27833 embedded newlines and the terminating newline. The character is one of the
27837 <<blank>> $t $rm{header in which Exim has no special interest}
27838 #B $t $rm{::Bcc:: header}
27839 #C $t $rm{::Cc:: header}
27840 #F $t $rm{::From:: header}
27841 #I $t $rm{::Message-id:: header}
27842 #P $t $rm{::Received:: header -- P for `postmark'}
27843 #R $t $rm{::Reply-To:: header}
27844 #S $t $rm{::Sender:: header}
27845 #T $t $rm{::To:: header}
27846 #* $t $rm{replaced or deleted header}
27848 Deleted or replaced (rewritten) headers remain in the spool file for debugging
27849 purposes. They are not transmitted when the message is delivered. Here is a
27850 typical set of headers:
27852 111P Received: by hobbit.fict.example with local (Exim 4.00)
27853 id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100
27854 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example>
27855 038* X-rewrote-sender: bb@hobbit.fict.example
27856 042* From: Bilbo Baggins <bb@hobbit.fict.example>
27857 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example>
27858 099* To: alice@wonderland.fict.example, rdo@foundation,
27859 darcy@austen.fict.example, editor@thesaurus.ref.example
27860 109T To: alice@wonderland.fict.example, rdo@foundation.fict.example,
27861 darcy@austen.fict.example, editor@thesaurus.ref.example
27862 038 Date: Fri, 11 May 2001 10:28:59 +0100
27864 The asterisked headers indicate that the envelope sender, ::From:: header, and
27865 ::To:: header have been rewritten, the last one because routing expanded the
27866 unqualified domain \*foundation*\.
27872 . ============================================================================
27873 .chapter Adding new drivers or lookup types
27874 .set runningfoot "adding drivers"
27875 .index adding drivers
27876 .index new drivers, adding
27877 .index drivers||adding new
27878 The following actions have to be taken in order to add a new router, transport,
27879 authenticator, or lookup type to Exim:
27881 Choose a name for the driver or lookup type that does not conflict with any
27882 existing name; I will use `newdriver' in what follows.
27884 Add to \(src/EDITME)\ the line
27886 <<type>>@_NEWDRIVER=yes
27888 where <<type>> is \\ROUTER\\, \\TRANSPORT\\, \\AUTH\\, or \\LOOKUP\\. If the
27889 code is not to be included in the binary by default, comment this line out. You
27890 should also add any relevant comments about the driver or lookup type.
27892 Add to \(src/config.h.defaults)\ the line
27894 @#define <<type>>@_NEWDRIVER
27897 Edit \(src/drtables.c)\, adding conditional code to pull in the private header
27898 and create a table entry as is done for all the other drivers and lookup types.
27900 Edit \(Makefile)\ in the appropriate sub-directory (\(src/routers)\,
27901 \(src/transports)\, \(src/auths)\, or \(src/lookups)\); add a line for the new
27902 driver or lookup type and add it to the definition of OBJ.
27904 Create \(newdriver.h)\ and \(newdriver.c)\ in the appropriate sub-directory of
27907 Edit \(scripts/MakeLinks)\ and add commands to link the \(.h)\ and \(.c)\ files
27908 as for other drivers and lookups.
27910 Then all you need to do is write the code! A good way to start is to make a
27911 proforma by copying an existing module of the same type, globally changing all
27912 occurrences of the name, and cutting out most of the code. Note that any
27913 options you create must be listed in alphabetical order, because the tables are
27914 searched using a binary chop procedure.
27916 There is a \(README)\ file in each of the sub-directories of \(src)\ describing
27917 the interface that is expected.
27923 . ============================================================================
27924 . Fudge for the index page number. We want it to be on a right-hand page.
27926 .set indexpage ~~sys.pagenumber + 1
27927 .if even ~~indexpage
27928 .set indexpage ~~indexpage + 1
27931 .%index Index$e~~indexpage--
27935 . End of Exim specification
git://git.exim.org / users / heiko / exim.git / blob